# Holo Folder developer documentation ## Machine-readable resources - [All documentation in one file](https://holofolder.com/app/docs/llms-full.txt) - [OpenAPI 3.1 contract](https://holofolder.com/app/openapi.json) - [MCP server](https://holofolder.com/app/mcp) REST requires a personal API key. MCP uses OAuth. Documentation is public; API operations require the access and permissions described in the guides. # Restore raw collection content Source: https://holofolder.com/app/docs/reference/collection/restore-raw-collection-content POST https://app.holofolder.com/app/api/v1/storage/restores/raw-content OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Import storage arrangement Source: https://holofolder.com/app/docs/reference/collection/import-storage-arrangement POST https://app.holofolder.com/app/api/v1/storage/imports/arrangement OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Execute slot commands Source: https://holofolder.com/app/docs/reference/collection/execute-slot-commands POST https://app.holofolder.com/app/api/v1/storage/slots/commands OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Execute inventory commands Source: https://holofolder.com/app/docs/reference/collection/execute-inventory-commands POST https://app.holofolder.com/app/api/v1/storage/inventory/commands OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List storage collections Source: https://holofolder.com/app/docs/reference/collection/list-storage-collections GET https://app.holofolder.com/app/api/v1/storage/collections OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Create storage collection Source: https://holofolder.com/app/docs/reference/collection/create-storage-collection POST https://app.holofolder.com/app/api/v1/storage/collections OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Preview storage recovery Source: https://holofolder.com/app/docs/reference/collection/preview-storage-recovery POST https://app.holofolder.com/app/api/v1/storage/recovery/preview OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Apply storage recovery Source: https://holofolder.com/app/docs/reference/collection/apply-storage-recovery POST https://app.holofolder.com/app/api/v1/storage/recovery/apply OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Preview storage recovery v2 Source: https://holofolder.com/app/docs/reference/collection/preview-storage-recovery-v2 POST https://app.holofolder.com/app/api/v1/storage/recovery/v2/preview OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Apply storage recovery v2 Source: https://holofolder.com/app/docs/reference/collection/apply-storage-recovery-v2 POST https://app.holofolder.com/app/api/v1/storage/recovery/v2/apply OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List inventory items Source: https://holofolder.com/app/docs/reference/collection/list-inventory-items GET https://app.holofolder.com/app/api/v1/inventory/items OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Get inventory item Source: https://holofolder.com/app/docs/reference/collection/get-inventory-item GET https://app.holofolder.com/app/api/v1/inventory/items/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List storage slots Source: https://holofolder.com/app/docs/reference/collection/list-storage-slots GET https://app.holofolder.com/app/api/v1/storage/collections/{collectionId}/slots OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Get storage slot Source: https://holofolder.com/app/docs/reference/collection/get-storage-slot GET https://app.holofolder.com/app/api/v1/storage/collections/{collectionId}/slots/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List storage presets Source: https://holofolder.com/app/docs/reference/collection/list-storage-presets GET https://app.holofolder.com/app/api/v1/storage/presets OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Preview storage preset Source: https://holofolder.com/app/docs/reference/collection/preview-storage-preset POST https://app.holofolder.com/app/api/v1/storage/presets/preview OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List binders Source: https://holofolder.com/app/docs/reference/collection/list-binders GET https://app.holofolder.com/app/api/v1/binders OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Create binder Source: https://holofolder.com/app/docs/reference/collection/create-binder POST https://app.holofolder.com/app/api/v1/binders OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update binder Source: https://holofolder.com/app/docs/reference/collection/update-binder PATCH https://app.holofolder.com/app/api/v1/binders/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 binder Source: https://holofolder.com/app/docs/reference/collection/delete-binder DELETE https://app.holofolder.com/app/api/v1/binders/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Reorder binders Source: https://holofolder.com/app/docs/reference/collection/reorder-binders PUT https://app.holofolder.com/app/api/v1/binders/order OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # List collection audit Source: https://holofolder.com/app/docs/reference/collection/list-collection-audit GET https://app.holofolder.com/app/api/v1/collection/audit OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get collection audit Source: https://holofolder.com/app/docs/reference/collection/get-collection-audit GET https://app.holofolder.com/app/api/v1/collection/audit/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get binder identity Source: https://holofolder.com/app/docs/reference/collection/get-binder-identity GET https://app.holofolder.com/app/api/v1/binders/{binderId}/identity OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update binder identity Source: https://holofolder.com/app/docs/reference/collection/update-binder-identity PATCH https://app.holofolder.com/app/api/v1/binders/{binderId}/identity OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get sharing Source: https://holofolder.com/app/docs/reference/collection/get-sharing GET https://app.holofolder.com/app/api/v1/binders/{binderId}/sharing OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update sharing Source: https://holofolder.com/app/docs/reference/collection/update-sharing PUT https://app.holofolder.com/app/api/v1/binders/{binderId}/sharing OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get appearance Source: https://holofolder.com/app/docs/reference/collection/get-appearance GET https://app.holofolder.com/app/api/v1/appearance OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update appearance Source: https://holofolder.com/app/docs/reference/collection/update-appearance PUT https://app.holofolder.com/app/api/v1/appearance OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # List show purchases Source: https://holofolder.com/app/docs/reference/collection/list-show-purchases GET https://app.holofolder.com/app/api/v1/show-purchases OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Add show purchase Source: https://holofolder.com/app/docs/reference/collection/add-show-purchase POST https://app.holofolder.com/app/api/v1/show-purchases OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Remove show purchase Source: https://holofolder.com/app/docs/reference/collection/remove-show-purchase DELETE https://app.holofolder.com/app/api/v1/show-purchases/{clientId} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Prepare artwork upload Source: https://holofolder.com/app/docs/reference/collection/prepare-artwork-upload POST https://app.holofolder.com/app/api/v1/artwork/uploads OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get artwork Source: https://holofolder.com/app/docs/reference/collection/get-artwork GET https://app.holofolder.com/app/api/v1/artwork/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Search cards Source: https://holofolder.com/app/docs/reference/catalog/list-cards GET https://app.holofolder.com/app/api/v1/cards OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Get card Source: https://holofolder.com/app/docs/reference/catalog/get-card GET https://app.holofolder.com/app/api/v1/cards/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List sets Source: https://holofolder.com/app/docs/reference/catalog/list-sets GET https://app.holofolder.com/app/api/v1/sets OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Get set Source: https://holofolder.com/app/docs/reference/catalog/get-set GET https://app.holofolder.com/app/api/v1/sets/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List series Source: https://holofolder.com/app/docs/reference/catalog/list-series GET https://app.holofolder.com/app/api/v1/series OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # Get series Source: https://holofolder.com/app/docs/reference/catalog/get-series GET https://app.holofolder.com/app/api/v1/series/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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 } } } } } } ``` # List languages Source: https://holofolder.com/app/docs/reference/catalog/list-languages GET https://app.holofolder.com/app/api/v1/languages OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # List pokemon Source: https://holofolder.com/app/docs/reference/catalog/list-pokemon GET https://app.holofolder.com/app/api/v1/pokemon OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get pokemon Source: https://holofolder.com/app/docs/reference/catalog/get-pokemon GET https://app.holofolder.com/app/api/v1/pokemon/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # List illustrators Source: https://holofolder.com/app/docs/reference/catalog/list-illustrators GET https://app.holofolder.com/app/api/v1/illustrators OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get pokemon set slots Source: https://holofolder.com/app/docs/reference/catalog/get-pokemon-set-slots GET https://app.holofolder.com/app/api/v1/pokemon/sets/{id}/slots OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get settings Source: https://holofolder.com/app/docs/reference/account/get-settings GET https://app.holofolder.com/app/api/v1/settings OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update settings Source: https://holofolder.com/app/docs/reference/account/update-settings PUT https://app.holofolder.com/app/api/v1/settings OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get identity Source: https://holofolder.com/app/docs/reference/account/get-identity GET https://app.holofolder.com/app/api/v1/identity OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Update identity Source: https://holofolder.com/app/docs/reference/account/update-identity PATCH https://app.holofolder.com/app/api/v1/identity OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # List partners Source: https://holofolder.com/app/docs/reference/account/list-partners GET https://app.holofolder.com/app/api/v1/partners OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Disconnect partner Source: https://holofolder.com/app/docs/reference/account/disconnect-partner DELETE https://app.holofolder.com/app/api/v1/partners OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Invite partner Source: https://holofolder.com/app/docs/reference/account/invite-partner POST https://app.holofolder.com/app/api/v1/partners/invites OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Accept partner invite Source: https://holofolder.com/app/docs/reference/account/accept-partner-invite POST https://app.holofolder.com/app/api/v1/partners/invites/{inviteId}/accept OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Reject partner invite Source: https://holofolder.com/app/docs/reference/account/reject-partner-invite POST https://app.holofolder.com/app/api/v1/partners/invites/{inviteId}/reject OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get prices Source: https://holofolder.com/app/docs/reference/prices-and-insights/get-prices POST https://app.holofolder.com/app/api/v1/prices/query OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Refresh prices Source: https://holofolder.com/app/docs/reference/prices-and-insights/refresh-prices POST https://app.holofolder.com/app/api/v1/prices/refresh OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get price checks Source: https://holofolder.com/app/docs/reference/prices-and-insights/get-price-checks GET https://app.holofolder.com/app/api/v1/price-checks/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Refresh price checks Source: https://holofolder.com/app/docs/reference/prices-and-insights/refresh-price-checks POST https://app.holofolder.com/app/api/v1/price-checks/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get comparison job Source: https://holofolder.com/app/docs/reference/prices-and-insights/get-comparison-job GET https://app.holofolder.com/app/api/v1/comparison-jobs/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Cancel comparison job Source: https://holofolder.com/app/docs/reference/prices-and-insights/cancel-comparison-job DELETE https://app.holofolder.com/app/api/v1/comparison-jobs/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Inspect comparison job Source: https://holofolder.com/app/docs/reference/prices-and-insights/inspect-comparison-job POST https://app.holofolder.com/app/api/v1/comparison-jobs/inspect OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Start comparison job Source: https://holofolder.com/app/docs/reference/prices-and-insights/start-comparison-job POST https://app.holofolder.com/app/api/v1/comparison-jobs OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get price history Source: https://holofolder.com/app/docs/reference/prices-and-insights/get-price-history GET https://app.holofolder.com/app/api/v1/prices/{id}/history OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Check deal Source: https://holofolder.com/app/docs/reference/prices-and-insights/check-deal POST https://app.holofolder.com/app/api/v1/deals/check OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # Get listings Source: https://holofolder.com/app/docs/reference/prices-and-insights/get-listings GET https://app.holofolder.com/app/api/v1/listings/{id} OpenAPI operation (parameters, authentication, request body and responses): ```json { "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." } } } ``` # ChatGPT Source: https://holofolder.com/app/docs/agents/chatgpt Connect your collection through a custom MCP connection. ChatGPT can connect to Holo Folder where your account and workspace support custom remote MCP servers. Availability and setup controls depend on your plan and workspace permissions. **Check your workspace first** OpenAI currently documents custom MCP connections for Business and Enterprise/Edu workspaces on ChatGPT web. A workspace admin may need to create the connection or grant permission. Check [OpenAI's current availability guide](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt) if the controls below are missing. ## Create the connection In a workspace where you can create custom MCP connections, open the custom plugin or app creation controls. Current interfaces may use **Create plugins with MCPs**; legacy interfaces use **Settings → Apps → Create**. Use these connection details: | Setting | Value | | -------------- | ------------------------------------ | | Name | Holo Folder | | MCP server URL | `https://app.holofolder.com/app/mcp` | | Authentication | OAuth | Create the connection and complete Holo Folder's browser sign-in. Review the client and permissions on the consent screen before approving. No personal REST API key is needed. ## Use it in a conversation Enable the connection for your conversation using ChatGPT's available app or tool controls. Ask “Show my Holo Folder binders, then help me browse my wanted cards. Don't change anything.” If the connection needs to be made available to other workspace members, follow your workspace's app review and publication process. [Connection and permission details](https://holofolder.com/app/docs/markdown/mcp) · [OpenAI's official custom MCP guide](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt) # Claude Source: https://holofolder.com/app/docs/agents/claude Connect Holo Folder to Claude and Claude Code. Use Holo Folder's remote MCP server with OAuth. You sign in through your browser and choose the permissions Claude receives. ## Claude Code Add the HTTP server from your terminal: ```sh title="Terminal" claude mcp add --transport http holofolder \ https://app.holofolder.com/app/mcp ``` Open Claude Code and run `/mcp`. Select Holo Folder and follow the browser authentication flow. Sign in, review the consent screen, and return to Claude Code after approving. ## Claude custom connector Where your Claude plan and workspace allow custom connectors, open **Customize → Connectors**, choose **Add custom connector**, name it **Holo Folder**, and enter: ```text title="Remote MCP server URL" https://app.holofolder.com/app/mcp ``` Choose OAuth sign-in. If asked how Claude should identify itself, select **Register automatically**, then complete the sign-in flow. Team and Enterprise workspaces may need an owner to add the connector first. This is a remote connection, so you don't need to configure a local command or install an MCP bridge. ## Check the connection Ask Claude to “List my Holo Folder binders without making any changes.” If tools are unavailable, open the client's MCP or connector controls and check whether the server needs authentication. [Connection and permission details](https://holofolder.com/app/docs/markdown/mcp) · [Claude Code's official MCP guide](https://code.claude.com/docs/en/mcp) · [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) # Codex Source: https://holofolder.com/app/docs/agents/codex Give your coding agent access to Holo Folder. Use the Codex CLI's remote MCP support to connect through OAuth. ## Add Holo Folder ```sh title="Terminal" codex mcp add holofolder --url https://app.holofolder.com/app/mcp codex mcp login holofolder ``` Complete the browser sign-in, review the consent screen and approve the permissions you want to grant. ## Configure it manually If you manage MCP servers in `~/.codex/config.toml`, add: ```toml title="~/.codex/config.toml" [mcp_servers.holofolder] url = "https://app.holofolder.com/app/mcp" ``` Then run `codex mcp login holofolder` to authorise the connection. The CLI and compatible editor environments can use the configured server; check your environment's MCP controls if it maintains a separate configuration. If you already added the old `holofolder.com` URL, update the `url` in your existing config entry to `https://app.holofolder.com/app/mcp`, then run `codex mcp login holofolder` again. ## Check the connection Ask “Use Holo Folder to list my binders. Do not change anything.” The agent should use the connected tools rather than ask for a personal API key. [Connection and permission details](https://holofolder.com/app/docs/markdown/mcp) · [Official MCP setup guide](https://developers.openai.com/codex/mcp/) # Cursor Source: https://holofolder.com/app/docs/agents/cursor Bring your collection into Cursor's agent. Add Holo Folder as a remote MCP server, then authorise it with your Holo Folder account. ## Add the server Put this configuration in `.cursor/mcp.json` for your project, or `~/.cursor/mcp.json` for your user: ```json title=".cursor/mcp.json" { "mcpServers": { "holofolder": { "url": "https://app.holofolder.com/app/mcp" } } } ``` Merge this entry into your existing `mcpServers` object if you already have servers configured. ## Sign in Open Cursor's MCP controls from its **Customize** settings. Enable Holo Folder and complete the OAuth sign-in when prompted. Review the client and requested permissions before approving. You do not need an `Authorization` header, REST API key or local server command for this connection. ## Check the connection In an agent conversation, ask “Find Pokémon cards featuring Umbreon in Holo Folder's catalog.” Check the proposed tool call before running it. Start with reads; only grant write access if you want the agent to change your collection. [Connection and permission details](https://holofolder.com/app/docs/markdown/mcp) · [Cursor's official MCP guide](https://cursor.com/docs/mcp) # API keys Source: https://holofolder.com/app/docs/api-keys Your first request, in a few minutes. Personal API keys connect your scripts and integrations to Holo Folder. Create a key, keep it on your server, and send it with each request. [ Open the API explorer ](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards) [ Connect an AI assistant ](https://holofolder.com/app/docs/markdown/mcp) **Using Claude, ChatGPT, Cursor or Codex?** Use the [AI setup guides](https://holofolder.com/app/docs/markdown/mcp) to connect through MCP with your Holo Folder login. You won't need to create or paste an API key. ## Create a key Create a key here using your signed-in account. You can also manage the same keys in **Settings → Account → Developer access** in the app. [Create or manage an API key in the interactive guide](https://holofolder.com/app/docs/api-keys#create-a-key) 1. Sign in above if you haven't already. 2. Give the key a name you'll recognise, such as “Collection export”. 3. Choose its permissions and expiry. Start with read access. 4. Copy the full key and save it somewhere secure. It's shown only once. A current Premium subscription or lifetime licence is required. Signup trials do not include developer access. ## Authentication Send the full key in the `Authorization` header with the `Bearer` prefix: ```http title="Request header" Authorization: Bearer hf_YOUR_KEY_ID.YOUR_SECRET ``` Keep the key in a server environment variable. Never put it in a URL, browser bundle or public repository. The REST API uses personal API keys; browser cookies and MCP OAuth tokens cannot replace them. ## Make your first request This request returns up to ten cards. Replace the placeholder with your key: ```sh title="Terminal" export HOLOFOLDER_API_KEY='hf_YOUR_KEY_ID.YOUR_SECRET' curl --fail-with-body \ -H "Authorization: Bearer $HOLOFOLDER_API_KEY" \ 'https://app.holofolder.com/app/api/v1/cards?limit=10' ``` Use the returned `nextCursor` with the same filters to continue. See [pagination](https://holofolder.com/app/docs/markdown/contracts#pagination) for the full convention. Prefer to try it in your browser? Open [Search cards](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards), select **Try in Playground**, enter your key, and send a request. The explorer also generates code examples from your inputs. ## Choose permissions Read access is the default. Select writes explicitly only when your integration needs them. Each endpoint in the [API explorer](https://holofolder.com/app/docs/markdown/reference) lists the permissions it requires. | Permission | What it allows | | ----------------------------------------------------- | ---------------------------------------------- | | `catalog:read` | Browse cards, sets and Pokémon | | `binders:read`, `collection:read` | Read your binders, collection and wanted cards | | `prices:read` | Read available price evidence | | `settings:read` | Read settings and account identity | | `binders:write`, `collection:write`, `settings:write` | Change the corresponding account data | | `prices:refresh` | Request provider refreshes within their limits | | `sharing:manage`, `partners:manage` | Manage sharing and partner access | A valid key still needs paid access and the right permissions. Partner access follows current membership. Revocation is checked on every request. ## Expiry, rotation & revocation Keys expire after **30, 90 or 365 days**, with **90 days** as the default. Each account can have up to **ten active keys**. Revoke a key at any time in developer settings. Rotation creates a new key; existing secrets cannot be recovered. Update your integration to use the replacement, then revoke the old one. # Bulk layout Source: https://holofolder.com/app/docs/bulk-layout Select, move, fill and remove several binder pockets at once. Choose **Edit layout** above the binder and tap pockets to select them, across pages if you like. The bar shows the count, and tapping a selected pocket deselects it. Up to 256 pockets can change in one edit. Every action works with buttons and the keyboard, without dragging across pages. ## Move and add **Move**, then tap a pocket outside the selection to move the whole group before it, or choose **To the start** or **To the end**. Pockets keep their targets, cards and wants, in their saved relative order. **Add** inserts one empty pocket before or after the selection or at the end of the binder, or a whole page of empty pockets (the current grid size) before the selection or at the end. Following pockets shift automatically, including across pages, and changing the grid later repaginates them. A binder holds at most 4,096 pockets. ## Fill from spare cards Select pockets and choose **Fill**. **Fill pockets from spare cards** lists each pocket with a **Choose a card** picker. Spare cards are ones you own that aren't in a pocket yet. **Match my spare cards** proposes compatible spares for empty targets; it creates no cards or grades. Choose a card or **Leave empty** for each pocket, then confirm **Add N cards**. Occupied pockets are kept. Target mismatches, copies already in a pocket and the same copy chosen twice can't be confirmed. ## Remove pockets Select pockets and choose **Remove**. The review lists the pockets that will go, their targets and explicit wants, and the owned cards that become spare. Every owned card keeps its identity, grading and source details. The pockets after them close up and everything else keeps its order. This does not delete the binder or any owned card, and it can't be undone with one tap: add pockets back and place the cards again, or use [Activity](https://holofolder.com/app/docs/markdown/collection-history) recovery where it's supported. ## Saving, conflicts and limits Each action is one atomic request, never several partial saves. A request that is too large is refused whole, so select fewer pockets. If the pockets change while selected, choose **Update selection**. Fill and Remove need a connection, a complete current read and no unsynced edits. Edits save on the device first and sync when online, keeping the original operation ID through retries. A lost reply is retried with the same request, and an unknown outcome can't be silently replaced. Device-save failures show **Try again** and **Discard**. **Done** exits editing without discarding accepted edits. ## API Moves, inserts and removals use `execute_slot_commands` (`POST /app/api/v1/storage/slots/commands`); fill uses `execute_inventory_commands`. Both are available over REST and MCP with `collection:write` and `binders:write`. See [native storage](https://holofolder.com/app/docs/markdown/native-storage). # Collection history Source: https://holofolder.com/app/docs/collection-history See what changed in your collection and safely undo a change. ## Activity in the app Open **Activity** from the collection's manage menu. Entries are grouped by day and say what happened, with the card, person and local time. Simple additions and removals are compact receipts. Choose **View changes** for meaningful before/after values such as a printing swap; bulk changes expand a few at a time. A previous member is labelled **Previous member**; an unattributed entry stays **Unknown**. These labels do not invent historical profile names. **Filters** searches the complete recorded history, including deleted cards. Choose a collection, person, action or inclusive UTC date range. **Older page** and **Newer page** follow server cursors, so long histories stay reachable. Displayed times use your device's timezone. ## Undo a change Undo works for recorded copy, slot and collection changes, such as adding, moving, assigning, removing or regrading a copy, slot edits, bulk changes and creating a collection. Choose **See what undoing does** to get a preview from the server, then **Undo this change** to apply it. If the change can no longer be undone, the preview says so and offers nothing to apply. When a change removed cards, tick the ones to bring back. They return to your collection as Unassigned copies, not to a pocket. Undoing the creation of your default binder asks which binder should open first instead. The server checks current access and later changes before applying. A newer edit to the same data is a conflict, and there is no force overwrite. Undo adds a new history entry linked to the original, and the original shows **Undone** once its linked undo is on the loaded page. Settings, sharing and appearance changes cannot be undone from Activity. ## Offline and connection failures Previously opened activity pages remain available on this device with their last-update time. They are saved pages, not a complete offline history. Reconnect to load another page or start an undo. Pending local edits must sync first. A confirmed undo is saved on the device before it is sent, so a lost connection or reload does not lose it. The app shows **Undo saved on this device** until the server confirms it, then checks your collection again before showing **Undone**. Use **Try again** or **Check my collection** to continue; a retry sends the same request and cannot apply it twice. If the server rejects the undo because your collection changed, nothing was applied. You can then **Discard this undo** and **Start a new undo** from a fresh preview. ## REST and MCP Developer access requires current entitlement, credential grants and owner/linked-partner access. The app uses its signed-in session. Responses are private and use `no-store`. Public share links have no private Activity. `list_collection_audit` (`GET /collection/audit`) and `get_collection_audit` (`GET /collection/audit/{id}`) require `collection:read`. Event IDs are strings. Lists return `data` and `nextCursor`, with up to 100 entries. Keep the same filters when following a cursor. Filters include `collectionId`, `pokemonId` and `cardId` (matched against slot targets, owned copies and wanted cards), `inventoryItemId`, `slotId`, `actorId`, `action`, `since`, `until` and `recoveryOfEventId`. The last filter finds undo events linked to an original. An undo entry also includes `recovery_of_event_id`. Undo through REST and MCP uses the native storage recovery operations (`preview_storage_recovery`, `apply_storage_recovery` and their v2 forms), described below. Each entry's `changes` lists the rows it changed, reduced to the fields Activity shows. Private certificates, label assets, uploaded artwork references and share tokens are never returned in history or recovery responses. Every write records one entry as part of the same transaction, so history and the collection never disagree. Binder renames, reordering, layout, sharing, appearance and settings saves are recorded too. ## Native storage recovery The app and the registered REST/MCP operations use the same recovery executor. A preview lists public-safe changes and explicit conflict reasons; applying it needs the exact reviewed plan, explicit confirmation and a retry-stable operation ID. There is no offline optimistic restoration and no automatic replacement request. ### Recovery rejection The v1/v2 apply contract declares REST `409 storage_recovery_rejected`, or MCP `isError:true`, only for a committed strict `error.rejection` containing `outcome:"rejected"`, the original `operationId`, known `code` and `inventoryRevision`. Codes are `recovery_plan_conflict` and `recovery_dependency_conflict`. Arbitrary 409/SQL errors, missing receipts, cancellation and billing/access errors are not noncommit proof. Exact accepted/rejected replay requires current authority and precedes mutable plan reconstruction. After a committed rejection, the app reads your current collection again before offering **Discard this undo**. A discarded undo is kept as discarded, never as applied. A new undo needs a new preview, explicit confirmation and a new operation ID. Unknown and accepted requests can only be retried or checked, never discarded. No private inverse, evidence, certificates or assets are exposed. ### Find an exact operation REST `GET /app/api/v1/collection/audit?operationId=synthetic-original-operation` and MCP `list_collection_audit` with `{"operationId":"synthetic-original-operation"}` find the exact original operation within your currently authorized history. The example ID is synthetic. Keep the same filters when following `nextCursor`, then use `get_collection_audit` with the selected event ID to inspect it. An empty result does not prove that a command failed. Multiple events require choosing an exact event; never use the newest event as a guessed inverse. Operation IDs are bounded opaque strings, up to 200 characters without surrounding whitespace or line breaks. Private recovery evidence remains server-only. # API conventions Source: https://holofolder.com/app/docs/contracts Permissions, pagination, errors and image availability. ## Card, copy and species identity `cardId` identifies a catalog printing, `inventoryItemId` a physical copy, `slotId` a stable storage slot and `collectionId` a storage collection. Repeated copies keep distinct identities. Existing versioned commands retain their `itemId` fields for physical copies; do not rewrite queued commands or backups to match Activity's `inventoryItemId` query filter. Catalog card, set and series responses declare `game: "pokemon"`. Only Pokémon TCG is supported today, including Trainers and Energy without National Dex links. No game selector is offered. Internal IDs, canonical IDs and reviewed aliases are globally unique opaque application IDs across games and sources. Keep existing IDs unchanged and pass them back exactly; do not parse them or use a bare provider-local product number as `cardId`. `externalIds` contains provider-local evidence keyed by source within the record's game. For example, synthetic `tcgplayer:["42"]` and `cardmarket:["42"]` on a `game:"pokemon"` record are different identifiers. Neither is application ID `42`. Future ingestion must allocate collision-free global card/set/series IDs and keep external IDs scoped by game and source before joining or inserting; adding a game field to copies cannot fix a catalog primary-key collision. No other game or provider integration is implied. `{kind:"pokemon",pokemonId}` deliberately identifies a species. `list_pokemon` and `get_pokemon` remain dedicated species endpoints. `get_pokemon_set_slots` (`GET /pokemon/sets/{id}/slots`) returns dex-grouped Pokémon species, not stable storage slots. Use `list_cards` with a set filter for all set printings, and `list_storage_slots` for actual stable slots. The public `list_collection`, `save_collection_item` and `delete_collection_item` species-row operations have been removed without aliases. Use [native reads](https://holofolder.com/app/docs/markdown/native-reads) and [native commands](https://holofolder.com/app/docs/markdown/native-storage) for copies, slots and wants. Every binder is native, so `get_legacy_pokemon_analytics` and `resolve_import` have been removed too. ## Pagination List and search operations use bounded pages with a maximum of 100 records. Follow the returned cursor for the next page. A page is not the entire dataset, and a cursor belongs to the query that created it. ## Limits The initial budget is 60 reads and 20 writes per minute per account, shared across its credentials. Provider refreshes and long-running comparisons have their own stricter limits. A `429` response includes `Retry-After`. ## Errors | Status | Meaning | | ------ | ---------------------------------------------------- | | 401 | Invalid, expired or revoked credential | | 402 | Premium or lifetime access required | | 403 | Required permission missing | | 404 | Record unavailable to this account | | 409 | Conflict or confirmation required | | 413 | Request body too large | | 422 | This operation is unsupported for the requested data | | 429 | Rate limit reached | | 503 | A required service is unavailable | Errors include a stable code, a message and a request ID. Private responses are not cacheable. Starting a sold-comps comparison job, or refreshing price checks from a source other than eBay, is app-only and returns `403` with code `ui_only`. Saved comparisons and price checks stay readable through the API. ## Images and prices Image fields refer only to verified R2 objects. Missing images remain missing; the API does not fall back to another image host. Public CDN image links can still be accessed by someone who already has the URL. Prices include available source, currency, confidence and freshness evidence. Missing amounts and uncertain prices are not invented. Price signals require medium or high confidence. Tracked background refreshes cover owned physical copies, including Unassigned ones, and explicit wanted cards, including Trainers and Energy. Empty targets are excluded. Repeated copies share a card/language request; a missing language stays unknown and no finish is guessed. An incomplete read stops selection before any provider request. Manual and scheduled refresh rules are unchanged, and the selection adds no REST/MCP permission. Private uploaded binder artwork lives in a separate private R2 bucket. Upload preparation returns a five-minute signed PUT URL, required headers and an `artworkRef` for the appearance design. Upload the exact declared bytes, then save the appearance revision. Downloads use five-minute signed GET URLs. ## Safe writes Collection and storage commands must protect against overwriting a newer edit. Duplicate retries of creation, purchase and job operations must not create duplicate effects. See the API reference for each request schema. Binder creation requires an `Idempotency-Key`, sent as a header or in the body; when both are present they must match. Settings replacement requires a `baseFingerprint` from the previous read. Native storage commands use revisions and a retry-stable `operationId` instead (see [native storage](https://holofolder.com/app/docs/markdown/native-storage)). Retry keys are retained for 24 hours. Cursors do not freeze the dataset while other clients make changes. ## Native storage [Native storage contracts](https://holofolder.com/app/docs/markdown/native-storage) use authenticated execution with exact revision and operation-ID semantics and their own bounds. They do not use the 24-hour `Idempotency-Key` retention. Native developer reads expose a separate redacted projection. Undo over REST and MCP uses the native storage recovery operations. ## Native reads [Native developer reads](https://holofolder.com/app/docs/markdown/native-reads) declare a private redacted copy/storage/slot projection with signed scope/filter/revision-bound cursors. A response page is never a complete planning snapshot or a fresh-read queue acknowledgement. [Copied preset previews](https://holofolder.com/app/docs/markdown/preset-previews) provide authenticated discovery and bounded read-only manifests through the same registry/dispatcher. Preset entry IDs are provenance, not slot/collection/operation identities. No private planning state, ownership, autosync or durable set/master-set scope is implied. # Changes saved on this device Source: https://holofolder.com/app/docs/device-changes How device-only changes work now that guests are read-only. Signed-out visitors browse read-only. Every collection edit opens the sign-up dialog, so guests no longer build up changes on the device that later need to be moved into an account. Signed-in edits are queued on this device and sent to your account automatically. While they wait, the app says the change is saved on this device and will sync when you are back online. If the collection changed somewhere else, or syncing is paused for your account or plan, the app holds the change and tells you why instead of discarding it. The older review for guest and pre-account changes (**Review changes**, **Keep on this device**, **Download original data**) has been removed along with the legacy collection model, and the app does not upload that older device data. # Build with your collection Source: https://holofolder.com/app/docs The cards you collect. The tools you already use. Connect Holo Folder to your scripts, integrations and AI assistants. Search the card catalog, work with your binders and wanted lists, and read the price evidence behind your collection. [ Connect an AI assistant ](https://holofolder.com/app/docs/markdown/mcp) [ Explore the API ](https://holofolder.com/app/docs/markdown/reference) ## Choose your connection - [AI & agents](https://holofolder.com/app/docs/markdown/mcp): Connect Claude, ChatGPT, Cursor or Codex through MCP. Sign in with Holo Folder, choose permissions, and start asking. - [REST API](https://holofolder.com/app/docs/markdown/api-keys): Create a personal API key and make your first request. Use the interactive explorer to build your integration. ## From a question to a working request Ask an assistant to find cards on your wanted list, or build a script that reads a binder. Both interfaces use the same operation schemas and account permissions. | | REST API | MCP | | ------------ | ------------------------------------------- | --------------------------------------- | | Best for | Scripts and custom integrations | AI assistants and coding agents | | Sign in with | A personal API key | Your Holo Folder account via OAuth | | Get started | [API keys](https://holofolder.com/app/docs/markdown/api-keys) | [AI setup guides](https://holofolder.com/app/docs/markdown/mcp) | | Reference | [Interactive API explorer](https://holofolder.com/app/docs/markdown/reference) | Tool names appear on each endpoint page | **Developer access** A current Premium subscription or lifetime licence is required. Signup trials do not include developer access. Partners follow the paid collection owner's access and current membership. ## Your account stays in your control Connections start with read permissions. Writes, sharing and partner management need explicit permission. Revoke a key or connected assistant at any time from **Settings → Account → Developer access**. The [API conventions](https://holofolder.com/app/docs/markdown/contracts) cover pagination, rate limits, safe writes and errors. ## Card data and images The API exposes the data available in Holo Folder's mirror. Missing data stays missing. Prices include available source, freshness and confidence evidence. Images come only from our Cloudflare R2 mirror; a missing mirrored image is reported as unavailable. Card data is sourced from TCGdex and the providers identified in each result. Pokémon card images are © The Pokémon Company, Nintendo, Creatures and GAME FREAK. Data licensing does not grant rights to the card artwork. ## Read these docs with an agent Use [llms.txt](https://holofolder.com/app/docs/llms.txt) as the documentation index, or [llms-full.txt](https://holofolder.com/app/docs/llms-full.txt) to read all guides and endpoint contracts in one request. Every page also has a **View as Markdown** link. These public documents need no authentication. The [OpenAPI document](https://holofolder.com/app/openapi.json) is the machine-readable REST contract. It includes authentication, parameters, request schemas and documented response statuses. MCP uses the [remote server](https://holofolder.com/app/docs/markdown/mcp) to discover tools directly. # Manual copy grading Source: https://holofolder.com/app/docs/manual-grading Record and edit private grading details for a single owned copy. Open **Inventory**, select an owned copy, open **More card options** and choose **Edit grading**. Choose **Not graded** or **Graded**, then record the provider, recorded grade, scale or version, designation or qualifier, optional certificate number, holder version, label variant and any subgrades. **Use certificate from URL** fills the certificate number from an official record URL. Choosing **Not graded** clears only that copy's grading. It does not remove ownership, acquisition details or location. Duplicate printings keep independent grades. Unknown text stays as recorded text; no label, grade, authenticity or price is inferred. **Save grading** queues the edit on this device and sends it with your other collection changes. If you are offline the app says the change is saved on this device and will sync when you are back online. If the collection changed somewhere else the edit is held rather than lost, and the app tells you so. Lost replies retry the same operation instead of creating another copy. Grading can only be edited once the app has a complete, current read of your collection in this session, with no unsynced or unresolved changes waiting. Otherwise the app asks you to try again once the collection has finished updating. When the app has started from saved data offline it is read-only, so grading cannot be edited until you reconnect. Certificates, private label asset references and official record links stay private to the owner and partners. Provider links open in an external browser page; they do not fetch or verify data. Certificate sharing is not available, and uploads, ACE evidence and automatic certificate import are not supported. Over REST or MCP, the `patchGrading` command in `execute_inventory_commands` updates only the declared public fields of existing grading and preserves hidden certificates, assets and provenance. It cannot set private certificate or asset fields. Developer reads return a redacted projection, never the complete private record. # AI & agents Source: https://holofolder.com/app/docs/mcp Your collection, one conversation away. Connect an AI assistant to Holo Folder through **MCP**, the Model Context Protocol. Your assistant can search cards, read your binders and wanted lists, and check available prices using the same data as the app. Sign in with your Holo Folder account. Choose what the assistant can access. No API key, local server or client secret to manage. ## Choose your assistant - [Claude](https://holofolder.com/app/docs/markdown/agents/claude): Connect Claude Code over HTTP, or add Holo Folder as a custom connector in Claude. - [ChatGPT](https://holofolder.com/app/docs/markdown/agents/chatgpt): Add a custom MCP connection where your account and workspace support it. - [Cursor](https://holofolder.com/app/docs/markdown/agents/cursor): Add the remote server to your MCP configuration and authorise it in Cursor. - [Codex](https://holofolder.com/app/docs/markdown/agents/codex): Connect the Codex CLI or configure a remote MCP server in your coding environment. ## The connection details Every compatible client uses this **Streamable HTTP** endpoint: ```text title="MCP server URL" https://app.holofolder.com/app/mcp ``` Choose **OAuth** when prompted. Compatible clients discover registration and authorisation from the server's authentication challenge. Do not paste a REST API key into an MCP connection. A current Premium subscription or lifetime licence is required. Signup trials do not include developer access. Partners follow the paid collection owner's access and current membership. ## Make the first connection 1. Add the server in your client using its setup guide above. 2. Follow the browser sign-in flow to Holo Folder. 3. Check the client name, redirect host and requested access on the consent screen. 4. Approve the connection, then return to your assistant. Start with read permissions. Writes, sharing and partner changes need explicit approval. ### Clients running on another machine If your agent runs on a remote machine, in an SSH session or in a container, a `localhost` callback points at that environment. Opening it in your browser reaches your own device instead. On the consent screen, select **My client is on another machine** before approving. Holo Folder will keep the callback URL on screen. Choose **Copy callback URL**, send it to the agent you are connecting, and ask it to open that URL on the machine where the MCP client is waiting. If copying is unavailable, select and copy the URL from the text field. Keep the client waiting while you do this; if the request expires, start a new connection. An already-approved connection with a localhost callback also shows this handoff. If the client is on your device, choose **Open on this device** to continue locally. Holo Folder cannot automatically forward a localhost callback to a remote machine; that requires forwarding support from the client. ## Try a first prompt ```text title="Ask your assistant" List my binders, then show the wanted cards in one I choose. Don't change anything in my collection. ``` Or ask it to search the catalog for a particular Pokémon or read the available price evidence for a card. Missing prices stay missing; your assistant should not guess them. ## Agent setup & API discovery Building your own agent? Use an OAuth-capable remote MCP client with the server URL above. The server exposes tools from the same operation registry as the REST API. Tool names and required permissions appear on each [endpoint page](https://holofolder.com/app/docs/markdown/reference). For an agent that calls REST directly, use a [personal API key](https://holofolder.com/app/docs/markdown/api-keys) and the [OpenAPI document](https://holofolder.com/app/openapi.json). Read [API conventions](https://holofolder.com/app/docs/markdown/contracts) before enabling writes, retries or pagination. The developer endpoint connects directly to the app host so OAuth discovery headers reach your client. Sign-in and consent still open on the Holo Folder website. If you previously configured `https://holofolder.com/app/mcp`, replace it with the URL above and connect again. ## Manage access Revoke a connected assistant from **Settings → Account → Developer access**. A revoked connection must authorise again; reconnecting does not restore access to its old tokens. MCP follows the same paid-access requirements, data permissions and provider limits as REST. If a connection fails, check that your client supports remote Streamable HTTP and OAuth, that paid access is active, and that your workspace allows custom MCP servers. # Saved collections offline Source: https://holofolder.com/app/docs/native-offline-startup What saved startup can show and when a connection is required. Visit the app online first so this device can save its app files and collection data. Saved collections can then reopen in Binder, List, Slabs and Inventory from this device, read-only, with the app showing what was last saved on this device. Pending changes stay on this device until syncing succeeds. ## Account and saved state Saved startup, including on dead Wi-Fi that still reports online, needs the same unexpired account session on this device and the saved collection-owner scope. Shared collections also need the saved partner access for that account and owner. This only allows the saved copy to be shown. It does not prove current membership or that pending changes reached the server. New binders, layout editing, grading and other edits are unavailable during saved startup. While the initial account and membership checks are waiting, the app can show the saved view read-only and keep those checks running, then switches to current data once access resolves. Changing account or partner closes the previous private view and its dialogs. Pending edits stay in their original device record. Once the app is running online, edits made after the connection drops are kept on this device and the app says they will sync when you are back online. If a refresh fails, the app keeps saved copies and pending changes and shows what was last saved. Open **Storage** (the box button beside the collection picker) and choose **Refresh** after reconnecting. Missing, corrupt or expired account or saved data requires a connection; the app never shows an empty collection in its place or deletes pending edits. A first-ever offline visit cannot open an app whose files were never cached. ## First collection New accounts get a default binder automatically. To add another, open **Storage** and choose **New binder**, which needs a connection and no unsynced changes. Startup and presentation preferences live on this device and add no REST or MCP operation. API keys and MCP access are separate from browser account checks. # Native inventory reads Source: https://holofolder.com/app/docs/native-reads Authenticated physical-copy, collection and stable-slot projections for REST and MCP. Native developer reads use the current authenticated key or OAuth boundary. Both require `collection:read`, `binders:read`, current owner or partner membership, and Premium or lifetime access. Read-only credentials can use them. They never impersonate a browser cookie session. | MCP tool | REST GET path relative to `/app/api/v1` | | -------------------------- | ------------------------------------------------ | | `list_inventory_items` | `/inventory/items` | | `get_inventory_item` | `/inventory/items/{id}` | | `list_storage_collections` | `/storage/collections` | | `list_storage_slots` | `/storage/collections/{collectionId}/slots` | | `get_storage_slot` | `/storage/collections/{collectionId}/slots/{id}` | Copies retain stable IDs, recorded card or Pokémon identity, public grading, acquisition time, item revision and current primary placement. Unassigned means no placement. Repeated cards are separate physical copies, including Trainers and Energy. Empty targets and wanted entries are goals, not ownership. Collection reads include private owner location, counts, grid and independent collection/layout revisions. Slot reads include ordered positions, exact targets, public wanted entries, and item/placement/collection/layout preconditions. Removing a slot retains its owned copy as Unassigned. Certificates, private label assets, immutable source evidence and private planning/audit state are omitted. Strict output schemas reject accidental private additions. Use [private-preserving commands](https://holofolder.com/app/docs/markdown/native-storage) to edit a redacted projection without erasing hidden fields. ## Pages and current authority Use `limit` from 1 to 100. Keep filters, limit and credential unchanged when following `nextCursor`. Cursors bind actor, owner, membership, credential/OAuth session, permissions, transport, operation, filters and current revision evidence. Changed state returns `409 stale_native_cursor`; malformed or mismatched cursors return `400 invalid_pagination`. Restart from the first page instead of combining revisions. Every result declares `projection:"developer-native-v1"`, `completeSnapshot:false`, `inventoryRevision` and `readRevision`. Pages are not complete owner snapshots or fresh-read browser queue acknowledgements. Private complete browser reads use cookie/RLS authority through their separate first-party transport, never a service-role snapshot sent to the browser. Current credential revocation, owner/membership change and entitlement loss fail closed. Uninitialized inventories and malformed rows return explicit errors rather than empty results. Missing records return `404`. ## Other supported and unsupported scopes [Copied preset discovery and previews](https://holofolder.com/app/docs/markdown/preset-previews) have a separate read-only contract. [Native commands and recovery](https://holofolder.com/app/docs/markdown/native-storage) retain explicit permissions, CAS preconditions and exact replay requirements. Saved collection metadata now includes `presetManifest`, the independent copied initial list. Its optional `setScope` preserves reviewed language, verified finish families, promo/exclusion selections and captured coverage evidence. It is historical disclosure, not enforced membership; current targets are in slot reads. No private source/certificate/asset evidence is added. See [Set checklists](https://holofolder.com/app/docs/markdown/set-checklist-drafts). Collection metadata pages include the saved initial manifest. Their response budget matches the 2 MiB creation limit plus 16 KiB of framing; use a smaller page if several large manifests exceed it. Other native reads retain the 1 MiB response limit. # Native storage contracts Source: https://holofolder.com/app/docs/native-storage Authenticated native storage commands, replay and recovery through REST and MCP. **Supported native developer operations use the trusted storage executor.** REST uses a personal API key; MCP uses OAuth. Current actor, credential, membership, billing and operation permissions remain required. Public share links grant no private inventory access. Five [native developer reads](https://holofolder.com/app/docs/markdown/native-reads) return redacted pages and current edit preconditions. Their `completeSnapshot:false` results are never private planning snapshots or browser queue acknowledgements. [Copied preset previews](https://holofolder.com/app/docs/markdown/preset-previews) require `catalog:read` and `binders:read`, allocate no creation identities, and do not create ownership. The app uses the same executor through its first-party routes. Unsupported operations return errors; they are never approximated or filled with guessed card data. ## Commands Use the same arguments with the REST path below or the same-named MCP tool. Paths are relative to `/app/api/v1`. All commands require `collection:write` and `binders:write`; recovery also requires `collection:read`. | MCP tool | REST POST path | Effect | | ----------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `execute_slot_commands` | `/storage/slots/commands` | Insert, update, clear, remove or reorder stable slots | | `execute_inventory_commands` | `/storage/inventory/commands` | Add, edit, remove, assign, move or unassign physical copies; delete a collection | | `create_storage_collection` | `/storage/collections` | Atomically create native storage and its copied targets | | `import_storage_arrangement` | `/storage/imports/arrangement` | Import explicit copies and arrangement into a compatible native destination | | `restore_raw_collection_content` | `/storage/restores/raw-content` | Reconcile supported same-owner raw content | | `preview_storage_recovery` / `apply_storage_recovery` | `/storage/recovery/preview` / `/storage/recovery/apply` | Review and apply version 1 native recovery | | `preview_storage_recovery_v2` / `apply_storage_recovery_v2` | `/storage/recovery/v2/preview` / `/storage/recovery/v2/apply` | Explicit default-creation replacement recovery | Use current inventory, collection, layout, slot, item and placement revisions. Preserve the original `operationId`, identities, expected owner and request across retries. A timeout or lost response is an unknown outcome. Never refresh preconditions or allocate a replacement ID to retry an unknown write. Only explicit `removeOwned` deletes ownership. Clearing or removing a slot, removing a placement, and deleting a collection release its copies to Unassigned. To delete a collection together with its cards, send `deleteCollection` with `removeOwned: true` (migration 111): raw copies in it are deleted, graded copies still go to Unassigned because their label assets can't be restored. Deleting the default requires an explicit valid replacement where the command requires one. Empty targets, spacers and wants never manufacture owned copies. ## Preserve private fields Developer reads omit certificates, private label assets and immutable source evidence. Use `privateFields:"preserve"` and `expectedOwnerUserId` for supported mutations of that redacted state. The expected owner is checked against the authenticated current scope before execution. The SQL executor preserves hidden data after the original-intent replay lookup; the client never reconstructs private JSON from a redacted read. Supported operations include slot insertion, reorder and target-only updates; explicit inventory add, removeOwned, unassign and placement; `patchGrading` on declared public grading fields; `setFinish`, which corrects the recorded finish of a card copy in place (same copy, grading and placement, and still matching any finish its pocket pins); and selected-want consumption using exact `expectedPublic` evidence. Private certificates/assets/provenance and unrelated wants remain intact. Selected wants require the exact locked slot/index public projection. Whole grading/wants replacement and destructive slot clearing are unsupported in preserve mode. Omitting the field or selecting `replace` keeps full-replacement semantics. Use that only with deliberately complete values, never by filling hidden fields with nulls. ## Atomic slot insertion and copy assignment `insertAssign` inserts a stable slot before an exact existing slot reference, or appends with `before:null`. Preserve `target:null` for a free slot or the explicit target. `selection:null` creates no ownership; `existing` needs an exact Unassigned copy/version; `new` explicitly acquires the given stable copy. It never chooses a grade or moves an assigned copy implicitly. The executor bounds insertion to 4,096 slots and 8,192 insertion work rows, 100 commands and 256 affected selected entities. Ordinary commands retain 256 KiB request and 1 MiB receipt bounds, a 10-second deadline and private audit bounds. Oversized evidence rejects atomically. See the generated endpoint reference for each exact schema and limit. ## Creation and arrangement import Creation saves the named collection, copied manifest and ordered stable slots in one transaction. Retain operation, collection and slot IDs. An owner's first collection creates their inventory root from revision 0 and becomes the default. If a first creation fails, retain the exact original request for retry or reconciliation; an unavailable response is not a terminal discard proof. Existing count/grid entitlements still apply. Empty goals create no ownership or wants. Creation receipts retain conservative `recoverySupported:false`; recovery preview determines supported evidence independently. Reviewed set/variant checklists additionally persist `manifest.setScope`: exact language, verified finish families, copied catalog evidence, promos, exclusions, count, capture time and warnings. Creation validates current mirror eligibility, then preserves the historical snapshot. `list_storage_collections` returns it in `presetManifest`. Later targets and free slots stay editable; membership is never permanently enforced. See [Set checklists](https://holofolder.com/app/docs/markdown/set-checklist-drafts). Arrangement import requires an empty or target-only native destination with an already identical copied manifest. Every physical copy needs an explicit add or versioned existing-copy move. It does not replace collections/configuration, import assets, authorize backup-file IDs or restore arbitrary historical snapshots. ## Terminal rejection and exact replay A committed terminal ledger rejection returns REST `409` or MCP `isError:true` with matching structured/text JSON. The error code is `storage_command_rejected`, `storage_creation_rejected`, `storage_import_rejected`, `storage_recovery_rejected` or `storage_restore_rejected` for the corresponding family. Strict `error.rejection` contains only `outcome:"rejected"`, the original `operationId`, a known `code`, `inventoryRevision`, and the version where that contract requires it. MCP `outputSchema` describes accepted output only; `holofolder.com/errorSchemas` declares errors separately. Arbitrary 409s, SQL conflicts, timeouts, cancellation and failed COMMIT are not terminal rejection proof. They do not authorize dropping retained intent. Current authorization precedes lifetime exact accepted/rejected replay. A replay receipt is historical. Browser consumers must obtain a fresh same-session complete current read started after the reply and explicitly reconcile before acknowledging, discarding or reviewing a replacement operation. Developer projections cannot supply that browser read authority. ## Recovery Preview returns public-safe Activity changes and conflicts, never private inverse state. Unsupported dependencies return no usable plan. Apply requires the exact reviewed `planToken`, explicit confirmation, version and retry-stable operation ID. Newer or ABA changes conflict. Version 2 default-creation recovery requires an explicit same-owner replacement and current inventory/content/layout revisions. There is no implicit replacement or fallback. Private label asset evidence can remain unsupported with `private_assets_unverifiable`. ## Bounded same-owner raw restore Raw restore reconciles one existing raw collection with the same stable slot IDs and unchanged configuration/grid. Version 4 is the only command version. It carries the exact copied manifest, canonical per-slot origins and `slotOrder.before`/`after`, either equal or a permutation of the same IDs; only a reordering advances the layout revision. Content and origins bind by stable ID, slot versions advance, and the receipt carries both exact orders. A command has at most 1,025 slots/manifest entries, 2,050 distinct copy references, 100 wants per slot, `2S+I+W ≤ 8,192` and 1.75 MiB command/JSONB text. Its complete prospective audit and undo graph is capped at 2.5 MiB. Explicit current choices and trusted actor/owner/session or credential/membership evidence bind the plan. File IDs never prove provenance. Every displaced copy needs explicit release consent and remains Unassigned. Copies placed elsewhere cannot move automatically. Acquisitions, graded copies, changed manifests/origins, metadata/settings/assets/CSV and multiple-collection restores are unsupported. SQL validates the complete actual audit graph and its undo before commit. Accepted receipts and dedicated rejections carry `version:4`. Other command versions return `invalid_input` and preserve device records. Files with unverified wanted-card image URLs remain blocked by the existing export/review policy; no URL is silently removed. First-party planning accepts a backup file up to 10 MiB. No file is stored as a server backup and no provider refresh is triggered. ## First-party app routes The cookie-authenticated app uses `GET /app/api/inventory`, `POST /app/api/binder-slots`, `POST /app/api/inventory`, `POST /app/api/storage-collections`, `POST /app/api/native-recovery` and `POST /app/api/raw-content-restore`. These are private, no-store boundaries. Write requests bind the current owner and auth session and use the app origin. Developer credentials use their separate REST/MCP boundaries and never impersonate an app cookie session. # Copied preset previews Source: https://holofolder.com/app/docs/preset-previews Authenticated discovery and bounded previews of independent ordered target lists. Preset discovery and previews use the trusted developer key/OAuth boundaries. They return detached goals and never save a collection. ## Discover a starting list Use `list_storage_presets` through REST `GET /app/api/v1/storage/presets` or the same-named MCP tool. Both require `catalog:read`, `binders:read`, current owner/partner membership and Premium or lifetime access. REST uses a personal API key; MCP uses OAuth. A developer credential is never a first-party cookie session. Read-only credentials can preview without write permission. Discovery returns stable preset IDs, version `1`, names, supported scope, limitations and explicit finite limits. Use `limit` from 1 to 100 and follow `nextCursor` with the unchanged limit. These are public preset definitions behind authenticated developer access; the operation reads no private inventory, owner planning snapshot, history, certificates or assets. Supported previews are `blank`, `national-dex`, `generation-1` through `generation-9`, `selected-species` and `selected-printings`. Discovery also lists `set` and `master-set` as unsupported, with the durable checklist-scope limitation. Neither is silently approximated with a species checklist or partial card search. ## Preview ordered targets `preview_storage_preset` uses REST `POST /app/api/v1/storage/presets/preview` or MCP. It is a read-only operation despite the REST POST body. Supply `presetId` and `version: "1"`. Only `selected-species` accepts `speciesIds`; only `selected-printings` accepts `printings`. Other selection fields are rejected. Synthetic request example: ```json { "presetId": "selected-species", "version": "1", "speciesIds": [925, 924, 143] } ``` Blank returns zero stored entries. National Dex uses the bundled 1,025 species in Dex order; generation presets use the same boundaries as the app. Selected species retain caller order and reject duplicates, unknown IDs and separate form identifiers. An explicit empty selection is valid. The species limit is 1,025. No form-specific or printing expansion is implied. For selected printings, supply up to 100 ordered `{ cardId, language, finish? }` selections with at most 25 unique exact mirrored row IDs. Repeated printings become separate target requirements with distinct preset entry IDs. Trainers and Energy use the same exact-card contract as Pokémon. Find real IDs with catalog operations; do not invent cards from names, rarity, anniversary labels or species forms. Alias-only identifiers are unsupported; ambiguous direct/alias/canonical evidence fails closed. Language requires a nonempty localized name on that exact row. A requested finish is supported only when its `normal`, `holo`, `reverse` or `jumbo` catalog flag is explicitly true; `reverse_holo` maps to `reverse`. False, missing and unknown flags are unavailable. Rarity and grading do not establish finish availability. Omitted finish stays unconstrained and is disclosed in `unknowns`. Every preview returns `projection: "copied-preset-preview-v1"`, `completeSnapshot: false`, the selected preset ID/version, detached `manifest`, exact selected `scope`, `targetCount`, `freeSlotCount: 0`, `ownershipCreated: false`, `exclusions` and `unknowns`. Manifest entry order is target order. Its copied `source` and entry IDs supply provenance. Targets are locked goals, not owned items or explicit wants. Free slots may later be inserted anywhere. Completion counts the actual current targets after editing, without an original-preset denominator or automatic catalog subscription. ## Creation and identity boundaries Copy only `manifest` into the existing immutable creation draft. The outer preview `scope`, exclusions and unknowns are read-time disclosure, not fields persisted by creation. This server preview does not generate set/master-set checklists. Separately, migration 101 enables reviewed `manifest.setScope` persistence through `create_storage_collection`, with saved reads returning `presetManifest`. See [Set checklists](https://holofolder.com/app/docs/markdown/set-checklist-drafts). Preset entry IDs are provenance labels. They are not collection UUIDs, stable slot IDs or operation IDs. Preview allocates none of those identities and does not return owner attribution. The client must create and retain its operation identity once, then obtain the real current authority/revisions and allocate collection/slot identities once when adapting the draft into the existing canonical creation command. Keep the original command across retries. A preview grants no creation entitlement and is not atomic acceptance, a terminal result, complete planner evidence or a fresh-read queue acknowledgement. See [native storage](https://holofolder.com/app/docs/markdown/native-storage) and [native reads](https://holofolder.com/app/docs/markdown/native-reads). ## Limits and failure Requests are at most 64 KiB; responses are at most 1 MiB. Each invocation has a 5-second deadline and at most 192 checked requests across current-authority fences and catalog reads, with a cumulative 2 MiB catalog budget. Mirror reads use real 10-row keyset pages, including ambiguity checks, and selected printing targets are revalidated before return. No provider purchase, refresh or sync is triggered. Incomplete, oversized, missing or changed catalog evidence produces no partial manifest. Offline clients may retain a detached preview; fresh discovery/printing evidence requires a connection and preview never saves offline. Unknown presets return `404 not_found`. Unsupported set/master-set scopes return `422 unsupported_preset_scope`; unavailable or ambiguous printing/language/finish evidence returns `422 preset_catalog_unavailable`. Invalid selections/version/extra fields return `400 invalid_input`; more than 25 unique printings returns `400 preset_scope_too_large`. Budget/deadline exhaustion returns `503 preset_read_unavailable`. Current credential revocation, owner/membership change and entitlement loss remain authoritative. No request flag bypasses current authority checks. # Public binder links Source: https://holofolder.com/app/docs/public-binder-links Read-only token and named binder links, with optional prices. Token links and named addresses (for example `https://holofolder.com/@name/binder-slug`) open a read-only copy of one binder. Set up sharing in **Settings → Share**. The owner controls whether sharing is enabled and whether prices may appear. Turning sharing off stops later reads; a visitor who already has the page open keeps the cards already downloaded. Public pages never load the visitor's own collection or offline binder. Shared links open the same binder app in read-only mode. Visitors can page, swipe, search and open card details, but every edit is refused, and signed-out visitors are offered **Join now**. Public pages keep the owner's pocket order, including repeated cards, Trainers, Energy, target placeholders and free spaces. Large custom grids scroll within the page. When the owner shares prices, the Prices view and card details show each printing's current price, looked up by public catalog printing through the normal price API. When prices are not shared they are absent from the page and its previews. Only public display fields appear. Account and member IDs, private notes, acquisition details, purchase costs, pending changes, other collections and Unassigned inventory are excluded. Certificates, provider verification links and slab or label photos are never shared; ordinary card artwork can appear alongside recorded provider and grade text. Public pages use free sharing and add no developer REST or MCP inventory endpoint or permission. Sharing management operations keep their existing registry contracts. A public page is a view of one binder, never an export of the owner's whole inventory. # API explorer Source: https://holofolder.com/app/docs/reference Build a request. Run it. See what comes back. Every endpoint below comes from the same operation schemas that power the REST API and MCP tools. Choose an endpoint to see its parameters, generate a code example and send a real request. [ Try a card search ](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards) [ Download OpenAPI ](https://holofolder.com/app/openapi.json) **Bring your API key** Create a personal key in **Settings → Account → Developer access**. In an endpoint's playground, enter the full key as the bearer token. Requests go directly to this site's API. Authentication is kept in your browser tab's session, so close the tab when you're finished on a shared device. ## Explore by resource - [Card catalog](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards): Search cards, browse sets and series, and look up Pokémon and illustrators. - [Your collection](https://holofolder.com/app/docs/markdown/reference/collection/list-binders): Manage binders, owned and wanted cards, sharing, artwork and show purchases. - [Prices & insights](https://holofolder.com/app/docs/markdown/reference/prices-and-insights/get-prices): Read price evidence, compare listings, check deals and follow price history. - [Account & preferences](https://holofolder.com/app/docs/markdown/reference/account/get-settings): Read settings, update your identity and manage partner connections. ## Before you send a request - **Real requests, real changes.** Write operations change your account. Start with a read-only key and a GET request. - **Permissions apply.** The explorer uses the same subscription, permissions and rate limits as your own integrations. - **Retry safely.** Creating a binder requires an `Idempotency-Key`. Settings changes use the fingerprint from your last read, and collection storage commands use current revisions with a retry-stable `operationId`. See [API conventions](https://holofolder.com/app/docs/markdown/contracts) for pagination, errors and limits. Prefer an AI assistant? [Connect through MCP](https://holofolder.com/app/docs/markdown/mcp) instead. # Scanning into your binder Source: https://holofolder.com/app/docs/scan-destinations Scan a binder page or a single card, choose where each card goes, and add them in one save. Open the binder's **Storage** menu and choose **Scan page** or **Scan card**. Both need a connection, a complete current read of your collection, no unsynced edits and a saved page grid that matches the binder. Until then the entries stay disabled. ## Scan a page Choose **Take photo**, or **Or choose a photo** when the camera isn't available. Each detected pocket is matched to the pocket at that position on the page you scanned. A card being present in a pocket does not identify it or prove you own it, so for each card choose **Choose card** and pick the catalog card from **Possible matches**, or **Skip** it. Cards already recorded in that pocket show **Already in your binder. Nothing to add.** Trainers and Energy work the same way as Pokémon. ## Scan a card **Scan card** keeps the existing on-device text reading and cached lookup. **Type instead** searches card identities already read or cached on this device. Unknown cards stay unresolved. Scanning never reads grades, certificates or label artwork. ## Review and add For each card, answer **Which card is this?**, **Which version?** and **Which copy?** where they apply. You can use one of your recorded spare copies or add **An ungraded copy**. Under **Put it in**, pick a matching pocket or **A new pocket at the end**. Two cards cannot go into the same pocket, and a card that doesn't fit a pocket's target is refused. When everything is chosen, confirm **Add N cards**. All the cards from one review are saved as a single atomic inventory request, in the order shown. A batch that exceeds the request limits is refused whole, so scan a smaller page. Nothing is padded into pockets you didn't create, and no ownership is implied for skipped cells. Adding an ungraded copy is unavailable when only graded matching spare copies exist; choose one of those copies instead. If the binder, its arrangement or its grid changes while you review, you'll see **This page changed after the scan. Close this and scan again. Nothing was added.** Cancelling saves nothing. Accepted changes save on the device first and sync when online, keeping the same pocket and copy IDs through retries and reloads. ## Offline Cached startup is read-only, so reconnect and let pending edits finish before scanning. A scanner that is already open keeps its cached lookup if the network drops, but adding cards needs a complete online read. It can't identify uncached cards or download the text reader for the first time offline. ## API There is no scan endpoint. The review submits the same `execute_inventory_commands` contract available at `POST /app/api/v1/storage/inventory/commands` and over MCP, using `insertAssign` for new pockets. # Set checklists Source: https://holofolder.com/app/docs/set-checklist-drafts Open the binder's **Storage** menu, choose **New binder**, then **A set**. Under **Which set?**, find the catalog set by name or code and pick a checklist language. Every card in the set gets a pocket, including Trainers, Energy, repeated Pokémon, secret rares and subsets. The next step covers versions, promos and cards to leave out. **Which versions?** defaults to **One of each card**, where any version fills the pocket. Choosing a finish such as Reverse holo or Jumbo adds one pocket per card that the catalog explicitly marks with that finish. Missing, false or unknown finish flags are not offered. **Add promos** loads a promo set by code (for example `svp`) so you can tap cards to include, and **Leave cards out** excludes cards you don't want. No checklist claims universal master-set completeness. Name the binder, choose its pages, check the **Preview**, then **Create binder**. Creating needs a connection with your latest changes saved; offline you can preview but not create. The binder opens as soon as it's saved to your account, and selecting targets never adds owned cards, wants or grades. ## After creation On the binder's collection view, **What this set binder covers** shows the saved language, versions, promos and exclusions. It is also visible from cached read-only startup. Your checklist is an independent copy, so catalog updates never change it. Add free pockets for extras, change or remove targets, or append new goals. Completion follows the current targets rather than the original set list. Normal never satisfies Reverse holo, and one owned copy can't fill two pockets. ## API `create_storage_collection` (`POST /app/api/v1/storage/collections`) accepts an optional `manifest.setScope`, and `list_storage_collections` returns it inside `presetManifest`. Keep the reviewed scope and the same operation, collection and pocket IDs across retries. Normal owner/partner access, permissions and plan limits apply. `preview_storage_preset` does not generate set or master-set checklists, so build the manifest from catalog reads as the app does. Collections without a set scope keep working unchanged. # Find sets by year Source: https://holofolder.com/app/docs/set-lookup Identify a set from the year and symbol printed on a card. Type a four-digit release year, such as `2017`, into Search or Quick mode to see all matching sets in the catalogue, newest first. Each result shows the set's symbol, name and available release details. Tap a result to open its cards. You can also search by year in Sets. Name and printed-code searches continue to work. Year lookup uses the set's release date, which may differ from a copyright year on a reprinted card. Sets without a known release date cannot be matched by year. Offline, search uses only set lists already saved on this device; an image that has not been cached falls back to the set's initials. Symbols and logos are served from Holo Folder's CDN. Credits & attributions lists their sources, including PokéSymbols. Show mode keeps its card and price lookup, without set navigation results. ## REST and MCP `GET /app/api/v1/sets?year=2017` and MCP `list_sets` with `{"year":"2017"}` filter the catalogue by the same release year. Use the existing cursor to page through every match. The optional `symbol` and `logo` fields contain available public CDN URLs. Missing artwork is omitted. Series filtering can be combined with the year. # Slabs view Source: https://holofolder.com/app/docs/slabs Provider-specific holder previews for graded copies in a collection. Open a collection and choose **Slabs** in the view picker (next to **Binder** and **List**). The Slabs view shows each copy in the collection that has saved grading, using its owned-copy record. PSA, supported current and historic CGC, and Beckett silver, gold and black each have their own holder and label layout. A grade of 10 alone never selects Black Label or Pristine. Raw copies stay raw. Unknown holder versions keep their entered metadata in a neutral holder. No provider import or slab photo is needed: the preview uses the catalog card image plus the recorded provider and grade. Missing catalog images show a readable fallback. Exact ACE/custom artwork and unsupported historical labels are shown as unavailable. Custom labels use the recorded text with one of four neutral colors. No certificate, barcode, QR code, verification graphic, invented grade or estimated slab value is added. The gallery and enlarged detail are read-only. View, search and scroll position are saved on this device for the signed-in account and collection owner. When the app has started from saved data offline, the gallery is read-only and may be incomplete until it refreshes. Switching views never moves or regrades a copy. To change grading, use [manual grading](https://holofolder.com/app/docs/markdown/manual-grading) in Inventory. Certificates, private record links and original label or slab assets are never passed to the renderer or shown on the page. There is no public slab sharing: public binder links show ordinary card artwork with recorded provider and grade text only. The view adds no REST or MCP operation. Developers read grading through the [native reads](https://holofolder.com/app/docs/markdown/native-reads), which return the redacted public projection. # Pockets and targets Source: https://holofolder.com/app/docs/slot-selection Choose what each pocket is for, place your cards and edit a binder's layout. Every binder is a list of stable pockets. A pocket can have a target (a Pokémon, any of its cards or one exact card), be a free pocket that takes any card, and hold one owned copy. ## Choose what goes in a pocket Open a pocket's details, or long-press or right-click it for its pocket menu, to **Add a card**, **View card**, **Take the card out**, **Remove from collection**, **Move this pocket** or **Add a pocket before** or **after**. From **Edit layout**, select a single empty pocket and open **More pocket options** to **Choose what goes here** (or **Change what goes here**). The **What goes in this pocket?** sheet offers **A Pokémon**, **Any of its cards**, **One exact card**, **Any card** or **A free pocket**. This only changes what the pocket is for. **Let any card go here** removes the target and keeps the pocket. Picking a card searches the catalog, including Trainers, items and Energy that have no Pokémon link. Distinct owned copies stay separate. Spare copies (owned but not in a pocket) can be reused, and copies already in another pocket stay where they are. Recorded grading stays with its copy and no slab details are invented. **Take the card out** leaves the pocket and its target in place, and the card stays in your collection as a spare. **Remove from collection** deletes the owned copy itself and empties its pocket. It can't be undone with one tap. ## Edit the layout Choose **Edit layout** above the binder, then tap pockets to select them. The bar shows how many are selected, with **Move**, **Add**, **Fill**, **Remove** and **Done**. - **Move** asks you to tap where the selection goes, or use **To the start** or **To the end**. **Cancel** stops the move. - **Add** inserts an empty pocket **Before the selection**, **After the selection** or **At the end of the binder**, or a whole page before the selection or at the end. Following pockets shift across pages. If the pockets change while selected, choose **Update selection** to carry on. Changing the binder or view ends editing, and presentation filters disable it. See [bulk layout](https://holofolder.com/app/docs/markdown/bulk-layout) for multi-pocket moves, fill and removal. ## Saving and offline Edits save on the device first and sync when online. If saving on the device fails you'll see **Save not confirmed** with **Try again** or **Discard**. Offline search uses cards already cached on the device, and missing catalog coverage is shown explicitly. Cached startup is read-only. ## API The same changes are available through `execute_slot_commands` (`POST /app/api/v1/storage/slots/commands`) for insert, update, clear, remove and reorder, and `execute_inventory_commands` for assigning copies. Reads use `list_storage_slots` and `get_storage_slot`. See [native storage](https://holofolder.com/app/docs/markdown/native-storage).