---
title: "New Cards Feed"
method: POST
path: "/v1/cards/card-feed"
tags: ["Card Search"]
---

# New Cards Feed

`POST /v1/cards/card-feed`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/card-feed`
- Auth: API key in header `X-API-Key`

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.

```bash
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}'
```

## Request body

- CardFeedRequest: Request for the new-cards feed.
  - `since` string, 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.
  - `category` string, 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_size` integer: Cards per page (1-100).
  - `cursor` string, 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_only` boolean, 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.

## Response `200`

Successful Response

- CardFeedResponse: One page of the new-cards feed, newest first.
  - `cards` CardFeedCard[]: Cards added in [`since`, `until`), newest first (by `created_at`, then `card_id`).
    - `description` string, required: Full card description
    - `player` string, required: Player or character name
    - `set` string, required: Card set name
    - `number` string, required: Card number in set
    - `variant` string, required: Card variant (e.g., 'Base', 'Gold', 'Refractor')
    - `card_id` string, required: Unique card identifier
    - `image` string, required: Card image URL
    - `category` string, required: Card category (e.g., 'Baseball', 'Pokemon')
    - `category_group` string, required: Category group (e.g., 'Sports Cards', 'Trading Cards')
    - `set_type` string, required: Set type
    - `7 Day Sales` integer, required: Sales volume in last 7 days
    - `30 Day Sales` integer, required: Sales volume in last 30 days
    - `rookie` boolean, required: Whether the card is a rookie card
    - `gain` number, required: Price gain percentage (7-day)
    - `gain_30day` number, required: Price gain percentage (30-day)
    - `stats_grade` string, required: Primary grade (e.g., 'PSA 10', 'BGS 9.5')
    - `prices` CardPrice[], required: Price information at different grades
      - `grade` string, required: Card grade (e.g., 'Raw', 'PSA 10')
      - `price` string, required: Price in string format
    - `subset` string, nullable: Card subset within the set (e.g. 'Base Set', 'Chrome'); null when the card has no subset
    - `gemrate_id` string, nullable: GemRate ID stored on this catalog card (usually GemRate's universal ID); null when the card has none.
    - `created_at` string, date-time, required: When the card was added to the Card Hedge catalog (UTC).
  - `next_cursor` string, nullable: Send as `cursor` to get the next, older page. null when this page reaches `since`: the walk is complete.
  - `category` string, nullable: The category this walk is filtered to; null for every category.
  - `since` string, 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.
  - `until` string, 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.

## Other responses

- `400`: `since` older than 30 days, a malformed cursor, or a cursor sent with a different `category` or `since`
- `403`: The API key is not on the Enterprise tier (use the x402 route /v1/agent/cards/card-feed instead)
- `422`: Validation Error
- `503`: The catalog is temporarily unavailable; retry

## Changes

- **2026-11-11** `e5a917368b20`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/card-feed/post.md)

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/c0635f1778ac?raw)
