Search a knowledge base

Run a knowledge base's retrieval without a decision: the passages a request with this query would read, with their text. Billed as one knowledge call.

POSThttps://api.decisionnode.com/v1/collections/{id}/search

curl -X POST https://api.decisionnode.com/v1/collections/col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80/search \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"claim without a receipt","scope":"M-42","top_k":4}'

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.

Path parameters#

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

Request body#

querystringrequired: What to search for, 1 to 2,000 characters.
scope, match, filter, top_k, pinnedas the booster's: As the booster's options.
max_tokensinteger or "auto"default "auto": auto is 1,024 tokens here, there being no request to fit; or 128 to 8,192.

Response#

200 OK with the result a decision's evidence.knowledge carries (What comes back), each passage's text and the query's included. Needs a Full access key, and is billed as one knowledge call; it counts against the free tier's booster calls.

200 OK

{
  "collection": "col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80",
  "collection_name": "Claims policy",
  "corpus": { "version": 41 },
  "query": { "source": "auto", "tokens": 212 },
  "budget": {
    "mode": "auto",
    "tokens": 840,
    "entry": "short",
    "cause": null
  },
  "scope": { "key": "mission", "value": "M-42" },
  "warnings": [],
  "passages": [
    {
      "n": 1,
      "pinned": true,
      "item": "itm_9a1c4e7b2d5f8a0c3e6b9d2f5a8c1e4b",
      "reference": "policy-2026",
      "title": "Claims policy 2026",
      "heading": "Receipts",
      "chunk": 0,
      "byte_start": 22,
      "byte_end": 83,
      "tokens": 14,
      "score": null,
      "lexical": false,
      "rendered": true
    },
    {
      "n": 2,
      "pinned": false,
      "item": "itm_4b7e0a3d6c9f2b5e8a1d4c7f0b3e6a9d",
      "reference": "m-42-brief",
      "title": "Mission M-42 brief",
      "heading": "Special instructions",
      "chunk": 0,
      "byte_start": 0,
      "byte_end": 83,
      "tokens": 19,
      "score": 0.7713,
      "lexical": true,
      "rendered": true
    }
  ],
  "omitted": {
    "below_min_score": 0,
    "per_item_cap": 0,
    "over_budget": 0,
    "pinned_filtered": 0,
    "short_entry": 0,
    "context_limit": 0
  },
  "pending_items": 0,
  "search": { "plan": "exact", "candidates": 50, "fallback": false },
  "truncated": false
}

Errors#

Errors this call returns
Status	Type	When	What to do
`400`	`api_usage_error`	A bad option, `scope` on a knowledge base without a scope key, the scope key in `match` or `filter`, a malformed filter	Fix the body
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`402`	`insufficient_credit`	The prepaid balance is empty. Reads, edits and deletes stay open	Add credit, then retry
`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
`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`	`knowledge_collection_empty`	No document is ready and none is processing	Add a document
`529`	`booster_unavailable`	No document is ready yet, some are processing: `Retry-After: 5`, or `60` with `details.reason` `ingestion_delayed`; an unpriced search is the `529` too	Retry after `Retry-After`
`422`	a `detail` list	The body is not JSON (`json_invalid`)	Send a JSON object
`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.