# Recipes

## Photo

Let the calling agent read the image using its existing vision capability.
Extract a short string with the printed name, collector number, game, set,
language and visible variant clues. Send one blob per card with `shape:"ocr"`;
this shape also covers model-read text. Put only clearly read numbers in
`hints.number`. Do not confuse names in rules text with the card title.

Use [the reusable skill](./skills/tcg-identify/SKILL.md) for the full workflow.
Review extracted text before any lookup; tiny, stylized or obscured text may need
manual correction. Photos stay with the calling agent. Send only the reviewed
identifying text to Strata; image reading alone does not establish a catalog match.

## Bulk list

Split into identification batches of at most 25. Processing is bounded to four
concurrent items per request. Monthly credits charge successful confident identities and usable selected-market prices; ambiguous identities are not charged. On 429 stop and honor Retry-After. Price confirmed products in
batches of at most ten and choose their printing/language/condition.

## Slab identity and graded prices

Use `POST /api/v1/slabs/identify` with `{"cert":"149085863","grader":"PSA","enrich":true}`.
A recognized cert returns its ALT identity, grade, optional population report and graded quote even when no raw catalog match exists. Barcode URLs and readable cert-label text are alternative inputs. TAG is explicitly unsupported. `shape:"cert"` on `/identify` searches the underlying raw catalog; it does not resolve the physical slab.

To price more grades, call `POST /api/v1/graded/prices` with the returned `strataProductId`, or its `identityRef` as `ref`, and up to four `markets`, for example `[{"grader":"PSA","grade":"9"},{"grader":"PSA","grade":"10"}]`. Each distinct grader, numeric grade, and tier is one market operation. Repeated equivalent selections are normalized and requested once, so `"10"` and `"10.0"` for PSA do not produce duplicate quotes or charges. ALT uses `10.5` to distinguish BGS Black Label and CGC Pristine; this is not a PSA grade. Grade/tier identities must remain separate.

## Verified raw comparison and registry progress

Read `GET /api/v1/products/{strataProductId}`. `rawMatch.status` may be `queued`, `resolving`, `verified`, `review_required`, `unmapped`, `unsupported` or `unavailable`. Only `verified` supplies a cross-market price. A raw-match proposal never changes the graded identity or its quote.

For a verified match, call `/enrich` with the same `strataProductId` and `condition:"NM"`. The API enforces the mapping's printing and language; conflicting selections return 409. Label this **Raw · NM reference**; a slab grade does not establish its raw condition. Preserve `mappingRevision` and revalidate it before reusing a cached cross-market comparison. A raw and graded price request can run concurrently once the identity and exact mapping are known.

A raw caller normally uses `/identify` with `enrich:true`; use a separate `/enrich` only when pricing was not already returned or a new selection is requested. To request graded prices, pass its `strataProductId`, the matched TCGplayer ID as `rawProductId`, and `rawSelection:{"printing":"Foil","language":"English"}` to `/graded/prices`. A scoped mapping requires matching selectors. The broad catalog UUID is retained even when different finishes link to different graded identities.

Poll only an open detail while matching is queued/resolving, honor `retryAfterSeconds`, and stop after a bounded interval or when the view closes/backgrounds. A later detail open can reread the mapping. No match is normal; `unavailable` means retryable failure, not absence from the catalog.

## App authentication and contributions

Connector customers use their own API keys. Strata app users use the app's existing session; they do not need connector keys. The first-party backend calls private, separately budgeted catalog operations. Service credentials never ship in the app and discovery does not consume another user scan.

Optional app feedback uses the first-party `POST /api/v1/products/{id}/raw-match-feedback` with a signed-in app session and either `{"action":"propose","productId":123}` or `{"action":"report"}`. This creates review evidence only. It is not a public connector approval endpoint. Operator approval verifies all relevant identity axes; sports and foreign-language graded results remain independent of catalog coverage.

CardLadder data is not scraped. A generated `cardLadderUrl` is a search link, not a verified card permalink.

## Partial outage

Keep a successful identification even if its `market.status` is unavailable.
For partial pricing, show which sources failed and the observation timestamp.
Never replace an unavailable observation with zero or infer no sales occurred.