TCDB APItcdb.com ↗
Access TCDB trading card set listings, base checklists, and insert/parallel data by sport and year. 3 endpoints covering Football, Baseball, Basketball, and Hockey.
What is the TCDB API?
The TCDB API gives developers access to trading card set data across major sports through 3 endpoints. Use list_sets to browse sets by year and sport, get_set_details to retrieve base checklists alongside insert and parallel breakdowns, and get_checklist to pull every card in a set with number, player name, team, and special notations like rookie cards and short prints.
curl -X GET 'https://api.parse.bot/scraper/123aeda8-4611-4871-a592-2109a3f6434f/list_sets?year=2025&query=Donruss&sport=Football' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tcdb-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.tcdb_trading_card_database_api import TCDB, CardSetSummary, CardSet, Card, Sport
tcdb = TCDB()
# Search for 2025 Baseball card sets
for card_set_summary in tcdb.cardsets.search(year="2025", sport=Sport.BASEBALL):
print(card_set_summary.name, card_set_summary.sid)
# Get full details for a specific set
details = tcdb.cardsets.get(sid="538963")
print(details.metadata.info)
print(details.total_inserts_parallels)
for insert in details.inserts_and_parallels:
print(insert.name, insert.sid)
# Navigate from a summary to its detail with limited inserts
for summary in tcdb.cardsets.search(year="2024", sport=Sport.FOOTBALL, limit=3):
full = summary.details(limit_inserts=2)
print(full.sid, full.total_inserts_parallels)
# Access cards sub-resource from a fetched set
card_set = tcdb.cardsets.get(sid="506623")
for card in card_set.cards.list(limit=10):
print(card.number, card.name, card.team)
List all trading card sets for a specific year and sport, optionally filtered by name. Returns an array of set summaries including set IDs usable with get_set_details and get_checklist. Results are not paginated; the full list for the given year/sport is returned in one response. When query is provided, only sets whose name contains the query (case-insensitive) are returned.
| Param | Type | Description |
|---|---|---|
| year | string | Year to list sets for (e.g. '2025', '2024', '2023'). |
| query | string | Optional search query to filter sets by name (case-insensitive substring match). When omitted, all sets for the year/sport are returned. |
| sport | string | Sport name to filter sets. |
{
"type": "object",
"fields": {
"sets": "array of set summary objects with sid, name, url, sport, and year"
},
"sample": {
"data": {
"sets": [
{
"sid": "506623",
"url": "https://www.tcdb.com/ViewSet.cfm/sid/506623/2025-Bowman",
"name": "2025 Bowman",
"year": "2025",
"sport": "Baseball"
}
]
},
"status": "success"
}
}About the TCDB API
Set Discovery
The list_sets endpoint accepts optional year and sport parameters — valid sport values are Football, Baseball, Basketball, and Hockey — and returns an array of set objects. Each object includes a sid (set ID), name, url, sport, and year. That sid flows directly into the other two endpoints, so discovery is the natural starting point for any workflow.
Set Details and Insert/Parallel Checklists
get_set_details accepts a required sid and an optional limit_inserts integer. The response bundles three data structures: a metadata object with a freeform info string describing the set, a base_checklist array of card objects (each with number, name, team, and notations), and an inserts_and_parallels array where each entry carries its own sid, name, and nested cards array. The total_inserts_parallels integer tells you how many insert/parallel sets exist for the set, which matters when limit_inserts is lower than that total.
Full Checklist Retrieval
get_checklist takes a single required sid and returns the complete cards array for that set, with pagination handled automatically. Each card object exposes number, name, team, and notations. Notations capture designations such as rookie cards, short prints, and variations — structured details that are otherwise tedious to collect manually from set checklists.
The TCDB API is a managed, monitored endpoint for tcdb.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tcdb.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tcdb.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a personal card collection tracker that syncs set checklists by sport and year using
list_setsandget_checklist. - Identify all rookie card notations in a given set's base checklist for targeted collecting or valuation research.
- Enumerate insert and parallel sets for a specific release to map out the full product breakdown with
get_set_details. - Populate a card database application with structured player, team, and card-number data across multiple sports seasons.
- Compare insert and parallel counts across sets in the same year to analyze product complexity trends.
- Build a checklist completion app that shows which cards a user still needs from a given
sid. - Aggregate short print and variation notations across multiple Football or Baseball sets to flag scarcity for collectors.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TCDB offer an official developer API?+
What does the `notations` field on a card object contain?+
notations field carries designations associated with that specific card, such as rookie card markers, short print indicators, and variation labels. Not every card will have notations — the field reflects only the designations TCDB associates with that entry in its checklist.Can I retrieve card market prices or sale history through this API?+
How does `limit_inserts` affect the `get_set_details` response?+
limit_inserts caps how many insert/parallel checklists are fetched and included in the inserts_and_parallels array. The total_inserts_parallels field in the response always reflects the true total available for that set, so you can detect when the limit cut the list short and decide whether to raise it.Is player search or card-level search by player name supported?+
sid, year, and sport — there is no endpoint that accepts a player name and returns matching cards across sets. You can fork this API on Parse and revise it to add a player-search endpoint if cross-set lookup is needed.