CARD LIBRARYDevelopers · API v1
BUILD WITH THE CATALOG

Every card. One connection.

Search Card Library’s published checklists and retrieve stable card IDs, release details, front/back image URLs, and the sources behind each image.

Explore the APIOpenAPI specificationBrowse the cards

Public, read-only v1. No API key required. Browser requests are supported through CORS. The current catalog covers licensed NBA products in the 2025 calendar-year archive. Coverage is incomplete; missing images are null, and unresolved editions are labeled.

Start with one request

curl 'https://cardlibrary.dev/api/v1/cards?collection=topps-flagship&subset=Base&number=1'

Endpoints

GET endpointReturns
/api/v1Catalog scope, totals, snapshot and API links.
/api/v1/collectionsPaginated releases. Filter by manufacturer or season.
/api/v1/collections/{collectionId}Full release name, checklist source, coverage and release details.
/api/v1/collections/{collectionId}/subsetsPaginated subsets and their image coverage.
/api/v1/cards?collection={collectionId}Paginated cards in one collection.
/api/v1/cards/{cardId}One card, its image URLs and provenance.

Find the right edition

The card list requires a collection ID, such as topps-flagship for 2025-26 Topps NBA Basketball. Use q for token search, or subset, number, player, and team for exact filters. Text matching ignores case and accents. Parallel editions remain separate records; a player name alone does not identify a specific card.

Filter image coverage using hasImage=any, front, back, both, or none. Promotional renders retain their image type. identityStatus describes the record’s evidence; checklist-sourced does not claim physical verification.

Use it in an app

const params = new URLSearchParams({
  collection: 'topps-flagship',
  q: 'Jayson Tatum',
  hasImage: 'both',
  limit: '20'
});
const response = await fetch(
  `https://cardlibrary.dev/api/v1/cards?${params}`
);
if (!response.ok) throw new Error(`Card Library: ${response.status}`);
const { data, pagination, meta } = await response.json();
// data[0].images.front.url is an absolute image URL.
// Save data[0].id to retrieve this specific card later.

Pagination and updates

Pages default to 50 records, with a maximum of 100. Follow pagination.next until it is null. Alternatively, pass pagination.nextCursor as cursor while keeping the same filters. Each response includes meta.snapshot. A cursor from an older catalog returns 409 stale_cursor; restart pagination to avoid mixing snapshots.

Responses include ETag. Send it in If-None-Match to receive 304 when unchanged. Successful responses may be cached at the CDN for five minutes. Prefer caching and paginated requests over repeated polling.

Errors and scope

Errors use {"error":{"code":"…","message":"…"}}. Invalid filters return 400, unknown IDs return 404, unsupported methods return 405, and stale cursors return 409. HEAD and OPTIONS are supported. There are no create, update, or delete endpoints.

This release provides public catalog access. API keys, per-customer quotas, billing, and a contractual service-level agreement are not implemented. Source links and image types are provided so integrations can preserve provenance.