Card Search

Cards newly added to the Card Hedge catalog, newest first, paged with a cursor.

Use it to keep your own copy of the catalog current: ask for every card added since a time you choose (at most 30 days back), optionally in one category.

Access: Enterprise API keys. Without one, the same feed is sold per call over x402 at /v1/agent/cards/card-feed ($0.01 per page).

How to poll:

  1. Start a walk: send {} or a category. Without since it covers the last 30 days.
  2. Send each response's next_cursor back as cursor until it is null.
  3. Next time, send the finished walk's until as since: you get only the cards added after it.

Window: each walk returns the cards added in [since, until), newest first (by created_at, then card_id). until is set when the walk starts, two minutes before then, so a card still being written is picked up by the next poll rather than skipped. Every page of a walk reads the same window; cursors never expire. No page returns cards added more than 30 days ago, so on a walk that takes a long time the window's oldest cards drop off. The feed lists cards by when they were added: it does not report later changes to a card (a new category, new prices) or cards that are removed.

Request:

  • since (optional): ISO 8601 date or date-time (no time zone = UTC), at most 30 days back. Default: 30 days ago. A date alone means midnight UTC, so the date 30 days ago is already too old for most of the day: omit since for the full 30 days.
  • category (optional): exact category name, any case ('Baseball', 'Pokemon'). Default: every category.
  • page_size: 1-100 cards per page (default 100), on the keyed API and x402.
  • cursor: the previous response's next_cursor. With a cursor, since and category may be omitted; if sent they must match the walk.
  • raw_images_only (optional): image preference, as on search-cards-wsort.

Response:

  • cards: the same card object as search-cards-wsort (card_id, description, player, set, number, variant, image, category, sales, gains, prices, gemrate_id) plus created_at, when the card was added.
  • next_cursor: the next (older) page; null when the walk is complete.
  • since, until: the walk's window. Send until as the next since.

Errors: 400 for a since older than 30 days, a malformed cursor, or a cursor sent with a different category or since; 403 for a key that is not Enterprise.

curl -X POST "https://api.cardhedger.com/v1/cards/card-feed" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "Baseball", "page_size": 100}'
post/v1/cards/card-feed

Request

  • Base URL
    https://api.cardhedger.com
  • Auth
    API key in header X-API-Key

Request body

sincestring date-time nullable

Return cards added at or after this time (ISO 8601 date or date-time; no time zone means UTC; a date alone means midnight UTC). At most 30 days back: an older since is a 400. Omit it for the whole last 30 days. To pick up only what is new since your last walk, send that walk's until here. With a cursor, omit it or send the same value.

categorystring nullable

Only cards in this category (exact name, any case: 'Baseball', 'Pokemon', 'Hockey'). Omit for every category. With a cursor, omit it or send the same value.

page_sizeinteger

Cards per page (1-100).

cursorstring nullable

Send the previous response's next_cursor to get the next (older) page; repeat until next_cursor is null. Omit it for the first page. A cursor never expires.

raw_images_onlyboolean nullable

Image preference. Omitted (default): the raw card photo, falling back to the graded slab image only when no raw photo exists. true: raw only (no graded fallback). false: prefer the graded slab image.

Example request

{
  "category": "Baseball",
  "page_size": 100
}

Response

Successful Response

next_cursorstring nullable

Send as cursor to get the next, older page. null when this page reaches since: the walk is complete.

categorystring nullable

The category this walk is filtered to; null for every category.

sincestring date-time required

Start of the walk's window (inclusive): cards added at or after this time. The same on every page of a walk. Cards added more than 30 days ago are never returned, even when since is a little earlier.

untilstring date-time required

End of the walk's window (exclusive). It trails the walk's start by two minutes, so a card still being written then is picked up by the next poll rather than skipped. When the walk is complete, send this as since on your next poll to get only cards added after it.

Changes