Identify

POST /api/v1/identify, JSON body. Use either text or blobs, not both. For ordinary agent lookups, explicitly set enrich:true to identify and price together unless the user asks for identity only. Resolve ambiguity before quoting; missing pricing does not erase a successful identity. See result presentation for links, images and price context.

{
  "blobs": [
    {
      "text": "Charizard ex 199/165 151",
      "shape": "listing",
      "hints": { "number": "199/165", "game": "Pokemon" },
      "source": { "row": 4 }
    }
  ],
  "enrich": true,
  "printing": "Foil",
  "language": "English",
  "condition": "Near Mint"
}

The example prices an English Foil Near Mint reference; it does not assess a physical card's condition.

Text: 1–4,000 characters. Batch: 1–25 items. Total body: 128 KiB. source is opaque JSON up to 2 KiB and returns as source_ref. shape accepts ocr, listing, title, cert, or freeform. hints.number is up to 40 characters. hints.game restricts candidates to a supported game; unknown values are rejected.

Supported games: Pokemon, Pokemon Japan, Magic, One Piece, Lorcana, Riftbound, Gundam, Dragon Ball Z, Dragon Ball Super, Dragon Ball Fusion World.

Query trace=1 or body trace:true includes the decision trace. Query enrich=1 or body enrich:true requests pricing for confident matches; this reserves two quota units per valid item. Optional pricing selectors: printing, language (default English), and condition (NM, LP, MP, HP, DMG or Unopened, or their full names).

Responses preserve batch order. ok:false is an item failure. confident:false means the match is a guess: show alternatives and ask. No published accuracy estimate exists. score is a ranking signal, not a calibrated probability.

Malformed items are isolated. If every item is invalid the response is 400; if all valid work fails it is 502. Mixed outcomes return 200 with per-item status. No request can learn an alias for other users. Reviewed aliases preserve explicit finish, variant and language constraints.

POST /api/v1/confirm records a user's explicit selection of one candidate in an agent's results as a pending alias-review candidate. It does not activate an alias or change future matches; configured reviewers still approve or reject it. For a candidate list without an identity decision, use GET /api/v1/suggest. Suggestions are not identity decisions and do not spend lookup credits.

When feedback storage is enabled, successful identify results include an opaque resultRef retained for 30 days and bound to the requesting account. Agents can use POST /api/v1/feedback with that reference and an Idempotency-Key to report a corrected selection, wrong identity/printing, or insufficient evidence. Feedback is private review evidence; it does not publish a mapping. Keep the reference with the result and do not share it across accounts.

Known unsupported releases

When source is unsupported and reason is unsupported_release, explain detail and follow nextAction. Do not retry with English substitutes or price another printing. Preserve the card language in the query and language field. See https://stratatcg.com/connector/docs/coverage.md .