{ "openapi": "3.1.0", "info": { "title": "Strata TCG API", "version": "1.2.0" }, "servers": [ { "url": "https://stratatcg.com/connector" } ], "paths": { "/api/v1/identify": { "get": { "summary": "Discover endpoint usage", "responses": { "200": { "description": "Endpoint contract", "content": { "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": { "operationId": "identify", "summary": "Identify one or more products", "description": "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 . GET /api/billing/status reports the active allowance and monthly transition date. Each item costs one credit; identify with enrichment reserves two. Before the monthly transition, beta quota counts attempts. Monthly credits charge successful, confident identification and successful pricing; unused reservations are returned. Select exactly one shorthand or batch input field. The public plan catalog is Free 1,000 credits/month, Pro 10,000 for $10/month, and Scale 50,000 for $50/month. Activation and checkout availability are live policy and must be read from GET /api/billing/status; do not infer availability from these catalog amounts. See /docs/monthly-plans.md. After monthly activation, unused or failed reservations are refunded.", "security": [ { "ConnectorKey": [] } ], "requestBody": { "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" ] } ] } } } }, "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." } ], "responses": { "200": { "description": "Results with per-item status; pricing can be partial or need a selection", "content": { "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 } } } }, "400": { "description": "Invalid request", "content": { "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 } } } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "409": { "description": "An identical price request is still running; retry after the indicated delay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "429": { "description": "account_quota_exceeded, daily_limit or rate_limited. Retry-After is seconds; retryAt gives the earliest retry time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "502": { "description": "All items failed due to upstream errors", "content": { "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 } } } }, "503": { "description": "Quota protection unavailable; request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/enrich": { "get": { "summary": "Discover endpoint usage", "responses": { "200": { "description": "Endpoint contract", "content": { "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": { "operationId": "enrich", "summary": "Price a product by printing, language and condition", "description": "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 . GET /api/billing/status reports the active allowance and monthly transition date. Each item costs one credit; identify with enrichment reserves two. Before the monthly transition, beta quota counts attempts. Monthly credits charge successful, confident identification and successful pricing; unused reservations are returned. Select exactly one shorthand or batch input field. The public plan catalog is Free 1,000 credits/month, Pro 10,000 for $10/month, and Scale 50,000 for $50/month. Activation and checkout availability are live policy and must be read from GET /api/billing/status; do not infer availability from these catalog amounts. See /docs/monthly-plans.md. After monthly activation, unused or failed reservations are refunded. An identical single-product price request without an Idempotency-Key is replayed for the same account for 30 seconds without another credit. Explicit Idempotency-Key semantics take precedence.", "security": [ { "ConnectorKey": [] } ], "requestBody": { "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" ] } ] } } } }, "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." } ], "responses": { "200": { "description": "Results with per-item status; pricing can be partial or need a selection", "headers": { "X-Strata-Replayed": { "description": "true when an identical single-product request was replayed without another credit.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "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 } } } }, "400": { "description": "Invalid request", "content": { "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 } } } } } }, "401": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "409": { "description": "An identical price request is still running; retry after the indicated delay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "429": { "description": "account_quota_exceeded, daily_limit or rate_limited. Retry-After is seconds; retryAt gives the earliest retry time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "502": { "description": "All items failed due to upstream errors", "content": { "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 } } } }, "503": { "description": "Quota protection unavailable; request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/billing/status": { "get": { "summary": "Discover active plans, or read account monthly usage with a bearer key", "description": "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.", "responses": { "200": { "description": "Plan policy or account usage", "content": { "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" } } } }, "401": { "description": "Invalid supplied API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/suggest": { "get": { "operationId": "suggest", "summary": "Suggest catalog matches without charging lookup credits", "description": "Account API key required. Suggestions are candidates, not an identity decision. Use identify to resolve a product before requesting prices.", "security": [ { "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": { "200": { "description": "Ranked candidate suggestions; these are not verified identities", "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "results" ], "properties": { "requestId": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSuggestion" } } } } } } }, "400": { "description": "Invalid query or kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "401": { "description": "An account API key is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/confirm": { "post": { "operationId": "confirm", "summary": "Record an explicit user selection as private review evidence", "description": "Does not activate an alias or authorize a shared mapping. Confirmation is not billable and requires the original query and selected catalog product.", "security": [ { "ConnectorKey": [] } ], "requestBody": { "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": { "202": { "description": "Selection queued as pending review evidence", "content": { "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" } } } } } }, "400": { "description": "Invalid selection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "401": { "description": "An account API key is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "404": { "description": "The product is not in the Strata catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "503": { "description": "The optional evidence queue is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/feedback": { "post": { "operationId": "submitRegistryFeedback", "summary": "Report a result correction or mapping concern", "description": "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.", "security": [ { "ConnectorKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "requestBody": { "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": { "202": { "description": "Feedback accepted for registry review; no mapping is activated by this call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackAccepted" }, "example": { "version": "v1", "status": "pending_review", "duplicate": false, "feedbackId": "00000000-0000-4000-8000-000000000005" } } } }, "400": { "description": "Invalid feedback or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "404": { "description": "Expired or account-inaccessible result reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "409": { "description": "Idempotency key reused with different feedback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "503": { "description": "Feedback store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/slabs/identify": { "post": { "operationId": "identifySlab", "summary": "Resolve a slab by cert, barcode or OCR label text", "description": "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.", "security": [ { "ConnectorKey": [] } ], "requestBody": { "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": { "200": { "description": "Resolution, optional graded quote and populations, independent ALT reference, mapping revision, rawMatch progress/selectors, and optional CardLadder search link", "content": { "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 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "401": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "503": { "description": "Graded identity provider temporarily unavailable; not a not-found result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/graded/prices": { "post": { "operationId": "gradedPrices", "summary": "Get up to four ALT graded-market quotes", "description": "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.", "security": [ { "ConnectorKey": [] } ], "requestBody": { "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": { "200": { "description": "One isolated quote per distinct normalized market selection", "content": { "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 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "401": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "429": { "description": "Quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/v1/products/{id}": { "get": { "operationId": "getStrataProduct", "summary": "Read a Strata product and its verified exact links", "security": [ { "ConnectorKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Identity, mappingRevision, verified links with printing/language scope, capabilities, and rawMatch with status/reason/selectors/revision/retryAfterSeconds. Proposed matches never supply prices.", "content": { "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" } } } } } }, "401": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "bad_request", "detail": "The request is invalid.", "retryable": false, "requestId": "00000000-0000-4000-8000-000000000009" } } } }, "404": { "description": "Unknown product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleError" }, "example": { "error": "not_found", "requestId": "00000000-0000-4000-8000-000000000009" } } } } } } }, "/api/agent/production": { "post": { "operationId": "agent_production", "summary": "Use your connected Strata production account", "description": "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.", "security": [ { "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." } ], "requestBody": { "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": { "200": { "description": "Account, billing state/action or public card operation result. Lookup shape matches the dispatched public endpoint.", "content": { "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" } ] } } } }, "201": { "description": "Prepared action, or replay of the same preparation key. No purchase performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBillingAction" } } } }, "400": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Refresh or reconnect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Missing scope or tester access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Conflict, changed quote or pending outcome: inspect error code", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Honor Retry-After; do not evade limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent/sandbox": { "post": { "operationId": "agent_sandbox", "summary": "Use your connected Strata sandbox account", "description": "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.", "security": [ { "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." } ], "requestBody": { "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": { "200": { "description": "Account, billing state/action or public card operation result. Lookup shape matches the dispatched public endpoint.", "content": { "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" } ] } } } }, "201": { "description": "Prepared action, or replay of the same preparation key. No purchase performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBillingAction" } } } }, "400": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Refresh or reconnect", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Missing scope or tester access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Conflict, changed quote or pending outcome: inspect error code", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Honor Retry-After; do not evade limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Request could not complete; inspect error code and retryable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "error" ] } } } } } } } }, "components": { "securitySchemes": { "ConnectorKey": { "type": "http", "scheme": "bearer", "description": "Create a connector key in your Strata connector dashboard." }, "AgentOAuth": { "type": "oauth2", "description": "Registered clients only. S256 PKCE and exact redirects required. A connection is scoped to production or sandbox; sandbox also requires tester access.", "flows": { "authorizationCode": { "authorizationUrl": "https://stratatcg.com/connector/oauth/authorize", "tokenUrl": "https://stratatcg.com/connector/oauth/token", "refreshUrl": "https://stratatcg.com/connector/oauth/token", "scopes": { "account:read": "Read account, allowance and billing state", "cards:read": "Use account credits for card identity and pricing", "billing:prepare": "Prepare billing actions for separate human review; no direct purchase execution" } } } } }, "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" ] } } } }