{ "openapi": "3.1.0", "info": { "title": "Holo Folder API", "version": "1.0.0", "description": "Premium/lifetime data API. MCP uses OAuth separately. Card image fields are R2-only." }, "servers": [ { "url": "https://app.holofolder.com/app/api/v1", "description": "Holo Folder production API" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Holo Folder personal API key" } } }, "paths": { "/storage/restores/raw-content": { "post": { "operationId": "restore_raw_collection_content", "summary": "Restore raw collection content", "description": "Bounded explicit same-owner raw content reconciliation of one existing collection, same stable slot IDs, no copied manifest/configuration change. Version 4 is the only command version: it carries the exact current copied manifest, per-slot origins and slotOrder.before/after (identical, or a permutation that also advances the layout revision). Content and origins bind by ID; slot versions advance. At most 1025 slots/manifest entries, 2050 distinct raw-copy refs, 100 wants/slot, 8192 work units (2S+I+W) and 1.75 MiB UTF-8/JSONB command text plus a 2.5 MiB complete prospective audit/undo graph. SQL independently refuses oversized graphs before writes with invalid_input, never a terminal rejection proof. Other command versions return invalid_input. Receipts and dedicated rejections carry version:4. These bounds do not establish production full-Dex availability. Current actor/owner/session or credential and partner preconditions are required, file IDs never prove provenance. Exact item/slot/placement/content/layout versions bind review. Explicit releases retain ownership in Unassigned; copies placed elsewhere cannot move. SQL checks the complete actual graph and its undo before commit. No acquisition, metadata replacement, graded copies, structural slot-set/configuration/grid, multi-collection/settings/assets/CSV restore. Lifetime exact accepted/rejected replay precedes mutable reconstruction after current authority checks. Only committed dedicated inventory/collection/content predicate rejection yields REST409 storage_restore_rejected or MCP isError with error.rejection. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas declares errors. Arbitrary conflicts, cancellation and failed COMMIT remain unknown; retain original intent and require a fresh complete read plus explicit reconciliation.\n\nRequired permissions: `collection:write`, `binders:write`. MCP tool: `restore_raw_collection_content`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 1835008, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 4 }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "slotOrder": { "type": "object", "properties": { "before": { "minItems": 1, "maxItems": 1025, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "after": { "minItems": 1, "maxItems": 1025, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "before", "after" ], "additionalProperties": false }, "manifest": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "entries": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "id", "target" ], "additionalProperties": false } }, "setScope": { "type": "object", "properties": { "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setName": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } }, "capturedAt": { "type": "string", "minLength": 1, "maxLength": 200 }, "officialCardCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cards": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "localId": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "languageConfirmed": { "type": "boolean" }, "verifiedFinishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } } }, "required": [ "cardId", "setId", "localId", "name", "languageConfirmed", "verifiedFinishes" ], "additionalProperties": false } }, "promoCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "excludedCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "warnings": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "required": [ "setId", "setName", "language", "finishes", "capturedAt", "officialCardCount", "cards", "promoCardIds", "excludedCardIds", "warnings" ], "additionalProperties": false } }, "required": [ "source", "name", "entries" ], "additionalProperties": false }, { "type": "null" } ] }, "planning": { "type": "object", "properties": { "actorUserId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "ownerUserId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source": { "type": "string", "enum": [ "app", "rest", "mcp" ] }, "credentialId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "authSessionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "partnershipId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ] }, "partnerUserId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ] } }, "required": [ "actorUserId", "ownerUserId", "source", "credentialId", "authSessionId", "partnershipId", "partnerUserId" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "kind": { "type": "string", "enum": [ "binder", "slab", "custom" ] }, "defaultPresentation": { "type": "string", "enum": [ "binder", "slabs", "list" ] }, "location": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "rows": { "type": "integer", "minimum": 1, "maximum": 8 }, "cols": { "type": "integer", "minimum": 1, "maximum": 8 } }, "required": [ "name", "kind", "defaultPresentation", "location", "rows", "cols" ], "additionalProperties": false }, "slots": { "minItems": 1, "maxItems": 1025, "type": "array", "items": { "type": "object", "properties": { "before": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false }, "after": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "collected", "finalized", "considering", "wishlisted" ] }, { "type": "null" } ] }, "wantedCards": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_image": { "type": "string" }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "wanted_by": { "maxItems": 2, "type": "array", "items": { "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)$" } } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "presetOrigin": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "entryId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "source", "entryId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "target", "status", "wantedCards", "inventoryItemId", "presetOrigin" ], "additionalProperties": false } }, "required": [ "before", "after" ], "additionalProperties": false } }, "items": { "maxItems": 2050, "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false } }, "releaseItemIds": { "maxItems": 2050, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "version", "operationId", "inventoryRevision", "slotOrder", "manifest", "planning", "collection", "configuration", "slots", "items", "releaseItemIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 4 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changed": { "type": "boolean", "const": true }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "slotOrder": { "type": "object", "properties": { "before": { "maxItems": 1025, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "after": { "maxItems": 1025, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "before", "after" ], "additionalProperties": false }, "slotIds": { "maxItems": 1025, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "releasedItemIds": { "maxItems": 2050, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "version", "inventoryRevision", "changed", "collectionId", "collectionVersion", "layoutRevision", "slotOrder", "slotIds", "releasedItemIds" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_restore_rejected" }, "message": { "type": "string", "const": "The original restore did not commit. Read current storage before explicit reconciliation." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "version": { "type": "number", "const": 4 }, "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "inventory_revision_conflict", "raw_restore_collection_conflict", "raw_restore_content_conflict" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "version", "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/imports/arrangement": { "post": { "operationId": "import_storage_arrangement", "summary": "Import storage arrangement", "description": " Migration 093 adds committed terminal noncommit proofs: REST 409 storage_creation_rejected or storage_import_rejected, MCP isError with strict error.rejection (outcome, original operationId, known code, inventoryRevision). Exact accepted/rejected replay is permanent and precedes mutable reconstruction after current authority checks. Arbitrary conflicts, billing, cancellation, failed COMMIT and network errors remain unknown. Consumers must bind the trusted response to the original family, immutable intent and owner/session scope; proof alone never authorizes discard. Fresh complete current reads and explicit reconciliation are a separate consumer gate. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas declares errors. Atomic JSON v2 arrangement into an empty or target-only native collection with an already identical copied manifest. Every copy needs an explicit add or versioned existing-copy move. Retain the immutable request after unknown outcome. Does not replace collections/configuration, import assets, restore changed same-owner snapshots or authorize backup IDs.\n\nRequired permissions: `collection:write`, `binders:write`. MCP tool: `import_storage_arrangement`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 8388608, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "destinationCollectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "collections": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } }, "emptyDestinationSlots": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "manifest": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "entries": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "id", "target" ], "additionalProperties": false } } }, "required": [ "source", "name", "entries" ], "additionalProperties": false }, { "type": "null" } ] }, "slots": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "collected", "finalized", "considering", "wishlisted" ] }, { "type": "null" } ] }, "wantedCards": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_image": { "type": "string" }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "wanted_by": { "maxItems": 2, "type": "array", "items": { "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)$" } } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "presetOrigin": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "entryId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "source", "entryId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "target", "status", "wantedCards", "inventoryItemId", "presetOrigin" ], "additionalProperties": false } }, "copies": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "add", "existing" ] }, "item": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "designation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "subgrades": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "grade": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "certificate": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "holder": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "label": { "type": "object", "properties": { "variant": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "assetIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "variant", "assetIds" ], "additionalProperties": false } }, "required": [ "provider", "grade", "scale", "designation", "subgrades", "certificate", "holder", "label" ], "additionalProperties": false }, { "type": "null" } ] }, "acquiredAt": { "type": [ "string", "null" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "identity", "grading", "acquiredAt", "version" ], "additionalProperties": false }, "ref": { "anyOf": [ { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "item", "ref" ], "additionalProperties": false } } }, "required": [ "version", "operationId", "inventoryRevision", "destinationCollectionId", "collections", "emptyDestinationSlots", "manifest", "slots", "copies" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changed": { "type": "boolean", "const": true }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "slotIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "addedItemIds": { "maxItems": 5000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "removedEmptySlotIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "inventoryRevision", "changed", "collectionId", "collectionVersion", "layoutRevision", "slotIds", "addedItemIds", "removedEmptySlotIds" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_import_rejected" }, "message": { "type": "string", "const": "The original import did not commit. Read current storage before explicit reconciliation." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "inventory_revision_conflict", "inventory_collection_conflict", "arrangement_destination_conflict", "import_copy_conflict" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/slots/commands": { "post": { "operationId": "execute_slot_commands", "summary": "Execute slot commands", "description": "A committed terminal ledger rejection returns REST 409 storage_command_rejected or MCP isError with the same error.rejection: outcome, original operationId, known code and inventoryRevision. Other conflicts/timeouts are not rejection proof. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas metadata declares errors. Atomic stable-ID slot insert/update/clear/remove/reorder. Requires exact inventory, collection, layout, slot/item/placement revisions and retry-stable operationId. Clear/remove release copies to Unassigned; neither deletes ownership. Set privateFields=preserve for create/reorder/target-only updates without replacing hidden wants; omitted or replace retains legacy full-replacement semantics.\n\nRequired permissions: `collection:write`, `binders:write`. MCP tool: `execute_slot_commands`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 262144, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "privateFields": { "description": "preserve allows public patchGrading and exact selected-want expectedPublic; rejects full grading/wants replacement and slot/collection removal. replace (also the legacy default when omitted) retains full-replacement semantics; never rebuild replacements from redacted reads.", "type": "string", "enum": [ "preserve", "replace" ] }, "expectedOwnerUserId": { "description": "Recipient precondition, required with privateFields=preserve. Must match the current authenticated owner scope; never selects or grants authority. Retain across retries.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "commands": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "create" }, "ids": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "beforeSlotId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "kind", "ids", "beforeSlotId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "move" }, "slots": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "beforeSlotId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "kind", "slots", "beforeSlotId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "clear", "remove" ] }, "slots": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } } }, "required": [ "kind", "slots" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "update" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "wantedCards": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_image": { "type": "string" }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "wanted_by": { "maxItems": 2, "type": "array", "items": { "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)$" } } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } } }, "required": [ "kind", "slot" ], "additionalProperties": false } ] } } }, "required": [ "collectionId", "operationId", "inventoryRevision", "collectionVersion", "layoutRevision", "commands" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changed": { "type": "boolean" }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "removedSlotIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "inventoryRevision", "changed", "collectionVersion", "layoutRevision", "removedSlotIds" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_command_rejected" }, "message": { "type": "string", "const": "The original storage command was rejected. Refresh current storage before explicit reconciliation." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "slot_revision_conflict", "inventory_revision_conflict", "inventory_collection_conflict", "slot_conflict", "item_conflict", "placement_conflict", "inventory_want_conflict", "inventory_copy_choice_required", "inventory_destination_empty", "inventory_destination_occupied" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/inventory/commands": { "post": { "operationId": "execute_inventory_commands", "summary": "Execute inventory commands", "description": "A committed terminal ledger rejection returns REST 409 storage_command_rejected or MCP isError with the same error.rejection: outcome, original operationId, known code and inventoryRevision. Other conflicts/timeouts are not rejection proof. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas metadata declares errors. Atomic insertAssign, owned-copy add/edit/remove/unassign/assign/move or collection deletion through the trusted executor. insertAssign creates one stable slot before an exact existing slot reference or appends with before:null, retaining explicit target:null/free or target intent. selection:null creates no ownership; existing requires an exact Unassigned item/version, new explicitly creates that stable item. It never auto-selects a grade or moves an assigned copy. Maximum 4096 slots and 8192 insertion work rows per request, 100 commands, 256 affected selected entities, 256 KiB ordinary request, 1 MiB ordinary receipt and unchanged 16 MiB/16384 audit bounds and 10s deadline; oversized evidence rejects atomically. Full selected-copy/destination and revision preconditions are mandatory. Only explicit removeOwned (a command, or removeOwned:true on deleteCollection, which deletes the raw copies in that collection and leaves graded copies Unassigned) deletes ownership; idempotent receipts require a fresh complete read before reconciliation. Set privateFields=preserve for add, explicit removeOwned, unassign or placement with fulfillWant:null; patchGrading updates only declared public fields on existing grading; setFinish corrects the recorded finish of a card copy in place (migration 114) and must still match the target of its pocket; selected-want expectedPublic compares the exact locked slot/index public projection. Hidden certificates/assets/provenance and unrelated wants are retained by migration 090 after original-intent replay lookup. Omitted or replace retains full-replacement semantics.\n\nRequired permissions: `collection:write`, `binders:write`. MCP tool: `execute_inventory_commands`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 8388608, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "privateFields": { "description": "preserve allows public patchGrading and exact selected-want expectedPublic; rejects full grading/wants replacement and slot/collection removal. replace (also the legacy default when omitted) retains full-replacement semantics; never rebuild replacements from redacted reads.", "type": "string", "enum": [ "preserve", "replace" ] }, "expectedOwnerUserId": { "description": "Recipient precondition, required with privateFields=preserve. Must match the current authenticated owner scope; never selects or grants authority. Retain across retries.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "collections": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } }, "commands": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "insertAssign" }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slotId": { "type": "string", "minLength": 1, "maxLength": 200 }, "before": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false }, { "type": "null" } ] }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "selection": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "existing" }, "inventoryItemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "inventoryItemId", "itemVersion" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "new" }, "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "designation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "subgrades": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "grade": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "certificate": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "holder": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "label": { "type": "object", "properties": { "variant": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "assetIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "variant", "assetIds" ], "additionalProperties": false } }, "required": [ "provider", "grade", "scale", "designation", "subgrades", "certificate", "holder", "label" ], "additionalProperties": false }, { "type": "null" } ] }, "acquiredAt": { "type": [ "string", "null" ] } }, "required": [ "kind", "itemId", "identity", "grading", "acquiredAt" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "kind", "collectionId", "slotId", "before", "target", "selection" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add" }, "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "designation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "subgrades": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "grade": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "certificate": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "holder": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "label": { "type": "object", "properties": { "variant": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "assetIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "variant", "assetIds" ], "additionalProperties": false } }, "required": [ "provider", "grade", "scale", "designation", "subgrades", "certificate", "holder", "label" ], "additionalProperties": false }, { "type": "null" } ] }, "acquiredAt": { "type": [ "string", "null" ] } }, "required": [ "kind", "itemId", "identity", "grading", "acquiredAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "edit" }, "item": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "designation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "subgrades": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "grade": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "certificate": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "holder": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "label": { "type": "object", "properties": { "variant": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "assetIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "variant", "assetIds" ], "additionalProperties": false } }, "required": [ "provider", "grade", "scale", "designation", "subgrades", "certificate", "holder", "label" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "item", "grading" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "setFinish" }, "item": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "item", "finish" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "patchGrading" }, "item": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false }, "patch": { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "designation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "subgrades": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "grade": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "holder": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "labelVariant": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "kind", "item", "patch" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "removeOwned", "unassign" ] }, "item": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false } }, "required": [ "kind", "item" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "assign" }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "existing" }, "inventoryItemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "inventoryItemId", "itemVersion" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "catalog" }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "newItemId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "kind", "identity", "newItemId" ], "additionalProperties": false } ] }, "destination": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, "occupied": { "type": "string", "enum": [ "cancel", "unassign" ] }, "fulfillWant": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 99 }, "expected": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_image": { "type": "string" }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "wanted_by": { "maxItems": 2, "type": "array", "items": { "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)$" } } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "required": [ "index", "expected" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 99 }, "expectedPublic": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "required": [ "index", "expectedPublic" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "kind", "selection", "destination", "occupied", "fulfillWant" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "move" }, "item": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "itemVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "placement": { "anyOf": [ { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "itemId", "itemVersion", "placement" ], "additionalProperties": false }, "destination": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false }, "occupied": { "type": "string", "enum": [ "cancel", "unassign", "swap" ] }, "fulfillWant": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 99 }, "expected": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_image": { "type": "string" }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "wanted_by": { "maxItems": 2, "type": "array", "items": { "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)$" } } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "required": [ "index", "expected" ], "additionalProperties": false }, { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 99 }, "expectedPublic": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string", "minLength": 1 }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } }, "required": [ "index", "expectedPublic" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "kind", "item", "destination", "occupied", "fulfillWant" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "removeSlots" }, "slots": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slot": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "required": [ "collectionId", "slot" ], "additionalProperties": false } } }, "required": [ "kind", "slots" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "deleteCollection" }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "slots": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "version", "inventoryItemId", "itemVersion", "placementVersion" ], "additionalProperties": false } }, "replacementDefaultCollectionId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, { "type": "null" } ] }, "removeOwned": { "type": "boolean", "const": true } }, "required": [ "kind", "collectionId", "slots", "replacementDefaultCollectionId" ], "additionalProperties": false } ] } } }, "required": [ "operationId", "inventoryRevision", "collections", "commands" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changed": { "type": "boolean" }, "selectedItemIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "acquiredItemIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "inventoryRevision", "changed", "selectedItemIds", "acquiredItemIds" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_command_rejected" }, "message": { "type": "string", "const": "The original storage command was rejected. Refresh current storage before explicit reconciliation." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "slot_revision_conflict", "inventory_revision_conflict", "inventory_collection_conflict", "slot_conflict", "item_conflict", "placement_conflict", "inventory_want_conflict", "inventory_copy_choice_required", "inventory_destination_empty", "inventory_destination_occupied" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/collections": { "post": { "operationId": "create_storage_collection", "summary": "Create storage collection", "description": " Migration 093 adds committed terminal noncommit proofs: REST 409 storage_creation_rejected or storage_import_rejected, MCP isError with strict error.rejection (outcome, original operationId, known code, inventoryRevision). Exact accepted/rejected replay is permanent and precedes mutable reconstruction after current authority checks. Arbitrary conflicts, billing, cancellation, failed COMMIT and network errors remain unknown. Consumers must bind the trusted response to the original family, immutable intent and owner/session scope; proof alone never authorizes discard. Fresh complete current reads and explicit reconciliation are a separate consumer gate. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas declares errors. Atomically create native storage from an ordered copied manifest, never a legacy create-then-edit. Migration 101 additionally accepts manifest.setScope, the exact reviewed language, verified finishes, promos, exclusions, coverage warnings and capture time. This is an independent copied initial list; goals remain editable and free slots can be appended. Catalog eligibility is checked at creation, not enforced on later edits. Preserve collection/slot/operation IDs across retries. Empty goals and spacers create no ownership or wants; recoverySupported remains conservative false.\n\nRequired permissions: `collection:write`, `binders:write`. MCP tool: `create_storage_collection`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 2097152, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "kind": { "type": "string", "enum": [ "binder", "slab", "custom" ] }, "defaultPresentation": { "type": "string", "enum": [ "binder", "slabs", "list" ] }, "location": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "grid": { "anyOf": [ { "type": "object", "properties": { "rows": { "type": "integer", "minimum": 1, "maximum": 8 }, "cols": { "type": "integer", "minimum": 1, "maximum": 8 } }, "required": [ "rows", "cols" ], "additionalProperties": false }, { "type": "null" } ] }, "manifest": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "entries": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "id", "target" ], "additionalProperties": false } }, "setScope": { "type": "object", "properties": { "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setName": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } }, "capturedAt": { "type": "string", "minLength": 1, "maxLength": 200 }, "officialCardCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cards": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "localId": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "languageConfirmed": { "type": "boolean" }, "verifiedFinishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } } }, "required": [ "cardId", "setId", "localId", "name", "languageConfirmed", "verifiedFinishes" ], "additionalProperties": false } }, "promoCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "excludedCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "warnings": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "required": [ "setId", "setName", "language", "finishes", "capturedAt", "officialCardCount", "cards", "promoCardIds", "excludedCardIds", "warnings" ], "additionalProperties": false } }, "required": [ "source", "name", "entries" ], "additionalProperties": false }, "slotIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "version", "operationId", "inventoryRevision", "collectionId", "name", "kind", "defaultPresentation", "location", "grid", "manifest", "slotIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changed": { "type": "boolean", "const": true }, "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "slotIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "recoverySupported": { "type": "boolean", "const": false } }, "required": [ "inventoryRevision", "changed", "collectionId", "collectionVersion", "layoutRevision", "slotIds", "recoverySupported" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_creation_rejected" }, "message": { "type": "string", "const": "The original creation did not commit. Read current storage before explicit reconciliation." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "inventory_revision_conflict", "creation_identity_conflict" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "list_storage_collections", "summary": "List storage collections", "description": "Page current native storage metadata, the copied initial presetManifest including optional setScope historical evidence, private location, counts and independent collection/layout revisions. Mixed legacy owners fail closed. Copied preset discovery/preview uses the separate preset operations.\n\nRequired permissions: `collection:read`, `binders:read`. MCP tool: `list_storage_collections`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "developer-native-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "readRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "data": { "type": "array", "items": { "type": "object", "properties": { "presetManifest": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "entries": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "id", "target" ], "additionalProperties": false } }, "setScope": { "type": "object", "properties": { "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setName": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } }, "capturedAt": { "type": "string", "minLength": 1, "maxLength": 200 }, "officialCardCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cards": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "setId": { "type": "string", "minLength": 1, "maxLength": 200 }, "localId": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "languageConfirmed": { "type": "boolean" }, "verifiedFinishes": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "jumbo" ] } } }, "required": [ "cardId", "setId", "localId", "name", "languageConfirmed", "verifiedFinishes" ], "additionalProperties": false } }, "promoCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "excludedCardIds": { "maxItems": 4096, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "warnings": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "required": [ "setId", "setName", "language", "finishes", "capturedAt", "officialCardCount", "cards", "promoCardIds", "excludedCardIds", "warnings" ], "additionalProperties": false } }, "required": [ "source", "name", "entries" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "binder", "slab", "custom" ] }, "defaultPresentation": { "type": "string", "enum": [ "binder", "slabs", "list" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isDefault": { "type": [ "boolean", "null" ] }, "sortOrder": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "slotCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "grid": { "anyOf": [ { "type": "object", "properties": { "rows": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "cols": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "rows", "cols" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "presetManifest", "id", "name", "kind", "defaultPresentation", "version", "layoutRevision", "isDefault", "sortOrder", "updatedAt", "slotCount", "grid" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "projection", "completeSnapshot", "inventoryRevision", "readRevision", "data", "total", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/recovery/preview": { "post": { "operationId": "preview_storage_recovery", "summary": "Preview storage recovery", "description": "Preview supported native audit evidence using the private native backend, never the legacy Activity facade. Unsupported events return conflicts/unsupported with no usable plan. Default-creation recovery needs explicit v2 replacement.\n\nRequired permissions: `collection:read`, `collection:write`, `binders:write`. MCP tool: `preview_storage_recovery`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 1048576, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "restoreUnassignedItemIds": { "maxItems": 16384, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "eventId", "restoreUnassignedItemIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "planVersion": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 } ] }, "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "supported": { "type": "boolean" }, "unsupported": { "maxItems": 16384, "type": "array", "items": { "type": "string" } }, "conflicts": { "maxItems": 16384, "type": "array", "items": {} }, "changes": { "maxItems": 16384, "type": "array", "items": {} }, "planToken": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "restoreUnassignedItemIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "rootRevisionsAdvance": { "type": "boolean", "const": true } }, "required": [ "planVersion", "eventId", "supported", "unsupported", "conflicts", "changes", "planToken", "restoreUnassignedItemIds", "rootRevisionsAdvance" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/recovery/apply": { "post": { "operationId": "apply_storage_recovery", "summary": "Apply storage recovery", "description": " A committed terminal rejection returns REST 409 storage_recovery_rejected or MCP isError with strict error.rejection (outcome, original operationId, code, inventoryRevision). Only recovery_plan_conflict and recovery_dependency_conflict are terminal. Accepted/rejected exact replay precedes mutable plan reconstruction but requires current authority. Preserve unknown requests; status, billing errors and cancellation are not proof. After proof, obtain a fresh complete current owner/session read and explicitly discard, or review a new preview and confirm a new operationId. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas metadata declares errors. Apply exactly reviewed native version-1 recovery with confirmation, planToken and retry-stable operationId. Current authority and newer/ABA changes remain enforced. No fallback to legacy recovery.\n\nRequired permissions: `collection:read`, `collection:write`, `binders:write`. MCP tool: `apply_storage_recovery`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 1048576, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "restoreUnassignedItemIds": { "maxItems": 16384, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "planToken": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "type": "boolean", "const": true }, "planVersion": { "type": "number", "const": 1 } }, "required": [ "eventId", "restoreUnassignedItemIds", "operationId", "planToken", "confirmed", "planVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "recoveredEventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "collections": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } } }, "required": [ "inventoryRevision", "eventId", "recoveredEventId", "collections" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_recovery_rejected" }, "message": { "type": "string", "const": "The original recovery did not commit. Read current storage before explicitly discarding or reviewing a new recovery." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "recovery_plan_conflict", "recovery_dependency_conflict" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/recovery/v2/preview": { "post": { "operationId": "preview_storage_recovery_v2", "summary": "Preview storage recovery v2", "description": "Preview default-creation recovery with one explicit same-owner replacement and its current inventory/content/layout revisions. Does not select a replacement or restore authority implicitly.\n\nRequired permissions: `collection:read`, `collection:write`, `binders:write`. MCP tool: `preview_storage_recovery_v2`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 1048576, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "restoreUnassignedItemIds": { "maxItems": 16384, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "planVersion": { "type": "number", "const": 2 }, "replacementDefaultCollectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collections": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } } }, "required": [ "eventId", "restoreUnassignedItemIds", "planVersion", "replacementDefaultCollectionId", "inventoryRevision", "collections" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "planVersion": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 } ] }, "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "supported": { "type": "boolean" }, "unsupported": { "maxItems": 16384, "type": "array", "items": { "type": "string" } }, "conflicts": { "maxItems": 16384, "type": "array", "items": {} }, "changes": { "maxItems": 16384, "type": "array", "items": {} }, "planToken": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "restoreUnassignedItemIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "rootRevisionsAdvance": { "type": "boolean", "const": true } }, "required": [ "planVersion", "eventId", "supported", "unsupported", "conflicts", "changes", "planToken", "restoreUnassignedItemIds", "rootRevisionsAdvance" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/recovery/v2/apply": { "post": { "operationId": "apply_storage_recovery_v2", "summary": "Apply storage recovery v2", "description": " A committed terminal rejection returns REST 409 storage_recovery_rejected or MCP isError with strict error.rejection (outcome, original operationId, code, inventoryRevision). Only recovery_plan_conflict and recovery_dependency_conflict are terminal. Accepted/rejected exact replay precedes mutable plan reconstruction but requires current authority. Preserve unknown requests; status, billing errors and cancellation are not proof. After proof, obtain a fresh complete current owner/session read and explicitly discard, or review a new preview and confirm a new operationId. MCP outputSchema describes accepted receipts only; holofolder.com/errorSchemas metadata declares errors. Apply the exact confirmed version-2 default-creation plan with explicit replacement and stable operationId. Unsupported dependencies and conflicts reject atomically; no legacy fallback.\n\nRequired permissions: `collection:read`, `collection:write`, `binders:write`. MCP tool: `apply_storage_recovery_v2`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 1048576, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "restoreUnassignedItemIds": { "maxItems": 16384, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "planVersion": { "type": "number", "const": 2 }, "replacementDefaultCollectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collections": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "planToken": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmed": { "type": "boolean", "const": true } }, "required": [ "eventId", "restoreUnassignedItemIds", "planVersion", "replacementDefaultCollectionId", "inventoryRevision", "collections", "operationId", "planToken", "confirmed" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "recoveredEventId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" }, "collections": { "maxItems": 4096, "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "collectionId", "version", "layoutRevision" ], "additionalProperties": false } } }, "required": [ "inventoryRevision", "eventId", "recoveredEventId", "collections" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only the bound terminal ledger rejection carries proof; ordinary conflicts do not.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "storage_recovery_rejected" }, "message": { "type": "string", "const": "The original recovery did not commit. Read current storage before explicitly discarding or reviewing a new recovery." }, "requestId": { "type": "string" }, "rejection": { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "operationId": { "type": "string", "minLength": 8, "maxLength": 100 }, "code": { "type": "string", "enum": [ "recovery_plan_conflict", "recovery_dependency_conflict" ] }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "outcome", "operationId", "code", "inventoryRevision" ], "additionalProperties": false } }, "required": [ "code", "message", "requestId", "rejection" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } ] } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/inventory/items": { "get": { "operationId": "list_inventory_items", "summary": "List inventory items", "description": "List physical copies with stable IDs, identity, recorded grade and placement. Certificates, private label assets and immutable source evidence are omitted. Pages are scope/filter/revision-bound and never complete snapshots or queue ACKs.\n\nRequired permissions: `collection:read`, `binders:read`. MCP tool: `list_inventory_items`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "collectionId", "in": "query", "required": false, "schema": { "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)$" } }, { "name": "cardId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "assignment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "assigned", "unassigned" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "developer-native-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "readRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string" } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "type": [ "string", "null" ] }, "scale": { "type": [ "string", "null" ] }, "designation": { "type": [ "string", "null" ] }, "holder": { "type": [ "string", "null" ] }, "subgrades": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "grade": { "type": "string" } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "labelVariant": { "type": [ "string", "null" ] } }, "required": [ "provider", "grade", "scale", "designation", "holder", "subgrades", "labelVariant" ], "additionalProperties": false }, { "type": "null" } ] }, "acquiredAt": { "type": [ "string", "null" ] }, "placement": { "anyOf": [ { "type": "object", "properties": { "inventoryItemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "inventoryItemId", "collectionId", "slotId", "version" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "version", "identity", "grading", "acquiredAt", "placement" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "projection", "completeSnapshot", "inventoryRevision", "readRevision", "data", "total", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/inventory/items/{id}": { "get": { "operationId": "get_inventory_item", "summary": "Get inventory item", "description": "Read one physical copy with its current item and placement revisions, using the same redacted private developer projection.\n\nRequired permissions: `collection:read`, `binders:read`. MCP tool: `get_inventory_item`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "developer-native-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "readRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "identity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, "grading": { "anyOf": [ { "type": "object", "properties": { "provider": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "known" }, "id": { "type": "string", "enum": [ "psa", "ace", "cgc", "beckett" ] } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" }, "name": { "type": "string" } }, "required": [ "kind", "name" ], "additionalProperties": false } ] }, "grade": { "type": [ "string", "null" ] }, "scale": { "type": [ "string", "null" ] }, "designation": { "type": [ "string", "null" ] }, "holder": { "type": [ "string", "null" ] }, "subgrades": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "grade": { "type": "string" } }, "required": [ "name", "grade" ], "additionalProperties": false } }, "labelVariant": { "type": [ "string", "null" ] } }, "required": [ "provider", "grade", "scale", "designation", "holder", "subgrades", "labelVariant" ], "additionalProperties": false }, { "type": "null" } ] }, "acquiredAt": { "type": [ "string", "null" ] }, "placement": { "anyOf": [ { "type": "object", "properties": { "inventoryItemId": { "type": "string", "minLength": 1, "maxLength": 200 }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "slotId": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "inventoryItemId", "collectionId", "slotId", "version" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "version", "identity", "grading", "acquiredAt", "placement" ], "additionalProperties": false } }, "required": [ "projection", "completeSnapshot", "inventoryRevision", "readRevision", "data" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/collections/{collectionId}/slots": { "get": { "operationId": "list_storage_slots", "summary": "List storage slots", "description": "Page ordered stable slots, current targets and wanted entries with item/placement/collection/layout preconditions. Empty targets are goals, not ownership. Cursor rejects changed revisions, scope or filters.\n\nRequired permissions: `collection:read`, `binders:read`. MCP tool: `list_storage_slots`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "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)$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "cardId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "collected", "finalized", "considering", "wishlisted" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "developer-native-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "readRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "collected", "finalized", "considering", "wishlisted" ] }, { "type": "null" } ] }, "wantedCards": { "type": "array", "items": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string" }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } } }, "required": [ "id", "collectionId", "position", "version", "collectionVersion", "layoutRevision", "inventoryItemId", "itemVersion", "placementVersion", "target", "status", "wantedCards" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "projection", "completeSnapshot", "inventoryRevision", "readRevision", "data", "total", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/collections/{collectionId}/slots/{id}": { "get": { "operationId": "get_storage_slot", "summary": "Get storage slot", "description": "Read one stable slot and all current edit preconditions. Removing a slot must retain its owned copy as Unassigned. No private planning/source/certificate/assets are returned.\n\nRequired permissions: `collection:read`, `binders:read`. MCP tool: `get_storage_slot`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "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)$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "developer-native-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "inventoryRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "readRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collectionVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layoutRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inventoryItemId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "itemVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "placementVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "kind", "cardId" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "collected", "finalized", "considering", "wishlisted" ] }, { "type": "null" } ] }, "wantedCards": { "type": "array", "items": { "type": "object", "properties": { "card_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "card_name": { "type": "string" }, "added_at": { "type": "string" }, "card_language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "card_finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "card_set": { "type": "string" }, "rarity": { "type": "string" }, "local_id": { "type": "string" }, "illustrator": { "type": "string" }, "set_total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "card_id", "card_name", "added_at" ], "additionalProperties": false } } }, "required": [ "id", "collectionId", "position", "version", "collectionVersion", "layoutRevision", "inventoryItemId", "itemVersion", "placementVersion", "target", "status", "wantedCards" ], "additionalProperties": false } }, "required": [ "projection", "completeSnapshot", "inventoryRevision", "readRevision", "data" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/presets": { "get": { "operationId": "list_storage_presets", "summary": "List storage presets", "description": "Discover versioned copied target presets and explicit unsupported scopes. Metadata only, no owner planning snapshot or creation intent. Existing Premium/lifetime key or OAuth authority is required.\n\nRequired permissions: `catalog:read`, `binders:read`. MCP tool: `list_storage_presets`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "copied-preset-preview-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "const": "1" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "supported": { "type": "boolean" }, "scope": { "type": "string" }, "limitation": { "type": [ "string", "null" ] } }, "required": [ "id", "version", "name", "supported", "scope", "limitation" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "limits": { "type": "object", "properties": { "species": { "type": "number", "const": 1025 }, "printings": { "type": "number", "const": 100 }, "uniquePrintings": { "type": "number", "const": 25 }, "responseBytes": { "type": "number", "const": 1048576 }, "catalogBytes": { "type": "number", "const": 2097152 }, "catalogRequests": { "type": "number", "const": 192 }, "timeoutMs": { "type": "number", "const": 5000 }, "pageSize": { "type": "number", "const": 10 } }, "required": [ "species", "printings", "uniquePrintings", "responseBytes", "catalogBytes", "catalogRequests", "timeoutMs", "pageSize" ], "additionalProperties": false } }, "required": [ "projection", "completeSnapshot", "data", "nextCursor", "limits" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/storage/presets/preview": { "post": { "operationId": "preview_storage_preset", "summary": "Preview storage preset", "description": "Preview a detached ordered copied manifest without saving, assigning ownership, creating wants or allocating operation/collection/slot IDs. Use version 1, with speciesIds only for selected-species or printings only for selected-printings. Exact catalog language and requested finish evidence must be available; incomplete/ambiguous evidence fails the whole preview. Set/master-set scopes are unsupported. Manifest entries are preset entry IDs, not slot IDs. Not complete planner or queue ACK evidence; no autosync.\n\nRequired permissions: `catalog:read`, `binders:read`. MCP tool: `preview_storage_preset`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-max-body-bytes": 65536, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetId": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "const": "1" }, "speciesIds": { "maxItems": 1025, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 1025 } }, "printings": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "cardId", "language" ], "additionalProperties": false } } }, "required": [ "presetId", "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projection": { "type": "string", "const": "copied-preset-preview-v1" }, "completeSnapshot": { "type": "boolean", "const": false }, "preset": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "manifest": { "type": "object", "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "version" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "entries": { "maxItems": 1025, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pokemon" }, "pokemonId": { "type": "integer", "minimum": 1, "maximum": 1025 } }, "required": [ "kind", "pokemonId" ], "additionalProperties": false }, { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "kind": { "type": "string", "const": "card" } }, "required": [ "cardId", "language", "kind" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "id", "target" ], "additionalProperties": false } } }, "required": [ "source", "name", "entries" ], "additionalProperties": false }, "scope": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 200 }, "speciesIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "printings": { "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] } }, "required": [ "cardId", "language" ], "additionalProperties": false } } }, "required": [ "kind" ], "additionalProperties": false }, "targetCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "freeSlotCount": { "type": "number", "const": 0 }, "ownershipCreated": { "type": "boolean", "const": false }, "exclusions": { "type": "array", "items": { "type": "string" } }, "unknowns": { "type": "array", "items": { "type": "string" } } }, "required": [ "projection", "completeSnapshot", "preset", "manifest", "scope", "targetCount", "freeSlotCount", "ownershipCreated", "exclusions", "unknowns" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/cards": { "get": { "operationId": "list_cards", "summary": "Search cards", "description": "Browse all card printings, including Trainers and Energy, with pagination. Records declare game:pokemon; IDs are globally unique opaque application IDs, not provider-local keys.\n\nRequired permissions: `catalog:read`. MCP tool: `list_cards`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "set", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "illustrator", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "pokemon", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9999 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "canonicalId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "aliasIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." } }, "localId": { "type": "string" }, "name": { "type": "string" }, "names": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "language": { "type": "string" }, "set": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name": { "type": "string" }, "officialCardCount": { "type": [ "number", "null" ] }, "releaseDate": { "type": [ "string", "null" ] } }, "required": [ "id", "game", "name", "officialCardCount", "releaseDate" ], "additionalProperties": false }, "seriesId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "category": { "type": [ "string", "null" ] }, "rarity": { "type": [ "string", "null" ] }, "hp": { "type": [ "number", "null" ] }, "illustrator": { "type": [ "string", "null" ] }, "types": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" } }, "externalIds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Provider-local IDs keyed by source, scoped to this record game. Not application IDs or aliases." }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "artworkRef": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "imageAvailability": { "type": "string", "enum": [ "available", "missing", "unavailable" ] }, "imageLanguage": { "type": [ "string", "null" ] }, "attribution": { "type": "string" } }, "required": [ "id", "game", "canonicalId", "aliasIds", "localId", "name", "names", "language", "set", "seriesId", "category", "rarity", "hp", "illustrator", "types", "variants", "externalIds", "details", "artworkRef", "image", "imageAvailability", "imageLanguage", "attribution" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": {} } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/cards/{id}": { "get": { "operationId": "get_card", "summary": "Get card", "description": "Look up a printing by its exact global application ID. game:pokemon is the only implemented catalog. externalIds are provider-local evidence scoped by game and source, never aliases.\n\nRequired permissions: `catalog:read`. MCP tool: `get_card`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "canonicalId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "aliasIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." } }, "localId": { "type": "string" }, "name": { "type": "string" }, "names": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "language": { "type": "string" }, "set": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name": { "type": "string" }, "officialCardCount": { "type": [ "number", "null" ] }, "releaseDate": { "type": [ "string", "null" ] } }, "required": [ "id", "game", "name", "officialCardCount", "releaseDate" ], "additionalProperties": false }, "seriesId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "category": { "type": [ "string", "null" ] }, "rarity": { "type": [ "string", "null" ] }, "hp": { "type": [ "number", "null" ] }, "illustrator": { "type": [ "string", "null" ] }, "types": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" } }, "externalIds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Provider-local IDs keyed by source, scoped to this record game. Not application IDs or aliases." }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "artworkRef": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "imageAvailability": { "type": "string", "enum": [ "available", "missing", "unavailable" ] }, "imageLanguage": { "type": [ "string", "null" ] }, "attribution": { "type": "string" } }, "required": [ "id", "game", "canonicalId", "aliasIds", "localId", "name", "names", "language", "set", "seriesId", "category", "rarity", "hp", "illustrator", "types", "variants", "externalIds", "details", "artworkRef", "image", "imageAvailability", "imageLanguage", "attribution" ], "additionalProperties": false } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/sets": { "get": { "operationId": "list_sets", "summary": "List sets", "description": "List card sets with game:pokemon and global application IDs. Filter by release year, for example 2017. Available symbol and logo URLs are served from the Holo Folder CDN.\n\nRequired permissions: `catalog:read`. MCP tool: `list_sets`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } }, { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(19|20)\\d{2}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name": { "type": "string" }, "names": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "symbol": { "description": "Available set symbol on the Holo Folder CDN.", "type": "string", "format": "uri" }, "logo": { "description": "Available set logo on the Holo Folder CDN.", "type": "string", "format": "uri" } }, "required": [ "id", "game", "name", "names" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": {} } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/sets/{id}": { "get": { "operationId": "get_set", "summary": "Get set", "description": "Look up a card set by global application ID, with game:pokemon.\n\nRequired permissions: `catalog:read`. MCP tool: `get_set`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name_json": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "game", "name_json" ], "additionalProperties": {} } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/series": { "get": { "operationId": "list_series", "summary": "List series", "description": "List card series with game:pokemon and global application IDs.\n\nRequired permissions: `catalog:read`. MCP tool: `list_series`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name": { "type": "string" }, "names": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "symbol": { "description": "Available set symbol on the Holo Folder CDN.", "type": "string", "format": "uri" }, "logo": { "description": "Available set logo on the Holo Folder CDN.", "type": "string", "format": "uri" } }, "required": [ "id", "game", "name", "names" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": {} } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/series/{id}": { "get": { "operationId": "get_series", "summary": "Get series", "description": "Look up a card series by global application ID, with game:pokemon.\n\nRequired permissions: `catalog:read`. MCP tool: `get_series`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Globally unique opaque application ID, never a reusable provider-local key." }, "game": { "type": "string", "const": "pokemon" }, "name_json": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "game", "name_json" ], "additionalProperties": {} } } } }, "400": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "See the API conventions page.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/languages": { "get": { "operationId": "list_languages", "summary": "List languages", "description": "List supported card languages.\n\nRequired permissions: `catalog:read`. MCP tool: `list_languages`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/pokemon": { "get": { "operationId": "list_pokemon", "summary": "List pokemon", "description": "List Pokédex entries.\n\nRequired permissions: `catalog:read`. MCP tool: `list_pokemon`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/pokemon/{id}": { "get": { "operationId": "get_pokemon", "summary": "Get pokemon", "description": "Look up a Pokédex entry.\n\nRequired permissions: `catalog:read`. MCP tool: `get_pokemon`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,4}$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/illustrators": { "get": { "operationId": "list_illustrators", "summary": "List illustrators", "description": "List card illustrators.\n\nRequired permissions: `catalog:read`. MCP tool: `list_illustrators`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/binders": { "get": { "operationId": "list_binders", "summary": "List binders", "description": "List your accessible binders with slot counts.\n\nRequired permissions: `binders:read`. MCP tool: `list_binders`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "post": { "operationId": "create_binder", "summary": "Create binder", "description": "Create a named binder.\n\nRequired permissions: `binders:write`. MCP tool: `create_binder`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/binders/{id}": { "patch": { "operationId": "update_binder", "summary": "Update binder", "description": "Rename a binder.\n\nRequired permissions: `binders:write`. MCP tool: `update_binder`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "delete": { "operationId": "delete_binder", "summary": "Delete binder", "description": "Delete a binder. Populated binders need explicit confirmation.\n\nRequired permissions: `binders:write`. MCP tool: `delete_binder`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirm": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/binders/order": { "put": { "operationId": "reorder_binders", "summary": "Reorder binders", "description": "Reorder all your binders.\n\nRequired permissions: `binders:write`. MCP tool: `reorder_binders`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "order": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "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)$" } } }, "required": [ "order" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/settings": { "get": { "operationId": "get_settings", "summary": "Get settings", "description": "Read persisted binder settings.\n\nRequired permissions: `settings:read`. MCP tool: `get_settings`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "binderId", "in": "query", "required": false, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "put": { "operationId": "update_settings", "summary": "Update settings", "description": "Replace persisted collection settings and optionally a binder layout.\n\nRequired permissions: `settings:write`. MCP tool: `update_settings`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "baseFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "binderId": { "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)$" }, "binderRows": { "type": "integer", "minimum": 1, "maximum": 8 }, "binderCols": { "type": "integer", "minimum": 1, "maximum": 8 }, "binderColorId": { "type": "string", "maxLength": 100 }, "binderPageColors": { "type": "object", "propertyNames": { "type": "string", "maxLength": 10 }, "additionalProperties": { "type": "string", "maxLength": 100 } }, "binderSlotGlareEnabled": { "type": "boolean" }, "cardFinishEffectsEnabled": { "type": "boolean" }, "darkMode": { "type": "boolean" }, "showBinderValue": { "type": "boolean" }, "pricingRegion": { "anyOf": [ { "type": "string", "enum": [ "UK", "EU", "US", "JP" ] }, { "type": "null" } ] }, "preferredCurrency": { "anyOf": [ { "type": "string", "enum": [ "GBP", "EUR", "USD", "JPY" ] }, { "type": "null" } ] }, "preferredCardLanguage": { "anyOf": [ { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, { "type": "null" } ] } }, "required": [ "baseFingerprint", "binderRows", "binderCols", "binderColorId", "binderPageColors", "binderSlotGlareEnabled", "cardFinishEffectsEnabled", "darkMode", "showBinderValue", "pricingRegion", "preferredCurrency", "preferredCardLanguage" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/prices/query": { "post": { "operationId": "get_prices", "summary": "Get prices", "description": "Read existing price evidence without contacting providers.\n\nRequired permissions: `prices:read`. MCP tool: `get_prices`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cards": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "maxLength": 50 } }, "required": [ "cardId" ], "additionalProperties": false } } }, "required": [ "cards" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/prices/refresh": { "post": { "operationId": "refresh_prices", "summary": "Refresh prices", "description": "Refresh a bounded batch of card prices with existing provider cooldowns.\n\nRequired permissions: `prices:refresh`. MCP tool: `refresh_prices`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cards": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } }, "required": [ "cardId" ], "additionalProperties": false } } }, "required": [ "cards" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/price-checks/{id}": { "get": { "operationId": "get_price_checks", "summary": "Get price checks", "description": "Read existing exact-printing market comparisons.\n\nRequired permissions: `prices:read`. MCP tool: `get_price_checks`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "finish", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "any" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ebay", "soldcomps" ] } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "post": { "operationId": "refresh_price_checks", "summary": "Refresh price checks", "description": "Refresh eBay asking comparisons within provider limits. Set source to ebay; sold-comps refreshes are app-only.\n\nRequired permissions: `prices:refresh`. MCP tool: `refresh_price_checks`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "any" ] }, "source": { "type": "string", "enum": [ "ebay", "soldcomps" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/comparison-jobs/{id}": { "get": { "operationId": "get_comparison_job", "summary": "Get comparison job", "description": "Read a background comparison job.\n\nRequired permissions: `prices:read`. MCP tool: `get_comparison_job`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "delete": { "operationId": "cancel_comparison_job", "summary": "Cancel comparison job", "description": "Cancel your accessible comparison job.\n\nRequired permissions: `prices:refresh`. MCP tool: `cancel_comparison_job`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/comparison-jobs/inspect": { "post": { "operationId": "inspect_comparison_job", "summary": "Inspect comparison job", "description": "Estimate comparison work and inspect existing jobs before starting.\n\nRequired permissions: `prices:read`. MCP tool: `inspect_comparison_job`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cards": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "any" ] } }, "required": [ "cardId", "finish" ], "additionalProperties": false } } }, "required": [ "cards" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/comparison-jobs": { "post": { "operationId": "start_comparison_job", "summary": "Start comparison job", "description": "App-only: starting background comparisons through REST or MCP returns ui_only. Read, inspect and cancel existing jobs instead.\n\nRequired permissions: `prices:refresh`. MCP tool: `start_comparison_job`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cards": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "any" ] } }, "required": [ "cardId", "finish" ], "additionalProperties": false } }, "confirmed": { "type": "boolean" } }, "required": [ "cards", "confirmed" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/prices/{id}/history": { "get": { "operationId": "get_price_history", "summary": "Get price history", "description": "Read all recorded price evidence with bounded keyset pagination.\n\nRequired permissions: `prices:read`. MCP tool: `get_price_history`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/collection/audit": { "get": { "operationId": "list_collection_audit", "summary": "List collection audit", "description": "Read private account-lifetime committed collection history. Filter operationId for the exact original acknowledged command; zero or multiple entries do not identify a single recovery event. Keyset cursor is bound to filters; private certificates and label assets are redacted. Legacy actors are Unknown. Requires current collection access.\n\nRequired permissions: `collection:read`. MCP tool: `list_collection_audit`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "operationId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(?:.*\\S)?$" } }, { "name": "collectionId", "in": "query", "required": false, "schema": { "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)$" } }, { "name": "inventoryItemId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "slotId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "pokemonId", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9999 } }, { "name": "cardId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "actorId", "in": "query", "required": false, "schema": { "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)$" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "recoveryOfEventId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/collection/audit/{id}": { "get": { "operationId": "get_collection_audit", "summary": "Get collection audit", "description": "Read one private committed audit event, including safe retained deltas and the original event ID for an undo.\n\nRequired permissions: `collection:read`. MCP tool: `get_collection_audit`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9]\\d{0,18}$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/deals/check": { "post": { "operationId": "check_deal", "summary": "Check deal", "description": "Evaluate an asking price using existing saved market evidence.\n\nRequired permissions: `prices:read`. MCP tool: `check_deal`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "askingPrice": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000000 }, "currency": { "type": "string", "enum": [ "GBP", "EUR", "USD", "JPY" ] }, "region": { "type": "string", "enum": [ "UK", "EU", "US", "JP" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo" ] }, "thresholds": { "type": "object", "properties": { "greatPct": { "type": "number", "minimum": 0, "maximum": 100 }, "fairPct": { "type": "number", "minimum": 0, "maximum": 100 }, "walkAwayPct": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "greatPct", "fairPct", "walkAwayPct" ], "additionalProperties": false } }, "required": [ "cardId", "askingPrice", "currency" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/pokemon/sets/{id}/slots": { "get": { "operationId": "get_pokemon_set_slots", "summary": "Get pokemon set slots", "description": "Read Pokémon species grouped by National Dex number within a set. These are not stable storage slots. Use list_cards for all printings, including Trainers and Energy.\n\nRequired permissions: `catalog:read`. MCP tool: `get_pokemon_set_slots`.", "tags": [ "Catalog" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/listings/{id}": { "get": { "operationId": "get_listings", "summary": "Get listings", "description": "Read current eBay listings. May contact the provider.\n\nRequired permissions: `prices:refresh`. MCP tool: `get_listings`.", "tags": [ "Prices and insights" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "finish", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "normal", "holo", "reverse_holo" ] } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/identity": { "get": { "operationId": "get_identity", "summary": "Get identity", "description": "Read your account username and display name.\n\nRequired permissions: `settings:read`. MCP tool: `get_identity`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "patch": { "operationId": "update_identity", "summary": "Update identity", "description": "Update your own public username or display name.\n\nRequired permissions: `settings:write`. MCP tool: `update_identity`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 60 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/binders/{binderId}/identity": { "get": { "operationId": "get_binder_identity", "summary": "Get binder identity", "description": "Read the public identity assigned to an accessible binder.\n\nRequired permissions: `binders:read`. MCP tool: `get_binder_identity`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "binderId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "patch": { "operationId": "update_binder_identity", "summary": "Update binder identity", "description": "Set a public slug on a binder you own.\n\nRequired permissions: `sharing:manage`. MCP tool: `update_binder_identity`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "binderId", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "slug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/binders/{binderId}/sharing": { "get": { "operationId": "get_sharing", "summary": "Get sharing", "description": "Read sharing state. Only the collection owner may access share tokens.\n\nRequired permissions: `sharing:manage`. MCP tool: `get_sharing`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "binderId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "put": { "operationId": "update_sharing", "summary": "Update sharing", "description": "Enable or disable sharing on a binder you own, with explicit price disclosure.\n\nRequired permissions: `sharing:manage`. MCP tool: `update_sharing`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "binderId", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "showPrices": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/appearance": { "get": { "operationId": "get_appearance", "summary": "Get appearance", "description": "Read the collection binder appearance and revision.\n\nRequired permissions: `binders:read`. MCP tool: `get_appearance`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "put": { "operationId": "update_appearance", "summary": "Update appearance", "description": "Save a binder appearance only if its revision still matches.\n\nRequired permissions: `binders:write`. MCP tool: `update_appearance`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "baseRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740990 }, "design": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "baseRevision", "design" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/partners": { "get": { "operationId": "list_partners", "summary": "List partners", "description": "Read your current partnership and paginated invitations.\n\nRequired permissions: `partners:manage`. MCP tool: `list_partners`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "delete": { "operationId": "disconnect_partner", "summary": "Disconnect partner", "description": "Disconnect your partnership. This removes your access to a partner-owned collection.\n\nRequired permissions: `partners:manage`. MCP tool: `disconnect_partner`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false, "required": [] } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/partners/invites": { "post": { "operationId": "invite_partner", "summary": "Invite partner", "description": "Invite a partner. Repeating a pending invitation does not create another.\n\nRequired permissions: `partners:manage`. MCP tool: `invite_partner`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/partners/invites/{inviteId}/accept": { "post": { "operationId": "accept_partner_invite", "summary": "Accept partner invite", "description": "Accept an invitation addressed to your verified account email.\n\nRequired permissions: `partners:manage`. MCP tool: `accept_partner_invite`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/partners/invites/{inviteId}/reject": { "post": { "operationId": "reject_partner_invite", "summary": "Reject partner invite", "description": "Reject an invitation addressed to your account.\n\nRequired permissions: `partners:manage`. MCP tool: `reject_partner_invite`.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/show-purchases": { "get": { "operationId": "list_show_purchases", "summary": "List show purchases", "description": "Read paginated account show purchases.\n\nRequired permissions: `collection:read`. MCP tool: `list_show_purchases`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } }, "post": { "operationId": "add_show_purchase", "summary": "Add show purchase", "description": "Record a purchase once using a client-generated purchase ID.\n\nRequired permissions: `collection:write`. MCP tool: `add_show_purchase`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "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)$" }, "cardId": { "type": "string", "minLength": 1, "maxLength": 64 }, "cardName": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "enum": [ "en", "fr", "de", "es", "it", "pt-br", "ja", "ko" ] }, "finish": { "type": "string", "enum": [ "normal", "holo", "reverse_holo", "double_rare", "ultra_rare", "illustration_rare", "special_illustration_rare", "secret_rare", "hyper_rare", "radiant_rare", "ace_spec", "amazing_rare", "shiny_rare", "jumbo" ] }, "price": { "type": "number", "minimum": 0, "maximum": 9999999999, "multipleOf": 0.01 }, "marketPrice": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 9999999999, "multipleOf": 0.01 }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "GBP", "EUR", "USD", "JPY" ] }, "boughtAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "bundleId": { "anyOf": [ { "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)$" }, { "type": "null" } ] } }, "required": [ "clientId", "cardId", "cardName", "price", "currency", "boughtAt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/show-purchases/{clientId}": { "delete": { "operationId": "remove_show_purchase", "summary": "Remove show purchase", "description": "Undo a purchase from your accessible collection account.\n\nRequired permissions: `collection:write`. MCP tool: `remove_show_purchase`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "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)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/artwork/uploads": { "post": { "operationId": "prepare_artwork_upload", "summary": "Prepare artwork upload", "description": "Create a signed private R2 upload URL and artworkRef for the appearance design. Send the returned headers and exact file bytes.\n\nRequired permissions: `binders:write`. MCP tool: `prepare_artwork_upload`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "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)$" }, "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 5242880 } }, "required": [ "id", "mimeType", "size" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } }, "/artwork/{id}": { "get": { "operationId": "get_artwork", "summary": "Get artwork", "description": "Get a five-minute download URL for your private binder artwork.\n\nRequired permissions: `binders:read`. MCP tool: `get_artwork`.", "tags": [ "Collection" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "See the API conventions page." }, "401": { "description": "See the API conventions page." }, "402": { "description": "See the API conventions page." }, "403": { "description": "See the API conventions page." }, "404": { "description": "See the API conventions page." }, "409": { "description": "See the API conventions page." }, "413": { "description": "See the API conventions page." }, "422": { "description": "See the API conventions page." }, "429": { "description": "See the API conventions page." }, "503": { "description": "See the API conventions page." } } } } } }