Agents and reference
MCP and the agent skill, the endpoint table, quotas, and latency targets
Last updated:
Agents and referenceLink copied!
Agents: MCP and skillLink copied!
Prefer the markdown copy of this guide (this HTML page is for humans): https://silphcoanalytics.xyz/docs/api/getting-started.md and the skill: https://silphcoanalytics.xyz/skill-api.md. MCP is Streamable HTTP at https://silphcoanalytics.xyz/api/v3/mcp/ (trailing slash — the bare path 307s) with the same dashboard Bearer [REDACTED] keyless calls run at the playground tier. Core tools: oracle, get_sales, resolve_cards, search, get_listings, get_population, get_usage, and send_private_feedback; the SilphCo Price is the price. Setup: https://silphcoanalytics.xyz/docs/reference/mcp.
curl "https://silphcoanalytics.xyz/api/v3/price?q=42382&grade_key=PSA%3A10"Endpoint tableLink copied!
Base URL: https://silphcoanalytics.xyz/api/v3. OpenAPI: openapi-public.json.
All endpoints (67)
Cards
| Method | Path | Description |
|---|---|---|
| GET | /api/v3/card-catalog/cards/{id} | /api/v3/card-catalog/cards/{id} |
| GET | /api/v3/card-catalog/cards/{id}/image | /api/v3/card-catalog/cards/{id}/image |
| GET | /api/v3/card-catalog/sets/{id}/cards | /api/v3/card-catalog/sets/{id}/cards |
| GET | /api/v3/cards/{id} | Card identity + headline dollars (playground slims the gold dump) |
| GET | /api/v3/cards/{id}/analytics | Card analytics |
| GET | /api/v3/cards/{id}/chart-series | Card-page history (sale_date × grade × finish) |
| GET | /api/v3/cards/{id}/facts | Cited card facts (lor-api thin proxy) |
| GET | /api/v3/cards/{id}/monthly-marks | PriceCharting monthly price-guide marks (lor-api thin proxy) |
| GET | /api/v3/cards/{id}/tcgplayer-history | TCGplayer daily price and sales history |
| GET | /api/v3/sets/{id}/cards | Paginated cards in a set with per-card volume and price fields (lor-api thin proxy) |
| POST | /api/v3/cards/batch | Batch core-card lookup by tcg_card_id (same as GET /cards/{id}; not productIds; fanned out to the lake in chunks; cost = unique ids, charged only on a clean fan-out; max 250) |
| POST | /api/v3/cards/population | Graded population for up to 50 cards (ids / queries), or one set page by page (set_id, rarity, cursor); one unit per card; same cards[].status vocabulary as MCP get_population |
Lists
| Method | Path | Description |
|---|---|---|
| DELETE | /api/v3/lists/{id} | Delete an owned list and its items |
| DELETE | /api/v3/lists/{id}/items/{item_id} | Remove one list item |
| DELETE | /api/v3/me/alerts/{id} | Delete an owned alert |
| GET | /api/v3/lists | The key owner's saved lists (watchlists and portfolios) |
| GET | /api/v3/lists/{id} | One owned list with items; watchlists add recent_activity and price_alert per item |
| GET | /api/v3/lists/{id}/activity-digest | New sales and new live asks per watched card; ack=true marks them read |
| GET | /api/v3/lists/{id}/analytics | One-call list analytics, up to 100 entries a page: per entry at its exact grade and finish the SilphCo Price, last clean sale, 90-day median, 30-day trend and momentum, lowest live ask, population and distance to target; rollups by series, grade, population band, price band and card type; sort, filters, changed_since, format=csv. One unit per distinct card analyzed, minimum 1 |
| GET | /api/v3/lists/{id}/summary | List rollup: current value, 7/30/90-day change and per-card rows; P&L only where cost basis is stored |
| GET | /api/v3/me/alerts | The key owner's price alerts (status= filters) |
| GET | /api/v3/me/alerts/digest | Triggered alerts not yet seen; ack=true marks them seen |
| GET | /api/v3/me/watchlist/movers | Watchlist items ranked by momentum (list_id= required) |
| PATCH | /api/v3/lists/{id} | Rename or convert an owned list |
| PATCH | /api/v3/lists/{id}/items/{item_id} | Edit one list item |
| PATCH | /api/v3/me/alerts/{id} | Change the threshold, direction or status of an owned alert |
| POST | /api/v3/lists | Create a list for the key owner |
| POST | /api/v3/lists/{id}/items | Add or upsert a card on an owned list |
| POST | /api/v3/lists/{id}/targets | Set or clear target (buy) prices on up to 40 watchlist entries, each at its exact grade and finish; 503 not_enabled until target storage is provisioned |
| POST | /api/v3/me/alerts | Arm a price-threshold alert on a watchlist item |
Market
| Method | Path | Description |
|---|---|---|
| GET | /api/v3/listings | Live listings / asks (ids= or set_id=; productId ok) |
| GET | /api/v3/listings/by-seller | Seller discovery: match sellers by free-text q and rank them by reputation (min_feedback_score/min_feedback_pct filter, sort= overrides the default ranking); page the listings of the seller_key you picked |
| GET | /api/v3/listings/changes | Change feed: asks that appeared (change=new, first_seen_at) or ended (change=ended, delisted_at) for ids= or set_id=; newest first, keyset cursor, one unit a page |
| GET | /api/v3/listings/export | Cursor-complete NDJSON or CSV export of one seller (seller_key) or one set (set_id); NDJSON ends with a completeness trailer |
| GET | /api/v3/listings/sellers/{seller_key}/listings | /api/v3/listings/sellers/{seller_key}/listings |
| GET | /api/v3/listings/{listing_id} | One ask by marketplace item id or stored listing_id, ungated (ended/stale rows come back with listing_status); 404 when no row carries the id |
| GET | /api/v3/market/price-series | /api/v3/market/price-series |
| GET | /api/v3/market/window-changes | Per-card 7/30/90d price window changes (lor-api thin proxy) |
| GET | /api/v3/prices | Historical prices (ids= tcg_card_id or TCGPlayer productId) |
| GET | /api/v3/sales | Verified sales tape (sales.v2; ids= or set_id=; grade=; since/until; group=sale|card|day|week|month|set; rollup=set; cert= for one slab's tape) |
| GET | /api/v3/sales/export | Keyed calendar-month parquet (since/until one month) |
| GET | /api/v3/sales/export.csv | Agent/export: sales CSV download for one card (lor-api thin proxy) |
| POST | /api/v3/prices | Historical prices, JSON {ids} (same prices.v1 job; keyed cap 1000) |
Meta
| Method | Path | Description |
|---|---|---|
| GET | /api/v3/certs/{cert} | Grader cert lookup (lor-api-cert.v1): resolved card identity and newest-first sale tape for one cert number (grader=; limit<=500; offset) |
| GET | /api/v3/meta/freshness | Data-plane surface freshness (lor-api thin proxy) |
| GET | /api/v3/meta/min-app-version | /api/v3/meta/min-app-version |
| GET | /api/v3/og/{card_id}.png | /api/v3/og/{card_id}.png |
| GET | /api/v3/pay/hosted/{receipt} | /api/v3/pay/hosted/{receipt} |
| GET | /api/v3/pay/status/{receipt} | /api/v3/pay/status/{receipt} |
| GET | /api/v3/price | SilphCo Price for one cohort (price.v2; tcg_card_id or q; grade_key or deprecated grade, finish, language, edition; method/outliers/marketplace; one-sale thin answers last_sale; wrong-language asks answer locale_mismatch) |
| GET | /api/v3/resolve | Lexical card-identity resolve for one phrase (card-resolve.v2; bare 8-10 digits resolve as a slab cert number with cert_match) |
| GET | /api/v3/test/pay | /api/v3/test/pay |
| POST | /api/v3/mcp | /api/v3/mcp |
| POST | /api/v3/me/imports/confirm | /api/v3/me/imports/confirm |
| POST | /api/v3/me/imports/preview | /api/v3/me/imports/preview |
| POST | /api/v3/pay/hosted/{receipt}/complete | /api/v3/pay/hosted/{receipt}/complete |
| POST | /api/v3/price/batch | SilphCo Price for many cohorts (price.v2; items[]; method/outliers/marketplace/include apply to all; billed per priced item) |
| POST | /api/v3/resolve | Bulk-resolve phrases or tcg_card_id / productId tokens (card-resolve.v2) |
Search
| Method | Path | Description |
|---|---|---|
| GET | /api/v3/search | Full-text card search |
| GET | /api/v3/search-quota | /api/v3/search-quota |
| POST | /api/v3/search-quota/consume | /api/v3/search-quota/consume |
Sets
| Method | Path | Description |
|---|---|---|
| GET | /api/v3/card-catalog/sets | /api/v3/card-catalog/sets |
| GET | /api/v3/card-catalog/sets/{id} | /api/v3/card-catalog/sets/{id} |
| GET | /api/v3/sets | List sets |
| GET | /api/v3/sets/{id} | Set detail |
| GET | /api/v3/sets/{id}/population | Set graded population overview (Pro tier; lor-api thin proxy) |
| GET | /api/v3/sets/{id}/trending-cards | Trending cards in a set |
LimitsLink copied!
Playground needs no key (10 req/s (burst 120), 50-row cap). Keyed quotas: Free 2,000 units/month · Pro 50,000 units/month · Elite 250,000 units/month. Limits are metered in units, not requests — a single-id call is 1 unit, an N-id call is N units. Read usage from GET /keys/usage.
Tier details
| Tier | Auth | Limits |
|---|---|---|
| Playground | No API key | 10 req/s (burst 120), 50-row cap, 50 ids |
| Free | Bearer [REDACTED] key | 2,000 units/month |
| Pro | Bearer [REDACTED] key | 50,000 units/month |
| Elite | Bearer [REDACTED] key | 250,000 units/month |
Latency expectationsLink copied!
Expected warm response ranges per route family. These are design targets, not a contractual SLO: there is no published uptime SLA. The load gate behind them is p50 250ms / p95 800ms / p99 1500ms at 25 concurrent requests.
Latency ranges by route family
| Route family | Warm p95 | Cold p95 | Notes |
|---|---|---|---|
ID lookups (/cards/{id}, /sets/{id}, /resolve, /price) | ~50ms | ~500ms | Keyless playground included. |
Search (/search) | ~20ms | ~500ms | 15s proxy timeout; treat query_interrupted as retryable with backoff. |
Lists and small collections (/catalog, /sets, /trending-cards) | ~15ms | ~500ms | Grows with page size. |
Price (/price, /price/batch, MCP oracle) | ~1–2s | ~1–2s | Runs the full grade ladder; batch rows share the call. |
Bulk collections (/sales, /listings, /prices) | seconds | seconds | Scales with id count; page with cursors and use generous client timeouts. |