Knowledge in a decision

The knowledge booster on a request: its options, filters, what require guarantees, the token budget, and the citations it returns in evidence.knowledge.

Name the knowledge base in the knowledge booster's collection option. The booster takes the object form only, since collection is required. It reads the request's questions and state, never a picture, and works beside other boosters, up to four a request, on DecisionNode MoE and Flash, live and in batches.

A request with knowledge, and its answer

curl https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-moe",
    "state": {
      "claim": { "amount": "740.00", "currency": "SEK", "receipt": false },
      "mission": "M-42"
    },
    "boosters": [
      {
        "name": "knowledge",
        "require": true,
        "options": {
          "collection": "col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80",
          "scope": "M-42"
        }
      }
    ],
    "questions": {
      "approve": {
        "type": "truth",
        "instructions": "Should the claim be approved under our policy?"
      }
    }
  }'

Options#

collectionstringrequired: The col_ id of one of your knowledge bases. A face collection is 400 collection_type_mismatch; another workspace's id, or one that does not exist, 404 collection_not_found.
scopestring: The value of the knowledge base's scope key, such as a mission id, 1 to 500 characters. See Scope.
top_kintegerdefault 4: 0 to 20: the most passages that matched, pinned documents not counted. 0 gives the pinned documents only, with no search.
max_tokensinteger or "auto"default "auto": The room for the passages that matched. auto fits them to the room the request has (below); a number from 128 to 8,192 gives them that room every time.
matchobject: Metadata the passages must carry: {"region": "SE", "product": ["car", "home"]}, a value equal, a list any of.
filterobject: A filter tree for anything match cannot say (below).
querystring: 1 to 2,000 characters searched in place of the request's own questions and state.
pinnedbooleandefault true: false leaves the pinned documents out.
min_scorenumber: 0 to 1: a floor on how close a passage found by meaning alone must be. Passages that share words with the request are never dropped by it.
include_textbooleandefault false: Adds each passage's text, and the query's, to the response. Needs a Full access key: another key gets 403 key_scope_denied, "include_text needs a full-scope key."
timeout_msinteger: The booster's time budget for this request, 100 to 5,000; left out, 800 ms.

What it searches with. Left to itself the booster searches with every question's instructions and the values of your state. Clear instructions and a state with named fields find the right rules best; set query when you know better what to look for.
images or videos on the knowledge entry are 400 booster_input_mismatch: it reads no pictures. A request with pictures for other boosters is fine.
Sessions take no boosters, knowledge included.

Filters#

match and filter narrow both the passages that matched and the pinned documents, by your documents' metadata. A document without the key does not match. A filter node is {"and": [...]}, {"or": [...]}, a metadata condition {"key", "op", "value"} with op one of eq, ne, in, nin, gt, gte, lt, lte and exists, or a document condition {"attr": "reference"} or {"attr": "item"} with eq, ne, in or nin. Up to 2 levels, 16 conditions, 32 values in a list and 500 characters a text; a malformed filter is 400 naming the node.

Swedish documents valid this year, or documents with no region

{
  "name": "knowledge",
  "options": {
    "collection": "col_3f6c1a9e0b2d4c7f8a1e5d9b2c4f6a80",
    "filter": {
      "and": [
        { "key": "year", "op": "gte", "value": 2026 },
        {
          "or": [
            { "key": "region", "op": "eq", "value": "SE" },
            { "key": "region", "op": "exists", "value": false }
          ]
        }
      ]
    }
  }
}

What comes back#

evidence.knowledge

{
  "version": "knowledge-v1",
  "status": "ok",
  "latency_ms": 141,
  "billed_calls": 1,
  "results": [
    {
      "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
    }
  ]
}

The result

collection, collection_namestring: The knowledge base searched, by id and name.
corpus.versioninteger: The knowledge base's version when it was read: the same request over the same version reads the same passages.
queryobject: source (auto, request for your query, or none with top_k: 0) and its tokens; text with include_text.
budgetobject: mode (auto or fixed) and the tokens the passages that matched had; entry is short when the request kept to the size the model answers fastest and long when it did not, and cause says what made it longer (state, images, other_boosters, pinned, fixed or require_floor).
scopeobject: The scope key and the value read, or null.
warningsarray: scope_not_named, over_budget, budget_floor, pinned_filtered: see When a rule does not appear.
passagesarray: Every passage given to the model, pinned first, in the order it read them. n is its number in what the model read; item, reference, title and heading say where it comes from; byte_start and byte_end are its position in the document's stored text (UTF-8 bytes, end not included), so text[byte_start:byte_end] of GET .../items/{id}?include=text is the passage; score is how close it was by meaning (null for a pinned one; the model never sees it); lexical is true when it shared words with the request; rendered: false marks a passage left out to fit the model's context.
omittedobject: How many passages were left out, and why: below_min_score, per_item_cap, over_budget, pinned_filtered, short_entry, context_limit.
pending_itemsinteger: Documents not ready yet, which this request could not read.
truncatedboolean: Always present: true when the model's context was full and passages that matched were left out (rendered: false).

Show the rule a decision rested on. The passages and their offsets are your citations: read the stored text once and quote text[byte_start:byte_end], or ask for include_text from your server.
From a browser, with a publishable key, a passage carries its ids and offsets only: collection_name, title, heading and reference are null, so no page shows your documents' titles. The model reads the same passages either way.
One call a request. billed_calls is 1 for an ok reading, a reading that matched nothing included, and 0 otherwise.

Budget: how much room passages get#

A request is answered fastest while it stays within a certain size. With max_tokens: "auto", the default, the passages that matched get the room the request has left after its state, its pictures, other boosters' readings and the pinned documents, up to 1,024 tokens: a short request gets several passages, a long one fewer, and knowledge does not slow it down. Pinned documents always come in whole.

A number gives the passages that much room on every request, at some added latency when the request grows past the fast size. Use it when completeness matters more than speed.
Passages are kept whole: one that does not fit is skipped for a shorter one that does, and counted in omitted.over_budget.
budget.entry says whether the request stayed within the fast size, and budget.cause what took it past.
Passages' tokens are input tokens at the model's price, in usage.booster_tokens.

require#

With "require": true a decision is never made without your rules: the booster must read a ready knowledge base, every pinned document in scope that passes your filters is given to the model, and when any passage matched, at least the best one is, even when the budget had no room for it. It does not promise every relevant passage: a rule that must always apply is pinned.

Outcomes
What happened	Without `require`	With `require`
Read, passages given (or none matched)	Answered, billed	Answered, billed
Passages matched but `auto` left no room	None of them given; warning `over_budget`	The best one given anyway; warning `budget_floor`
Timed out or failed	Answered without knowledge, not billed	`529` `booster_unavailable`
No document ready yet, some processing	Answered without knowledge, not billed	`529`, `Retry-After: 5`; when processing is delayed, `Retry-After: 60` and `details.reason` `ingestion_delayed`
No document ready or processing (empty, or every one failed)	Answered without knowledge, not billed	`409` `knowledge_collection_empty`, with `details.items` and `details.failed`

Search without a decision#

POST https://api.decisionnode.com/v1/collections/{id}/search runs the same retrieval with a query you give and answers the same result, passages' text included, without a decision. Use it to check what a request would read. It is billed as one knowledge call and needs a Full access key. See Search a knowledge base.

Errors#

Errors of a request with knowledge
Status	Type	When
`400`	`api_usage_error`	`knowledge` as a bare name or without `options.collection` ("the booster 'knowledge' needs options.collection"); an unknown option or a value out of range; `scope` on a knowledge base without a scope key; the scope key in `match` or `filter`; a malformed filter. `x-decisionnode-error` says which
`400`	`booster_input_mismatch`	`images` or `videos` on the knowledge entry
`400`	`collection_type_mismatch`	`collection` is a face collection
`403`	`key_scope_denied`	`include_text` from a key that is not Full access
`403`	`booster_not_enabled`	Knowledge is turned off for your workspace
`404`	`collection_not_found`	No such knowledge base in your workspace
`409`	`knowledge_collection_empty`	With `require`: nothing ready and nothing processing
`529`	`booster_unavailable`	With `require`: the booster failed or timed out, or no document is ready yet; retry after `Retry-After`