# Set up DecisionNode

These are DecisionNode's own instructions for a coding agent, published at https://decisionnode.com/agent-setup.md so you can check where they come from.

DecisionNode is a decision engine: send it text, JSON or images with a question, and it answers with calibrated probabilities. It sits behind one HTTPS endpoint and answers typed questions (a choice, a score, the probability that a statement is true, a number, a point or a box) in milliseconds. It never generates text, so output is free.

Follow the steps in order. Run the commands yourself, except a step marked **User step**: ask the user to do it, and wait. Never run a command that waits on an interactive prompt.

## 1. The API key (User step)

Ask the user to create a key in the console at https://decisionnode.com/console/keys (a workspace needs a plan, which sign-up starts with a card) and to put it in the environment as `DECISIONNODE_API_KEY`, for example in the project's untracked `.env`. Keys start with `dn_live_`. Read the key from the environment only: never write it into code, a config file, a commit, a log or your reply, and never ship it to a browser.

## 2. Connect the docs MCP server

`https://decisionnode.com/mcp` serves the DecisionNode docs over Streamable HTTP, with no key and no sign-in. It has two tools: `search_docs` finds pages, `read_doc` returns one as Markdown. It reads the docs; it makes no decisions.

### Claude Code

Run it in a terminal:

```bash
claude mcp add --transport http decisionnode-docs https://decisionnode.com/mcp
```

### Cursor

In `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "decisionnode-docs": { "url": "https://decisionnode.com/mcp" }
  }
}
```

### VS Code

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "decisionnode-docs": {
      "type": "http",
      "url": "https://decisionnode.com/mcp"
    }
  }
}
```

### Codex

Run it in a terminal:

```bash
codex mcp add decisionnode-docs --url https://decisionnode.com/mcp
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.decisionnode-docs]
url = "https://decisionnode.com/mcp"
```

A client may need a reload to see a new server: ask the user to reload it if yours does (**User step**). If your client takes none of these, go on: step 3 gives you the same content.

## 3. Read the reference

Fetch https://decisionnode.com/llms.txt: the key facts and a map of every docs page. https://decisionnode.com/llms-full.txt has every page as Markdown, for the whole reference. With the MCP server connected, `search_docs` and `read_doc` give you one page at a time.

## 4. The client library

DecisionNode has an official SDK for Python, TypeScript and JavaScript, Go, Java and Kotlin, C# and .NET, PHP, Ruby and Rust. If the project's language is one of them, add it with the project's own package manager (its line below, or the equivalent such as `uv add` or `pnpm add`) and write the integration with it: it builds the request in step 5, parses the answers into types and retries temporary errors itself. Each reads the key from `DECISIONNODE_API_KEY`, and its README (linked) has the calls. Any other language calls the endpoint over plain HTTPS.

- Python (PyPI, [`bynn-decisionnode`](https://github.com/Bynn-Intelligence/decision-node-python)): `pip install bynn-decisionnode`
- TypeScript and JavaScript (npm, [`@decisionnode/sdk`](https://github.com/Bynn-Intelligence/decision-node-node)): `npm install @decisionnode/sdk`
- Go (the Go module proxy, [`github.com/Bynn-Intelligence/decision-node-go`](https://github.com/Bynn-Intelligence/decision-node-go)): `go get github.com/Bynn-Intelligence/decision-node-go`
- Java and Kotlin (Maven Central, [`com.bynn:decisionnode`](https://github.com/Bynn-Intelligence/decision-node-java)): Gradle `implementation("com.bynn:decisionnode:0.3.2")`
- C# and .NET (NuGet, [`Bynn.DecisionNode`](https://github.com/Bynn-Intelligence/decision-node-dotnet)): `dotnet add package Bynn.DecisionNode`
- PHP (Packagist, [`bynn/decisionnode`](https://github.com/Bynn-Intelligence/decision-node-php)): `composer require bynn/decisionnode`
- Ruby (RubyGems, [`bynn-decisionnode`](https://github.com/Bynn-Intelligence/decision-node-ruby)): `bundle add bynn-decisionnode`
- Rust (crates.io, [`bynn-decisionnode`](https://github.com/Bynn-Intelligence/decision-node-rust)): `cargo add bynn-decisionnode --features blocking`

For an agent of the user's own that should ask DecisionNode questions as tools, the DecisionNode MCP server (https://github.com/Bynn-Intelligence/decision-node-mcp-server) runs on the user's machine with uv: `uvx bynn-decisionnode-mcp`, the key in its environment as `DECISIONNODE_API_KEY`. Set it up only if the user asks for it; it is not the docs MCP server of step 2.

The `dn` command line asks the same questions from a shell. Install it only if the user asks for it: `curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/Bynn-Intelligence/decision-node-cli/main/install.sh | sh` on macOS and Linux, `brew install bynn-intelligence/bynn/dn`, or Scoop on Windows (https://decisionnode.com/docs/cli). It reads `DECISIONNODE_API_KEY` from the environment; never run `dn auth login`, which waits on a prompt.

## 5. The call

The smallest request: one Truth question about one message, on DecisionNode Flash.

```bash
curl -sS https://api.decisionnode.com/v1/decide \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"decisionnode-flash","state":"Customer: I was charged twice for order 4411 and want my money back.","questions":{"refund":{"type":"truth","instructions":"Should this ticket get an automatic refund?"}}}'
```

The whole contract, which the integration follows as written:

```text
Endpoint: POST https://api.decisionnode.com/v1/decide
Auth: header "Authorization: Bearer <key>", key read from the DECISIONNODE_API_KEY environment variable on the server. Never ship that key to a browser, an app or a device, and never log it. The API refuses browser (cross-origin) calls except with a publishable key, so frontend code calls this app's own backend, which calls DecisionNode; a device gets a Decisions-only key of its own from the app's server.

Request body (questions required; model, state, images and boosters optional; model defaults to "decisionnode"; a field sent as null equals one left out):
{
  "model": "decisionnode",  // or "decisionnode-flash", or the workspace's fine-tuned model "decisionnode-flash@acme/fraud"
  "fallback": true,  // default; when DecisionNode has no ready capacity, DecisionNode Flash answers (body "model" and header x-decisionnode-fallback say so, billed at DecisionNode Flash's price); false = a 529 to retry instead
  "state": "<text>" | { ...json },
  "images": [{ "id": "photo", "media_type": "image/jpeg", "data": "<base64>" }],  // up to 16; or { "id": "photo", "url": "https://..." }
  "boosters": ["age", "ai_generated"],  // optional, up to 4, each once; specialist readings of every image, priced per picture read (`age` (Human Age) $0.024, `ai_generated` (AI-generated) $0.006, `face_detection` (Face detection) $0.001, `face_recognition` (Face recognition) $0.001 on your own collection and $0.001 on `celebrities`, `ocr` (OCR) $0.0015, `bynn_depth` (Depth Vision) free, `bynn_segment` (Segment Vision) $0.001 and `knowledge` (Knowledge) $0.001 a request). An entry may instead be { "name": "ai_generated", "images": ["photo"], "require": true } to narrow the images it reads or to fail the request (529) without it, or with "timeout_ms" (100 up to the booster's ceiling) to set its time budget for the request. The knowledge booster reads your own stored documents instead of images: { "name": "knowledge", "options": { "collection": "<knowledge base id>" } }, $0.001 a request; its passages come back cited in evidence.knowledge (docs: /docs/knowledge)
  "questions": {
    "<key>": { "type": "choice", "instructions": "...",
      "criteria": { "<option>": "<what it means>" } },
    "<key>": { "type": "score", "instructions": "...",
      "criteria": ["<lowest>", "...", "<highest>"] },
    "<key>": { "type": "truth", "instructions": "<a statement to test>" },  // needs instructions or criteria
    "<key>": { "type": "number", "instructions": "<what to count or read>",
      "min": 0, "max": 50 },
    "<key>": { "type": "point", "instructions": "<what to find>" }  // or "box"; needs an image; "image": "<id>" with two or more
  }
}
With two or more images, say in each question which image it is about: by id in backticks (preferred; give images short names such as "receipt", not digits, and an id stays right when images are reordered), or by number from 1 in array order ("image 2", "the second image"). Videos work the same way, numbered separately ("video 1"). The point and box "image" field takes the id, never a number.

Response:
{ "model", "answers": { "<key>": answer },
  "usage": { "input_tokens", "output_tokens": 0,
             "cost": { "usd", "model_usd", "boosters_usd", "free_tier" } } }  // what the answer booked, in USD
With boosters, also "evidence": { "<booster>": { "version", "status": "ok" | "timeout" | "error" | "skipped", "latency_ms", "results": [{ "image": "<id>", ... }] } } (on "timeout" or "error", results list bare { "image" } entries and billed_calls is 0; a picture the booster cannot decode is { "image", "readable": false }, not billed) and usage.booster_tokens and usage.boosters (calls billed). age results: age_years, low, high, confidence, faces. ai_generated results: generated, confidence, method ("inference" | "c2pa": trusted Content Credentials declare it AI-made), top_generator ({ name, probability } only when an inference reading says likely generated, else null), c2pa_signer (for trusted credentials, else null), and c2pa: "untrusted" only when the file's credentials validate but are not trusted (no signer, no override). A booster never answers a question: read the answers, and log evidence with the decision.
- choice: { "choice": "<one of your option keys>", "confidence", "probabilities" }
- score:  { "score": <expected level index>, "confidence", "legend", "probabilities" }
- truth:  { "truth": <probability the statement is true, 0.00 to 1.00> }
- number: { "number": <most probable grid value>, "expected", "confidence", "probabilities" }
- point:  { "x", "y", "present", "confidence", "image", "width", "height" }  // pixels from the top-left corner
- box:    { "x1", "y1", "x2", "y2", "present", "confidence", "image", "width", "height" }
```

## 6. Rules for the code you write

1. Ask every question about one input in one request; the state is read once.
2. Branch on confidence (choice, score), on the truth probability, or on present (point, box: their confidence is not calibrated yet, so never gate on it). Keep the thresholds in config, not inline. Above a threshold act at once; below it take a safe automatic action (hold, decline, or re-check with the full model). Exception: if the decision is about a person in hiring, credit, housing, insurance, education, benefits, law enforcement or healthcare, route it to a qualified human reviewer before it takes effect; if it concerns a vehicle, drone, robot or machine, feed the answer to the system's own controller and never act on it directly.
3. On 429 and 529 wait for retry-after-ms (or Retry-After, in seconds), then retry with exponential backoff and jitter. Every 5xx, a 408 and a client timeout (10 s per attempt) are safe to retry, except a request naming the ocr booster: give it 30 s per attempt and never retry it after a timeout, since the attempt may still be billed. Do not retry 400, 401, 402, 403, 413 or 422; fix the key or the body (the x-decisionnode-error header says what is wrong). A 403 is a safety refusal (error_type "refusal_error", with a "category") or a paused workspace (error_type "workspace_suspended"); neither is billed. A 402 (error_type "insufficient_credit") means the prepaid balance is empty: alert, and send again only after credit is added. Boosters: 400 "booster_unknown" (a name that is not a booster), 400 "booster_input_mismatch" (a booster on a request without images, or an images id not in the request), 400 "api_usage_error" (a malformed boosters array) and 403 "booster_not_enabled" (turned off for the workspace) are fixed in code or the console, never retried; 529 "booster_unavailable" (a required booster failed) is retried like any 529. Sessions take no boosters. A fine-tuned model name that is unknown, not deployed or another workspace's is the 400 "Unknown model: <name>".
4. Pin a version such as "decisionnode-main-0.9.1-rc1" (for a fine-tuned model, "decisionnode-flash@acme/fraud:3") where answers must not change across releases; the response's "model" names the version that answered.
5. Write a test that posts a fixed request and asserts the answer keys and types.
6. Read the response's "model" (the model that answered) and log it with the decision. A DecisionNode request may be answered by DecisionNode Flash when DecisionNode has no ready capacity; send "fallback": false where the decision must come from DecisionNode (a re-check of an unsure DecisionNode Flash answer), and retry its 529. Only live /v1/decide calls for DecisionNode fall back; DecisionNode Flash, fine-tuned models, sessions and batch lines never do, and a fine-tuned model that was idle may answer 529 for a few minutes until it is ready: retry after Retry-After.

## 7. Verify

Make the call in step 5 once, with the key from the environment. Check that:

- the status is `200`;
- `answers.refund.truth` is a number from 0 to 1;
- `usage.cost` is there, with `usd` equal to `model_usd` plus `boosters_usd`, and `free_tier` `false`.

A `401` means the key is missing or wrong. A `402` means the workspace cannot pay; `detail.details.reason` says why (`plan_required`, `trial_allowance_used` or `allowance_used`): tell the user to fix it on the console's Plan or Billing page. For any other status, read the `x-decisionnode-error` header and the body's `detail`.

## 8. Report

Tell the user, one line each, what is set up and what is not: the key (found in the environment, never printed), the SDK (added, with its version, or plain HTTPS), the MCP server (connected, or waiting on a reload), and the verify call (its status and `usage.cost.usd`). Mark nothing done that you could not check.
