Response shape - Endstate API

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, verify results, 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/chips/{id}` (verify)	Top-level: `{ session_token, unit, ... }`	`response.session_token`
`GET /v1/session-tokens/current`	Top-level: `{ chip_id, unit_id, ... }`	`response.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 verify 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 verifying a tap:

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

List responses

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

{ "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.

​Single resources are top-level

​List responses

​Errors

Single resources are top-level

List responses

Errors