API Endpoints

Complete reference for all 8 CardMind API endpoints. All requests must include an Authorization: Bearer header unless noted otherwise. See Authentication → for details.

Standard response envelope

Every endpoint returns the same JSON shape. On success: { "data": T, "error": null }. On error: { "data": null, "error": { "message": "...", "code": "..." } }.

GET

/api/cards/search

Public

Full-text search across the CardMind card database. Returns cards matching the query with current price data. Supports optional filters by set code and card format. Paginated via limit and offset.

Parameters

Name	In	Type	Required	Description
q	query	string	required	Search term — matches card name, oracle text, and type line
set	query	string	optional	Filter by set code (e.g. "ltr", "lea")
format	query	string	optional	Filter by legality format (e.g. "standard", "modern", "legacy")
limit	query	number	optional	Results per page. Default: 20. Max: 100
offset	query	number	optional	Number of results to skip for pagination. Default: 0

Example request

curl "https://api.cardmind.app/api/cards/search?q=lightning+bolt&limit=2" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Example response

{
  "data": [
    {
      "id": "f29ba16f-c8fb-42fe-aabf-87089cb214a7",
      "name": "Lightning Bolt",
      "set": "lea",
      "set_name": "Limited Edition Alpha",
      "mana_cost": "{R}",
      "type_line": "Instant",
      "rarity": "common",
      "price_usd": "9750.00",
      "price_usd_foil": null,
      "image_uri": "https://cards.scryfall.io/normal/front/f/2/f29ba16f.jpg"
    },
    {
      "id": "e3285e6b-3e79-4d7c-bf96-d920f973b122",
      "name": "Lightning Bolt",
      "set": "m10",
      "set_name": "Magic 2010",
      "mana_cost": "{R}",
      "type_line": "Instant",
      "rarity": "common",
      "price_usd": "1.49",
      "price_usd_foil": "4.20",
      "image_uri": "https://cards.scryfall.io/normal/front/e/3/e3285e6b.jpg"
    }
  ],
  "error": null
}

GET

/api/cards/[id]

Public

Retrieve a single card by its Scryfall UUID. Returns full card metadata plus the last 30 days of price history as a nested array.

Parameters

Name	In	Type	Required	Description
id	path	string (UUID)	required	Scryfall card UUID (e.g. "e3285e6b-3e79-4d7c-bf96-d920f973b122")

Example request

curl "https://api.cardmind.app/api/cards/e3285e6b-3e79-4d7c-bf96-d920f973b122" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Example response

{
  "data": {
    "id": "e3285e6b-3e79-4d7c-bf96-d920f973b122",
    "name": "Lightning Bolt",
    "set": "m10",
    "set_name": "Magic 2010",
    "mana_cost": "{R}",
    "cmc": 1,
    "type_line": "Instant",
    "oracle_text": "Lightning Bolt deals 3 damage to any target.",
    "rarity": "common",
    "price_usd": "1.49",
    "price_usd_foil": "4.20",
    "image_uri": "https://cards.scryfall.io/normal/front/e/3/e3285e6b.jpg",
    "price_history": [
      { "date": "2026-04-16", "price_usd": "1.49", "price_usd_foil": "4.20" },
      { "date": "2026-04-15", "price_usd": "1.45", "price_usd_foil": "4.15" }
    ]
  },
  "error": null
}

POST

/api/cards/bulk-lookup

Public

Look up multiple cards by name in a single request. Uses exact case-insensitive matching. Card names containing commas are handled correctly via double-quoted OR filter. Returns matched cards only — unrecognised names are silently omitted.

Request body

Name	In	Type	Required	Description
names	body	string[]	required	Array of card names to look up. Maximum 200 names per request

Example request

curl -X POST "https://api.cardmind.app/api/cards/bulk-lookup" \
  -H "Authorization: Bearer cm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Black Lotus", "Lightning Bolt", "Brainstorm"]}'

Example response

{
  "data": [
    {
      "id": "bd8fa327-dd41-4737-8f19-2cf5eb1f7cdd",
      "name": "Black Lotus",
      "set": "lea",
      "price_usd": "194999.00",
      "price_usd_foil": null,
      "image_uri": "https://cards.scryfall.io/normal/front/b/d/bd8fa327.jpg"
    },
    {
      "id": "f29ba16f-c8fb-42fe-aabf-87089cb214a7",
      "name": "Lightning Bolt",
      "set": "lea",
      "price_usd": "9750.00",
      "price_usd_foil": null,
      "image_uri": "https://cards.scryfall.io/normal/front/f/2/f29ba16f.jpg"
    }
  ],
  "error": null
}

“Brainstorm” was omitted from the response above because no card matched that exact name in the database at request time. Unmatched names never produce an error.

GET

/api/prices/movers

Public

Returns the top price gainers and losers for a given time period. Useful for building market-mover dashboards, alerts, and trend analysis. Backed by a Supabase RPC function that ranks cards by absolute price delta.

Parameters

Name	In	Type	Required	Description
period	query	"1d" \| "7d" \| "30d" \| "all"	optional	Time window for price comparison. Default: "1d"
limit	query	number	optional	Number of cards to return in each list (gainers + losers). Default: 10. Max: 100

Example request

curl "https://api.cardmind.app/api/prices/movers?period=7d&limit=5" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Example response

{
  "data": {
    "gainers": [
      {
        "id": "e3285e6b-3e79-4d7c-bf96-d920f973b122",
        "name": "Lightning Bolt",
        "set": "m10",
        "price_usd": "1.49",
        "price_change": 0.38,
        "price_change_pct": 34.2
      }
    ],
    "losers": [
      {
        "id": "9a1e44aa-e21f-4c6e-8ff4-d3a76c276c4a",
        "name": "Jace, the Mind Sculptor",
        "set": "wwk",
        "price_usd": "64.00",
        "price_change": -8.50,
        "price_change_pct": -11.7
      }
    ]
  },
  "error": null
}

GET

/api/prices/history/[id]

Public

Retrieves the full price history for a card by Scryfall UUID. Returns one data point per day, ordered from oldest to newest. Useful for rendering price charts.

Parameters

Name	In	Type	Required	Description
id	path	string (UUID)	required	Scryfall card UUID
days	query	number	optional	Number of days of history to return. Default: 30. Max: 365

Example request

curl "https://api.cardmind.app/api/prices/history/e3285e6b-3e79-4d7c-bf96-d920f973b122?days=7" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Example response

{
  "data": [
    { "date": "2026-04-10", "price_usd": "1.11", "price_usd_foil": "3.80" },
    { "date": "2026-04-11", "price_usd": "1.15", "price_usd_foil": "3.85" },
    { "date": "2026-04-12", "price_usd": "1.20", "price_usd_foil": "3.90" },
    { "date": "2026-04-13", "price_usd": "1.25", "price_usd_foil": "3.95" },
    { "date": "2026-04-14", "price_usd": "1.35", "price_usd_foil": "4.00" },
    { "date": "2026-04-15", "price_usd": "1.45", "price_usd_foil": "4.15" },
    { "date": "2026-04-16", "price_usd": "1.49", "price_usd_foil": "4.20" }
  ],
  "error": null
}

GET

/api/signals/recent

Public

Returns recent market signals — algorithmically detected price movement events, buy/sell recommendations, and trend alerts. Results are ordered by recency (newest first). Supports optional filtering by signal type and pagination.

Parameters

Name	In	Type	Required	Description
type	query	string	optional	Filter by signal type (e.g. "BUY", "SELL", "WATCH"). Omit to return all types
limit	query	number	optional	Number of signals to return. Default: 20. Max: 100
offset	query	number	optional	Number of results to skip for pagination. Default: 0

Example request

curl "https://api.cardmind.app/api/signals/recent?type=BUY&limit=3" \
  -H "Authorization: Bearer cm_live_YOUR_KEY"

Example response

{
  "data": [
    {
      "id": "sig_01hwqbc34xem9e4b3kga70x7v2",
      "card_id": "e3285e6b-3e79-4d7c-bf96-d920f973b122",
      "card_name": "Lightning Bolt",
      "signal_type": "BUY",
      "reason": "34% price increase over 7 days with rising tournament play",
      "price_at_signal": "1.49",
      "created_at": "2026-04-16T18:30:00Z"
    },
    {
      "id": "sig_01hwqbc34xem9e4b3kga70x7v3",
      "card_id": "bd8fa327-dd41-4737-8f19-2cf5eb1f7cdd",
      "card_name": "Black Lotus",
      "signal_type": "WATCH",
      "reason": "Unusual volume spike detected on reserved list card",
      "price_at_signal": "194999.00",
      "created_at": "2026-04-16T12:00:00Z"
    }
  ],
  "error": null
}

POST

/api/internal/fleet-heartbeat

Internal only

Internal use only. This endpoint is called by CardMind satellite projects (cardmind-social, cardmind-video, cardmind-pages) to register health pings. It requires the X-Internal-Secret header instead of a Bearer token. External API keys are rejected with 401.

Request body

Name	In	Type	Required	Description
project	body	string	required	Name of the calling satellite project (e.g. "cardmind-social")
status	body	"healthy" \| "degraded" \| "down"	required	Current operational status of the satellite project
version	body	string	required	Deployed version string of the satellite (e.g. "1.4.2")
metadata	body	Record<string, unknown>	optional	Optional key-value map of additional diagnostic information

Example request

curl -X POST "https://api.cardmind.app/api/internal/fleet-heartbeat" \
  -H "x-internal-secret: <INTERNAL_API_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "cardmind-social",
    "status": "healthy",
    "version": "1.4.2",
    "metadata": { "last_tweet_at": "2026-04-16T18:00:00Z" }
  }'

Example response

{
  "data": { "ok": true },
  "error": null
}

GET

/api/health

No auth required

Simple liveness check. Returns 200 OK when the API hub is running. No authentication required. Suitable for uptime monitors and load balancer health checks.

Parameters

None.

Example request

curl "https://api.cardmind.app/api/health"

Example response

{
  "data": { "status": "ok" },
  "error": null
}