Identifiers

Identifier bindings pair a scanned value (raw) with the thing it stands for (target), under one scan scheme: a cartridge’s tag with the material lot it carries, a plate with the printer it is aboard. All endpoints require authentication. See Identifier bindings for binders, exclusive targets and the bind scan step.

Endpoint	Access
GET /api/identifiers/:scheme/bindings	Any signed-in user
POST /api/identifiers/:scheme/bindings	Role management, or a role the scheme names in identifier.binders
POST /api/identifiers/:scheme/rebind	Role management, or a scheme binder
DELETE /api/identifiers/:scheme/bindings/:id	Role management, or a scheme binder

A binding reads back as:

{
  "id": "41",
  "scheme_version": 22,
  "raw": "PL-0193",
  "target": "PRN-007",
  "exclusive": true,
  "bound_by": "8e2f1c0a-...",
  "bound_via": "api",
  "bound_at": "2026-11-10T14:02:11.418Z",
  "retired_at": null,
  "retired_by": null
}

bound_via is api, scan or workflow. bound_by is the user when the caller is one.

List bindings

GET /api/identifiers/:scheme/bindings?target=&raw=&includeRetired=&limit=&offset=

A scheme’s live bindings, newest first. raw answers one value’s live target; target lists the values bound to it; includeRetired=true adds retired bindings as history. limit is 1 to 500, default 100.

Response 200: { "bindings": [ ... ] }

Bind

POST /api/identifiers/:scheme/bindings

{ "raw": "PL-0193", "target": "PRN-007" }

Response 201: bound, as { "binding", "already": false, "retired": [] }. Under a scheme with identifier.exclusiveTarget, the target’s old value is retired in the same transaction and listed in retired. 200 when the same pair already stands (already: true). 409 when the value is bound to another target. 403 when the caller is not a binder.

Rebind

POST /api/identifiers/:scheme/rebind

{ "raw": "PL-0193", "target": "PRN-012" }

Moves a value to a new target. Its old binding (and, under an exclusive scheme, the target’s old value) is retired and the new one inserted in one transaction.

Response 200: { "binding", "already", "retired" }. 403 when the caller is not a binder.

Retire

DELETE /api/identifiers/:scheme/bindings/:id

Ends one live binding. It stays as history, and the value is free to bind again.

Response 200: the retired binding. 404 when no live binding has that id under the scheme. 403 when the caller is not a binder.