Skip to content
DecisionNodeDecisionNdedocs
  • Guides
  • API reference
  • Examples
  • Playground

start here

  • QuickstartGet startedGet an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, no SDK to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state and optional images. One request, one buffered JSON response, one answer per question.
  • QuestionsConceptsQuestions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a…
  • ConfidenceConceptsProbabilities are calibrated per question type, so a threshold means what it says.
  • ImagesConceptsSend images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and answers…
  • Pricing and billingYou pay for input tokens only. Output is free because the model generates no text.
↑↓ moveopen6 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • With coding agents
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Images
  • Confidence
  • Determinism

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loopscomingcoming soon

API reference

  • POST/v1/decide
  • POST/v1/sessionscomingcoming soon
  • GET/v1/models
  • Errors
  • Rate limits

Pricing and billing

  • Pricing and billing

Policies

  • Responsible use

Migrate

  • Coming from a Jev-shaped API
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • With coding agents
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Images
  • Confidence
  • Determinism

Models

  • DecisionNode-1.0
  • DecisionNode-1.0 Flash
  • Limits

Patterns

  • Confidence-gated routing
  • Fan-out
  • Guardrails
  • Control loopscomingcoming soon

API reference

  • POST/v1/decide
  • POST/v1/sessionscomingcoming soon
  • GET/v1/models
  • Errors
  • Rate limits

Pricing and billing

  • Pricing and billing

Policies

  • Responsible use

Migrate

  • Coming from a Jev-shaped API
  1. docs
  2. /
  3. Get started

With coding agents

DecisionNode is one HTTPS call, so a coding agent can write the integration for you once it knows the shape. Paste the prompt below, or give your own agents a decide tool.

on this page3 sections
  1. A prompt for your coding agent
  2. Give your agents a decide tool
  3. Ask before you act

A prompt for your coding agent#

Paste this into the agent that works in your repository, then tell it what to decide: "route new tickets in support/inbox.ts with DecisionNode". It carries the endpoint, the request and response shapes and the rules that keep the integration honest.

Agent prompt
You are adding DecisionNode to this codebase. DecisionNode is a decision API: it reads a state (text, JSON or images) and answers typed questions with calibrated probabilities. It never generates text.Endpoint: POST https://api.decisionnode.com/v1/decideAuth: header "Authorization: Bearer <key>", key read from the DECISIONNODE_API_KEY environment variable on the server. Never ship the key to a browser or log it.Request body (model and questions required, state and images optional):{  "model": "decisionnode-latest",  // or "decisionnode-flash-latest"  "state": "<text>" | { ...json },  "images": [{ "id": "photo", "media_type": "image/jpeg", "data": "<base64>" }],  "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>" },    "<key>": { "type": "number", "instructions": "<what to count or read>",      "min": 0, "max": 50 }  }}Response:{ "model", "answers": { "<key>": answer },  "usage": { "input_tokens", "output_tokens": 0 } }- 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" }Rules for the integration:1. Ask every question about one input in one request; the state is read once.2. Branch on confidence (choice, score) or on the truth probability. 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).3. On 429 wait for the Retry-After header, on 529 retry with exponential backoff and jitter. Do not retry 401, 403 or 422; fix the key or the body.4. Pin a version such as "decisionnode-1.0" where answers must not change across releases.5. Write a test that posts a fixed request and asserts the answer keys and types.

Keep it in the repository

Save the prompt next to your code, for example in the agent instructions file your tools read, so every session starts with the same contract. An agent that can fetch URLs gets the same contract, the key facts and a map of these docs from decisionnode.com/llms.txt; the whole documentation as Markdown is at /llms-full.txt.

Give your agents a decide tool#

Agents act on judgments: is this email a refund request, is this command safe to run, does this reply answer the question. Expose DecisionNode as a tool and the agent gets a typed, calibrated answer instead of its own guess. Most agent runtimes accept a tool described with JSON Schema, like this one.

Tool definition
{
  "name": "decide",
  "description": "Ask DecisionNode a typed question about some input. Returns a choice, a score or the probability that a statement is true, all calibrated. Use it before acting on a judgment.",
  "input_schema": {
    "type": "object",
    "properties": {
      "state": {
        "type": "string",
        "description": "The text or JSON to decide about"
      },
      "question": {
        "type": "string",
        "description": "What to decide, in one sentence"
      },
      "type": {
        "type": "string",
        "enum": ["choice", "score", "truth"]
      },
      "options": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Options for choice, levels low to high for score"
      }
    },
    "required": ["state", "question", "type"]
  }
}
Tool handler
type DecideInput = {
  state: string;
  question: string;
  type: "choice" | "score" | "truth";
  options?: string[];
};

export async function decide(input: DecideInput, apiKey: string) {
  const criteria =
    input.type === "choice"
      ? Object.fromEntries((input.options ?? []).map((o) => [o, o]))
      : input.type === "score"
        ? input.options
        : undefined;

  const response = await fetch("https://api.decisionnode.com/v1/decide", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "decisionnode-flash-latest",
      state: input.state,
      questions: { answer: { type: input.type, instructions: input.question, criteria } },
    }),
  });
  if (!response.ok) throw new Error(`decide failed: ${response.status}`);
  const { answers } = await response.json();
  return answers.answer; // the typed answer goes back to the agent as the tool result
}

Ask before you act#

The most useful place for the tool is right before an agent does something it cannot undo. Pass the proposed action as the state and ask a Truth question; run it only when the probability clears your bar. Guardrails has the full recipe.

previousQuickstartnextExamples

DecisionNode is built and run by Bynn Intelligence, Inc.

  • Home
  • Playground
  • Examples
  • Console
  • Responsible use
  • Terms
  • Acceptable use
  • Privacy
  • Data processing
  • Defence addendum
  • Cookies

on this page

  1. A prompt for your coding agent
  2. Give your agents a decide tool
  3. Ask before you act