SDK Reference

Create a new container (admin). typescript const cask = await containers.create('coll_123', { containerType: 'cask', ref: 'CASK-0042', name: 'Cask 42 — Single Malt', metadata: { distilleryYear: 2019, capacity: 200 }, })

List containers (admin). Supports filtering by type, status, ref, parent, and top-level flag. typescript // All active pallets const { containers: pallets } = await containers.list('coll_123', { containerType: 'pallet', status: 'active', limit: 50, }) // Top-level containers only const { containers: roots } = await containers.list('coll_123', { topLevel: true })

Reverse lookup — find all containers currently holding a specific item (admin). typescript const { containers: holding } = await containers.findForItem('coll_123', { itemType: 'proof', itemId: 'proof-uuid', })

Get a single container by ID (admin). Pass ?tree=true to recursively embed children, and/or ?includeContents=true to embed the current item list. typescript // Flat const cask = await containers.get('coll_123', 'cask-uuid') // Full tree with contents const tree = await containers.get('coll_123', 'warehouse-uuid', { tree: true, treeDepth: 3, includeContents: true, })

Partially update a container (admin). Only fields present in the request body are modified. Pass parentContainerId: null to promote a container to top-level. typescript const updated = await containers.update('coll_123', 'cask-uuid', { status: 'archived', metadata: { bottledAt: '2025-04-01' }, })

Soft-delete a container (admin). Sets deletedAt; the record and its full item history remain queryable by admins. Public API responses automatically exclude deleted containers.

List items currently (or historically) inside a container (admin). Pass history: true to include removed items and see the full membership log. typescript // Current contents const { items } = await containers.listItems('coll_123', 'cask-uuid') // Full history including removed items const { items: history } = await containers.listItems('coll_123', 'cask-uuid', { history: true })

Add one or more items to a container (admin). Each item requires itemType and itemId. Pass productId / proofId for denormalisation convenience. typescript const { items } = await containers.addItems('coll_123', 'pallet-uuid', { items: [ { itemType: 'tag', itemId: 'NFC-00AABBCC' }, { itemType: 'proof', itemId: 'proof-uuid', productId: 'product-id' }, ], })

Soft-remove items from a container (admin). Sets removedAt on the specified ContainerItem records. The records are retained in the history log and can be queried with history: true. typescript const result = await containers.removeItems('coll_123', 'pallet-uuid', { ids: ['container-item-uuid-1', 'container-item-uuid-2'], }) console.log(`Removed ${result.removedCount} items`)

List containers (public). Soft-deleted containers and containers with metadata.publicListing === false are excluded from results.

Get a single container (public). Soft-deleted containers return a 404. Same ?tree and ?includeContents options as the admin version.

List current contents of a container (public). Returns only items where removedAt is null. No ?history option on the public side.