SDK Reference

Create a single tag mapping (admin). If productId is set without proofId, a serial number is auto-generated unless useSerialNumber: true is explicitly passed. refType and refId can be set independently of or alongside product/proof. typescript // Auto-generate serial number const tag = await tags.create('coll_123', { tagId: 'NFC-001', productId: 'prod_456', batchId: 'batch_2026_01', }) // Explicit proof + polymorphic ref const tag2 = await tags.create('coll_123', { tagId: 'NFC-002', refType: 'container', refId: 'container-uuid', })

Batch-create tags (admin). Tags with productId but no proofId automatically get serial numbers. Serial number generation is grouped by (productId, variantId, batchId) for efficiency. Partial success is possible — check results for individual outcomes. typescript const result = await tags.createBatch('coll_123', { tags: [ { tagId: 'NFC-001', productId: 'prod_456', batchId: 'batch_2026_01' }, { tagId: 'NFC-002', productId: 'prod_456', batchId: 'batch_2026_01' }, ], }) console.log(`Created: ${result.summary.created}, Conflicts: ${result.summary.conflicts}`)

Get a single tag by tagId (admin).

Update a tag (admin). Partial update — only provided fields are changed. metadata is deep-merged with the existing value. Pass refType: null, refId: null to clear the polymorphic ref. typescript const updated = await tags.update('coll_123', 'NFC-001', { variantId: 'var_premium', metadata: { notes: 'Updated to premium variant' }, }) // Clear polymorphic ref await tags.update('coll_123', 'NFC-001', { refType: null, refId: null })

Delete a tag (admin). Permanently removes the tag from the per-org shard and the shared index.

List tags with optional filters and pagination (admin). typescript // All tags for a product const { tags: list } = await tags.list('coll_123', { productId: 'prod_456' }) // All tags linked to a container const { tags: linked } = await tags.list('coll_123', { refType: 'container', refId: 'container-uuid', })

Reverse lookup — find all tags linked to a given object (admin). Uses a compound index on (orgId, refType, refId) on the per-org shard. No embed support on the admin side. typescript const { tags: linked } = await tags.byRef('coll_123', { refType: 'container', refId: 'container-uuid', })

Global tag resolve — returns { tagId, collectionId } only. Use this only when you have a raw tagId and do not yet know which collection it belongs to. Queries the shared tag_index shard. Once collectionId is resolved, call publicGetByCollection for full data. > The global /public/tags/by-ref endpoint has been removed. > Use the collection-scoped publicByRef instead. typescript // Step 1: resolve collection const { collectionId } = await tags.resolveTag('NFC-001') // Step 2: full lookup with embedded data const { tag, embedded } = await tags.publicGetByCollection( collectionId, 'NFC-001', 'product,proof' )

Single tag lookup with optional embedded data (public). GET /public/collection/:collectionId/tags/:tagId?embed=product,proof,container,ref Supported embed values: 'product', 'proof', 'container', 'ref' ('collection' is not supported — the collection is already known from the URL). typescript const { tag, embedded } = await tags.publicGetByCollection( 'coll_123', 'NFC-001', 'product,proof' ) const product = embedded.products?.[tag.productId!] const proof = embedded.proofs?.[tag.proofId!]

Batch tag lookup via POST (public). POST /public/collection/:collectionId/tags/lookup Tags not belonging to this collection are filtered out silently. Returns deduplicated embedded objects alongside the tag array. typescript const { count, tags: list, embedded } = await tags.lookupTags('coll_123', { tagIds: ['NFC-001', 'NFC-002', 'NFC-003'], embed: 'product,proof', })

Batch tag lookup via GET (public). GET /public/collection/:collectionId/tags/lookup?tagIds=NFC-001,NFC-002&embed=product

Reverse lookup by ref via GET (public). GET /public/collection/:collectionId/tags/by-ref?refType=container&refId=<uuid>&embed=ref typescript const { tags: linked, embedded } = await tags.publicByRef('coll_123', { refType: 'container', refId: 'container-uuid', embed: 'container', }) const container = embedded.containers?.[containerId]

Reverse lookup by ref via POST (public). POST /public/collection/:collectionId/tags/by-ref