Card recognition

Recognition returns a printing, not a card name — which set, which collector number, which language, which finish — with the full catalog record and both price feeds attached. It is metered separately from the data API in scans, where one scan is one matched card. Frames that do not resolve are answered and billed zero.

Pricing and the per-game gotchas live on the card recognition page. This page is the contract.

Single photo

POST /v1/scan accepts a multipart upload, a public URL, or base64 in a JSON body. One request, one response — there is no job to poll and no id to chase.

curl -X POST "https://api.tcggraph.com/v1/scan" \
  -H "Authorization: Bearer $TCGGRAPH_KEY" \
  -F image=@front.jpg \
  -F games=pokemon \
  -F minConfidence=0.92

Parameters

The same names work as multipart fields, query parameters, JSON keys, and in the socket’s config frame.

The match object

{
  "requestId": "scan_01K5Z8P4XQJ7YB3M",
  "latencyMs": 41,
  "matches": [
    {
      "confidence": 0.9962,
      "billed": true,
      "box": {
        "x": 0.171,
        "y": 0.064,
        "w": 0.658,
        "h": 0.872
      },
      "printing": {
        "id": "pkm_sv3pt5_199",
        "language": "en",
        "finish": "holofoil",
        "edition": "unlimited",
        "collectorNumber": "199/165"
      },
      "card": {
        "id": "pkm_sv3pt5_199",
        "game": "pokemon",
        "name": "Charizard ex",
        "set": {
          "code": "sv3pt5",
          "name": "151"
        },
        "rarity": "Special Illustration Rare",
        "prices": [
          {
            "source": "tcgplayer",
            "region": "NA",
            "currency": "USD",
            "market": 370.48
          },
          {
            "source": "cardmarket",
            "region": "EU",
            "currency": "EUR",
            "market": 312.67,
            "trend": 312.67,
            "sellers": 86
          }
        ]
      },
      "alternatives": []
    }
  ],
  "scans": {
    "billed": 1,
    "remaining": 5842
  }
}

matches[].card is byte-for-byte the object /v1/cards returns, so an existing parser handles it unchanged. The prices on it are the same objects, from the same sources, at the same freshness as the price endpoints — identification and pricing are one operation and one charge.

Unresolved frames

Half the contract, and the half people forget to handle. When nothing clears minConfidence you still get a body: where the card was, why it failed, and the ranked runners-up. scans.billed is 0.

{
  "requestId": "scan_01K5Z8P51N4WQD0T",
  "latencyMs": 29,
  "matches": [],
  "unresolved": [
    {
      "box": { "x": 0.19, "y": 0.07, "w": 0.63, "h": 0.86 },
      "reason": "glare across set symbol",
      "alternatives": [
        { "printingId": "pkm_sv3pt5_199", "confidence": 0.71 },
        { "printingId": "pkm_sv3pt5_223", "confidence": 0.68 }
      ]
    }
  ],
  "scans": { "billed": 0, "remaining": 5842 }
}

Surface the reason to whoever is holding the card. An operator told glare on the set symbol fixes the shot in a second; the same operator shown a spinner tries the same angle three more times.

Choosing a threshold

• 0.98 and up — unattended pipelines where a wrong printing corrupts inventory. Expect to refuse more frames.
• 0.90 to 0.95 — the default range, and right for anything with a human watching. Pair it with a confirm step driven by alternatives.
• Below 0.85 — only when a person confirms every match. A confident wrong answer costs more than a refused frame, and refused frames are free.

The live socket

wss://api.tcggraph.com/v1/scan keeps one connection open for a whole scanning session. It exists to avoid paying connection setup per card: at a few hundred cards an hour, handshakes are most of the wall clock. Authenticate in the subprotocol list, since browsers cannot set headers on a WebSocket.

const socket = new WebSocket("wss://api.tcggraph.com/v1/scan", [
  "tcggraph.v1",
  `bearer.${process.env.TCGGRAPH_KEY}`,
]);

socket.onopen = () =>
  socket.send(
    JSON.stringify({
      type: "config",
      games: ["pokemon", "magic-the-gathering"],
      minConfidence: 0.92,
      prices: ["cardmarket", "tcgplayer"],
    }),
  );

socket.onmessage = (event) => {
  const frame = JSON.parse(event.data);
  if (frame.type === "match") addToInventory(frame.matches[0]);
  if (frame.type === "unresolved") showHint(frame.reason);
};

// Binary frames need no envelope. Push them straight off the camera.
setInterval(async () => socket.send(await captureJpeg()), 100);

What you send

What you receive

Operating it

• Replies carry the seq of the frame they answer, and they can arrive out of order. Key your UI on seq, not on arrival order.
• Frames are downsampled on the way in. Sending 4K stills costs you bandwidth and buys nothing; 1080p is ample.
• Roughly ten frames a second per socket is plenty for a hand-fed stack. Sustained excess is dropped rather than queued, so the newest frame is always the one being matched.
• Concurrent sockets are capped by plan: Starter 2, Growth 10, Scale 50. A third camera needs a third socket, not a third key.
• Reconnect with backoff on an unexpected close. A closing frame tells you whether reconnecting will help.

How scans are counted

• One matched card is one scan, whether it arrived over HTTPS or the socket.
• A multi-card frame is billed per card matched. Nine cards in a binder photo where eight resolve is eight scans.
• An unresolved frame is zero. So is a rejected or malformed one.
• Scans never draw on your data credits, and catalog calls never draw on your scans. The two counters are reported separately on the dashboard and in X-TCGGraph-Scans-Remaining.
• Without a recognition plan, scans are drawn from your prepaid balance at $0.012 per matched card. With one, overage applies past the allowance and stops at the plan price.

Getting good frames

A phone camera in ordinary indoor light is enough, and no minimum resolution needs hitting. What actually moves the match rate:

• All four corners in frame. The collector number line is the primary key on most modern cards, and it lives in a corner.
• Light from the side, not the front. Head-on light bounces off foils and takes the set symbol with it — glare is the most common reason a frame is refused.
• Sleeves are fine unless a seam crosses a set symbol or a promo stamp. Worth knowing when you design the jig.
• Roughly flat and roughly square. Perspective is corrected; a card folded over a thumb is not.