Replace a document

Replace a document whole. A new text or title is indexed again while the old version keeps answering requests; the same text again changes nothing.

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

curl -X PUT https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items/itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Claims policy 2026","text":"# Claims policy 2026\n\n## Receipts\n\nReject any claim over 500 SEK without a receipt.\n\n## Photos\n\nPhotos of damage must show the date they were taken.\n\n## Deadlines\n\nA claim is filed within 30 days.","format":"markdown","reference":"policy-2026","pinned":true}'

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."
Content-Typeheader: application/json. Not checked: the body is read as JSON whatever its type.
Idempotency-Keyheader: 1 to 255 printable ASCII characters of your choosing, sent once. A retry with the same key, route and body within 24 hours gets the first answer again; see Retrying.

Path parameters#

idstringrequired: The collection: col_ and 32 hex digits for your own.
item_idstringrequired: The item: itm_ and 32 hex digits.

Query parameters

waitbooleandefault false: Wait up to 10 seconds for the document to be ready.

Request body#

The whole document, as Add a document takes it. A field left out takes its default.

Response#

A new text, format or title: 202 Accepted, a new version queued; the previous version keeps answering requests (serving previous) until the new one is ready and takes its place at once. With ?wait=true, 200 OK once it is ready.
The same text, format and title: 200 OK, nothing indexed, nothing billed; the other fields are applied.
reference, label, metadata, pinned, pin_rank are applied at once, to the version that answers too.

202 Accepted

{
  "id": "itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b",
  "title": "Claims policy 2026",
  "reference": "policy-2026",
  "format": "markdown",
  "label": null,
  "metadata": {},
  "pinned": true,
  "pin_rank": 0,
  "source": "article",
  "file": null,
  "status": "queued",
  "stage": null,
  "progress": null,
  "serving": "current",
  "error": null,
  "delayed": false,
  "warnings": [],
  "chunks": 2,
  "tokens": 41,
  "content_sha256": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "version": 2,
  "queued_at": "2026-10-20T11:00:04Z",
  "ready_at": "2026-10-20T11:00:06Z",
  "created_at": "2026-10-20T11:00:04Z"
}

Errors#

400
Type
api_usage_error
When
A malformed Idempotency-Key: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."
What to do
Send one key of 1 to 255 printable ASCII characters
401
Type
authentication_error
When
The key is missing, unknown or revoked
What to do
Check the Authorization header
402
Type
insufficient_credit
When
"Add credit to store more knowledge.": the balance cannot pay and the free allowance does not cover the write; on the free tier details.reason is free_text_chunks or free_text_tokens, with resets_at
What to do
Add credit, or wait for resets_at
403
Type
key_scope_denied
When
A Decisions-only key: "This key may only make decisions."
What to do
Use a Full access key on your server
403
Type
booster_not_enabled
When
Knowledge is turned off for your workspace
What to do
Write to us
404
Type
collection_not_found
When
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
What to do
Check the id
404
Type
item_not_found
When
No such item in the collection: "Item not found: <id>." (likewise)
What to do
Check the item id
400
Type
collection_type_mismatch
When
The collection is a face collection: a face body to a knowledge base, or a document to a face collection
What to do
Use a knowledge base's id
409
Type
reference_taken
When
"Another item of this collection has this reference."; details.item_id names it
What to do
Use another reference, or PUT that document
409
Type
pinned_budget_exceeded
When
Pinning this, or its new text, would take the pinned documents past their cap (512 tokens by default)
What to do
Shorten or unpin a pinned document
409
Type
chunks_limit_reached, items_limit_reached
When
Your workspace's passages or items are at their limit
What to do
Delete documents, or write to us
409
Type
idempotency_key_reused, idempotency_in_progress
When
The key was used with another request, or its first request still runs (Retry-After: 1)
What to do
See Retrying
400
Type
upload_not_found, upload_expired, upload_consumed, upload_incomplete, upload_purpose_mismatch
When
The upload_id is unknown, past its hour, already a document's, has no bytes of the declared size yet, or is an image upload
What to do
Presign and upload the file again, or finish its PUT
413
Type
item_too_large
When
The text is over 512 KiB once stored
What to do
Split the document
422
Type
a detail list
When
A field out of bounds; invalid_text for a text that is not UTF-8 or holds a NUL; text or format beside an upload_id; an image in the body
What to do
Fix the field; a 422 frees the Idempotency-Key
422
Type
a detail list
When
The body is not JSON (json_invalid)
What to do
Send a JSON object
429
Type
rate_limit_error
When
"This workspace has reached its ingestion rate. Retry later.": details.reason ingest_queue_full (1,000 documents waiting) or ingest_tokens_per_hour (2,000,000 newly indexed tokens within the hour)
What to do
Wait Retry-After (or retry-after-ms), then send it again
500
Type
api_error
When
A fault on our side
What to do
Retry with backoff
529
Type
overloaded_error
When
details.reason enrollment_unpriced: "Text ingestion is not available on this deployment yet."
What to do
Never retried; write to us
529
Type
overloaded_error
When
The collections cannot take the call right now
What to do
Wait Retry-After (1 s, or 1 to 2 s when the key store is busy), then retry

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	A malformed `Idempotency-Key`: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."	Send one key of 1 to 255 printable ASCII characters
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`402`	`insufficient_credit`	"Add credit to store more knowledge.": the balance cannot pay and the free allowance does not cover the write; on the free tier `details.reason` is `free_text_chunks` or `free_text_tokens`, with `resets_at`	Add credit, or wait for `resets_at`
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`booster_not_enabled`	Knowledge is turned off for your workspace	Write to us
`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
`409`	`reference_taken`	"Another item of this collection has this reference."; `details.item_id` names it	Use another reference, or `PUT` that document
`409`	`pinned_budget_exceeded`	Pinning this, or its new text, would take the pinned documents past their cap (512 tokens by default)	Shorten or unpin a pinned document
`409`	`chunks_limit_reached`, `items_limit_reached`	Your workspace's passages or items are at their limit	Delete documents, or write to us
`409`	`idempotency_key_reused`, `idempotency_in_progress`	The key was used with another request, or its first request still runs (`Retry-After: 1`)	See Retrying
`400`	`upload_not_found`, `upload_expired`, `upload_consumed`, `upload_incomplete`, `upload_purpose_mismatch`	The `upload_id` is unknown, past its hour, already a document's, has no bytes of the declared size yet, or is an image upload	Presign and upload the file again, or finish its `PUT`
`413`	`item_too_large`	The text is over 512 KiB once stored	Split the document
`422`	a `detail` list	A field out of bounds; `invalid_text` for a text that is not UTF-8 or holds a NUL; `text` or `format` beside an `upload_id`; an `image` in the body	Fix the field; a `422` frees the `Idempotency-Key`
`422`	a `detail` list	The body is not JSON (`json_invalid`)	Send a JSON object
`429`	`rate_limit_error`	"This workspace has reached its ingestion rate. Retry later.": `details.reason` `ingest_queue_full` (1,000 documents waiting) or `ingest_tokens_per_hour` (2,000,000 newly indexed tokens within the hour)	Wait `Retry-After` (or `retry-after-ms`), then send it again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	`details.reason` `enrollment_unpriced`: "Text ingestion is not available on this deployment yet."	Never retried; write to us
`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.

curl -X PUT https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items/itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b \ -H "Authorization: Bearer $DECISIONNODE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title":"Claims policy 2026","text":"# Claims policy 2026\n\n## Receipts\n\nReject any claim over 500 SEK without a receipt.\n\n## Photos\n\nPhotos of damage must show the date they were taken.\n\n## Deadlines\n\nA claim is filed within 30 days.","format":"markdown","reference":"policy-2026","pinned":true}'

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

Content-Typeheader

application/json. Not checked: the body is read as JSON whatever its type.

Idempotency-Keyheader

1 to 255 printable ASCII characters of your choosing, sent once. A retry with the same key, route and body within 24 hours gets the first answer again; see Retrying.

Response#

A new text, format or title: 202 Accepted, a new version queued; the previous version keeps answering requests (serving previous) until the new one is ready and takes its place at once. With ?wait=true, 200 OK once it is ready.

The same text, format and title: 200 OK, nothing indexed, nothing billed; the other fields are applied.

reference, label, metadata, pinned, pin_rank are applied at once, to the version that answers too.

202 Accepted

{
  "id": "itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b",
  "title": "Claims policy 2026",
  "reference": "policy-2026",
  "format": "markdown",
  "label": null,
  "metadata": {},
  "pinned": true,
  "pin_rank": 0,
  "source": "article",
  "file": null,
  "status": "queued",
  "stage": null,
  "progress": null,
  "serving": "current",
  "error": null,
  "delayed": false,
  "warnings": [],
  "chunks": 2,
  "tokens": 41,
  "content_sha256": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "version": 2,
  "queued_at": "2026-10-20T11:00:04Z",
  "ready_at": "2026-10-20T11:00:06Z",
  "created_at": "2026-10-20T11:00:04Z"
}

Errors#

400

Type: api_usage_error
When: A malformed Idempotency-Key: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."
What to do: Send one key of 1 to 255 printable ASCII characters

401

Type: authentication_error
When: The key is missing, unknown or revoked
What to do: Check the Authorization header

402

Type: insufficient_credit
When: "Add credit to store more knowledge.": the balance cannot pay and the free allowance does not cover the write; on the free tier details.reason is free_text_chunks or free_text_tokens, with resets_at
What to do: Add credit, or wait for resets_at

403

Type: key_scope_denied
When: A Decisions-only key: "This key may only make decisions."
What to do: Use a Full access key on your server

403

Type: booster_not_enabled
When: Knowledge is turned off for your workspace
What to do: Write to us

404

Type: collection_not_found
When: 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
What to do: Check the id

404

Type: item_not_found
When: No such item in the collection: "Item not found: <id>." (likewise)
What to do: Check the item id

400

Type: collection_type_mismatch
When: The collection is a face collection: a face body to a knowledge base, or a document to a face collection
What to do: Use a knowledge base's id

409

Type: reference_taken
When: "Another item of this collection has this reference."; details.item_id names it
What to do: Use another reference, or PUT that document

409

Type: pinned_budget_exceeded
When: Pinning this, or its new text, would take the pinned documents past their cap (512 tokens by default)
What to do: Shorten or unpin a pinned document

409

Type: chunks_limit_reached, items_limit_reached
When: Your workspace's passages or items are at their limit
What to do: Delete documents, or write to us

409

Type: idempotency_key_reused, idempotency_in_progress
When: The key was used with another request, or its first request still runs (Retry-After: 1)
What to do: See Retrying

400

Type: upload_not_found, upload_expired, upload_consumed, upload_incomplete, upload_purpose_mismatch
When: The upload_id is unknown, past its hour, already a document's, has no bytes of the declared size yet, or is an image upload
What to do: Presign and upload the file again, or finish its PUT

413

Type: item_too_large
When: The text is over 512 KiB once stored
What to do: Split the document

422

Type: a detail list
When: A field out of bounds; invalid_text for a text that is not UTF-8 or holds a NUL; text or format beside an upload_id; an image in the body
What to do: Fix the field; a 422 frees the Idempotency-Key

422

Type: a detail list
When: The body is not JSON (json_invalid)
What to do: Send a JSON object

429

Type: rate_limit_error
When: "This workspace has reached its ingestion rate. Retry later.": details.reason ingest_queue_full (1,000 documents waiting) or ingest_tokens_per_hour (2,000,000 newly indexed tokens within the hour)
What to do: Wait Retry-After (or retry-after-ms), then send it again

500

Type: api_error
When: A fault on our side
What to do: Retry with backoff

529

Type: overloaded_error
When: details.reason enrollment_unpriced: "Text ingestion is not available on this deployment yet."
What to do: Never retried; write to us

529

Type: overloaded_error
When: The collections cannot take the call right now
What to do: Wait Retry-After (1 s, or 1 to 2 s when the key store is busy), then retry

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	A malformed `Idempotency-Key`: "Idempotency-Key must be sent once, as 1 to 255 printable ASCII characters."	Send one key of 1 to 255 printable ASCII characters
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`402`	`insufficient_credit`	"Add credit to store more knowledge.": the balance cannot pay and the free allowance does not cover the write; on the free tier `details.reason` is `free_text_chunks` or `free_text_tokens`, with `resets_at`	Add credit, or wait for `resets_at`
`403`	`key_scope_denied`	A Decisions-only key: "This key may only make decisions."	Use a Full access key on your server
`403`	`booster_not_enabled`	Knowledge is turned off for your workspace	Write to us
`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
`409`	`reference_taken`	"Another item of this collection has this reference."; `details.item_id` names it	Use another reference, or `PUT` that document
`409`	`pinned_budget_exceeded`	Pinning this, or its new text, would take the pinned documents past their cap (512 tokens by default)	Shorten or unpin a pinned document
`409`	`chunks_limit_reached`, `items_limit_reached`	Your workspace's passages or items are at their limit	Delete documents, or write to us
`409`	`idempotency_key_reused`, `idempotency_in_progress`	The key was used with another request, or its first request still runs (`Retry-After: 1`)	See Retrying
`400`	`upload_not_found`, `upload_expired`, `upload_consumed`, `upload_incomplete`, `upload_purpose_mismatch`	The `upload_id` is unknown, past its hour, already a document's, has no bytes of the declared size yet, or is an image upload	Presign and upload the file again, or finish its `PUT`
`413`	`item_too_large`	The text is over 512 KiB once stored	Split the document
`422`	a `detail` list	A field out of bounds; `invalid_text` for a text that is not UTF-8 or holds a NUL; `text` or `format` beside an `upload_id`; an `image` in the body	Fix the field; a `422` frees the `Idempotency-Key`
`422`	a `detail` list	The body is not JSON (`json_invalid`)	Send a JSON object
`429`	`rate_limit_error`	"This workspace has reached its ingestion rate. Retry later.": `details.reason` `ingest_queue_full` (1,000 documents waiting) or `ingest_tokens_per_hour` (2,000,000 newly indexed tokens within the hour)	Wait `Retry-After` (or `retry-after-ms`), then send it again
`500`	`api_error`	A fault on our side	Retry with backoff
`529`	`overloaded_error`	`details.reason` `enrollment_unpriced`: "Text ingestion is not available on this deployment yet."	Never retried; write to us
`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