Endpoint reference
This reference is generated from the same OpenAPI document published for clients. Expand an endpoint for parameters, request schema, examples where supplied, response schemas and authentication requirements. Schemas describe data; the linked guides explain workflow decisions.
Base URL: https://stratatcg.com/connector. Paths below append to that base. Personal API keys authenticate the public card routes; OAuth access tokens authenticate only the environment-specific agent gateway. Browser session and internal administration routes are not third-party APIs.
Use JSON content type on JSON POSTs and a stable Idempotency-Key for each billable logical request. Read per-item state even after HTTP 200. Authentication, OAuth, errors and retries, OpenAPI JSON.
GET /api/v1/identify
Discover endpoint usage
Authentication
[]Responses
HTTP 200
Endpoint contract
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiscoveryResponse"
},
"example": {
"service": "tcg-identify",
"version": "v1",
"endpoint": "POST /api/v1/identify",
"openapi": "/openapi.json",
"docs": "/llms.txt",
"auth": {
"required": true,
"type": "bearer",
"dashboard": "https://stratatcg.com/connector/dashboard#signup"
},
"limits": {
"monthlyPlansActive": false,
"accountLookups": 1000,
"globalLookups": 10000,
"maxBatch": 25
},
"billing": "Free beta. One unit per item.",
"example": {
"blobs": [
{
"text": "Charizard ex 199/165",
"hints": {
"game": "Pokemon"
}
}
]
}
}
}
}POST /api/v1/identify
Identify one or more products
A free account and API key are required. Create a key at https://stratatcg.com/connector/dashboard#signup, save it in your agent secret settings, and send Authorization: Bearer
Authentication
[
{
"ConnectorKey": []
}
]Parameters
[
{
"name": "enrich",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1"
]
}
},
{
"name": "trace",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1"
]
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "Monthly plans: reuse for identical logical retries to avoid duplicate credit charges."
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
},
"blobs": {
"minItems": 1,
"maxItems": 25,
"type": "array",
"items": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"text"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
}
},
"trace": {
"type": "boolean"
},
"enrich": {
"description": "Set true for ordinary agent lookups to identify and price together; false for identity-only requests. Omission does not request pricing.",
"type": "boolean"
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
},
"oneOf": [
{
"required": [
"text"
]
},
{
"required": [
"blobs"
]
}
]
}
}
}
}Responses
HTTP 200
Results with per-item status; pricing can be partial or need a selection
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Batch"
},
"example": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000001",
"count": 1,
"results": [
{
"ok": true,
"resultRef": "00000000-0000-4000-8000-000000000002",
"confident": true,
"source": "catalog",
"source_ref": {
"provider": "catalog",
"item": 517045
},
"status": "ok",
"selectionRequired": false,
"currency": "USD",
"strataProductId": "00000000-0000-4000-8000-000000000003",
"mappingRevision": 4,
"resolution": {
"status": "resolved"
},
"capabilities": {
"raw": {
"status": "supported"
}
}
}
],
"quota": null
}
}
}HTTP 400
Invalid request
{
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ApiError"
},
{
"$ref": "#/components/schemas/Batch"
}
]
},
"examples": {
"validationError": {
"value": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
},
"invalidBatch": {
"value": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000009",
"count": 1,
"results": [
{
"ok": false,
"status": "unavailable",
"error": "invalid_input",
"retryable": false
}
],
"quota": null
}
}
}
}
}HTTP 401
api_key_required, api_key_malformed, api_key_invalid, api_key_expired or api_key_revoked. Response includes setupUrl, docsUrl, steps, header and retryable:false. Do not retry without correcting credentials.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 409
An identical price request is still running; retry after the indicated delay
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 413
Payload too large
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 415
JSON required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 429
account_quota_exceeded, daily_limit or rate_limited. Retry-After is seconds; retryAt gives the earliest retry time.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 502
All items failed due to upstream errors
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Batch"
},
"example": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000009",
"count": 1,
"results": [
{
"ok": false,
"status": "unavailable",
"error": "upstream_error",
"retryable": true
}
],
"quota": null
}
}
}HTTP 503
Quota protection unavailable; request refused
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}GET /api/v1/enrich
Discover endpoint usage
Authentication
[]Responses
HTTP 200
Endpoint contract
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiscoveryResponse"
},
"example": {
"service": "tcg-identify",
"version": "v1",
"endpoint": "POST /api/v1/enrich",
"openapi": "/openapi.json",
"example": {
"productId": 517045,
"printing": "Foil",
"language": "English",
"condition": "Near Mint"
},
"limits": {
"monthlyPlansActive": false,
"accountLookups": 1000,
"globalLookups": 10000,
"maxBatch": 10
},
"notes": [
"Choose a printing and condition when selectionRequired is true.",
"Partial source failures are explicit."
]
}
}
}POST /api/v1/enrich
Price a product by printing, language and condition
A free account and API key are required. Create a key at https://stratatcg.com/connector/dashboard#signup, save it in your agent secret settings, and send Authorization: Bearer
Authentication
[
{
"ConnectorKey": []
}
]Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "Monthly plans: reuse for identical logical retries to avoid duplicate credit charges."
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"productIds": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"strataProductId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": {
"type": "string",
"enum": [
"card",
"sealed"
]
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"productId"
]
},
{
"required": [
"productIds"
]
},
{
"required": [
"strataProductId"
]
}
]
}
}
}
}Responses
HTTP 200
Results with per-item status; pricing can be partial or need a selection
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Batch"
},
"example": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000004",
"count": 1,
"results": [
{
"ok": true,
"status": "ok",
"selectionRequired": false,
"identityRef": {
"provider": "tcgplayer",
"entityType": "product",
"id": "517045"
},
"selection": {
"printing": "Holofoil",
"language": "English",
"condition": "Near Mint"
},
"quote": {
"status": "ok",
"amountCents": 1250,
"currency": "USD",
"sampleCount": 6
}
}
],
"quota": null
}
}
}HTTP 400
Invalid request
{
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ApiError"
},
{
"$ref": "#/components/schemas/Batch"
}
]
},
"examples": {
"validationError": {
"value": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
},
"invalidBatch": {
"value": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000009",
"count": 1,
"results": [
{
"ok": false,
"status": "unavailable",
"error": "invalid_input",
"retryable": false
}
],
"quota": null
}
}
}
}
}HTTP 401
api_key_required, api_key_malformed, api_key_invalid, api_key_expired or api_key_revoked. Response includes setupUrl, docsUrl, steps, header and retryable:false. Do not retry without correcting credentials.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 409
An identical price request is still running; retry after the indicated delay
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 413
Payload too large
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 415
JSON required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 429
account_quota_exceeded, daily_limit or rate_limited. Retry-After is seconds; retryAt gives the earliest retry time.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 502
All items failed due to upstream errors
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Batch"
},
"example": {
"version": "v1",
"requestId": "00000000-0000-4000-8000-000000000009",
"count": 1,
"results": [
{
"ok": false,
"status": "unavailable",
"error": "upstream_error",
"retryable": true
}
],
"quota": null
}
}
}HTTP 503
Quota protection unavailable; request refused
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}GET /api/billing/status
Discover active plans, or read account monthly usage with a bearer key
Without a key returns plan prices, rate limits and migration date. With a valid key after monthly activation returns the account balance and reset date.
Authentication
[]Responses
HTTP 200
Plan policy or account usage
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/BillingStatus"
},
"example": {
"monthlyPlansActive": false,
"monthlyPlansStartAt": null,
"checkoutEnabled": false,
"plans": {
"free": {
"name": "Free",
"credits": 1000,
"monthlyCents": 0,
"perMinute": 50
},
"pro": {
"name": "Pro",
"credits": 10000,
"monthlyCents": 1000,
"perMinute": 100
},
"scale": {
"name": "Scale",
"credits": 50000,
"monthlyCents": 5000,
"perMinute": 250
}
},
"accountLookups": 1000,
"period": "rolling_24_hours",
"globalLookups": 10000,
"windowSeconds": 86400,
"contactUrl": "mailto:tony@stratatcg.com?subject=Strata%20custom%20plan"
}
}
}HTTP 401
Invalid supplied API key
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}GET /api/v1/suggest
Suggest catalog matches without charging lookup credits
Account API key required. Suggestions are candidates, not an identity decision. Use identify to resolve a product before requesting prices.
Authentication
[
{
"ConnectorKey": []
}
]Parameters
[
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 120
}
},
{
"name": "kind",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"all",
"card",
"sealed"
],
"default": "all"
}
}
]Responses
HTTP 200
Ranked candidate suggestions; these are not verified identities
{
"application/json": {
"schema": {
"type": "object",
"required": [
"requestId",
"results"
],
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogSuggestion"
}
}
}
}
}
}HTTP 400
Invalid query or kind
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 401
An account API key is required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}POST /api/v1/confirm
Record an explicit user selection as private review evidence
Does not activate an alias or authorize a shared mapping. Confirmation is not billable and requires the original query and selected catalog product.
Authentication
[
{
"ConnectorKey": []
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"text",
"productId"
],
"properties": {
"text": {
"type": "string",
"minLength": 2,
"maxLength": 4000
},
"productId": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
}
}
}
}Responses
HTTP 202
Selection queued as pending review evidence
{
"application/json": {
"schema": {
"type": "object",
"required": [
"version",
"status",
"queued",
"candidateId",
"observations",
"productId",
"match"
],
"properties": {
"version": {
"type": "string",
"const": "v1"
},
"status": {
"type": "string",
"const": "pending_review"
},
"queued": {
"type": "boolean",
"const": true
},
"candidateId": {
"type": "string"
},
"observations": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"match": {
"$ref": "#/components/schemas/CatalogProduct"
}
}
}
}
}HTTP 400
Invalid selection
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 401
An account API key is required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 404
The product is not in the Strata catalog
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 503
The optional evidence queue is unavailable
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}POST /api/v1/feedback
Report a result correction or mapping concern
Feedback is private, idempotent evidence for review. It never directly approves a shared alias or cross-market link. resultRef is returned by identify and expires after 30 days.
Authentication
[
{
"ConnectorKey": []
}
]Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
}
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"resultRef",
"registry",
"action"
],
"properties": {
"resultRef": {
"type": "string",
"format": "uuid"
},
"registry": {
"type": "string",
"enum": [
"shorthand",
"linkage"
]
},
"action": {
"type": "string",
"enum": [
"correct_selection",
"wrong_identity",
"wrong_printing",
"insufficient_evidence"
]
},
"correctedRef": {
"type": "object"
},
"mappingRevision": {
"type": "integer",
"minimum": 0
},
"comment": {
"type": "string",
"maxLength": 500
}
}
}
}
}
}Responses
HTTP 202
Feedback accepted for registry review; no mapping is activated by this call.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackAccepted"
},
"example": {
"version": "v1",
"status": "pending_review",
"duplicate": false,
"feedbackId": "00000000-0000-4000-8000-000000000005"
}
}
}HTTP 400
Invalid feedback or missing idempotency key
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 404
Expired or account-inaccessible result reference
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 409
Idempotency key reused with different feedback
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 503
Feedback store unavailable
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}POST /api/v1/slabs/identify
Resolve a slab by cert, barcode or OCR label text
ALT cert identity is independent of TCGplayer. TAG cert-only lookup is explicitly unsupported. CardLadder is link-only; a generated URL is a cert search, not a verified permalink. No CardLadder data is fetched. Registry discovery is asynchronous and cannot erase graded identity.
Authentication
[
{
"ConnectorKey": []
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cert": {
"type": "string"
},
"grader": {
"type": "string"
},
"barcode": {
"type": "string"
},
"symbology": {
"type": "string"
},
"labelText": {
"type": "string"
},
"enrich": {
"type": "boolean"
}
},
"oneOf": [
{
"required": [
"cert"
]
},
{
"required": [
"barcode"
]
},
{
"required": [
"labelText"
]
}
]
}
}
}
}Responses
HTTP 200
Resolution, optional graded quote and populations, independent ALT reference, mapping revision, rawMatch progress/selectors, and optional CardLadder search link
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/SlabIdentityResponse"
},
"example": {
"requestId": "00000000-0000-4000-8000-000000000006",
"resolution": {
"status": "resolved"
},
"slabRef": {
"grader": "PSA",
"cert": "149085863"
},
"identityRef": {
"provider": "alt",
"entityType": "asset",
"id": "00000000-0000-4000-8000-000000000007"
},
"altAssetId": "00000000-0000-4000-8000-000000000007",
"strataProductId": null,
"mappingRevision": null,
"product": {
"name": "Example card",
"category": "Pokemon"
},
"rawMatch": {
"status": "unmapped"
},
"capabilities": {
"graded": {
"status": "supported"
},
"raw": {
"status": "unmapped"
}
},
"populations": [],
"cardLadderUrl": null
}
}
}HTTP 400
Invalid request
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 401
API key required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 429
Quota exceeded
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 503
Graded identity provider temporarily unavailable; not a not-found result
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}POST /api/v1/graded/prices
Get up to four ALT graded-market quotes
Each distinct grader, numeric grade, and tier is one billable market operation. Repeated equivalent selections are normalized and requested once; grades "10" and "10.0" are equivalent.
Authentication
[
{
"ConnectorKey": []
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"markets"
],
"oneOf": [
{
"required": [
"strataProductId"
]
},
{
"required": [
"ref"
]
}
],
"properties": {
"strataProductId": {
"type": "string",
"format": "uuid"
},
"ref": {
"type": "object",
"properties": {
"provider": {
"const": "alt"
},
"entityType": {
"const": "asset"
},
"id": {
"type": "string",
"format": "uuid"
}
}
},
"markets": {
"type": "array",
"minItems": 1,
"maxItems": 4,
"items": {
"type": "object",
"required": [
"grader",
"grade"
],
"properties": {
"grader": {
"type": "string"
},
"grade": {
"type": "string"
},
"tier": {
"type": [
"string",
"null"
]
}
}
}
},
"rawProductId": {
"type": "integer",
"minimum": 1,
"description": "TCGplayer product ID required for a raw-origin cross-market comparison."
},
"rawSelection": {
"type": "object",
"required": [
"printing",
"language"
],
"properties": {
"printing": {
"type": "string",
"maxLength": 80
},
"language": {
"type": "string",
"maxLength": 40
}
}
},
"basis": {
"type": "string",
"enum": [
"median",
"lastSale"
]
}
}
}
}
}
}Responses
HTTP 200
One isolated quote per distinct normalized market selection
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/GradedPricesResponse"
},
"example": {
"requestId": "00000000-0000-4000-8000-000000000008",
"status": "ok",
"identityRef": {
"provider": "alt",
"entityType": "asset",
"id": "00000000-0000-4000-8000-000000000007"
},
"mappingRevision": 4,
"altAssetId": "00000000-0000-4000-8000-000000000007",
"quotes": [
{
"market": {
"grader": "PSA",
"grade": "10",
"tier": null
},
"status": "ok",
"amountCents": 12500,
"currency": "USD",
"sampleCount": 8,
"stale": false
}
],
"cardLadderUrl": null
}
}
}HTTP 400
Invalid request
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 401
API key required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 429
Quota exceeded
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}GET /api/v1/products/{id}
Read a Strata product and its verified exact links
Authentication
[
{
"ConnectorKey": []
}
]Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
]Responses
HTTP 200
Identity, mappingRevision, verified links with printing/language scope, capabilities, and rawMatch with status/reason/selectors/revision/retryAfterSeconds. Proposed matches never supply prices.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductReadResponse"
},
"example": {
"strataProductId": "00000000-0000-4000-8000-000000000003",
"aliasOf": null,
"product": {
"kind": "card",
"name": "Example card"
},
"rawMatch": {
"status": "verified",
"selectors": {
"printing": "Holofoil",
"language": "English"
}
},
"mappingRevision": 4,
"verifiedLinks": [],
"capabilities": {
"raw": {
"status": "supported"
},
"graded": {
"status": "supported"
},
"sealed": {
"status": "unsupported"
}
}
}
}
}HTTP 401
API key required
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
},
"example": {
"error": "bad_request",
"detail": "The request is invalid.",
"retryable": false,
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}HTTP 404
Unknown product
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/SimpleError"
},
"example": {
"error": "not_found",
"requestId": "00000000-0000-4000-8000-000000000009"
}
}
}POST /api/agent/production
Use your connected Strata production account
Requires the operation-specific scope: account/billing_status → account:read; lookup → cards:read; prepare_billing/billing_action → billing:prepare. Preparation is a write, not payment approval. No operation executes a purchase. Return reviewUrl for separate human approval and poll the original action with bounded backoff; redirects are not payment confirmation. Lookups consume shared account credits and can record registry evidence. See /docs/oauth.md for full lifecycle, retry and status semantics.
Authentication
[
{
"AgentOAuth": [
"account:read"
]
},
{
"AgentOAuth": [
"cards:read"
]
},
{
"AgentOAuth": [
"billing:prepare"
]
}
]Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_.:-]{8,128}$"
},
"description": "Required for prepare_billing. Reuse unchanged for the same logical lookup/action and identical retries."
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"const": "account"
}
},
"required": [
"operation"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "billing_status"
}
},
"required": [
"operation"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "billing_action"
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"operation",
"id"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "prepare_billing"
},
"input": {
"type": "object",
"properties": {
"action": {
"enum": [
"subscribe",
"upgrade",
"downgrade",
"cancel",
"resume",
"payment_method",
"invoices"
]
},
"plan": {
"enum": [
"pro",
"scale"
]
},
"resumeContext": {
"type": "string",
"maxLength": 128
}
},
"required": [
"action"
],
"description": "plan is required for subscribe, upgrade and downgrade. resumeContext is an opaque job reference, not user text."
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "lookup"
},
"input": {
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"const": "identify"
},
"input": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
},
"blobs": {
"minItems": 1,
"maxItems": 25,
"type": "array",
"items": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"text"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
}
},
"trace": {
"type": "boolean"
},
"enrich": {
"description": "Set true for ordinary agent lookups to identify and price together; false for identity-only requests. Omission does not request pricing.",
"type": "boolean"
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
},
"oneOf": [
{
"required": [
"text"
]
},
{
"required": [
"blobs"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "enrich"
},
"input": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"productIds": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"strataProductId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": {
"type": "string",
"enum": [
"card",
"sealed"
]
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"productId"
]
},
{
"required": [
"productIds"
]
},
{
"required": [
"strataProductId"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "slabs"
},
"input": {
"type": "object",
"properties": {
"cert": {
"type": "string"
},
"grader": {
"type": "string"
},
"barcode": {
"type": "string"
},
"symbology": {
"type": "string"
},
"labelText": {
"type": "string"
},
"enrich": {
"type": "boolean"
}
},
"oneOf": [
{
"required": [
"cert"
]
},
{
"required": [
"barcode"
]
},
{
"required": [
"labelText"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "graded"
},
"input": {
"type": "object",
"required": [
"markets"
],
"oneOf": [
{
"required": [
"strataProductId"
]
},
{
"required": [
"ref"
]
}
],
"properties": {
"strataProductId": {
"type": "string",
"format": "uuid"
},
"ref": {
"type": "object",
"properties": {
"provider": {
"const": "alt"
},
"entityType": {
"const": "asset"
},
"id": {
"type": "string",
"format": "uuid"
}
}
},
"markets": {
"type": "array",
"minItems": 1,
"maxItems": 4,
"items": {
"type": "object",
"required": [
"grader",
"grade"
],
"properties": {
"grader": {
"type": "string"
},
"grade": {
"type": "string"
},
"tier": {
"type": [
"string",
"null"
]
}
}
}
},
"rawProductId": {
"type": "integer",
"minimum": 1,
"description": "TCGplayer product ID required for a raw-origin cross-market comparison."
},
"rawSelection": {
"type": "object",
"required": [
"printing",
"language"
],
"properties": {
"printing": {
"type": "string",
"maxLength": 80
},
"language": {
"type": "string",
"maxLength": 40
}
}
},
"basis": {
"type": "string",
"enum": [
"median",
"lastSale"
]
}
}
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "product"
},
"input": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
}
},
"required": [
"operation",
"input"
]
}
]
}
},
"required": [
"operation",
"input"
]
}
]
}
}
}
}Responses
HTTP 200
Account, billing state/action or public card operation result. Lookup shape matches the dispatched public endpoint.
{
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/AgentBillingAction"
},
{
"type": "object",
"properties": {
"account": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
},
"environment": {
"enum": [
"production",
"sandbox"
]
},
"usage": {
"type": "object"
},
"accountUrl": {
"type": "string"
},
"consoleUrl": {
"type": "string"
},
"supportUrl": {
"type": "string"
}
},
"required": [
"account",
"environment",
"usage",
"accountUrl",
"consoleUrl",
"supportUrl"
]
},
{
"type": "object",
"properties": {
"environment": {
"enum": [
"production",
"sandbox"
]
}
},
"required": [
"environment"
]
},
{
"$ref": "#/components/schemas/Batch"
},
{
"$ref": "#/components/schemas/Batch"
},
{
"$ref": "#/components/schemas/SlabIdentityResponse"
},
{
"$ref": "#/components/schemas/GradedPricesResponse"
},
{
"$ref": "#/components/schemas/ProductReadResponse"
}
]
}
}
}HTTP 201
Prepared action, or replay of the same preparation key. No purchase performed.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentBillingAction"
}
}
}HTTP 400
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 401
Refresh or reconnect
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 403
Missing scope or tester access
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 404
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 409
Conflict, changed quote or pending outcome: inspect error code
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 429
Honor Retry-After; do not evade limits
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 502
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 503
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}POST /api/agent/sandbox
Use your connected Strata sandbox account
Requires the operation-specific scope: account/billing_status → account:read; lookup → cards:read; prepare_billing/billing_action → billing:prepare. Preparation is a write, not payment approval. No operation executes a purchase. Return reviewUrl for separate human approval and poll the original action with bounded backoff; redirects are not payment confirmation. Lookups consume shared account credits and can record registry evidence. See /docs/oauth.md for full lifecycle, retry and status semantics.
Authentication
[
{
"AgentOAuth": [
"account:read"
]
},
{
"AgentOAuth": [
"cards:read"
]
},
{
"AgentOAuth": [
"billing:prepare"
]
}
]Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_.:-]{8,128}$"
},
"description": "Required for prepare_billing. Reuse unchanged for the same logical lookup/action and identical retries."
}
]Request
{
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"const": "account"
}
},
"required": [
"operation"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "billing_status"
}
},
"required": [
"operation"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "billing_action"
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"operation",
"id"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "prepare_billing"
},
"input": {
"type": "object",
"properties": {
"action": {
"enum": [
"subscribe",
"upgrade",
"downgrade",
"cancel",
"resume",
"payment_method",
"invoices"
]
},
"plan": {
"enum": [
"pro",
"scale"
]
},
"resumeContext": {
"type": "string",
"maxLength": 128
}
},
"required": [
"action"
],
"description": "plan is required for subscribe, upgrade and downgrade. resumeContext is an opaque job reference, not user text."
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "lookup"
},
"input": {
"oneOf": [
{
"type": "object",
"properties": {
"operation": {
"const": "identify"
},
"input": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
},
"blobs": {
"minItems": 1,
"maxItems": 25,
"type": "array",
"items": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"shape": {
"type": "string",
"enum": [
"ocr",
"listing",
"title",
"cert",
"freeform"
]
},
"hints": {
"type": "object",
"properties": {
"number": {
"type": "string",
"maxLength": 40
},
"game": {
"type": "string",
"enum": [
"Pokemon",
"Pokemon Japan",
"Magic",
"One Piece",
"Lorcana",
"Riftbound",
"Gundam",
"Dragon Ball Z",
"Dragon Ball Super",
"Dragon Ball Fusion World"
]
}
},
"additionalProperties": false
},
"source": {
"$ref": "#/$defs/__schema0"
}
},
"required": [
"text"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
}
}
},
"trace": {
"type": "boolean"
},
"enrich": {
"description": "Set true for ordinary agent lookups to identify and price together; false for identity-only requests. Omission does not request pricing.",
"type": "boolean"
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
}
},
"oneOf": [
{
"required": [
"text"
]
},
{
"required": [
"blobs"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "enrich"
},
"input": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"productIds": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"strataProductId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"kind": {
"type": "string",
"enum": [
"card",
"sealed"
]
},
"printing": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"language": {
"default": "English",
"type": "string",
"minLength": 1,
"maxLength": 40
},
"condition": {
"type": "string",
"enum": [
"Near Mint",
"Lightly Played",
"Moderately Played",
"Heavily Played",
"Damaged",
"Unopened",
"NM",
"LP",
"MP",
"HP",
"DMG"
]
}
},
"required": [
"language"
],
"additionalProperties": false,
"oneOf": [
{
"required": [
"productId"
]
},
{
"required": [
"productIds"
]
},
{
"required": [
"strataProductId"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "slabs"
},
"input": {
"type": "object",
"properties": {
"cert": {
"type": "string"
},
"grader": {
"type": "string"
},
"barcode": {
"type": "string"
},
"symbology": {
"type": "string"
},
"labelText": {
"type": "string"
},
"enrich": {
"type": "boolean"
}
},
"oneOf": [
{
"required": [
"cert"
]
},
{
"required": [
"barcode"
]
},
{
"required": [
"labelText"
]
}
]
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "graded"
},
"input": {
"type": "object",
"required": [
"markets"
],
"oneOf": [
{
"required": [
"strataProductId"
]
},
{
"required": [
"ref"
]
}
],
"properties": {
"strataProductId": {
"type": "string",
"format": "uuid"
},
"ref": {
"type": "object",
"properties": {
"provider": {
"const": "alt"
},
"entityType": {
"const": "asset"
},
"id": {
"type": "string",
"format": "uuid"
}
}
},
"markets": {
"type": "array",
"minItems": 1,
"maxItems": 4,
"items": {
"type": "object",
"required": [
"grader",
"grade"
],
"properties": {
"grader": {
"type": "string"
},
"grade": {
"type": "string"
},
"tier": {
"type": [
"string",
"null"
]
}
}
}
},
"rawProductId": {
"type": "integer",
"minimum": 1,
"description": "TCGplayer product ID required for a raw-origin cross-market comparison."
},
"rawSelection": {
"type": "object",
"required": [
"printing",
"language"
],
"properties": {
"printing": {
"type": "string",
"maxLength": 80
},
"language": {
"type": "string",
"maxLength": 40
}
}
},
"basis": {
"type": "string",
"enum": [
"median",
"lastSale"
]
}
}
}
},
"required": [
"operation",
"input"
]
},
{
"type": "object",
"properties": {
"operation": {
"const": "product"
},
"input": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
}
},
"required": [
"operation",
"input"
]
}
]
}
},
"required": [
"operation",
"input"
]
}
]
}
}
}
}Responses
HTTP 200
Account, billing state/action or public card operation result. Lookup shape matches the dispatched public endpoint.
{
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/AgentBillingAction"
},
{
"type": "object",
"properties": {
"account": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
},
"environment": {
"enum": [
"production",
"sandbox"
]
},
"usage": {
"type": "object"
},
"accountUrl": {
"type": "string"
},
"consoleUrl": {
"type": "string"
},
"supportUrl": {
"type": "string"
}
},
"required": [
"account",
"environment",
"usage",
"accountUrl",
"consoleUrl",
"supportUrl"
]
},
{
"type": "object",
"properties": {
"environment": {
"enum": [
"production",
"sandbox"
]
}
},
"required": [
"environment"
]
},
{
"$ref": "#/components/schemas/Batch"
},
{
"$ref": "#/components/schemas/Batch"
},
{
"$ref": "#/components/schemas/SlabIdentityResponse"
},
{
"$ref": "#/components/schemas/GradedPricesResponse"
},
{
"$ref": "#/components/schemas/ProductReadResponse"
}
]
}
}
}HTTP 201
Prepared action, or replay of the same preparation key. No purchase performed.
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentBillingAction"
}
}
}HTTP 400
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 401
Refresh or reconnect
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 403
Missing scope or tester access
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 404
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 409
Conflict, changed quote or pending outcome: inspect error code
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 429
Honor Retry-After; do not evade limits
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 502
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}HTTP 503
Request could not complete; inspect error code and retryable
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string"
}
},
"required": [
"error"
]
}
}
}Shared response schemas
{
"CatalogProduct": {
"type": "object",
"required": [
"productId",
"kind",
"name",
"set",
"number",
"rarity",
"game",
"url",
"image",
"imageLarge"
],
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"kind": {
"type": "string",
"enum": [
"card",
"sealed"
]
},
"name": {
"type": "string"
},
"set": {
"type": [
"string",
"null"
]
},
"number": {
"type": [
"string",
"null"
]
},
"rarity": {
"type": [
"string",
"null"
]
},
"game": {
"type": [
"string",
"null"
]
},
"url": {
"type": "string",
"format": "uri"
},
"image": {
"type": "string",
"format": "uri"
},
"imageLarge": {
"type": "string",
"format": "uri"
}
}
},
"CatalogSuggestion": {
"type": "object",
"required": [
"productId",
"kind",
"name",
"set",
"number",
"game",
"image"
],
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"kind": {
"type": "string",
"enum": [
"card",
"sealed"
]
},
"name": {
"type": "string"
},
"set": {
"type": [
"string",
"null"
]
},
"number": {
"type": [
"string",
"null"
]
},
"game": {
"type": [
"string",
"null"
]
},
"image": {
"type": "string",
"format": "uri"
}
}
},
"Batch": {
"type": "object",
"required": [
"version",
"requestId",
"results"
],
"properties": {
"version": {
"type": "string"
},
"requestId": {
"type": "string"
},
"count": {
"type": "integer"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"resultRef": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "Opaque account-bound reference for optional POST /api/v1/feedback; retained for 30 days."
},
"confident": {
"type": "boolean"
},
"source": {
"type": "string",
"description": "unsupported indicates a known coverage gap, not a substitute match."
},
"reason": {
"type": "string",
"description": "unsupported_release means the reviewed release is absent from the current catalog."
},
"detail": {
"type": "string"
},
"nextAction": {
"type": "string"
},
"unsupported": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"game": {
"type": "string"
},
"language": {
"type": "string"
}
}
},
"error": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"ok",
"partial",
"no_data",
"selection_required",
"unavailable",
"unsupported",
"skipped"
]
},
"selectionRequired": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"fetchedAt": {
"type": "string",
"format": "date-time"
},
"cacheAgeSeconds": {
"type": "integer"
},
"strataProductId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"identityRef": {
"type": [
"object",
"null"
]
},
"mappingRevision": {
"type": [
"integer",
"null"
]
},
"resolution": {
"type": "object",
"description": "Resolved, selection required, ambiguous, unsupported, or not found."
},
"source_ref": {},
"selection": {
"type": "object",
"description": "The printing, language and market condition actually priced."
},
"market": {
"type": "object",
"description": "Optional raw/sealed price result. Its nested quote can be absent or null; inspect status and amountCents."
},
"capabilities": {
"type": "object",
"description": "Raw, graded and sealed support status and reason."
},
"quote": {
"$ref": "#/components/schemas/PriceQuote"
}
}
}
},
"quota": {
"type": [
"object",
"null"
]
}
}
},
"PriceQuote": {
"type": "object",
"description": "Sales-derived quote. Missing data has amountCents:null, never zero.",
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"partial",
"no_data",
"unavailable",
"unsupported",
"selection_required"
]
},
"amountCents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string",
"example": "USD"
},
"basis": {
"type": [
"object",
"null"
]
},
"window": {
"type": [
"object",
"null"
]
},
"sampleCount": {
"type": "integer"
},
"lastSale": {
"type": [
"object",
"null"
]
},
"observedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastSuccessAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cacheAge": {
"type": [
"integer",
"null"
]
},
"stale": {
"type": "boolean"
},
"sales": {
"type": "array",
"items": {
"type": "object"
}
},
"listings": {
"type": "array",
"items": {
"type": "object"
}
},
"benchmarks": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"ApiError": {
"type": "object",
"required": [
"error",
"detail",
"retryable"
],
"properties": {
"error": {
"type": "string"
},
"detail": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"requestId": {
"type": "string",
"format": "uuid"
},
"retryAfterSeconds": {
"type": "integer",
"minimum": 1
},
"retryAt": {
"type": "string",
"format": "date-time"
},
"setupUrl": {
"type": "string",
"format": "uri"
},
"docsUrl": {
"type": "string",
"format": "uri"
},
"steps": {
"type": "array",
"items": {
"type": "string"
}
},
"header": {
"type": "string"
},
"remaining": {
"type": "integer",
"minimum": 0
},
"requiredCredits": {
"type": "integer",
"minimum": 0
},
"resetsAt": {
"type": "string",
"format": "date-time"
},
"billingUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": true
},
"SimpleError": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"requestId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true
},
"DiscoveryResponse": {
"type": "object",
"required": [
"service",
"version",
"endpoint",
"openapi",
"limits"
],
"properties": {
"service": {
"type": "string"
},
"version": {
"type": "string"
},
"auth": {
"type": "object"
},
"endpoint": {
"type": "string"
},
"openapi": {
"type": "string"
},
"docs": {
"type": "string"
},
"limits": {
"type": "object"
},
"billing": {
"type": "string"
},
"example": {
"type": "object"
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BillingStatus": {
"oneOf": [
{
"$ref": "#/components/schemas/PlanPolicy"
},
{
"$ref": "#/components/schemas/MonthlyUsage"
},
{
"$ref": "#/components/schemas/LegacyBillingStatus"
}
]
},
"PlanPolicy": {
"type": "object",
"required": [
"monthlyPlansActive",
"monthlyPlansStartAt",
"checkoutEnabled",
"plans"
],
"properties": {
"monthlyPlansActive": {
"type": "boolean"
},
"monthlyPlansStartAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"checkoutEnabled": {
"type": "boolean"
},
"plans": {
"type": "object"
},
"accountLookups": {
"type": "integer"
},
"period": {
"type": "string",
"enum": [
"calendar_month",
"rolling_24_hours"
]
},
"globalLookups": {
"type": "integer"
},
"windowSeconds": {
"type": [
"integer",
"null"
]
},
"contactUrl": {
"type": "string",
"format": "uri"
}
}
},
"MonthlyUsage": {
"type": "object",
"required": [
"plan",
"period",
"limit",
"used",
"remaining",
"resetsAt",
"perMinute"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"pro",
"scale"
]
},
"period": {
"type": "string",
"const": "month"
},
"limit": {
"type": "integer"
},
"used": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"resetsAt": {
"type": "string",
"format": "date-time"
},
"perMinute": {
"type": "integer"
},
"lowBalance": {
"type": "boolean"
},
"subscriptionStatus": {
"type": [
"string",
"null"
]
},
"hasCustomer": {
"type": "boolean"
},
"checkoutEnabled": {
"type": "boolean"
},
"portalEnabled": {
"type": "boolean"
},
"plans": {
"type": "object"
},
"billingUrl": {
"type": "string",
"format": "uri"
}
}
},
"LegacyBillingStatus": {
"type": "object",
"required": [
"billingEnabled"
],
"properties": {
"billingEnabled": {
"type": "boolean"
},
"accountRequired": {
"type": "boolean"
},
"plan": {
"type": "string"
},
"accountLookups": {
"type": "integer"
},
"globalLookups": {
"type": "integer"
},
"windowSeconds": {
"type": "integer"
},
"credits": {
"type": "integer"
}
}
},
"FeedbackAccepted": {
"type": "object",
"required": [
"version",
"status",
"duplicate",
"feedbackId"
],
"properties": {
"version": {
"type": "string",
"const": "v1"
},
"status": {
"type": "string",
"enum": [
"pending_review",
"reported_for_review"
]
},
"duplicate": {
"type": "boolean"
},
"feedbackId": {
"type": "string",
"format": "uuid"
}
}
},
"SlabIdentityResponse": {
"type": "object",
"required": [
"requestId",
"resolution"
],
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"resolution": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"resolved",
"selection_required",
"unsupported",
"not_found",
"unavailable"
]
},
"reason": {
"type": "string"
}
}
},
"slabRef": {
"type": "object"
},
"strataProductId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"mappingRevision": {
"type": [
"integer",
"null"
]
},
"identityRef": {
"type": "object"
},
"altAssetId": {
"type": "string",
"format": "uuid"
},
"product": {
"type": "object"
},
"productId": {
"type": [
"string",
"null"
]
},
"rawMatch": {
"type": "object"
},
"capabilities": {
"type": "object"
},
"market": {
"type": "object"
},
"populations": {
"type": "array",
"items": {
"type": "object"
}
},
"quote": {
"$ref": "#/components/schemas/PriceQuote"
},
"cardLadderUrl": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"GradedMarketQuote": {
"type": "object",
"required": [
"market",
"status"
],
"properties": {
"market": {
"type": "object",
"required": [
"grader",
"grade"
],
"properties": {
"grader": {
"type": "string"
},
"grade": {
"type": "string"
},
"tier": {
"type": [
"string",
"null"
]
}
}
},
"status": {
"type": "string",
"enum": [
"ok",
"partial",
"no_data",
"unavailable",
"unsupported"
]
},
"amountCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"currency": {
"type": "string",
"const": "USD"
},
"reason": {
"type": [
"string",
"null"
]
},
"basis": {
"type": [
"object",
"null"
]
},
"sampleCount": {
"type": "integer",
"minimum": 0
},
"observedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastSuccessAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cacheAge": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"stale": {
"type": "boolean"
}
}
},
"GradedPricesResponse": {
"type": "object",
"required": [
"requestId"
],
"properties": {
"requestId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"ok",
"partial",
"unsupported"
]
},
"reason": {
"type": "string"
},
"identityRef": {
"type": "object"
},
"mappingRevision": {
"type": [
"integer",
"null"
]
},
"strataProductId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"rawMatch": {
"type": "object",
"description": "Verified raw mapping or automatic background discovery status. Pending candidates are never usable mappings. Optional discovery failure does not invalidate graded quotes.",
"properties": {
"status": {
"type": "string",
"enum": [
"verified",
"queued",
"resolving",
"review_required",
"unmapped",
"unsupported",
"unavailable",
"catalog_version_refreshed"
]
},
"productId": {
"type": "integer",
"minimum": 1
},
"selectors": {
"type": [
"object",
"null"
]
},
"revision": {
"type": [
"integer",
"null"
]
},
"reason": {
"type": "string"
},
"retryAfterSeconds": {
"type": "integer",
"minimum": 0
}
}
},
"altAssetId": {
"type": "string",
"format": "uuid"
},
"quotes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GradedMarketQuote"
}
},
"cardLadderUrl": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"ProductReadResponse": {
"type": "object",
"required": [
"strataProductId",
"product",
"rawMatch",
"mappingRevision",
"verifiedLinks",
"capabilities"
],
"properties": {
"strataProductId": {
"type": "string",
"format": "uuid"
},
"aliasOf": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"product": {
"type": "object"
},
"rawMatch": {
"type": "object"
},
"mappingRevision": {
"type": "integer"
},
"verifiedLinks": {
"type": "array",
"items": {
"type": "object"
}
},
"capabilities": {
"type": "object"
}
}
},
"AgentBillingAction": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"environment": {
"enum": [
"production",
"sandbox"
]
},
"action": {
"enum": [
"subscribe",
"upgrade",
"downgrade",
"cancel",
"resume",
"payment_method",
"invoices"
]
},
"plan": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"quoted",
"pending",
"requires_action",
"confirmed",
"cancelled",
"expired",
"failed",
"handoff_ready"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"reviewUrl": {
"type": "string",
"format": "uri"
},
"quote": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"seller": {
"type": "string"
},
"amountDue": {
"type": "integer",
"minimum": 0
},
"monthlyCents": {
"type": "integer"
},
"creditDelta": {
"type": "integer"
},
"timing": {
"type": "string"
},
"refundPolicy": {
"type": "string"
},
"termsUrl": {
"type": "string"
},
"taxNote": {
"type": "string"
}
},
"required": [
"currency",
"seller",
"amountDue",
"timing",
"refundPolicy",
"termsUrl"
]
},
"resumeContext": {
"type": [
"string",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"environment",
"action",
"plan",
"status",
"createdAt",
"expiresAt",
"reviewUrl",
"quote",
"resumeContext",
"detail"
]
}
}