{"openapi":"3.1.0","info":{"title":"CardCounter POS workspace API","version":"1.1.0","description":"Read-only API v1. Use an owner-issued, location-scoped API key for server integrations or the HttpOnly staff-session cookie from the workspace origin. API keys support inventory:read and shop:read, expire after 30 or 90 days, and allow 60 requests per minute per key. A key cannot change its location and stops working if its owner loses access. Read meta.environment to distinguish synthetic testing from a hosted workspace; hosted does not imply payment activation. OAuth, browser CORS access, write endpoints, and outgoing webhooks are not implemented. Inventory pages are current reads, not an immutable export snapshot."},"servers":[{"url":"/","description":"This workspace origin"}],"security":[{"staffSession":[]},{"integrationKey":[]}],"tags":[{"name":"Inventory"},{"name":"Shop"}],"paths":{"/api/v1/inventory":{"get":{"operationId":"listInventory","tags":["Inventory"],"summary":"Read a page of exact inventory records","description":"Includes active and inactive SKUs. Prices are integer USD cents. No acquisition cost, customer information, or staff identities are exposed. Cursors are bound to the authenticated organization, location, normalized search, and availability filter. Keep these filters unchanged while following links.next.","parameters":[{"name":"location","in":"query","required":false,"description":"Defaults to the workspace location. Each request requires a current staff grant for the selected location.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":128},"description":"Literal, case-insensitive search across exact identity, barcode, and populated bin labels."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"available","in":"query","schema":{"type":"boolean","default":false},"description":"true limits results to stock available at this location."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Opaque nextCursor from the preceding response."}],"responses":{"200":{"description":"Authorized inventory page. Responses are private and never cached.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/InventoryItem"}},"meta":{"type":"object","required":["requestId","apiVersion","environment","scope"],"properties":{"requestId":{"type":"string","format":"uuid"},"apiVersion":{"const":"v1"},"environment":{"enum":["synthetic","hosted"]},"scope":{"type":"object","required":["organizationId","locationId"],"properties":{"organizationId":{"type":"string"},"locationId":{"type":"string"}}},"pagination":{"type":"object","required":["limit","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}},"links":{"type":"object","required":["next"],"properties":{"next":{"type":["string","null"]}}}}}}}},"400":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API key rate limit reached (60 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1,"maximum":60},"description":"Seconds before retrying."}}},"503":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shop":{"get":{"operationId":"getShopSummary","tags":["Shop"],"summary":"Read the current shop and location inventory summary","description":"Catalog SKU counts are organization-wide. Stock quantities are restricted to the selected location. No sales, cash, acquisition costs, or customer data are included.","parameters":[{"name":"location","in":"query","required":false,"description":"Defaults to the workspace location. Each request requires a current staff grant for the selected location.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}}],"responses":{"200":{"description":"Authorized shop summary.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["organizationId","locationId","currency","timezone","inventory"],"properties":{"organizationId":{"type":"string"},"locationId":{"type":"string"},"currency":{"type":["string","null"]},"timezone":{"type":["string","null"]},"inventory":{"type":"object","required":["catalogSkus","activeSkus","onHand","held","available"],"properties":{"catalogSkus":{"type":"integer","minimum":0},"activeSkus":{"type":"integer","minimum":0},"onHand":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0}}}}},"meta":{"type":"object","required":["requestId","apiVersion","environment","scope"],"properties":{"requestId":{"type":"string","format":"uuid"},"apiVersion":{"const":"v1"},"environment":{"enum":["synthetic","hosted"]},"scope":{"type":"object","required":["organizationId","locationId"],"properties":{"organizationId":{"type":"string"},"locationId":{"type":"string"}}}}}}}}}},"400":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API key rate limit reached (60 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1,"maximum":60},"description":"Seconds before retrying."}}},"503":{"description":"Structured error. Database details and credentials are never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi":{"get":{"operationId":"getApiSpecification","summary":"Download this public OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON; contains no private shop data."}}}}},"components":{"securitySchemes":{"staffSession":{"type":"apiKey","in":"cookie","name":"pokepos_pilot_session","description":"Existing HttpOnly, SameSite=Strict staff session. Sign in through the workspace; never copy session cookies into scripts or share them."},"integrationKey":{"type":"http","scheme":"bearer","bearerFormat":"CardCounter POS API key","description":"An owner issues a key in Developers. Keep it in server secret storage. inventory:read is required for inventory; shop:read for shop. Keys are location-scoped, independently revocable, and shown only once."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}},"InventoryItem":{"type":"object","required":["id","name","kind","game","printing","price","stock","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"enum":["single","sealed","accessory","other"]},"game":{"type":"string"},"status":{"enum":["active","inactive"]},"printing":{"type":"object","properties":{"setCode":{"type":"string"},"collectorNumber":{"type":["string","null"]},"language":{"type":["string","null"]},"finish":{"type":["string","null"]},"edition":{"type":["string","null"]},"condition":{"type":["string","null"]}}},"price":{"type":"object","required":["amount","currency","revision"],"properties":{"amount":{"type":"integer","minimum":0,"description":"Integer USD cents."},"currency":{"const":"USD"},"revision":{"type":"integer","minimum":1}}},"stock":{"type":"object","required":["onHand","held","available","bins"],"properties":{"onHand":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"available":{"type":"integer","minimum":0},"bins":{"type":["string","null"],"description":"Comma-separated occupied bin identifiers, or null."}}}}}}}}