List a document's passages

The passages a document was cut into, with their headings, byte offsets, tokens and text: what a request can read from it.

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

curl https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items/itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b/chunks \
  -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.
item_idstringrequired: The item: itm_ and 32 hex digits.

Query parameters

offsetintegerdefault 0: Where the page starts.
limitintegerdefault 20: 1 to 100.

Response#

200 OK with the passages of the version that answers, in order: chunk (the number a citation names), heading (its heading path, A > B), byte_start and byte_end in the stored text, page_start and page_end (a PDF's pages, else null), tokens and text. Never the index's numbers.

200 OK

{
  "chunks": [
    {
      "chunk": 0,
      "heading": "Receipts",
      "byte_start": 22,
      "byte_end": 83,
      "page_start": null,
      "page_end": null,
      "tokens": 14,
      "text": "## Receipts\n\nReject any claim over 500 SEK without a receipt."
    },
    {
      "chunk": 1,
      "heading": "Photos",
      "byte_start": 85,
      "byte_end": 151,
      "page_start": null,
      "page_end": null,
      "tokens": 15,
      "text": "## Photos\n\nPhotos of damage must show the date they were taken."
    }
  ],
  "offset": 0,
  "limit": 20,
  "total": 2,
  "next_offset": null
}

Errors#

Errors this call returns
Status	Type	When	What to do
`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
`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
`404`	`item_not_found`	No such item in the collection: "Item not found: <id>." (likewise)	Check the item id
`400`	`collection_type_mismatch`	The collection is a face collection: a face body to a knowledge base, or a document to a face collection	Use a knowledge base's 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.