Execute inventory commands

Loading API explorer…

POST

/storage/inventory/commands

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.

Required permissions: collection:write, binders:write. MCP tool: execute_inventory_commands.

Authorization

apiKey

headerAuthorizationBearer <Holo Folder personal API key>

Request Body

application/json

body

operationId*string

Length8 <= length <= 100

inventoryRevision*integer

Range0 <= value <= 9007199254740991

privateFields?string

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.

Value in"preserve""replace"

expectedOwnerUserId?string

Recipient precondition, required with privateFields=preserve. Must match the current authenticated owner scope; never selects or grants authority. Retain across retries.

Match^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

collections*array<>

Itemsitems <= 32

commands*array<|||||||||>

Items1 <= items <= 100

Response Body

Success

application/json

response

inventoryRevision*integer

Range0 <= value <= 9007199254740991

changed*boolean

selectedItemIds*array<>

acquiredItemIds*array<>

Example Request

curl -X POST 'https://app.holofolder.com/app/api/v1/storage/inventory/commands' \  -H 'Content-Type: application/json' \  -d '{  "operationId": "stringst",  "inventoryRevision": 0,  "collections": [    {      "collectionId": "string",      "version": 0,      "layoutRevision": 0    }  ],  "commands": [    {      "kind": "insertAssign",      "collectionId": "string",      "slotId": "string",      "before": {        "id": "string",        "version": 0,        "inventoryItemId": "string",        "itemVersion": 0,        "placementVersion": 0      },      "target": {        "kind": "pokemon",        "pokemonId": 1      },      "selection": {        "kind": "existing",        "inventoryItemId": "string",        "itemVersion": 0      }    }  ]}'

Example ResponseSchema

{  "inventoryRevision": 0,  "changed": true,  "selectedItemIds": [    "string"  ],  "acquiredItemIds": [    "string"  ]}

Loading API explorer…

curl -X POST 'https://app.holofolder.com/app/api/v1/storage/inventory/commands' \ -H 'Content-Type: application/json' \ -d '{ "operationId": "stringst", "inventoryRevision": 0, "collections": [ { "collectionId": "string", "version": 0, "layoutRevision": 0 } ], "commands": [ { "kind": "insertAssign", "collectionId": "string", "slotId": "string", "before": { "id": "string", "version": 0, "inventoryItemId": "string", "itemVersion": 0, "placementVersion": 0 }, "target": { "kind": "pokemon", "pokemonId": 1 }, "selection": { "kind": "existing", "inventoryItemId": "string", "itemVersion": 0 } } ]}'

Execute inventory commands

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Request Body

Response Body

Authorization

Request Body

Response Body