Skip to main content

API Endpoints

This page provides a complete reference of all available API endpoints.

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

Health​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /health​

Liveness/readiness healthcheck (infrastructure)

Infrastructure healthcheck for load balancers and uptime monitors. Returns 200 when the database and cache are reachable, or 503 when a dependency check fails. Unauthenticated, unthrottled, and excluded from API usage logging. Not a public API feature. The checks.billing key is advisory only: it reports degraded when billing or lifecycle-email configuration is incomplete and never affects the status code.

Authentication: Public — no API token required.

Example Request​

curl -X GET "https://api.tradingcardapi.com/health" \
  -H "Accept: application/json"

Example Response​

{
  "status": "ok",
  "version": "0.2.84",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "billing": "ok"
  }
}

Internal​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /internal/analytics/sales-readiness​

Sales readiness report (internal)

Returns the analyze:sales-readiness data-coverage report. Requires the 'internal' OAuth scope. Use format=json (default) for the structured payload or format=table for the rendered text table.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
formatstringNoOutput format: json (default) or table
yearsintegerNoNumber of most recent years to include in year coverage (must be a positive integer)
monthsintegerNoNumber of most recent months for the update-cadence window (positive integer)

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/analytics/sales-readiness" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

GET /internal/audit-logs​

List audit log events (internal)

Retrieve audit log events with optional filtering by entity, event type, and date range. Defaults to last 30 days when no date filters are provided. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
filter[auditable_type]stringNoFilter by entity type (e.g. set, card, player, team)
filter[auditable_id]stringNoFilter by entity UUID
filter[event_type]stringNoFilter by event type
filter[start_date]stringNoFilter events on or after this date (ISO 8601)
filter[end_date]stringNoFilter events on or before this date (ISO 8601)
per_pageintegerNoNumber of results per page (default 50, max 500)
pageintegerNoPage number

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/audit-logs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "audit_logs",
      "id": 12345,
      "attributes": {
        "event_type": "agent_spawned",
        "auditable_type": "set",
        "auditable_id": "string",
        "agent_id": "agent-abc-123",
        "data": {},
        "created_at": "string"
      }
    }
  ]
}

POST /internal/audit-logs​

Create an audit log event (internal)

Record a new audit log event. Supports polymorphic association with any entity. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"audit_logs"
data.attributesobjectNoNo
data.attributes.event_typestringYesNo"agent_spawned"
data.attributes.auditable_typestringNoYes"set"
data.attributes.auditable_idstring (uuid)NoYes"550e8400-e29b-41d4-a716-446655440000"
data.attributes.agent_idstringNoYes"agent-abc-123"
data.attributes.dataobjectNoYes{"step":"populate","status":"started"}

Example Request​

curl -X POST "https://api.tradingcardapi.com/internal/audit-logs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"audit_logs","attributes":{"event_type":"agent_spawned","auditable_type":"set","auditable_id":"550e8400-e29b-41d4-a716-446655440000","agent_id":"agent-abc-123","data":{"step":"populate","status":"started"}}}}'

Example Response​

{
  "data": {
    "type": "audit_logs",
    "id": 12345,
    "attributes": {
      "event_type": "agent_spawned",
      "auditable_type": "set",
      "auditable_id": "string",
      "agent_id": "agent-abc-123",
      "data": {},
      "created_at": "string"
    }
  }
}

GET /internal/invites​

List signup invites (internal)

Lists issued invites with their label, pinned email, use counts, expiry and revocation state. Internal endpoint: requires the internal OAuth scope.

The plaintext code is NEVER returned here — it is surfaced exactly once at issuance and only its SHA-256 hash is stored.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/invites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

POST /internal/invites​

Issue a signup invite (internal)

Mints a new invite code and returns its plaintext EXACTLY ONCE — only the SHA-256 hash is persisted, so the code cannot be retrieved afterward. Internal endpoint: requires the internal OAuth scope.

All attributes are optional; an empty body issues a single-use, unpinned invite with the configured default TTL. Supply max_uses for a cohort code, email to pin the invite to one address, and expires_at: null for an invite that never expires.

The code attribute seeds a caller-supplied plaintext instead of minting one. It exists for the cutover from the marketing site's single shared code, so links already in a cohort's hands keep working when enforcement deploys.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"invites"
data.attributesobjectNoNo
data.attributes.labelstringNoYes
data.attributes.emailstring (email)NoYes
data.attributes.max_usesintegerNoNo1
data.attributes.expires_atstring (date-time)NoYes
data.attributes.codestringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/internal/invites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"invites","attributes":{"label":"string","email":"string","max_uses":1,"expires_at":"string","code":"string"}}}'

GET /internal/sets/{set}/todos​

List the workflow todos for a set (internal)

Returns the set's workflow todos ordered by sort_order. Returns an empty collection when the set exists but has no workflow initialized. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the parent set

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/sets/{set}/todos" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "set_todos",
      "id": "string",
      "attributes": {
        "step": "fetch",
        "status": "in_progress",
        "sort_order": 1,
        "started_at": "string",
        "completed_at": "string",
        "completed_by": "admin",
        "notes": "string",
        "created_at": "string",
        "updated_at": "string"
      }
    }
  ]
}

POST /internal/sets/{set}/todos​

Create a workflow todo for a set (internal)

Create a new workflow todo on the set's workflow. The todo is bound to the set's existing workflow; the set must already have one. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the parent set

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"set_todos"
data.attributesobjectNoNo
data.attributes.stepstringYesNo"fetch"
data.attributes.statusstringYesNo"pending"
data.attributes.sort_orderintegerNoYes
data.attributes.notesstringNoYes
data.attributes.completed_bystringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/internal/sets/{set}/todos" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"set_todos","attributes":{"step":"fetch","status":"pending"}}}'

Example Response​

{
  "data": {
    "type": "set_todos",
    "id": "string",
    "attributes": {
      "step": "fetch",
      "status": "in_progress",
      "sort_order": 1,
      "started_at": "string",
      "completed_at": "string",
      "completed_by": "admin",
      "notes": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  }
}

GET /internal/sets/{set}/todos/{todo}​

Get a single workflow todo for a set (internal)

Returns a single todo scoped to the parent set. A todo from a different set returns 404. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the parent set
todostringYesUUID of the set todo

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/sets/{set}/todos/{todo}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "set_todos",
    "id": "string",
    "attributes": {
      "step": "fetch",
      "status": "in_progress",
      "sort_order": 1,
      "started_at": "string",
      "completed_at": "string",
      "completed_by": "admin",
      "notes": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  }
}

DELETE /internal/sets/{set}/todos/{todo}​

Delete a workflow todo for a set (internal)

Delete a todo scoped to the parent set. A todo from a different set returns 404. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the parent set
todostringYesUUID of the set todo to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/internal/sets/{set}/todos/{todo}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /internal/sets/{set}/todos/{todo}​

Update a set todo step status (internal)

Transition a workflow step. Enrichment steps skip ordering; others need prior completion. The todo is scoped to the parent set; a todo from a different set returns 404. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the parent set
todostringYesUUID of the set todo to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"set_todos"
data.attributesobjectNoNo
data.attributes.statusstringYesNo"in_progress"
data.attributes.notesstringNoYes
data.attributes.completed_bystringNoYes
data.attributes.issues_foundbooleanNoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/internal/sets/{set}/todos/{todo}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"set_todos","attributes":{"status":"in_progress"}}}'

Example Response​

{
  "data": {
    "type": "set_todos",
    "id": "string",
    "attributes": {
      "step": "fetch",
      "status": "in_progress",
      "sort_order": 1,
      "started_at": "string",
      "completed_at": "string",
      "completed_by": "admin",
      "notes": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  }
}

GET /internal/sets/{set}/workflow​

Get the workflow state for a set (internal)

Returns the workflow record and its todos for the given set. Returns {"workflow": null} (200) when the set exists but has no workflow initialized. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesSet UUID

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/sets/{set}/workflow" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "workflow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "set_id": "661f9511-f30c-52e5-b827-557766551111",
    "priority": 1,
    "current_step": "fetch",
    "todos": [
      {
        "id": "772a0622-a41d-43f6-c938-668877662222",
        "step": "discover_sources",
        "status": "completed",
        "sort_order": 1,
        "started_at": "2024-03-15T09:00:00+00:00",
        "completed_at": "2024-03-15T09:15:00+00:00",
        "notes": null
      },
      {
        "id": "883b1733-b52e-44a7-d049-779988773333",
        "step": "fetch",
        "status": "in_progress",
        "sort_order": 2,
        "started_at": "2024-03-15T09:20:00+00:00",
        "completed_at": null,
        "notes": "Retrying after transient 502 from source."
      }
    ],
    "created_at": "2024-03-15T08:00:00+00:00",
    "updated_at": "2024-03-15T10:30:00+00:00"
  }
}

GET /internal/actionable-sets​

Get sets that are actionable for a given workflow step (internal)

Returns sets where the given step matches the requested status (default: pending). For pipeline steps with pending status, all prior steps must be completed or skipped. Enrichment steps bypass this requirement. Use status=review to find sets needing human intervention. Each row includes the current todo_id (for PATCH operations) and notes (the review reason when status=review). Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
stepstringYesWorkflow step (discover_sources, fetch, parse, populate, validate, cleanup, publish, audit)
statusstringNoFilter by todo status (default: pending). Use 'review' to find sets needing human intervention.
limitintegerNoMaximum number of results to return (1–100, default 25)
prioritystringNoPriority filter: 'current' (current year), 'backlog' (prior years), or 'all' (default)
genre_idstringNoFilter by genre UUID
yearstringNoFilter by year name (e.g. '2025', '2025-26')

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/actionable-sets" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "todo_id": "string",
      "set_id": "string",
      "set_name": "string",
      "genre": "string",
      "year": "string",
      "step": "string",
      "priority": 0,
      "card_count": 0,
      "has_sources": false,
      "notes": "string",
      "updated_at": "2025-01-15T13:45:30+00:00"
    }
  ],
  "meta": {
    "total": 0,
    "full_total": 0,
    "step": "string",
    "status": "string",
    "priority_filter": "string"
  }
}

GET /internal/actionable-sets/count​

Count sets that are actionable for a given workflow step (internal)

Returns the unpaginated count of sets that are actionable for the given step, using the exact same filters as GET /internal/actionable-sets (step, status, priority, genre_id, year) but without materializing the row page or the per-row card_count / has_sources subqueries. The returned count is consistent with that endpoint's full_total for identical filters. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
stepstringYesWorkflow step (discover_sources, fetch, parse, populate, validate, cleanup, publish, audit)
statusstringNoFilter by todo status (default: pending). Use 'review' to find sets needing human intervention.
prioritystringNoPriority filter: 'current' (current year), 'backlog' (prior years), or 'all' (default)
genre_idstringNoFilter by genre UUID
yearstringNoFilter by year name (e.g. '2025', '2025-26')
limitintegerNoAccepted for request-shape parity with GET /internal/actionable-sets but ignored: this endpoint returns an unpaginated count, so no row cap applies. Still validated (integer, 1-100) — an out-of-range value yields 422.

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/actionable-sets/count" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "count": 0,
  "meta": {
    "step": "string",
    "status": "string",
    "priority_filter": "string"
  }
}

POST /internal/todo-initialization-jobs​

Bulk-initialize workflow todos for pre-existing sets (internal)

Initializes workflow todos for sets that have no existing workflow. Sets with existing workflows or published status are counted as skipped. When more than 100 sets would be processed, the operation is dispatched as a background job. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
set_idsarray of stringNoNoSpecific set UUIDs to initialize. Mutually exclusive with all_draft.
all_draftbooleanNoNoInitialize all draft sets without existing workflows.
genre_idstring (uuid)NoNoFilter by genre (only valid with all_draft).
yearstringNoNoFilter by year name, e.g. '2025' (only valid with all_draft).

Example Request​

curl -X POST "https://api.tradingcardapi.com/internal/todo-initialization-jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"set_ids":["string"],"all_draft":false,"genre_id":"string","year":"string"}'

Example Response​

{
  "initialized": 0,
  "skipped": 0,
  "errors": [
    {}
  ],
  "job_id": "string",
  "resolved_count": 0,
  "meta": {
    "total_draft_sets": 0,
    "draft_with_workflow": 0,
    "draft_without_workflow": 0
  }
}

GET /internal/todo-initialization-jobs/{job_id}​

Poll the status of an async bulk-initialize job (internal)

Returns the current status of a background bulk-initialize job. The job_id is obtained from the 202 response of POST /internal/todo-initialization-jobs. Results are retained for 24 hours after job completion. Internal endpoint: requires the internal OAuth scope (#1557).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
job_idstringYesJob UUID returned by the async bulk-initialize request

Example Request​

curl -X GET "https://api.tradingcardapi.com/internal/todo-initialization-jobs/{job_id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "status": "completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "initialized": 42,
  "skipped": 3,
  "errors": [],
  "resolved_count": 45,
  "meta": null
}

Webhooks​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

POST /webhooks/stripe​

Stripe webhook receiver (infrastructure)

Receives Stripe webhook events. Unauthenticated — the Stripe-Signature header verified against the configured signing secret is the authentication. Returns 200 on accepted (including duplicate and unknown event types) and 400 on signature verification failure. Not a public API feature.

Authentication: Public — no API token required.

Example Request​

curl -X POST "https://api.tradingcardapi.com/webhooks/stripe" \
  -H "Accept: application/vnd.api+json"

Authentication​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/user/api-key​

Get the authenticated user's API key (masked)

Returns masked metadata for the authenticated end user's single opaque API key. Never returns the plaintext key. If no key exists yet, data is null.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/user/api-key" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

POST /v1/user/api-key​

Regenerate the authenticated user's API key

Revokes the user's existing API key (if any) and issues a new opaque tc_live_ key. Returns the plaintext key exactly once, alongside masked metadata. The previous key stops authenticating immediately.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/user/api-key" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

DELETE /v1/user/api-key​

Revoke the authenticated user's API key

Revokes the user's existing opaque tc_live_ key (if any) without minting a replacement. The key stops authenticating immediately. Idempotent: a no-op 204 when the user has no live key. To rotate the key instead, POST the same path.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/user/api-key" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

POST /v1/invites/validate​

Validate a signup invite code (v1)

Reports whether an invite code may currently be used to create an account. Public (no authentication) so the marketing site's signup page can check the link a visitor arrived on before rendering a form.

This endpoint CONSUMES NOTHING and reserves nothing: a valid verdict means the code is live and had a use left at the moment of the check, not that a use — or a founding slot — is held for the caller. Enforcement happens again at POST /v1/signup.

Rejections carry a distinguishable code: invite_invalid (unknown, revoked, or pinned to a different address), invite_expired (410, renewable), or invite_exhausted (every use spent). The code must be sent in the JSON body; a code in the query string is ignored, since a query string is recorded by proxies and travels onward in Referer. Throttled by throttle:invite-validate per IP and per code so the endpoint is not a brute-force oracle.

Authentication: Public — no API token required.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"invite-validations"
data.attributesobjectNoNo
data.attributes.codestringYesNo"FOUNDING-2026"

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/invites/validate" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"invite-validations","attributes":{"code":"FOUNDING-2026"}}}'

GET /v1/me​

Get the authenticated user (v1)

Returns the currently authenticated user as a JSON:API resource exposing name, email, company, and the plan / subscription status / trial end mirrored from the user's billing account (null when the user has no billing account).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "users",
    "id": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d",
    "attributes": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "plan": "pro_monthly",
      "subscription_status": "active",
      "trial_ends_at": "2026-07-15T00:00:00+00:00"
    }
  }
}

DELETE /v1/me​

Delete the authenticated user's account and associated data (v1)

Irreversibly deletes the authenticated user's own account (issue #1979). Requires an interactive first-party session (personal access tokens are rejected) and an explicit confirmation body { "data": { "confirm": true } }. Revokes the user's API keys and OAuth tokens, cancels the Stripe subscription, removes the Loops contact, then anonymizes the user's PII and soft-deletes the account. Billing/invoice financial records are retained (unlinked) per the documented retention policy.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectYesNo
data.confirmbooleanYesNotrue

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"confirm":true}}'

Example Response​

{
  "data": {
    "type": "users",
    "id": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d",
    "attributes": {
      "deleted": true
    }
  }
}

PATCH /v1/me​

Update the authenticated user's profile (v1)

Updates the authenticated user's own name and/or company from the portal Profile page. Authorized on the first-party interactive session (#1971): a long-lived data key (PAT / opaque tc_ key) is rejected. The body is a JSON:API resource document (data.type = users); both attributes are optional, so a partial update leaves the omitted attribute unchanged, and company may be nulled to clear it. Requires Content-Type: application/vnd.api+json (415 otherwise). There is no user id in the path — the caller can only ever update their own record.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"users"
data.attributesobjectNoNo
data.attributes.namestringNoNo"Jane Doe"
data.attributes.companystringNoYes"Acme Corp"

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"users","attributes":{"name":"Jane Doe","company":"Acme Corp"}}}'

Example Response​

{
  "data": {
    "type": "users",
    "id": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d",
    "attributes": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "plan": "pro_monthly",
      "subscription_status": "active",
      "trial_ends_at": "2026-07-15T00:00:00+00:00"
    }
  }
}

PATCH /v1/user/password​

Change the authenticated user's password

Verifies the caller's current password, validates and rehashes the new one, and persists it. On success the user's OTHER OAuth access/refresh tokens are revoked (other login sessions and Passport personal-access tokens stop authenticating; opaque tc_ data keys live in a separate store and are NOT revoked by this sweep) while the current session stays alive. Requires an interactive first-party session; long-lived data keys are rejected.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"user-passwords"
data.attributesobjectNoNo
data.attributes.current_passwordstring (password)YesNo"current-secret"
data.attributes.new_passwordstring (password)YesNo"new-secret-123"
data.attributes.new_password_confirmationstring (password)YesNo"new-secret-123"

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/user/password" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"user-passwords","attributes":{"current_password":"current-secret","new_password":"new-secret-123","new_password_confirmation":"new-secret-123"}}}'

POST /v1/signup​

Self-service signup (v1)

Creates an unverified user and dispatches a verification email. Public (no authentication). Gated on remaining founding-pool capacity; when the pool is full a waitlist response is returned. The success response is identical whether or not the email already exists (non-enumerating).

Requires a valid invite code (data.attributes.invite_code, issue #2282). A missing code is a 422 validation error; a code that is unknown, revoked, expired, or fully used is rejected with invite_invalid, invite_expired (410) or invite_exhausted. Holding an invite is permission to create an account — it does NOT reserve a founding slot, which is still claimed first-come-first-served at POST /v1/signup/verify. Use POST /v1/invites/validate to check a code without attempting a signup.

A re-submit never changes an existing account's password. When the address already belongs to an account, the submitted password is discarded and the account keeps whatever credential it currently has. For an account that is still unverified the verification email is re-sent, so re-submitting is a valid way to recover a lost link — but the password sent with it does not take effect, and the account's existing password is unaffected. Overwriting it is deliberately not supported: this endpoint is unauthenticated and cannot prove the re-submitter started the signup, so allowing it would let an attacker plant a credential that the victim's own verification click activates. Prefer POST /v1/signup/resend, which recovers an expired link from the token alone and never asks for a password. Because the 202 body is byte-identical on every branch, its meta.message states this conditionally rather than only when it applies.

Authentication: Public — no API token required.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"signups"
data.attributesobjectNoNo
data.attributes.emailstring (email)YesNo"[email protected]"
data.attributes.passwordstring (password)YesNo"correct horse battery"
data.attributes.invite_codestringYesNo"FOUNDING-2026"

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/signup" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"signups","attributes":{"email":"[email protected]","password":"correct horse battery","invite_code":"FOUNDING-2026"}}}'

POST /v1/signup/verify​

Verify signup email, start trial, issue API key (v1)

Redeems the emailed verification token: marks the email verified, atomically claims a founding slot, starts a 14-day app-managed trial, issues the single opaque tc_live_ API key (returned once), and sends the welcome email. Public (no authentication) — the token in the JSON:API body is the sole authorization. When the founding pool has filled since signup a waitlist response is returned and no trial is started.

Authentication: Public — no API token required.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"email-verifications"
data.attributesobjectNoNo
data.attributes.tokenstringYesNo"kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f"

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/signup/verify" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"email-verifications","attributes":{"token":"kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f"}}}'

POST /v1/signup/resend​

Resend the signup verification email from an expired token (v1)

Mints a fresh verification token for the account the supplied token belongs to and re-sends the verification email. Public (no authentication) — the token in the JSON:API body is the sole authorization, which is what lets the marketing site's /verify?token=… page offer a one-click resend when POST /v1/signup/verify has answered 410 token_expired. An expired token is accepted here; that is the whole point of the endpoint.

Token rotation, not extension: a successful resend replaces the stored token and its expiry, so the previous link stops working immediately and the new one carries a full 24-hour window. Because rotation is immediate, a spent token keeps replaying its 202 for 60 seconds — a double-submitted or retried request is idempotent and sends no second email, rather than reporting the link it just replaced as unknown.

The 202 response is identical whether or not the account is already verified (non-enumerating); the email is only dispatched when it is not. A token that resolves to no account — never issued, already rotated, or burned by a completed verification — is answered with 422 token_unknown, which is safe to distinguish because the token is a 64-character random secret rather than a guessable identifier. The token must be sent in the JSON body; a token in the query string is ignored, since a query string is recorded by proxies and travels onward in Referer. Unlike signup and verify, this endpoint is NOT gated on founding-pool capacity: capacity is enforced when the link is redeemed, and a waitlist response here would be indistinguishable from a sent email.

Authentication: Public — no API token required.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"verification-resends"
data.attributesobjectNoNo
data.attributes.tokenstringYesNo"kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f"

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/signup/resend" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"verification-resends","attributes":{"token":"kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f"}}}'

GET /v1/user/subscription​

Get the authenticated user's subscription/plan and trial state

Returns the authenticated end user's plan, subscription status, trial state, and period/cancellation flags as a JSON:API resource. Read-only; never mutates billing state. A user with no billing account gets a graceful "no plan" resource (200), not a 500.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/user/subscription" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

GET /v1/user/usage​

Get the authenticated caller's current rate-limit window

Returns the live rate-limit window (limit, remaining, resets_at) for the authenticated user's tc_live_ API key, as a JSON:API resource. The window is the API key's own bucket in the same named api rate limiter the throttle middleware enforces — deliberately NOT the bucket of the token making this request, since the portal proxies its screens with an interactive session token whose browsing would otherwise be reported as API usage (issue #2304). A user with no API key is reported as a full, untouched window at their default tier. Read-only. The portal dashboard derives requests-used as limit - remaining.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/user/usage" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/user/email​

Initiate a change of the authenticated user's login email

Validates a new login-email address (well-formed, unused, and different from the current login), stores it as a pending change, and emails a confirmation link to the NEW address. The login email is NOT changed until the confirmation link is redeemed via POST /v1/user/email/confirm. Authorized on an interactive first-party session (#1971); personal-access / opaque data keys are rejected.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"user-emails"
data.attributesobjectNoNo
data.attributes.emailstring (email)YesNo"[email protected]"

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/user/email" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"user-emails","attributes":{"email":"[email protected]"}}}'

POST /v1/user/email/confirm​

Confirm a pending login-email change

Redeems the confirmation token emailed to the new address, promotes the pending address to the login email, and marks it verified. The previous address stops authenticating. Followed from an emailed link, so it authenticates on the opaque token alone (no session, no bearer). Rejects a missing, unknown, or expired token.

Authentication: Public — no API token required.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"user-email-confirmations"
data.attributesobjectNoNo
data.attributes.tokenstringYesNo

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/user/email/confirm" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"user-email-confirmations","attributes":{"token":"string"}}}'

Attributes v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/attributes​

Get all card attributes (v1)

Retrieve a paginated list of all card attributes (autographs, variations, etc.)

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
namestringNoFilter by attribute name
limitintegerNoNumber of attributes per page
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/attributes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "attributes",
      "id": "string",
      "attributes": {
        "attribute": "Autograph",
        "name": "Autograph",
        "description": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/attributes​

Create a new attribute (v1)

Create a new card attribute (autograph, variation, etc.)

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"attributes"
data.attributesobjectNoNo
data.attributes.attributestringYesNo"AU"
data.attributes.namestringYesNo"Autograph"
data.attributes.descriptionstringNoYes"Player's signature on card"
data.attributes.colorstringNoYes"#FF0000"

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/attributes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"attributes","attributes":{"attribute":"AU","name":"Autograph","description":"Player'\''s signature on card","color":"#FF0000"}}}'

Example Response​

{
  "data": {
    "type": "attributes",
    "id": "string",
    "attributes": {
      "attribute": "Autograph",
      "name": "Autograph",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/attributes/{id}​

Get a specific attribute (v1)

Retrieve detailed information about a specific card attribute by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the attribute to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "attributes",
    "id": "string",
    "attributes": {
      "attribute": "Autograph",
      "name": "Autograph",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/attributes/{id}​

Delete an attribute (v1)

Delete an existing card attribute

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the attribute to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/attributes/{id}​

Update an attribute (v1)

Update an existing card attribute

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the attribute to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"attributes"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.attributestringNoNo"AU"
data.attributes.namestringNoNo"Autograph"
data.attributes.descriptionstringNoYes"Player's signature on card"
data.attributes.colorstringNoYes"#FF0000"

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"attributes","id":"string","attributes":{"attribute":"AU","name":"Autograph","description":"Player'\''s signature on card","color":"#FF0000"}}}'

Example Response​

{
  "data": {
    "type": "attributes",
    "id": "string",
    "attributes": {
      "attribute": "Autograph",
      "name": "Autograph",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Billing​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

POST /v1/billing/checkout​

Create a Stripe Checkout Session for self-service subscribe (v1)

Creates a subscription-mode Stripe Checkout Session for the authenticated caller's billing account (lazily creating the account and Stripe customer on first use) and returns the hosted session URL. The plan selects the Stripe price; optional success_url/cancel_url must match the configured trusted-origin allowlist.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
planstringYesNo"starter"The plan slug to subscribe to. Must be one of the plans configured for the API (at launch: starter or pro).
success_urlstring (uri)NoNo"https://app.tradingcardapi.com/account/billing?checkout=success"Optional. Where Stripe returns the user after a completed checkout. Its origin must be in the configured trusted-origin allowlist.
cancel_urlstring (uri)NoNo"https://app.tradingcardapi.com/account/billing?checkout=cancel"Optional. Where Stripe returns the user if they abandon checkout. Its origin must be in the configured trusted-origin allowlist.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/billing/checkout" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"plan":"starter","success_url":"https://app.tradingcardapi.com/account/billing?checkout=success","cancel_url":"https://app.tradingcardapi.com/account/billing?checkout=cancel"}'

Example Response​

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_abc123"
}

POST /v1/billing/portal​

Create a Stripe Customer Portal session (v1)

Creates a Stripe Billing Portal session for the authenticated caller's billing account (lazily creating the account and Stripe customer on first use) and returns the hosted session URL. An optional return_url must match the configured trusted-origin allowlist.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
return_urlstring (uri)NoNo"https://app.tradingcardapi.com/account/billing"Optional. Where Stripe returns the user after the portal session. Its origin must be in the configured trusted-origin allowlist.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/billing/portal" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"return_url":"https://app.tradingcardapi.com/account/billing"}'

Example Response​

{
  "url": "https://billing.stripe.com/session/test_abc123"
}

GET /v1/founding-slots/remaining​

Get the remaining founding-customer slots

Returns the number of founding-customer slots still available as a single derived count (capacity minus the billing accounts currently trialing or active). Public and unauthenticated — it exposes only the aggregate remaining count for the marketing-site indicator, no per-user state. Throttled by the default anonymous rate limit.

Authentication: Public — no API token required.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/founding-slots/remaining" \
  -H "Accept: application/vnd.api+json"

Brands v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/brands​

Get all brands (v1)

Retrieve a list of all trading card brands

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/brands" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "brands",
      "id": "string",
      "attributes": {
        "name": "Topps",
        "description": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ]
}

POST /v1/brands​

Create a new brand (v1)

Create a new trading card brand

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"brands"
data.attributesobjectNoNo
data.attributes.namestringYesNo"Topps"
data.attributes.descriptionstringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/brands" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"brands","attributes":{"name":"Topps","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "brands",
    "id": "string",
    "attributes": {
      "name": "Topps",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/brands/{id}​

Get a specific brand (v1)

Retrieve detailed information about a specific brand by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the brand to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/brands/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "brands",
    "id": "string",
    "attributes": {
      "name": "Topps",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

DELETE /v1/brands/{id}​

Delete a brand (v1)

Delete an existing brand

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the brand to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/brands/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/brands/{id}​

Update a brand (v1)

Update an existing brand

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the brand to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"brands"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.namestringNoNo"Topps"
data.attributes.descriptionstringNoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/brands/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"brands","id":"string","attributes":{"name":"Topps","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "brands",
    "id": "string",
    "attributes": {
      "name": "Topps",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Cards v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/cards​

Get all cards (v1)

Retrieve a paginated list of all trading cards in the system

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
filter[set_id]stringNoFilter cards by set UUID
filter[player_id]stringNoFilter cards by player UUID. Returns every card the player appears on, both directly and via a player-team.
includestringNoComma-separated list of relationships to include (set,oncard,attributes,children)
pageintegerNoPage number for pagination
per_pageintegerNoNumber of items per page (max 100, default 25)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/cards" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "cards",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "attributes": {
        "name": "Michael Jordan",
        "number": "23",
        "serial_number": "001/100",
        "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Rookie Card",
        "notes": "string",
        "has_player": true,
        "has_team": true,
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      },
      "relationships": {
        "set": {
          "data": {
            "type": "sets",
            "id": "string"
          }
        },
        "oncard": {
          "data": [
            {
              "type": "string",
              "id": "string"
            }
          ]
        },
        "attributes": {
          "data": [
            {
              "type": "attributes",
              "id": "string"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "card_images",
              "id": "string"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/cards​

Create a new card (v1)

Create a new trading card record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"cards"
data.attributesobjectNoNo
data.attributes.numberstringNoNo"23"Card number within the set
data.attributes.serial_numberstringNoYes"001/100"
data.attributes.image_uuidstring (uuid)NoYes"550e8400-e29b-41d4-a716-446655440000"UUID reference for card image
data.attributes.titlestringNoYes"Rookie Card"
data.attributes.notesstringNoYes
data.relationshipsobjectNoNo
data.relationships.setobjectNoNo
data.relationships.set.dataobjectNoNo
data.relationships.set.data.typestringNoNo"sets"
data.relationships.set.data.idstring (uuid)NoNo
data.relationships.oncardobjectNoNo
data.relationships.oncard.dataarray of objectNoNo
data.relationships.oncard.data[].typestringNoNo
data.relationships.oncard.data[].idstring (uuid)NoNo

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/cards" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"cards","attributes":{"number":"23","serial_number":"001/100","image_uuid":"550e8400-e29b-41d4-a716-446655440000","title":"Rookie Card","notes":"string"},"relationships":{"set":{"data":{"type":"sets","id":"string"}},"oncard":{"data":[{"type":"string","id":"string"}]}}}}'

Example Response​

{
  "data": {
    "type": "cards",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "name": "Michael Jordan",
      "number": "23",
      "serial_number": "001/100",
      "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Rookie Card",
      "notes": "string",
      "has_player": true,
      "has_team": true,
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "set": {
        "data": {
          "type": "sets",
          "id": "string"
        }
      },
      "oncard": {
        "data": [
          {
            "type": "string",
            "id": "string"
          }
        ]
      },
      "attributes": {
        "data": [
          {
            "type": "attributes",
            "id": "string"
          }
        ]
      },
      "images": {
        "data": [
          {
            "type": "card_images",
            "id": "string"
          }
        ]
      }
    }
  }
}

GET /v1/cards/{id}​

Get a specific card (v1)

Retrieve detailed information about a specific trading card by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the card to retrieve
includestringNoComma-separated list of relationships to include (set,oncard,attributes,children)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/cards/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "cards",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "name": "Michael Jordan",
      "number": "23",
      "serial_number": "001/100",
      "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Rookie Card",
      "notes": "string",
      "has_player": true,
      "has_team": true,
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "set": {
        "data": {
          "type": "sets",
          "id": "string"
        }
      },
      "oncard": {
        "data": [
          {
            "type": "string",
            "id": "string"
          }
        ]
      },
      "attributes": {
        "data": [
          {
            "type": "attributes",
            "id": "string"
          }
        ]
      },
      "images": {
        "data": [
          {
            "type": "card_images",
            "id": "string"
          }
        ]
      }
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/cards/{id}​

Delete a card (v1)

Delete an existing trading card record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the card to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/cards/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/cards/{id}​

Update a card (v1)

Update an existing trading card record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the card to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"cards"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.numberstringNoNo"23"
data.attributes.serial_numberstringNoYes"001/100"
data.attributes.image_uuidstring (uuid)NoYes"550e8400-e29b-41d4-a716-446655440000"UUID reference for card image
data.attributes.titlestringNoYes"Rookie Card"
data.attributes.notesstringNoYes
data.attributes.attributesarray of objectNoNoExtra attributes for the card
data.attributes.attributes[].idstring (uuid)NoNo
data.attributes.attributes[].valuestringNoNo
data.attributes.field_overridesarray of stringNoYesFields not inherited from parent (parallel cards only)
data.relationshipsobjectNoNo
data.relationships.setobjectNoNo
data.relationships.set.dataobjectNoNo
data.relationships.set.data.typestringNoNo"sets"
data.relationships.set.data.idstring (uuid)NoNo
data.relationships.oncardobjectNoNo
data.relationships.oncard.dataarray of objectNoNo
data.relationships.oncard.data[].typestringNoNo
data.relationships.oncard.data[].idstring (uuid)NoNo

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/cards/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"cards","id":"string","attributes":{"number":"23","serial_number":"001/100","image_uuid":"550e8400-e29b-41d4-a716-446655440000","title":"Rookie Card","notes":"string","attributes":[{"id":"string","value":"string"}],"field_overrides":["string"]},"relationships":{"set":{"data":{"type":"sets","id":"string"}},"oncard":{"data":[{"type":"string","id":"string"}]}}}}'

Example Response​

{
  "data": {
    "type": "cards",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "name": "Michael Jordan",
      "number": "23",
      "serial_number": "001/100",
      "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Rookie Card",
      "notes": "string",
      "has_player": true,
      "has_team": true,
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "set": {
        "data": {
          "type": "sets",
          "id": "string"
        }
      },
      "oncard": {
        "data": [
          {
            "type": "string",
            "id": "string"
          }
        ]
      },
      "attributes": {
        "data": [
          {
            "type": "attributes",
            "id": "string"
          }
        ]
      },
      "images": {
        "data": [
          {
            "type": "card_images",
            "id": "string"
          }
        ]
      }
    }
  }
}

Card Images​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/card-images​

List all card images

List all card images

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
includestringNoInclude related resources (card)
pageintegerNoPage number for pagination
per_pageintegerNoNumber of items per page (default 50, max 100)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/card-images" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

POST /v1/card-images​

Upload a new card image

Upload a new card image

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: multipart/form-data

FieldTypeRequiredNullableExampleDescription
filestring (binary)YesNoImage file (JPEG, PNG, or WebP, max 10MB, max 4000x4000px)
datastring (json)YesNo"{\"type\":\"card_images\",\"attributes\":{\"card_id\":\"uuid\",\"image_type\":\"front\"}}"JSON:API formatted data

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/card-images" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -F 'file=@/path/to/file' \
  -F 'data={"type":"card_images","attributes":{"card_id":"uuid","image_type":"front"}}'

GET /v1/card-images/{id}​

Get a specific card image

Get a specific card image

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesCard image UUID
includestringNoInclude related resources (card)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/card-images/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

DELETE /v1/card-images/{id}​

Delete a card image

Delete a card image

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesCard image UUID

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/card-images/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/card-images/{id}​

Update a card image

Update a card image

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesCard image UUID

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/card-images/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

GET /v1/card-images/{card_image}/download​

Download the actual image file

Download/stream the actual image file

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
card_imagestringYesCard image UUID
sizestringNoImage size variant. Sizes configured in config/images.php (default: small/medium/large)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/card-images/{card_image}/download" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: image/*"

POST /v1/card-image-batches​

Upload multiple card images in a batch

Accepts up to 50 images per request. Returns immediately with a batch ID for polling status. The legacy POST /v1/card-images/bulk URL is a deprecated alias for this endpoint (slated for removal in v2).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: multipart/form-data

FieldTypeRequiredNullableExampleDescription
files[]array of stringNoNoImage files (max 50, each max 10MB, JPEG/PNG/WebP)
datastring (json)YesNo"{\"type\":\"bulk_card_images\",\"attributes\":{\"mappings\":[...]}}"JSON:API formatted data with mappings

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/card-image-batches" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -F 'files[]=@/path/to/file' \
  -F 'data={"type":"bulk_card_images","attributes":{"mappings":[...]}}'

GET /v1/card-image-batches/{card_image_batch}​

Get bulk upload batch status

Returns bulk upload batch status and progress. Poll to track progress. The legacy GET /v1/card-images/bulk/{batch_id} URL is a deprecated alias for this endpoint (slated for removal in v2).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
card_image_batchstringYesBatch UUID

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/card-image-batches/{card_image_batch}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Genres v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/genres​

Get all genres (v1)

Retrieve a paginated list of all trading card genres

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
limitintegerNoNumber of genres per page
namestringNoFilter by genre name
includestringNoComma-separated list of relationships to include
filter[status]stringNoFilter genres by soft-delete state. Use 'deleted' to list only soft-deleted genres or 'active' for live genres (the default).

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/genres" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "genres",
      "id": "string",
      "attributes": {
        "name": "Baseball",
        "description": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ]
}

POST /v1/genres​

Create a new genre (v1)

Create a new trading card genre, restoring if previously soft-deleted

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"genres"
data.attributesobjectNoNo
data.attributes.namestringYesNo"Baseball"
data.attributes.descriptionstringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/genres" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"genres","attributes":{"name":"Baseball","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "genres",
    "id": "string",
    "attributes": {
      "name": "Baseball",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/genres/{id}​

Get a specific genre (v1)

Retrieve detailed information about a specific genre by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the genre to retrieve
includestringNoComma-separated list of relationships to include
include_trashedbooleanNoWhen true, a soft-deleted genre is returnable by id. Defaults to false (soft-deleted genres 404).

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/genres/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "genres",
    "id": "string",
    "attributes": {
      "name": "Baseball",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

DELETE /v1/genres/{id}​

Delete a genre (v1)

Soft delete an existing genre record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the genre to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/genres/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/genres/{id}​

Update a genre (v1)

Update an existing genre record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the genre to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"genres"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.namestringNoNo"Baseball"
data.attributes.descriptionstringNoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/genres/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"genres","id":"string","attributes":{"name":"Baseball","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "genres",
    "id": "string",
    "attributes": {
      "name": "Baseball",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Manufacturers v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/manufacturers​

Get all manufacturers (v1)

Retrieve a list of all trading card manufacturers

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/manufacturers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "manufacturers",
      "id": "string",
      "attributes": {
        "name": "Topps Company",
        "description": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ]
}

POST /v1/manufacturers​

Create a new manufacturer (v1)

Create a new trading card manufacturer

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"manufacturers"
data.attributesobjectNoNo
data.attributes.namestringYesNo"Topps Company"
data.attributes.descriptionstringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/manufacturers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"manufacturers","attributes":{"name":"Topps Company","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "manufacturers",
    "id": "string",
    "attributes": {
      "name": "Topps Company",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/manufacturers/{id}​

Get a specific manufacturer (v1)

Retrieve detailed information about a specific manufacturer by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the manufacturer to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/manufacturers/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "manufacturers",
    "id": "string",
    "attributes": {
      "name": "Topps Company",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

DELETE /v1/manufacturers/{id}​

Delete a manufacturer (v1)

Delete an existing manufacturer

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the manufacturer to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/manufacturers/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/manufacturers/{id}​

Update a manufacturer (v1)

Update an existing manufacturer

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the manufacturer to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"manufacturers"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.namestringNoNo"Topps Company"
data.attributes.descriptionstringNoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/manufacturers/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"manufacturers","id":"string","attributes":{"name":"Topps Company","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "manufacturers",
    "id": "string",
    "attributes": {
      "name": "Topps Company",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

ObjectAttributes v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/object-attributes​

Get all object attributes (v1)

Retrieve a paginated list of all object attributes (card-specific attribute instances)

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
limitintegerNoNumber of object attributes per page
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/object-attributes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "object-attributes",
      "id": "string",
      "attributes": {
        "attribute_id": "string",
        "attribute_value": "Authenticated",
        "object_type": "App\\Models\\Card",
        "object_id": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/object-attributes​

Create a new object attribute (v1)

Create a new object attribute instance linking an attribute to a specific object (card)

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"object-attributes"
data.attributesobjectNoNo
data.attributes.attribute_idstring (uuid)YesNoID of the attribute definition
data.attributes.attribute_valuestringYesNo"Authenticated"Value of the attribute for this object
data.attributes.object_typestringYesNo"App\\Models\\Card"Type of object this attribute is attached to
data.attributes.object_idstring (uuid)YesNoID of the object this attribute is attached to

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/object-attributes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"object-attributes","attributes":{"attribute_id":"string","attribute_value":"Authenticated","object_type":"App\\Models\\Card","object_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "object-attributes",
    "id": "string",
    "attributes": {
      "attribute_id": "string",
      "attribute_value": "Authenticated",
      "object_type": "App\\Models\\Card",
      "object_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/object-attributes/{id}​

Get a specific object attribute (v1)

Retrieve detailed information about a specific object attribute by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the object attribute to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/object-attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "object-attributes",
    "id": "string",
    "attributes": {
      "attribute_id": "string",
      "attribute_value": "Authenticated",
      "object_type": "App\\Models\\Card",
      "object_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/object-attributes/{id}​

Delete an object attribute (v1)

Delete an existing object attribute instance

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the object attribute to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/object-attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/object-attributes/{id}​

Update an object attribute (v1)

Update an existing object attribute instance

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the object attribute to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"object-attributes"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.attribute_idstring (uuid)NoNo
data.attributes.attribute_valuestringNoNo"Authenticated"
data.attributes.object_typestringNoNo"App\\Models\\Card"
data.attributes.object_idstring (uuid)NoNo

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/object-attributes/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"object-attributes","id":"string","attributes":{"attribute_id":"string","attribute_value":"Authenticated","object_type":"App\\Models\\Card","object_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "object-attributes",
    "id": "string",
    "attributes": {
      "attribute_id": "string",
      "attribute_value": "Authenticated",
      "object_type": "App\\Models\\Card",
      "object_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Players v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/players​

Get all players (v1)

Retrieve a paginated list of all players with optional filtering

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
first_namestringNoFilter by player first name
last_namestringNoFilter by player last name
full_namestringNoFilter by full name (searches both first and last name)
limitintegerNoNumber of players per page (max 100, default 25)
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/players" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "players",
      "id": "string",
      "attributes": {
        "name": "Michael Jordan",
        "first_name": "Michael",
        "last_name": "Jordan",
        "position": "Shooting Guard",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/players​

Create a new player (v1)

Create a new player record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"players"
data.attributesobjectNoNo
data.attributes.first_namestringNoNo"Michael"
data.attributes.last_namestringNoNo"Jordan"
data.attributes.positionstringNoYes"Shooting Guard"
data.attributes.full_namestringNoNo"Michael Jordan"Alternative to first_name/last_name

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/players" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"players","attributes":{"first_name":"Michael","last_name":"Jordan","position":"Shooting Guard","full_name":"Michael Jordan"}}}'

Example Response​

{
  "data": {
    "type": "players",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan",
      "first_name": "Michael",
      "last_name": "Jordan",
      "position": "Shooting Guard",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/players/{id}​

Get a specific player (v1)

Retrieve detailed information about a specific player by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/players/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "players",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan",
      "first_name": "Michael",
      "last_name": "Jordan",
      "position": "Shooting Guard",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/players/{id}​

Delete a player (v1)

Delete an existing player record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/players/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/players/{id}​

Update a player (v1)

Update an existing player record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"players"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.first_namestringNoNo"Michael"
data.attributes.last_namestringNoNo"Jordan"
data.attributes.positionstringNoYes"Shooting Guard"

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/players/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"players","id":"string","attributes":{"first_name":"Michael","last_name":"Jordan","position":"Shooting Guard"}}}'

Example Response​

{
  "data": {
    "type": "players",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan",
      "first_name": "Michael",
      "last_name": "Jordan",
      "position": "Shooting Guard",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

PlayerTeams v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/player-teams​

Get all player-team associations (v1)

Retrieve a paginated list of player-team associations with optional filtering

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
team_idstringNoFilter by team ID
player_idstringNoFilter by player ID
limitintegerNoNumber of player-teams per page
includestringNoComma-separated list of relationships to include (player,team)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/player-teams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "playerteams",
      "id": "string",
      "attributes": {
        "name": "Michael Jordan - Chicago Bulls",
        "player_id": "string",
        "team_id": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/player-teams​

Create a new player-team association (v1)

Create a new player-team association record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"playerteams"
data.attributesobjectNoNo
data.attributes.player_idstring (uuid)YesNoID of the player
data.attributes.team_idstring (uuid)YesNoID of the team

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/player-teams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"playerteams","attributes":{"player_id":"string","team_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "playerteams",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan - Chicago Bulls",
      "player_id": "string",
      "team_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/player-teams/{id}​

Get a specific player-team association (v1)

Retrieve detailed information about a specific player-team association by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player-team association to retrieve
includestringNoComma-separated list of relationships to include (player,team)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/player-teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "playerteams",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan - Chicago Bulls",
      "player_id": "string",
      "team_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/player-teams/{id}​

Delete a player-team association (v1)

Delete an existing player-team association record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player-team association to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/player-teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/player-teams/{id}​

Update a player-team association (v1)

Update an existing player-team association record (PATCH only; PUT is not supported and returns 405 Method Not Allowed).

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the player-team association to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"playerteams"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.player_idstring (uuid)NoNoID of the player
data.attributes.team_idstring (uuid)NoNoID of the team

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/player-teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"playerteams","id":"string","attributes":{"player_id":"string","team_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "playerteams",
    "id": "string",
    "attributes": {
      "name": "Michael Jordan - Chicago Bulls",
      "player_id": "string",
      "team_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Sets v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/sets​

Get all card sets (v1)

Retrieve a paginated list of all trading card sets

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
includestringNoComma-separated list of relationships to include
per_pageintegerNoNumber of sets per page (max 100, default 25)
limitintegerNoNumber of sets per page (deprecated, use per_page instead)
order_bystringNoField to order by
sortstringNoSort direction
namestringNoFilter by set name
genrestringNoFilter by genre ID
yearstringNoFilter by year ID
parent_idstringNoFilter by parent set ID (returns child sets/parallels of the specified parent)
filter[status]stringNoFilter by status (requires X-TCAPI-Ignore-Status header to see draft sets)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/sets" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "sets",
      "id": "string",
      "attributes": {
        "name": "1989 Topps Baseball",
        "title": "Series 1",
        "description": "string",
        "card_count": 792,
        "current_card_count": 792,
        "is_parallel": false,
        "is_insert": false,
        "is_autograph": false,
        "is_relic": false,
        "is_variation": false,
        "serial": 250,
        "number_prefix": "string",
        "parent_set": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      },
      "relationships": {
        "sources": {
          "data": [
            {
              "type": "set_sources",
              "id": "string"
            }
          ]
        },
        "genre": {
          "data": {
            "type": "genres",
            "id": "string"
          }
        },
        "manufacturer": {
          "data": {
            "type": "manufacturers",
            "id": "string"
          }
        },
        "brand": {
          "data": {
            "type": "brands",
            "id": "string"
          }
        },
        "year": {
          "data": {
            "type": "years",
            "id": "string"
          }
        }
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/sets​

Create a new set (v1)

Create a new trading card set

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"sets"
data.attributesobjectNoNo
data.attributes.namestringYesNo"1989 Topps Baseball"
data.attributes.descriptionstringNoYes
data.attributes.total_cardsintegerNoYes792
data.attributes.genre_idstring (uuid)NoYes
data.attributes.manufacturer_idstring (uuid)NoYes
data.attributes.brand_idstring (uuid)NoYes
data.attributes.year_idstring (uuid)NoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/sets" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"sets","attributes":{"name":"1989 Topps Baseball","description":"string","total_cards":792,"genre_id":"string","manufacturer_id":"string","brand_id":"string","year_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "sets",
    "id": "string",
    "attributes": {
      "name": "1989 Topps Baseball",
      "title": "Series 1",
      "description": "string",
      "card_count": 792,
      "current_card_count": 792,
      "is_parallel": false,
      "is_insert": false,
      "is_autograph": false,
      "is_relic": false,
      "is_variation": false,
      "serial": 250,
      "number_prefix": "string",
      "parent_set": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "sources": {
        "data": [
          {
            "type": "set_sources",
            "id": "string"
          }
        ]
      },
      "genre": {
        "data": {
          "type": "genres",
          "id": "string"
        }
      },
      "manufacturer": {
        "data": {
          "type": "manufacturers",
          "id": "string"
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": "string"
        }
      },
      "year": {
        "data": {
          "type": "years",
          "id": "string"
        }
      }
    }
  }
}

GET /v1/sets/{id}​

Get a specific set (v1)

Retrieve detailed information about a specific trading card set by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/sets/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "sets",
    "id": "string",
    "attributes": {
      "name": "1989 Topps Baseball",
      "title": "Series 1",
      "description": "string",
      "card_count": 792,
      "current_card_count": 792,
      "is_parallel": false,
      "is_insert": false,
      "is_autograph": false,
      "is_relic": false,
      "is_variation": false,
      "serial": 250,
      "number_prefix": "string",
      "parent_set": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "sources": {
        "data": [
          {
            "type": "set_sources",
            "id": "string"
          }
        ]
      },
      "genre": {
        "data": {
          "type": "genres",
          "id": "string"
        }
      },
      "manufacturer": {
        "data": {
          "type": "manufacturers",
          "id": "string"
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": "string"
        }
      },
      "year": {
        "data": {
          "type": "years",
          "id": "string"
        }
      }
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/sets/{id}​

Delete a set (v1)

Delete an existing trading card set. By default the deletion is refused with a 409 when the set is still published or still has child records (cards, set sources, subsets); the response names the specific blocker(s). Pass force=true to cascade-delete those children and remove the set in a single call.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set to delete
forcebooleanNoWhen true, cascade-delete remaining children (cards, set sources, subsets) and remove the set even if it is published. When false or omitted, a published set or a set with remaining children is refused with a structured 409.
confirmbooleanNoReserved confirmation flag accepted for forward compatibility with the documented delete contract; parsed as a boolean and currently advisory.

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/sets/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/sets/{id}​

Update a set (v1)

Update an existing trading card set

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"sets"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.namestringNoNo"1989 Topps Baseball"
data.attributes.descriptionstringNoYes
data.attributes.total_cardsintegerNoYes792
data.attributes.genre_idstring (uuid)NoYes
data.attributes.manufacturer_idstring (uuid)NoYes
data.attributes.brand_idstring (uuid)NoYes
data.attributes.year_idstring (uuid)NoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/sets/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"sets","id":"string","attributes":{"name":"1989 Topps Baseball","description":"string","total_cards":792,"genre_id":"string","manufacturer_id":"string","brand_id":"string","year_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "sets",
    "id": "string",
    "attributes": {
      "name": "1989 Topps Baseball",
      "title": "Series 1",
      "description": "string",
      "card_count": 792,
      "current_card_count": 792,
      "is_parallel": false,
      "is_insert": false,
      "is_autograph": false,
      "is_relic": false,
      "is_variation": false,
      "serial": 250,
      "number_prefix": "string",
      "parent_set": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "sources": {
        "data": [
          {
            "type": "set_sources",
            "id": "string"
          }
        ]
      },
      "genre": {
        "data": {
          "type": "genres",
          "id": "string"
        }
      },
      "manufacturer": {
        "data": {
          "type": "manufacturers",
          "id": "string"
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": "string"
        }
      },
      "year": {
        "data": {
          "type": "years",
          "id": "string"
        }
      }
    }
  }
}

GET /v1/sets/{set}/checklist​

Get set checklist (v1)

Retrieve the complete checklist for a trading card set including all cards. Supports compact format for large sets to avoid response size limits. Compact format returns only id, number, and name fields, reducing response size by ~75%.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the set to get checklist for
formatstringNoResponse format: 'full' returns all card fields, 'compact' returns only id, number, and name
pageintegerNoPage number for pagination (starts at 1)
per_pageintegerNoNumber of cards per page (max 100, returns all if not specified)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/sets/{set}/checklist" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "sets",
    "id": "string",
    "attributes": {
      "name": "1989 Topps Baseball",
      "title": "Series 1",
      "description": "string",
      "card_count": 792,
      "current_card_count": 792,
      "is_parallel": false,
      "is_insert": false,
      "is_autograph": false,
      "is_relic": false,
      "is_variation": false,
      "serial": 250,
      "number_prefix": "string",
      "parent_set": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    },
    "relationships": {
      "sources": {
        "data": [
          {
            "type": "set_sources",
            "id": "string"
          }
        ]
      },
      "genre": {
        "data": {
          "type": "genres",
          "id": "string"
        }
      },
      "manufacturer": {
        "data": {
          "type": "manufacturers",
          "id": "string"
        }
      },
      "brand": {
        "data": {
          "type": "brands",
          "id": "string"
        }
      },
      "year": {
        "data": {
          "type": "years",
          "id": "string"
        }
      }
    }
  },
  "included": [
    {
      "type": "cards",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "attributes": {
        "name": "Michael Jordan",
        "number": "23",
        "serial_number": "001/100",
        "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Rookie Card",
        "notes": "string",
        "has_player": true,
        "has_team": true,
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      },
      "relationships": {
        "set": {
          "data": {
            "type": "sets",
            "id": "string"
          }
        },
        "oncard": {
          "data": [
            {
              "type": "string",
              "id": "string"
            }
          ]
        },
        "attributes": {
          "data": [
            {
              "type": "attributes",
              "id": "string"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "card_images",
              "id": "string"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/sets/{set}/checklist​

Add checklist to set (v1)

Add or import a checklist to a trading card set. Can either generate empty cards or parse a detailed checklist.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the set to add checklist to
queuebooleanNoQueue the import for async processing. When omitted, large checklists (more than 50 lines) are auto-queued and smaller ones run synchronously. Pass queue=true to force async or queue=false to force sync.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"checklist"
data.attributesobjectNoNo
data.attributes.linesarray of stringNoNo["# Base Set","1 Mike Trout - Los Angeles Angels"]Checklist lines to parse, one entry per line. Lines starting with '#' denote a section. More than 50 lines are auto-queued when the queue parameter is omitted.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/sets/{set}/checklist" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"checklist","attributes":{"lines":["# Base Set","1 Mike Trout - Los Angeles Angels"]}}}'

DELETE /v1/sets/{set}/checklist​

Delete set checklist (v1)

Bulk delete cards from a trading card set. Supports optional range filtering by card number. Without range parameters, all cards in the set are deleted.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the set to delete cards from
from_numberintegerNoStart of card number range to delete (inclusive, integer >= 1)
to_numberintegerNoEnd of card number range to delete (inclusive, integer >= 1, must be >= from_number)
queuebooleanNoQueue the deletion for async processing (recommended for large sets)

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/sets/{set}/checklist" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "bulk_delete_result",
    "attributes": {
      "cards_deleted": 50,
      "set_id": "string"
    }
  }
}

POST /v1/sets/{id}/actions/sync-parallel​

Sync parallel set with parent (v1)

Add missing cards from parent set to a parallel set. This endpoint finds cards in the parent set that don't exist in the parallel set and creates them with their on-card relationships and attributes. This is the canonical JSON:API action-namespace route; the legacy POST /v1/sets/{id}/sync-parallel path is a deprecated alias.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the parallel set to sync
queuestringNoQueue the sync for async processing. Defaults to "auto", which forces queued processing when the parent set has more than 20 cards and otherwise runs the sync inline. Pass "true" to always queue or "false" to always run inline.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"sync_parallel"
data.attributesobjectNoNoNo attributes currently required. Reserved for future options.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/sets/{id}/actions/sync-parallel" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"sync_parallel","attributes":{}}}'

Example Response​

{
  "data": {
    "type": "sync_result",
    "id": "string",
    "attributes": {
      "cards_created": 15,
      "cards_updated": 0,
      "cards_skipped": 85
    }
  }
}

POST /v1/sets/{id}/sync-parallel​

Sync parallel set with parent (v1) — DEPRECATED alias

Deprecated RPC-style alias of POST /v1/sets/{id}/actions/sync-parallel. Behaves identically but responds with deprecation headers (Deprecation, Sunset, Link, Warning). Retained for a removal window; migrate to the action-namespace route. (issue #1500)

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the parallel set to sync
queuestringNoQueue the sync for async processing. Defaults to "auto", which forces queued processing when the parent set has more than 20 cards and otherwise runs the sync inline. Pass "true" to always queue or "false" to always run inline.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"sync_parallel"
data.attributesobjectNoNoNo attributes currently required. Reserved for future options.

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/sets/{id}/sync-parallel" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"sync_parallel","attributes":{}}}'

Example Response​

{
  "data": {
    "type": "sync_result",
    "id": "string",
    "attributes": {
      "cards_created": 15,
      "cards_updated": 0,
      "cards_skipped": 85
    }
  }
}

Set Sources v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/set-sources​

Get all set sources (v1)

Retrieve all set sources. Filter by set_id and/or source_type using filter[] params.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
filter[set_id]stringNoFilter by set UUID
filter[source_type]stringNoFilter by source type
includestringNoComma-separated list of relationships to include (set)
pageintegerNoPage number for pagination
per_pageintegerNoNumber of items per page (default 50, max 200)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "set_sources",
      "id": "string",
      "attributes": {
        "source_url": "https://example.com/checklist",
        "source_name": "CardboardConnection",
        "source_type": "checklist",
        "verified_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/set-sources​

Create a new set source (v1)

Create a new set source tracking record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"set_sources"
data.attributesobjectNoNo
data.attributes.set_idstring (uuid)YesNo"550e8400-e29b-41d4-a716-446655440000"
data.attributes.source_urlstring (url)YesNo"https://example.com/checklist"
data.attributes.source_namestringNoYes"CardboardConnection"
data.attributes.source_typestringYesNo"checklist"
data.attributes.verified_atstring (date-time)NoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/set-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"set_sources","attributes":{"set_id":"550e8400-e29b-41d4-a716-446655440000","source_url":"https://example.com/checklist","source_name":"CardboardConnection","source_type":"checklist","verified_at":"string"}}}'

Example Response​

{
  "data": {
    "type": "set_sources",
    "id": "string",
    "attributes": {
      "source_url": "https://example.com/checklist",
      "source_name": "CardboardConnection",
      "source_type": "checklist",
      "verified_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/set-sources/{id}​

Get a specific set source (v1)

Retrieve detailed information about a specific set source by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set source to retrieve
includestringNoComma-separated list of relationships to include (set)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/set-sources/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "set_sources",
    "id": "string",
    "attributes": {
      "source_url": "https://example.com/checklist",
      "source_name": "CardboardConnection",
      "source_type": "checklist",
      "verified_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

DELETE /v1/set-sources/{id}​

Delete a set source (v1)

Delete an existing set source

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set source to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/set-sources/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/set-sources/{id}​

Update a set source (v1)

Update an existing set source

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the set source to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"set_sources"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.source_urlstring (url)NoNo
data.attributes.source_namestringNoYes
data.attributes.source_typestringNoNo
data.attributes.verified_atstring (date-time)NoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/set-sources/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"set_sources","id":"string","attributes":{"source_url":"string","source_name":"string","source_type":"string","verified_at":"string"}}}'

Example Response​

{
  "data": {
    "type": "set_sources",
    "id": "string",
    "attributes": {
      "source_url": "https://example.com/checklist",
      "source_name": "CardboardConnection",
      "source_type": "checklist",
      "verified_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Statistics v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/stats/{type}​

Get statistics for a model type (v1)

Retrieve daily statistics showing creation and deletion counts for a specific model type

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
typestringYesType of model to get statistics for (e.g., cards, sets, players)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/stats/{type}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "stats",
    "attributes": {
      "model": "cards",
      "unit": "daily",
      "count": 30,
      "stats": [
        {
          "date": "2024-01-15",
          "count": 5,
          "total": 150
        }
      ]
    }
  }
}

GET /v1/stats/counts​

Get current counts for all entity types

Get entity counts by status. Cached for 1 hour.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/stats/counts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "stats",
    "attributes": {
      "counts": [
        {
          "entity_type": "set",
          "total": 21616,
          "published": 730,
          "draft": 20886,
          "archived": 0
        }
      ]
    }
  }
}

GET /v1/stats/snapshots​

Get historical snapshots with optional filtering

Get historical snapshots with date/type filters.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
entity_typestringNoFilter by entity type
fromstringNoFilter snapshots from this date (YYYY-MM-DD)
tostringNoFilter snapshots to this date (YYYY-MM-DD)
per_pageintegerNoNumber of results per page (default: 100, max: 500)
pageintegerNoPage number

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/stats/snapshots" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "snapshots",
    "attributes": {
      "snapshots": [
        {
          "date": "2024-01-15",
          "entity_type": "set",
          "total": 21616,
          "published": 730,
          "draft": 20886,
          "archived": 0
        }
      ],
      "entity_type": "set",
      "from": "string",
      "to": "string"
    }
  },
  "meta": {
    "total": 100,
    "per_page": 100,
    "current_page": 1,
    "last_page": 1
  }
}

GET /v1/stats/growth​

Get growth metrics for a specific time period

Compare current counts to previous period. Cached for 1 hour.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
periodstringNoTime period for comparison

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/stats/growth" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "growth",
    "attributes": {
      "period": "7d",
      "metrics": [
        {
          "entity_type": "set",
          "current": 21616,
          "previous": 21500,
          "change": 116,
          "percentage_change": 0.54
        }
      ]
    }
  }
}

Teams v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/teams​

Get all teams (v1)

Retrieve a paginated list of all teams with optional filtering

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
locationstringNoFilter by team location
mascotstringNoFilter by team mascot
namestringNoFilter by full team name (searches both location and mascot)
genre_idstringNoFilter by genre ID
limitintegerNoNumber of teams per page (max 100, default 25)
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/teams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "teams",
      "id": "string",
      "attributes": {
        "name": "Chicago Bulls",
        "city": "Chicago",
        "abbreviation": "CHI",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ],
  "included": [
    {}
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

POST /v1/teams​

Create a new team (v1)

Create a new team record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"teams"
data.attributesobjectNoNo
data.attributes.locationstringNoNo"Chicago"
data.attributes.mascotstringNoNo"Bulls"
data.attributes.citystringNoYes"Chicago"
data.attributes.abbreviationstringNoYes"CHI"
data.attributes.namestringNoNo"Chicago Bulls"Alternative to location/mascot
data.attributes.genre_idstring (uuid)NoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/teams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"teams","attributes":{"location":"Chicago","mascot":"Bulls","city":"Chicago","abbreviation":"CHI","name":"Chicago Bulls","genre_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "teams",
    "id": "string",
    "attributes": {
      "name": "Chicago Bulls",
      "city": "Chicago",
      "abbreviation": "CHI",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/teams/{id}​

Get a specific team (v1)

Retrieve detailed information about a specific team by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the team to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "teams",
    "id": "string",
    "attributes": {
      "name": "Chicago Bulls",
      "city": "Chicago",
      "abbreviation": "CHI",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  },
  "included": [
    {}
  ]
}

DELETE /v1/teams/{id}​

Delete a team (v1)

Delete an existing team record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the team to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/teams/{id}​

Update a team (v1)

Update an existing team record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the team to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"teams"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.locationstringNoNo"Chicago"
data.attributes.mascotstringNoNo"Bulls"
data.attributes.citystringNoYes"Chicago"
data.attributes.abbreviationstringNoYes"CHI"
data.attributes.genre_idstring (uuid)NoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/teams/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"teams","id":"string","attributes":{"location":"Chicago","mascot":"Bulls","city":"Chicago","abbreviation":"CHI","genre_id":"string"}}}'

Example Response​

{
  "data": {
    "type": "teams",
    "id": "string",
    "attributes": {
      "name": "Chicago Bulls",
      "city": "Chicago",
      "abbreviation": "CHI",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Years v1​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /v1/years​

Get all years (v1)

Retrieve a list of all years available for trading card sets

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/years" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "years",
      "id": "string",
      "attributes": {
        "year": "1989",
        "description": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      }
    }
  ]
}

POST /v1/years​

Create a new year (v1)

Create a new year record for trading card classification

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"years"
data.attributesobjectNoNo
data.attributes.namestringYesNo"1989"
data.attributes.descriptionstringNoYes

Example Request​

curl -X POST "https://api.tradingcardapi.com/v1/years" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"years","attributes":{"name":"1989","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "years",
    "id": "string",
    "attributes": {
      "year": "1989",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

GET /v1/years/{id}​

Get a specific year (v1)

Retrieve detailed information about a specific year by ID

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the year to retrieve
includestringNoComma-separated list of relationships to include

Example Request​

curl -X GET "https://api.tradingcardapi.com/v1/years/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": {
    "type": "years",
    "id": "string",
    "attributes": {
      "year": "1989",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

DELETE /v1/years/{id}​

Delete a year (v1)

Delete an existing year record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the year to delete

Example Request​

curl -X DELETE "https://api.tradingcardapi.com/v1/years/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

PATCH /v1/years/{id}​

Update a year (v1)

Update an existing year record

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
idstringYesUUID of the year to update

Request Body​

Media type: application/vnd.api+json

FieldTypeRequiredNullableExampleDescription
dataobjectNoNo
data.typestringNoNo"years"
data.idstring (uuid)NoNo
data.attributesobjectNoNo
data.attributes.namestringNoNo"1989"
data.attributes.descriptionstringNoYes

Example Request​

curl -X PATCH "https://api.tradingcardapi.com/v1/years/{id}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{"data":{"type":"years","id":"string","attributes":{"name":"1989","description":"string"}}}'

Example Response​

{
  "data": {
    "type": "years",
    "id": "string",
    "attributes": {
      "year": "1989",
      "description": "string",
      "created_at": "string",
      "updated_at": "string",
      "url": "string"
    }
  }
}

Sets v2​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

Why v2?​

The v2 checklist endpoint fixes a JSON:API semantic issue in v1:

  • v1 returns the set as primary data (data: {type: "sets"}) with cards in included - incorrect for a "checklist"
  • v2 returns cards as primary data (data: [{type: "cards"}, ...]) with set in included - correct semantics

When to use v2:

  • New integrations that want standards compliance
  • Applications prioritizing cards over set metadata
  • When you need the improved response structure

When to use v1:

  • Existing integrations (backward compatibility)
  • No breaking changes needed

Both versions are fully supported long-term.

GET /v2/sets/{set}/checklist​

Get set checklist (v2)

Retrieve the complete checklist for a trading card set. V2 returns cards as the primary data with set information in the included array. Supports compact format for large sets to avoid response size limits. Compact format returns only id, number, and name fields, reducing response size by ~75%.

Authentication: Bearer token required — send Authorization: Bearer YOUR_API_TOKEN.

Parameters​

NameTypeRequiredDescription
setstringYesUUID of the set to get checklist for
includestringNoComma-separated list of relationships to include (set,oncard,attributes)
formatstringNoResponse format: 'full' returns all card fields, 'compact' returns only id, number, and name
pageintegerNoPage number for pagination (starts at 1)
per_pageintegerNoNumber of cards per page (max 100, returns all if not specified)

Example Request​

curl -X GET "https://api.tradingcardapi.com/v2/sets/{set}/checklist" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/vnd.api+json"

Example Response​

{
  "data": [
    {
      "type": "cards",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "attributes": {
        "name": "Michael Jordan",
        "number": "23",
        "serial_number": "001/100",
        "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Rookie Card",
        "notes": "string",
        "has_player": true,
        "has_team": true,
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      },
      "relationships": {
        "set": {
          "data": {
            "type": "sets",
            "id": "string"
          }
        },
        "oncard": {
          "data": [
            {
              "type": "string",
              "id": "string"
            }
          ]
        },
        "attributes": {
          "data": [
            {
              "type": "attributes",
              "id": "string"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "card_images",
              "id": "string"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "sets",
      "id": "string",
      "attributes": {
        "name": "1989 Topps Baseball",
        "title": "Series 1",
        "description": "string",
        "card_count": 792,
        "current_card_count": 792,
        "is_parallel": false,
        "is_insert": false,
        "is_autograph": false,
        "is_relic": false,
        "is_variation": false,
        "serial": 250,
        "number_prefix": "string",
        "parent_set": "string",
        "created_at": "string",
        "updated_at": "string",
        "url": "string"
      },
      "relationships": {
        "sources": {
          "data": [
            {
              "type": "set_sources",
              "id": "string"
            }
          ]
        },
        "genre": {
          "data": {
            "type": "genres",
            "id": "string"
          }
        },
        "manufacturer": {
          "data": {
            "type": "manufacturers",
            "id": "string"
          }
        },
        "brand": {
          "data": {
            "type": "brands",
            "id": "string"
          }
        },
        "year": {
          "data": {
            "type": "years",
            "id": "string"
          }
        }
      }
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

Version​

Unless an endpoint states otherwise, endpoints in this section are subject to the API rate limits. See the rate limits guide for quotas, response headers, and retry patterns.

GET /version​

Get API version information

Retrieve version information about the API, application, and supported versions

Authentication: Public — no API token required.

Example Request​

curl -X GET "https://api.tradingcardapi.com/version" \
  -H "Accept: application/json"

Example Response​

{
  "api_version": "1.0",
  "app_version": "2.1.3",
  "build_date": "2024-01-15",
  "build_commit": "abc123def",
  "supported_versions": [
    "1.0",
    "1.1"
  ],
  "deprecated_versions": [
    "0.9"
  ],
  "changelog_url": "https://api.example.com/changelog"
}