# 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](./agent-workflows.md) for links, images and price context.

```json
{
  "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`](./suggest.md). 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 .