Response shape

Single resources are top-level

Every single-resource response returns the resource’s fields at the top level - there is no wrapper key. This applies uniformly to collections, units, chips, taps, session-token introspection, claims, transfers, and chip replacements.

Endpoint	Shape	Read it as
`POST /v1/collections`, `GET /v1/collections/{id}`, `PATCH`	Top-level: `{ id, contract, name, ... }`	`response.id`
`POST /v1/units`, `GET /v1/units/{id}`, `PATCH`	Top-level: `{ id, collection, chips, ... }`	`response.collection.token`
`POST /v1/chips` (pair)	Top-level: `{ chip_id, unit, ... }`	`response.chip_id`
`POST /v1/taps` (record a tap)	Top-level: `{ session_token, unit, ... }`	`response.session_token`
`GET /v1/session-tokens/current`	Top-level: `{ expires_at, scope }`	`response.scope.unit_id`
`POST /v1/units/{id}/claims`, `GET .../claims/{claim_id}`	Top-level: `{ id, status, to, ... }`	`response.status`
`POST /v1/units/{id}/transfers`, `GET .../transfers/{id}`	Top-level: `{ id, status, to, ... }`	`response.status`

Earlier versions of this API wrapped single collection and unit responses in a collection / unit envelope ({ "collection": {...} }). That envelope is gone - if your integration reads response.collection.id from GET /v1/collections/{id} or response.unit.id from GET /v1/units/{id}, update it to read the fields at the top level.

Some top-level responses contain a nested resource as a field - for example, the tap response includes the verified unit, and the chip-pair response includes a unit snapshot. That nesting is part of the resource’s own shape, not an envelope. For example, creating a collection and then polling it:

const created = await fetch(`${ENDSTATE}/v1/collections`, {
  method: "POST",
  headers,
  body,
}).then((r) => r.json());
const collectionId = created.id;

const polled = await fetch(`${ENDSTATE}/v1/collections/${collectionId}`, {
  headers,
}).then((r) => r.json());
if (polled.contract.status === "active") {
  /* ready */
}

And recording a tap:

const tap = await fetch(`${ENDSTATE}/v1/taps`, {
  method: "POST",
  headers,
  body: JSON.stringify({ chip_id: chipId, e }),
}).then((r) => r.json());
const token = tap.session_token.token; // the verified unit is tap.unit

These examples use fetch deliberately, to show the shapes on the wire. @endstate-sdk/core preserves them exactly - it renames nothing, so created.id, polled.contract.status, and tap.session_token.token are the same paths in TypeScript.

List responses

List endpoints wrap their array under a plural key alongside pagination:

Response

{ "collections": [ ... ], "pagination": { "limit": 50, "has_more": false, "next_cursor": null } }

See Pagination for cursoring through results.

Errors

Errors use a separate, uniform envelope - { "error": { "code", "message", "request_id" } } - across every endpoint. See Errors.

Get started

Settings

Core concepts

API conventions

Updates

Single resources are top-level

List responses

Errors

​Single resources are top-level

​List responses

​Errors

Single resources are top-level

List responses

Errors