API & MCP documentation
Diecast Detective exposes a REST API and an MCP server so you can pull your collection, watchlist, and wishlist data, and search the product catalog, from your own tools. Both surfaces use the same bearer token and the same account data.
Authentication
Every request needs a bearer token. Get one from your API Access page: issue a token, copy it immediately, it is only shown once.
Send it as a standard Authorization header:
Authorization: Bearer YOUR_TOKENA missing or invalid token gets a 401:
{
"error": "invalid_token",
"error_description": "Invalid or expired token"
}If no token is sent at all, error_description reads "No bearer token provided" instead.
Rate limits
Limits are per account, not per token, and reset every minute:
| Plan | Requests per minute |
|---|---|
| Trial | 30 |
| Paid | 120 |
| No active subscription | 10 |
The REST API and the MCP server are metered separately. Using one does not eat into the other's budget.
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers. Going over the limit gets a 429 with a Retry-After header and:
{
"error": "rate_limited",
"error_description": "Rate limit exceeded for your plan (paid: 120/min). Upgrade or wait for the window to reset."
}Base URL
Requests go to your account's API host, shown on the API Access page. All endpoints below are relative to that host.
Versioning
This is v1. A breaking change ships as v2 at a new path (/v2/...), never as a breaking change to v1 in place. v1 keeps working after v2 exists.
Endpoints
All endpoints are GET-only and require a bearer token.
Collection
GET /v1/collection
Your collection entries, paginated 25 per page. Optional folder_id query param restricts results to one folder.
{
"data": [
{
"id": 4821,
"name": "1:18 Ford GT40 Gulf Racing",
"condition": "n",
"sold": false,
"sale_price": null,
"sale_date": null,
"purchase_price": 145.00,
"purchase_date": "2024-03-11",
"insurance_value": 180.00,
"insurance_date": "2024-03-11",
"today_price": 172.50,
"yesterday_price": 171.00,
"product": {
"code": "18001A",
"year": 1968,
"make": "Ford",
"model": "GT40",
"event": "Le Mans",
"colour": "Gulf Blue/Orange",
"model_brand": "CMC",
"scale": "1:18"
},
"folder_ids": [12, 15],
"created_at": "2024-03-11T09:22:41+00:00",
"updated_at": "2024-03-11T09:22:41+00:00"
}
]
}GET /v1/collection/{entry}
A single collection entry by id. Same shape as one item above. 404 if it doesn't exist or belongs to another account.
GET /v1/collection/folders
Your collection folders.
{
"data": [
{ "id": 12, "name": "F1 1:18", "order": 1 },
{ "id": 15, "name": "Le Mans", "order": 2 }
]
}GET /v1/collection/totals
Aggregate value and gain/loss for your collection. Optional folder_id restricts to one folder.
{
"total_value": 4820.50,
"total_value_12m": 4390.00,
"total_value_original": 3900.00,
"total_gain_loss": 920.50,
"total_gain_loss_percent": 23.6,
"total_change_day": 12.00,
"total_change_month": 88.50,
"total_change_6_months": 340.00,
"total_change_year": 430.50,
"total_insurance_value": 5200.00,
"item_count": 62
}Watchlist and wishlist
GET /v1/watchlist
GET /v1/wishlist
Your entries with current valuation and price-history chart data. Paginated 25 per page.
{
"data": [
{
"id": 901,
"name": "1:43 Porsche 917K",
"classification": "vintage",
"condition": "new",
"start_price": 89.00,
"start_date": "2023-11-02",
"today_price": 104.20,
"yesterday_price": 103.90,
"daily_change": 0.30,
"diecast_now": 104.20,
"diecast_original": 89.00,
"change_day": 0.30,
"change_month": 4.10,
"change_6_months": 9.80,
"change_year": 15.20,
"lost_gain": 15.20,
"percent_lost_gain": 17.1,
"average_new": 106.00,
"average_used": 78.50,
"last_week_price": 103.10,
"product": {
"code": "43005B",
"year": 1970,
"make": "Porsche",
"model": "917K",
"event": "Le Mans",
"colour": "Salzburg",
"model_brand": "CMR",
"scale": "1:43"
},
"chart_data": { "datasets": [], "axis": [] },
"created_at": "2023-11-02T14:05:09+00:00"
}
]
}Products
GET /v1/products/search
Search the catalog. Query params, all optional: q (free text against code, make, model), make, model, year.
{
"data": [
{
"code": "18001A",
"year": 1968,
"make": "Ford",
"model": "GT40",
"event": "Le Mans",
"colour": "Gulf Blue/Orange",
"model_brand": "CMC",
"scale": "1:18",
"thumbnail": "https://.../18001a.jpg",
"diecast_price_new": 172.50,
"diecast_price_used": 138.00
}
]
}GET /v1/products/{code}
A single product: descriptor fields, current price at both conditions, and up to 50 of its most recent sales.
{
"code": "18001A",
"year": 1968,
"make": "Ford",
"model": "GT40",
"event": "Le Mans",
"colour": "Gulf Blue/Orange",
"model_brand": "CMC",
"scale": "1:18",
"edition": "Limited",
"category": "Racing",
"number_made": 999,
"thumbnail": "https://.../18001a.jpg",
"launch_price": 150.00,
"release_date": "2020-06-01",
"diecast_price_new": 172.50,
"diecast_price_used": 138.00,
"sales": [
{ "sale_price": 175.00, "sale_date": "2026-08-20", "condition": 1, "platform": "eBay" }
]
}Homepage
GET /v1/homepage/recently-added
Products added in the last 30 days that already have a recorded sale.
GET /v1/homepage/highest-value
GET /v1/homepage/most-traded
The same sales feeding the site's homepage carousels.
GET /v1/homepage/model-in-focus
The currently featured model, with commentary and price stats. 404 if none is configured.
Connecting an MCP client
The MCP server sits at your account's MCP host, shown on the API Access page, at path /mcp.
Add it as a custom connector using the same bearer token from the API Access page. The token that authenticates your REST calls also authenticates your MCP session, no separate MCP credential and no OAuth flow required for now. OAuth-based connection may be added later, but bearer token is the only option today.
Available tools
Scoped to your own account:
list_collection_entries, your collection entries, optionally filtered to one folderget_collection_entry, a single collection entry by idlist_collection_folders, your collection foldersget_collection_totals, aggregate value and gain/loss for your collectionlist_watchlist_entries, your watchlist with current valuation and chart datalist_wishlist_entries, your wishlist with current valuation and chart data
Public catalog data, not scoped to any account:
search_products, search the catalog by free text, make, model, and/or yearget_product, a single product by code, with recent sale historyrecently_added_products, products added in the last 30 days with at least one salehighest_value_products, the highest-value recent sales across all time windowsmost_traded_products, the most-traded products by recent sale countmodel_in_focus, the currently featured model, with commentary and price stats