Delete failed documents

Delete every failed document of a knowledge base in one call: the documents whose processing failed and that never got ready.

DELETEhttps://api.decisionnode.com/v1/collections/{id}/items?status=failed

curl -X DELETE https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/items?status=failed \
  -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

statusstringrequired: failed, the only value: a delete of a knowledge base's items is only ever of its failed documents.

Response#

200 OK with how many documents were deleted, 0 when there were none. A failed document counts toward nothing while it is listed; this only tidies the list. A document whose newest version failed while an earlier one serves is not deleted: delete it by id. It works whatever your balance or settings.

200 OK

{ "deleted": 3 }

Errors#

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	No `status=failed`, or a face collection	Send `status=failed` to a knowledge base
`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
`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.