Changelog

​

Unit descriptions and content updates

• The unit resource gains description, a plain-text string or null. It is returned by POST /v1/units, GET /v1/units, GET /v1/units/{unit_id} and PATCH /v1/units/{unit_id}, and inside unit on GET /v1/chips/{chip_id}, POST /v1/chips and POST /v1/chips/bulk.
• POST /v1/units accepts an optional description (plain text, 1 to 10,000 characters).
• PATCH /v1/units/{unit_id} now updates external_id, name, description and attributes, as well as redirect_url. Send only the fields to change; the body must contain at least one field. attributes replaces the full set, and null clears a field. external_id cannot be cleared, and an external_id that another unit in your environment uses returns 409 unit.already_exists. redirect_url is now optional, so existing update requests stay valid.

const unit = await endstate.units.update(unitId, {
  externalId: "SN-0002",
  attributes: { serial: "SN-0002" },
});

​

Filter units by status and chip

• GET /v1/units accepts two optional query parameters: status (pending or active, the unit’s collection.token.status) and chip (paired or unpaired). They combine with each other, with external_id and collection_id, and with cursor pagination. Any other value returns validation.failed.

const page = await endstate.units.list({ status: "pending", chip: "unpaired" });

​

Collection unit counts and units by collection

• The collection resource gains unit_count, the number of units in the collection. It is returned by GET /v1/collections, GET /v1/collections/{collection_id}, POST /v1/collections, and PATCH /v1/collections/{collection_id}.
• GET /v1/units accepts a collection_id query parameter that lists only the units in that collection. The response keeps the usual list shape and cursor pagination, and an id that is not a UUID returns validation.failed.

const page = await endstate.units.list({ collectionId: collection.id });

​

API keys enforce role permissions

​

c is carried verbatim

​

Tap redirects send endstate_chip_id

https://brand.example/p?endstate_e=C78566198547116F3A715DC1C62AF96F&endstate_chip_id=ABCDEF0123

const params = new URLSearchParams(window.location.search);
const chipId = params.get("endstate_chip_id"); // the API's chip_id
const e = params.get("endstate_e");

const tap = tryParseTapUrl(window.location.href);
if (tap) await endstate.verify(tap);

​

Retry a create safely with Idempotency-Key

• Send the same key on the retry and you get the original response back with Idempotent-Replayed: true.
• The header is optional. Omit it and nothing about these calls changes.
• Updates (PATCH, PUT) still need no key: they set fields to the values you send, so a repeat leaves the same result.

​

Breaking: the tap endpoints moved to /v1/taps

​

Verify a tap, with or without a backend

• Send chip_id and the one-time e value from the tap URL - plus the optional c if the tag provides one. The response is the tap id, the session token with its expiry and what it is bound to, the chip, the unit, and the redirect URL.
• Authenticate with end_sk_... from your server, or end_pk_live_... from the browser. This is the only endpoint that accepts a publishable key.
• ttl and dry_run are API-key only - a server is trusted to choose a token lifetime; a browser is not. A publishable-key call gets the 600-second default.
• Calling from the browser also needs the origins your page is served from registered with PUT /v1/settings/cors-origins, or the browser will block the call.

​

Simulate a tap without hardware

​

Added: fetch a single chip

​

Added: stable operationId on every endpoint

​

Added: staging base URL in the OpenAPI spec

​

Added: optional c verification code on pairing and tap endpoints

​

Breaking: one canonical session-token shape

​

Browser calls: use the default credentials mode

​

Publishable keys

• GET /v1/publishable-keys returns your active keys. If you have none, one is created automatically, so a first call always returns a usable key.
• A publishable key (end_pk_live_...) is safe to embed in browser code: it identifies your organization and grants no access by itself. Retrieving it requires your secret API key.

​

Manage your own CORS origins

• GET /v1/settings/cors-origins returns the origins allowed to call the API from a browser; PUT replaces the list (send an empty array to remove all origins).
• Each entry is an exact origin (https://brand.example), a subdomain wildcard (https://*.brand.example), or a port wildcard (http://localhost:*) - one wildcard per entry. Entries are stored in canonical form and returned as saved.
• Changes take effect within about a minute. Remove development origins before you go live.

​

Tap history

• GET /v1/taps returns a cursor-paginated history of verified taps. Filter by chip_id, unit_id, or a time window; test-chip taps are excluded unless is_test=true.
• Each item’s id matches the id POST /v1/taps returned when the tap was recorded.

​

Pair chips in bulk

• POST /v1/chips/bulk accepts a list of the same per-chip payloads as POST /v1/chips (test or encoded). All units must belong to the same collection, and units are issued in the order provided.
• The request is all-or-nothing: if any entry fails validation, nothing is paired.
• Send an Idempotency-Key header to retry safely.
• New error codes: chip.bulk_mixed_collections, chip.bulk_pending.

​

Transfer a unit between owners

• POST /v1/units/{unit_id}/transfers (session token required) creates the transfer and returns a transaction payload. Only the unit’s current owner can submit it - Endstate authorizes the transfer but never relays it, and the authorization is valid for 30 minutes.
• GET /v1/units/{unit_id}/transfers/{transfer_id} (API key or session token) polls status: prepared → confirmed; expired and failed are terminal.
• New error codes: transfer.in_progress, transfer.already_to_recipient, transfer.owner_unknown, transfer.not_found.

​

Replace a unit’s chip

• POST /v1/units/{unit_id}/chip-replacements pairs an existing, unpaired chip to the unit and retires the current one. Endstate performs the swap; replacement is asynchronous.
• GET /v1/units/{unit_id}/chip-replacements/{replacement_id} polls status (prepared → submitted → confirmed; failed is terminal).
• New error codes: chip_replacement.locked (unit already claimed - the chip is permanently locked), chip_replacement.in_progress, and chip_replacement.not_found.

​

chain_id is now optional on collection create

​

Single-resource responses are now top-level (breaking)

​

Empty request bodies accepted on all-optional POSTs

​

Tap redirects

• redirect_url is a new (nullable, always-present) field on the unit and collection resources, accepted on create and editable via new PATCH /v1/units/{unit_id} and PATCH /v1/collections/{collection_id} endpoints.
• New GET/PATCH /v1/settings endpoints manage the org-wide default_redirect_url.
• Redirected taps carry the tapped chip’s id and its one-time credential as query parameters, so your page can verify the tap.

​

Claims

• POST /v1/units/{unit_id}/claims creates a claim (endstate_relay or client_broadcast execution).
• GET /v1/units/{unit_id}/claims/{claim_id} polls status (claiming → claimed / expired / failed).