Cards

The Cards API exposes each item in a partner user's collection — a user_cards row joined to catalog metadata in cards. Use it to sync inventory, show grades in your portal, or resolve a user_card_id before fetching a grading.

List cards

GET /v1/cards?limit=25&sort=added&dir=desc

Query	Default	Description
limit	25	Page size, 1–100
cursor	—	ISO 8601 datetime; cards with added_at before this value
q	—	Search player, brand, year, card number, or team
graded	all	all, graded, or raw
category_id	—	Filter by catalog category ID
sort	added	added, player, year, brand, grade
dir	desc	asc or desc

Response

{
  "cards": [
    {
      "user_card_id": 42,
      "card_id": 1001,
      "brand": "Bowman",
      "year": "2000",
      "card_number": "1",
      "variant": null,
      "player_name": "Vladimir Guerrero",
      "team_name": null,
      "category": "Baseball",
      "grade": "8.5",
      "grader": "chck",
      "shoebox_value": 12500,
      "added_at": "2026-02-17T06:34:29.825Z",
      "images": {
        "front": "https://…",
        "back": "https://…"
      }
    }
  ],
  "next_cursor": "2026-02-17T06:34:29.825Z"
}

Each list item includes presigned images.front and images.back (same shape as card detail; null when no attachment). URLs expire after 300 seconds by default.

shoebox_value is the catalog value in cents. When next_cursor is null, there are no more pages.

Pagination with cursor

When paginating with cursor, results are ordered by added_at descending regardless of sort/dir, matching the gradings list cursor behavior.

Card detail

GET /v1/cards/{user_card_id}

The path parameter is user_cards.id (not cards.id). Use user_card_id from the list response or your dashboard.

Response highlights

Section	Contents
user_card	Ownership, grade, grader, share slug, timestamps
card	Full catalog metadata (player, team, TCDB fields, category)
images	Presigned front / back plus slab and damage-report URLs when available
gradings	Linked grading UUIDs (use with Gradings)
grade_runs	Historical grade records with subgrades
model_grade	Internal model payload (optional)

Presigned URLs expire after 300 seconds by default (PRESIGNED_URL_TTL_SECONDS).

Typical flows

Inventory sync — Page through GET /v1/cards and store user_card_id, catalog fields, and presigned image URLs in your DB (refresh URLs before they expire).

Webhook → grading → card — On webhook, call GET /v1/gradings/{uuid}, then GET /v1/cards/{user_card_id} only when you need slab images, full grade history, or model payload.

Graded-only feed — GET /v1/cards?graded=graded&sort=grade&dir=desc.

OpenAPI

Request/response schemas and try-it-out: API reference.