{ "openapi": "3.1.1", "info": { "title": "CardCounter POS Market Data API", "version": "1.0.0", "description": "Versioned JSON access to catalog identity, card images, SKU market prices, market history, and current listings. Prices use USD. The local build is a development integration; external access and commercial data rights are separate launch gates." }, "servers": [ { "url": "https://pokepos-market-api.vercel.app", "description": "Hosted market API" }, { "url": "/", "description": "Current API origin" }, { "url": "http://127.0.0.1:8787", "description": "Local development service" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Catalog", "description": "Find product lines, sets, and products." }, { "name": "Cards", "description": "Identify Pokémon cards from text or photos." }, { "name": "Products", "description": "Read a product snapshot and individual market sections." }, { "name": "Account", "description": "Plan information and authenticated usage." } ], "paths": { "/v1/plans": { "get": { "tags": [ "Account" ], "operationId": "listPlans", "summary": "List API plans", "security": [], "responses": { "200": { "description": "Three available plan definitions.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "plans" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } } } } } } }, "/v1/usage": { "get": { "tags": [ "Account" ], "operationId": "getUsage", "summary": "Read current account usage", "description": "The authenticated request itself consumes one request. Periods reset on UTC minute and month boundaries.", "responses": { "200": { "description": "Current account limits and remaining allowances.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing, invalid, expired, or revoked API key.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Access store or service is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/categories": { "get": { "tags": [ "Catalog" ], "operationId": "listCategories", "summary": "List product lines", "responses": { "200": { "description": "Product lines available in the source catalog.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "categories" ], "properties": { "source": { "type": "string" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/categories/{category}/sets": { "get": { "tags": [ "Catalog" ], "operationId": "listSets", "summary": "List sets in a product line", "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string" }, "example": "pokemon" } ], "responses": { "200": { "description": "Sets and source counts for the product line.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetList" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/search": { "get": { "tags": [ "Catalog" ], "operationId": "searchProducts", "summary": "Search the full product catalog", "description": "Use a product line and optional set slug to narrow results. Offset pagination is capped at 10,000.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "example": "Mew ex" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "example": "pokemon" }, { "name": "set", "in": "query", "schema": { "type": "string" }, "example": "me-30th-celebration" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 24 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "name" ] } } ], "responses": { "200": { "description": "Paginated catalog products.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/identify": { "get": { "tags": [ "Cards" ], "operationId": "identifyCard", "summary": "Resolve a Pokémon name and collector number", "description": "Separates a trailing collector number, resolves an optional set hint, then ranks matching printings. A broad search inspects at most 200 catalog results; use a set hint to narrow it.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 120 }, "example": "Mew ex 66" }, { "name": "set", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "example": "30th Celebration" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 12 } } ], "responses": { "200": { "description": "Ranked candidate printings.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/identify-image": { "post": { "tags": [ "Cards" ], "operationId": "identifyCardImage", "summary": "Read a card photo and identify candidates", "description": "Accepts a PNG, JPEG, or WebP data URL up to 6 MB. OCR is best effort; review and correct the suggested query when needed. Image bytes are not retained by this service.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "imageDataUrl" ], "properties": { "imageDataUrl": { "type": "string", "format": "byte", "description": "Complete data:image/...;base64,... URL, not raw base64." }, "setHint": { "type": "string", "maxLength": 80 } } } } } }, "responses": { "200": { "description": "OCR text, editable suggestion, and optional catalog matches.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageIdentifyResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/lookup": { "get": { "tags": [ "Products" ], "operationId": "lookupProductUrl", "summary": "Read a snapshot from a TCGplayer URL or ID", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "example": "https://www.tcgplayer.com/product/716465" }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "month", "quarter", "semi-annual", "annual" ], "default": "quarter" }, "description": "One, three, six, or twelve months of recorded history." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Full product snapshot.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSnapshot" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}": { "get": { "tags": [ "Products" ], "operationId": "getProductSnapshot", "summary": "Read a full product snapshot", "description": "Returns product identity, image URL, per-SKU market prices, chosen history range, current listings, and section-level availability. A secondary source failure is null and marked unavailable; an empty successful source is an empty array.", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "month", "quarter", "semi-annual", "annual" ], "default": "quarter" }, "description": "One, three, six, or twelve months of recorded history." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "price", "none" ], "default": "price" } } ], "responses": { "200": { "description": "Full product snapshot.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSnapshot" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}/details": { "get": { "tags": [ "Products" ], "operationId": "getProductDetails", "summary": "Read product identity and attributes", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 } ], "responses": { "200": { "description": "Product details and SKU identities.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailsResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}/prices": { "get": { "tags": [ "Products" ], "operationId": "getProductPrices", "summary": "Read per-SKU market prices", "description": "Each price is joined with its condition, printing variant, and language. A missing observation is null, never an invented zero.", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 } ], "responses": { "200": { "description": "Per-SKU USD prices.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}/history": { "get": { "tags": [ "Products" ], "operationId": "getProductHistory", "summary": "Read market price and sales history", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "month", "quarter", "semi-annual", "annual" ], "default": "quarter" }, "description": "One, three, six, or twelve months of recorded history." } ], "responses": { "200": { "description": "Chronological history buckets by SKU.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}/listings": { "get": { "tags": [ "Products" ], "operationId": "getProductListings", "summary": "Read current seller listings", "description": "The price sort is item price, so totals after shipping may appear out of order.", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "price", "none" ], "default": "price" } }, { "name": "condition", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "variant", "in": "query", "schema": { "type": "string", "maxLength": 80 } }, { "name": "language", "in": "query", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Paginated current offers.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingsResult" } } } }, "400": { "description": "Invalid parameter or request body.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/products/{productId}/image": { "get": { "tags": [ "Products" ], "operationId": "getProductImageUrl", "summary": "Read the verified source image URL", "description": "Returns a checked source URL. Image bytes are not copied or served by this API.", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "Numeric TCGplayer product ID.", "schema": { "type": "integer", "minimum": 1 }, "example": 716465 } ], "responses": { "200": { "description": "Source image URL.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResult" } } } }, "404": { "description": "Product, route, or image not found.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "An upstream market source is unavailable.", "headers": { "x-request-id": { "description": "Unique request ID for support and tracing.", "schema": { "type": "string" } }, "x-ratelimit-remaining": { "description": "Requests left in the current minute for account-backed keys.", "schema": { "type": "integer" } }, "x-monthly-remaining": { "description": "Requests left in the current UTC month for account-backed keys.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "CardCounter POS API key", "description": "Use the key issued to your account. The server stores only a SHA-256 hash of the random token." } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "upstreamStatus": { "type": [ "integer", "null" ] } } } } }, "Plan": { "type": "object", "required": [ "id", "name", "monthlyRequests", "requestsPerMinute", "activeKeys", "price", "availability" ], "properties": { "id": { "type": "string", "enum": [ "starter", "growth", "scale" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "monthlyRequests": { "type": "integer" }, "requestsPerMinute": { "type": "integer" }, "activeKeys": { "type": "integer" }, "price": { "type": "null" }, "availability": { "type": "string", "const": "request-access" } }, "examples": [ { "id": "starter", "name": "Starter", "monthlyRequests": 10000, "requestsPerMinute": 30, "activeKeys": 2, "description": "For prototypes and focused integrations.", "price": null, "availability": "request-access" }, { "id": "growth", "name": "Growth", "monthlyRequests": 100000, "requestsPerMinute": 120, "activeKeys": 10, "description": "For production apps and growing catalog workflows.", "price": null, "availability": "request-access" }, { "id": "scale", "name": "Scale", "monthlyRequests": 1000000, "requestsPerMinute": 600, "activeKeys": 50, "description": "For high-volume commerce and data operations.", "price": null, "availability": "request-access" } ] }, "Usage": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "plan": { "type": "string" }, "limits": { "type": "object", "properties": { "monthlyRequests": { "type": "integer" }, "requestsPerMinute": { "type": "integer" } } }, "remaining": { "type": "object", "properties": { "monthlyRequests": { "type": "integer" }, "requestsThisMinute": { "type": "integer" } } }, "periods": { "type": "object", "properties": { "monthStartsAt": { "type": "string" }, "minuteStartsAt": { "type": "string" } } } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "Set": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "count": { "type": "integer" } } }, "SetList": { "type": "object", "properties": { "source": { "type": "string" }, "category": { "type": "string" }, "totalProducts": { "type": "integer" }, "coveredBySets": { "type": "integer" }, "sets": { "type": "array", "items": { "$ref": "#/components/schemas/Set" } } } }, "Sku": { "type": "object", "properties": { "skuId": { "type": "integer" }, "condition": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } } }, "ProductSummary": { "type": "object", "properties": { "productId": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "setName": { "type": [ "string", "null" ] }, "setId": { "type": [ "integer", "null" ] }, "cardNumber": { "type": [ "string", "null" ] }, "rarity": { "type": [ "string", "null" ] }, "sealed": { "type": "boolean" }, "marketPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "lowestPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "listingCount": { "type": [ "integer", "null" ] } } }, "SearchResult": { "type": "object", "properties": { "source": { "type": "string" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "query": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "set": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "sort": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } }, "IdentifyResult": { "type": "object", "properties": { "source": { "type": "string" }, "query": { "type": "string" }, "parsed": { "type": "object", "properties": { "name": { "type": "string" }, "cardNumber": { "type": [ "string", "null" ] }, "setHint": { "type": [ "string", "null" ] } } }, "matchedSet": { "anyOf": [ { "$ref": "#/components/schemas/Set" }, { "type": "null" } ] }, "searchedCount": { "type": "integer" }, "totalSearchResults": { "type": "integer" }, "truncated": { "type": "boolean" }, "candidates": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ProductSummary" }, { "type": "object", "properties": { "matchScore": { "type": "number" } } } ] } } } }, "ImageIdentifyResult": { "type": "object", "properties": { "ocr": { "type": "object", "properties": { "text": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "suggested": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "cardNumber": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] } } } } }, "identification": { "anyOf": [ { "$ref": "#/components/schemas/IdentifyResult" }, { "type": "null" } ] } } }, "Product": { "type": "object", "properties": { "productId": { "type": "integer" }, "sourceUrl": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "group": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] } } }, "productType": { "type": [ "string", "null" ] }, "sealed": { "type": "boolean" }, "cardNumber": { "type": [ "string", "null" ] }, "rarity": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": true }, "formattedAttributes": { "type": "object", "additionalProperties": true }, "skus": { "type": "array", "items": { "$ref": "#/components/schemas/Sku" } }, "marketPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "lowestPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "lowestPriceWithShipping": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "listingCount": { "type": [ "integer", "null" ] }, "sellerCount": { "type": [ "integer", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } } }, "Price": { "type": "object", "properties": { "skuId": { "type": "integer" }, "condition": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "marketPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "lowSalePrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "highSalePrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "sampleSize": { "type": [ "integer", "null" ] }, "calculatedAt": { "type": [ "string", "null" ] } } }, "PricesResult": { "type": "object", "properties": { "source": { "type": "string" }, "productId": { "type": "integer" }, "currency": { "type": "string", "const": "USD" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } } } }, "HistoryBucket": { "type": "object", "properties": { "date": { "type": [ "string", "null" ] }, "marketPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "quantitySold": { "type": [ "integer", "null" ] }, "transactionCount": { "type": [ "integer", "null" ] }, "lowSalePrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "highSalePrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "lowSalePriceWithShipping": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "highSalePriceWithShipping": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." } } }, "HistoryVariant": { "type": "object", "properties": { "skuId": { "type": "integer" }, "condition": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "averageDailyQuantitySold": { "type": [ "number", "null" ] }, "totalQuantitySold": { "type": [ "integer", "null" ] }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryBucket" } } } }, "HistoryResult": { "type": "object", "properties": { "source": { "type": "string" }, "productId": { "type": "integer" }, "range": { "type": "string" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryVariant" } } } }, "Seller": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "ratingPercent": { "type": [ "number", "null" ] }, "sales": { "type": [ "string", "null" ] }, "direct": { "type": "boolean" }, "verified": { "type": "boolean" } } }, "Offer": { "type": "object", "properties": { "listingId": { "type": "integer" }, "skuId": { "type": [ "integer", "null" ] }, "seller": { "$ref": "#/components/schemas/Seller" }, "condition": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "itemPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "shippingPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "totalPrice": { "type": [ "number", "null" ], "description": "US dollars. Null means no observation is available." }, "currency": { "type": "string", "const": "USD" } } }, "ListingsResult": { "type": "object", "properties": { "source": { "type": "string" }, "productId": { "type": "integer" }, "total": { "type": [ "integer", "null" ] }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "sort": { "type": "string" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" } } }, "SectionStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unavailable" ] }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "code": { "type": "string" }, "upstreamStatus": { "type": [ "integer", "null" ] } } }, "ProductSnapshot": { "type": "object", "properties": { "source": { "type": "string" }, "sourceUrl": { "type": "string" }, "observedAt": { "type": "string" }, "currency": { "type": "string", "const": "USD" }, "product": { "$ref": "#/components/schemas/Product" }, "marketPrices": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, { "type": "null" } ] }, "marketHistory": { "anyOf": [ { "$ref": "#/components/schemas/HistoryResult" }, { "type": "null" } ] }, "listings": { "anyOf": [ { "$ref": "#/components/schemas/ListingsResult" }, { "type": "null" } ] }, "featuredListing": { "anyOf": [ { "$ref": "#/components/schemas/Offer" }, { "type": "null" } ] }, "sections": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SectionStatus" } } } }, "DetailsResult": { "type": "object", "properties": { "source": { "type": "string" }, "productId": { "type": "integer" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/Product" } } }, "ImageResult": { "type": "object", "properties": { "source": { "type": "string" }, "productId": { "type": "integer" }, "fetchedAt": { "type": "string" }, "cacheHit": { "type": "boolean" }, "imageUrl": { "type": "string" } } } } } }