List items

A page of your collection's items: all of them newest first, or those of one reference or reference prefix in reference order.

GEThttps://api.decisionnode.com/v1/collections/{id}/items

curl https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items?limit=20 \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

By reference: the SDK releases list items without a reference filter, so send the query over HTTPS.

Every item of one reference

curl https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items?reference=emp-1042 \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

Headers#

Authorizationheaderrequired: Bearer dn_live_.... A Full access key: every call acts for that key's workspace only, and a Decisions-only key gets 403 key_scope_denied, "This key may only make decisions."

Path parameters#

idstringrequired: The collection: col_ and 32 hex digits for your own, or a public collection's name, celebrities.

Query parameters#

offsetintegerdefault 0: Items to skip, 0 or more.
limitintegerdefault 20: Items in the page, 1 to 100.
referencestring: Only the items of this reference, exactly: 1 to 64 characters of A-Z, a-z, 0-9 and _ . : -.
reference_prefixstring: Only the items whose reference starts with this, in the same characters. Not with reference.

Response#

200 OK with a page. Without a filter the items are newest first and total counts them all. With reference or reference_prefix they come in reference order (byte order, then the item id), and total counts the matches up to 10,000: past that it is 10,000 and total_capped is true. Pass next_offset as offset for the next page, until it is null. A template never leaves the service.

200 OK

{
  "items": [
    {
      "id": "itm_9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d",
      "reference": "emp-1042",
      "label": "Anna, reception",
      "metadata": {
        "department": "reception",
        "badge": 1042,
        "visitor": false
      },
      "created_at": "2026-10-12T09:00:00Z"
    }
  ],
  "offset": 0,
  "limit": 20,
  "total": 1,
  "total_capped": false,
  "next_offset": null,
  "reference": null,
  "reference_prefix": null
}

The page

itemsarray: Item objects.
offset, limitinteger: As asked, or their defaults.
totalinteger: Every item, or the matches of a filter counted to 10,000.
total_cappedboolean: true when a filter matched more than 10,000.
next_offsetinteger or null: The next page's offset; null on the last.
reference, reference_prefixstring or null: The filter applied, null when not sent.

Errors#

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	`offset` not an integer of at least 0, `limit` not 1 to 100, `reference` and `reference_prefix` both sent, or either outside its characters; the message names the parameter	Fix the query
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`collection_read_only`	The collection is a public one: "<name> is a public collection and cannot be changed or listed."	Act on one of your own collections
`404`	`collection_not_found`	No such collection for your workspace; another workspace's reads the same. "Collection not found: <id>.", the id repeated only when it has the form of one	Check the id
`429`	`rate_limit_error`	Over your request rate	Wait `Retry-After`, then send the same call again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	The collections cannot take the call right now	Wait `Retry-After` (1 s, or 1 to 2 s when the key store is busy), then retry

A refusal is {"detail": {"error_type": "...", "message": "..."}}; a 422 is {"detail": [...]}, one entry per field, each with type, loc, msg and input (a string cut to 64 characters, an object or array never echoed). Every 429 and 529 and the 409 idempotency_in_progress carry Retry-After (seconds) and retry-after-ms (milliseconds); enrollment_unpriced carries neither. The Collections API's own refusals (api_usage_error, collection_read_only, item_not_found, collections_region_unavailable, the limits, the idempotency 409s and image_url_refused) also carry x-decisionnode-error, the message in ASCII. Retry 408, 429, 529 and any 5xx after Retry-After; fix the call for the other 4xx.

Query parameters#

offsetintegerdefault 0

Items to skip, 0 or more.

limitintegerdefault 20

Items in the page, 1 to 100.

referencestring

Only the items of this reference, exactly: 1 to 64 characters of A-Z, a-z, 0-9 and _ . : -.

reference_prefixstring

Only the items whose reference starts with this, in the same characters. Not with reference.

Response#

200 OK

{
  "items": [
    {
      "id": "itm_9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d",
      "reference": "emp-1042",
      "label": "Anna, reception",
      "metadata": {
        "department": "reception",
        "badge": 1042,
        "visitor": false
      },
      "created_at": "2026-10-12T09:00:00Z"
    }
  ],
  "offset": 0,
  "limit": 20,
  "total": 1,
  "total_capped": false,
  "next_offset": null,
  "reference": null,
  "reference_prefix": null
}

The page

itemsarray

Item objects.

offset, limitinteger

As asked, or their defaults.

totalinteger

Every item, or the matches of a filter counted to 10,000.

total_cappedboolean

true when a filter matched more than 10,000.

next_offsetinteger or null

The next page's offset; null on the last.

reference, reference_prefixstring or null

The filter applied, null when not sent.

Errors#

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	`offset` not an integer of at least 0, `limit` not 1 to 100, `reference` and `reference_prefix` both sent, or either outside its characters; the message names the parameter	Fix the query
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`collection_read_only`	The collection is a public one: "<name> is a public collection and cannot be changed or listed."	Act on one of your own collections
`404`	`collection_not_found`	No such collection for your workspace; another workspace's reads the same. "Collection not found: <id>.", the id repeated only when it has the form of one	Check the id
`429`	`rate_limit_error`	Over your request rate	Wait `Retry-After`, then send the same call again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	The collections cannot take the call right now	Wait `Retry-After` (1 s, or 1 to 2 s when the key store is busy), then retry