Products, identities and mappings
GET /api/v1/products/{id} reads a Strata product and its current capabilities or registry progress. Use the strataProductId UUID returned by identification; a numeric TCGplayer ID is not a Strata UUID. This authenticated read uses no lookup credits. It does not identify arbitrary text or create a mapping on demand.
Keep identifiers distinct
| Identifier | Represents | Next use |
|---|---|---|
productId |
Numeric TCGplayer catalog product; printing may still require selection. | Raw/sealed enrich; explicit catalog confirmation. |
strataProductId |
Strata UUID returned by identity resolution. | Product capabilities, verified raw/graded pricing. |
identityRef |
Provider identity, such as an ALT asset. | Pass as ref to graded pricing. |
cert and grader |
A particular graded copy's certification evidence. | Slab identification. |
resultRef |
Account-bound evidence for a past identification, not a product. | Feedback during its retention period. |
mappingRevision |
Revision of an observed cross-market relationship. | Detect changed mappings before reusing a comparison. |
A physical slab, an underlying card, a catalog product and a market selection are different things. Two copies can share the same underlying market without sharing a cert. A catalog product can contain finishes that map to different graded assets.
Read capabilities before composing markets
Inspect capabilities and rawMatch rather than assuming every product supports both price sources. rawMatch.status distinguishes:
| State | What the agent should do |
|---|---|
verified |
Use the returned link and its exact printing/language selectors. |
queued / resolving |
Preserve the original result. A bounded later read may observe progress. |
review_required |
Explain that a mapping needs review; do not infer a price through it. |
unmapped |
Show the available market without a cross-market comparison. |
unsupported |
Explain the coverage limitation; do not substitute another language or edition. |
unavailable |
Treat as a service failure, not proof that no mapping exists. |
When available, honor retryAfterSeconds. Poll only while the user is waiting for that product, with a bounded stop condition. Do not continuously crawl registry progress.
Slab to raw
Resolve the slab through /api/v1/slabs/identify first. Keep the graded result even when no TCGplayer match exists. After the registry supplies a verified raw mapping, call /api/v1/enrich with the returned Strata UUID and the desired raw condition. The API enforces mapping selectors; conflicting selections return 409. Label the result “Raw · Near Mint reference” when using NM. Slab grade does not establish raw condition.
Raw to graded
After raw identification, choose the actual printing and language. Request /api/v1/graded/prices with strataProductId, rawProductId and rawSelection matching that verified link, plus explicit grade markets. Once the link and selectors are known, raw and graded pricing may run concurrently. Do not fall back to a similarly named ALT asset when a link is absent.
See recipes, graded prices, registry feedback, and endpoint schemas.