POST /v1/systemone

The same decisions in the System One request format: a state and noul, choice, score or box questions in, typed answers out. For clients and benchmark harnesses written for that format, which run against DecisionNode as they are.

POSThttps://api.decisionnode.com/v1/systemone

curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": "Customer: I was charged twice for my October invoice and nobody has replied for 3 days.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "payments, invoices and refunds",
          "technical": "bugs and outages",
          "sales": "plans and upgrades"
        }
      }
    }
  }'

Clients, evaluation harnesses and benchmark runners written for the System One request format work here without changing their requests. Point them at https://api.decisionnode.com/v1https://api.decisionnode.com/v1, give them a DecisionNode key, and set the model to decisionnode or decisionnode-flash.

It answers from the same models as /v1/decide, at the same prices. New code should use /v1/decide: it also takes truth and number questions, boosters, uploads and videos, and it is the route the SDKs call.

Headers#

Authorizationstringrequired: Bearer dn_live_..., a key that may make decisions, kept on your server in an environment variable such as DECISIONNODE_API_KEY. A request is admitted as on /v1/decide: balance, free tier, suspension and rate limits.
Content-Typestring: application/json.

Headers this page does not list are ignored, so a client that sends its own headers for images or for long inputs works unchanged.

Request body#

modelstringrequired

decisionnode or decisionnode-flash, or a pinned version such as decisionnode-flash-0.9.1-rc1. Required on this route: a body without it is a 400. A fine-tuned model is not taken here; call it on /v1/decide.

statestring | object | array

The input to decide about: text, a JSON object or a JSON array, read once and shared by every question. An array made only of text and image_url parts is read as its text, the parts joined by a line break, with each image in its place.

questionsobjectrequired

Your question ids mapped to questions, at least one. Answers come back under the same ids.

type"noul" | "choice" | "score" | "box"required: The answer's shape. truth and number are a 400 Invalid request. here; ask them on /v1/decide.
instructionsstring | object | array: What to decide, in one sentence. A noul question needs instructions or criteria; a box question needs instructions.
criteriaobject | array: Choice: option name to description, 1 to 255 options. Score: the levels, lowest first, 2 to 10, echoed in legend as sent. Noul: optional, {"true": "...", "false": "..."}, what yes and what no mean.

assetsobject

Images by reference: your reference string mapped to an image. Write the reference wherever a string goes in the state, the instructions or the criteria, and the model reads the image in its place. See Images.

type"image"required: The only type taken.
data_base64stringrequired: The image's bytes in base64. A data: prefix and line breaks are dropped.
format"png" | "jpg" | "jpeg": Checked when sent. The format is read from the bytes: PNG, JPEG and WebP are taken.

imagesarray

Images as data:image/...;base64, URL strings, read in order and seen by every question.

Question types#

What each type asks and answers
Type	Asks	Answers
`noul`	A yes or no question	`noul`, the probability of yes, from 0.00 to 1.00
`choice`	One option from `criteria`	`choice`, `confidence` and `probabilities`, one per option, alphabetical by option
`score`	A level on the scale in `criteria`	`score` (the expected level, counted from 0), `confidence`, `legend` and `probabilities`, one per level
`box`	Where something is in an image	`box` with `top`, `bottom`, `left` and `right`, and `confidence`

The probabilities of a choice or a score sum to exactly 1 on this route, each to 2 decimals.

Noul#

curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": "Customer: I was charged twice for my October invoice and nobody has replied for 3 days.",
    "questions": {
      "refund": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      }
    }
  }'

Choice#

The request at the top of this page: a ticket routed to one of three teams.

Score#

curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": "Customer: I was charged twice for my October invoice and nobody has replied for 3 days.",
    "questions": {
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["routine", "today", "urgent", "critical"]
      }
    }
  }'

Box#

IMAGE=$(base64 < dock.png | tr -d '\n')
curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": { "photo": "dock.png" },
    "assets": {
      "dock.png": {
        "type": "image",
        "format": "png",
        "data_base64": "'"$IMAGE"'"
      }
    },
    "questions": {
      "parcel": {
        "type": "box",
        "instructions": "Draw a box around the red rectangle in `photo`."
      }
    }
  }'

The edges are fractions of the image's height (top, bottom) and width (left, right), from 0 to 1, to 4 decimals. confidence is the probability that the box is right: that it overlaps the true box by an intersection over union of 0.5 or more.

With several images, name the one to search by its place in the state, in backticks, as the example does with photo. Without such a name, the box searches the first image in the state.

Images#

Up to 16 images a request, in any of three forms: a top-level assets map (the box example above), image_url content parts anywhere a string goes, or data-URL strings in images. Every question sees every image, and an image named twice is read once.

References. A reference is found as a whole string value or inside a longer string, in the state, the instructions and the criteria values, never in an object key. Every asset must be referenced at least once. A reference is at most 1,024 bytes, and all of a request's references at most 65,536 bytes together.
Content parts. {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}, or "image_url" as the URL string itself, is the image in its place. The URL is a base64 data: URL of a PNG, JPEG or WebP image.
Size. Each image as on /v1/decide: up to 10 MB, resized to fit the model. The whole body is at most 25 MiB.
Not taken: multipart bodies. Send each image base64-encoded in data_base64.

An image as a content part

IMAGE=$(base64 < dock.png | tr -d '\n')
curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": [
      { "type": "text", "text": "Photo from the loading dock:" },
      {
        "type": "image_url",
        "image_url": { "url": "data:image/png;base64,'"$IMAGE"'" }
      }
    ],
    "questions": {
      "red": {
        "type": "noul",
        "instructions": "Is there a red rectangle in the photo?"
      }
    }
  }'

Images as data URLs

IMAGE=$(base64 < dock.png | tr -d '\n')
curl https://api.decisionnode.com/v1/systemone \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "decisionnode-flash",
    "state": "Photo from the loading dock.",
    "images": ["data:image/png;base64,'"$IMAGE"'"],
    "questions": {
      "colour": {
        "type": "choice",
        "instructions": "What colour is the rectangle in the picture?",
        "criteria": { "red": "red", "green": "green", "blue": "blue" }
      }
    }
  }'

Response body#

modelstring: The pinned version that answered, such as decisionnode-flash-0.9.1-rc1, also in the x-decisionnode-model header.
answersobject: One answer per question id, each with its type and the fields in Question types.
usageobject: input_tokens billed for the request, images included, output_tokens, always 0, and cost, what it booked, as on every answer.

The answer carries x-request-id and x-decisionnode-request-id, x-decisionnode-model, x-decisionnode-latency-ms, x-decisionnode-image-tokens when a request has images, x-decisionnode-safety and Server-Timing. A refusal carries x-decisionnode-error, which says what was wrong.

Errors#

In the body every route uses, a detail with an error_type and a message. A question type this route does not take:

400

{
  "detail": {
    "error_type": "api_usage_error",
    "message": "Invalid request."
  }
}

Errors this route returns
Status	error_type	When
`400`	`api_usage_error`	"Invalid request." for a question type this route does not take, such as `truth` or `number`; `x-decisionnode-error` names the question and its type
`400`	`api_usage_error`	The body names no `model`
`400`	`api_usage_error`	"Unknown model: <name>" for a name the API does not serve, or a fine-tuned model
`400`	`api_usage_error`	An asset that is wrong, such as "Asset 'dock.png': it is not referenced in the state, the instructions or the criteria." The message names the asset and the fault: no `data_base64`, a `format` other than `png`, `jpg` or `jpeg`, data that is not an image, or a `part` asset
`400`	`api_usage_error`	An empty reference, an `image_url` part that is not a base64 data URL of a PNG, JPEG or WebP image, or more images than the limit: "Too many images: <n>, the limit is 16."
`400`	`max_tokens_exceeded`	The request does not fit the model's maximum context length or its work limit; the message gives the limit and the count
`400`	none, a plain `detail`	"Too many choices. Must have at most 255 choices (255 options per choice)." or "Too many score levels. Must have at most 10 levels (a score takes 2 to 10 levels; one level is answered without the model)."
`401`	`authentication_error`	No key, or a key that is unknown, expired or revoked
`402`, `403`	As on `/v1/decide`: out of credit, refused by the safety check, or a suspended workspace. See Errors
`413`	`request_too_large_error`	The body is over 25 MiB, an asset reference is over 1,024 bytes, or a request's references are over 65,536 bytes together
`422`	a list of fields	`assets` is not an object or is empty, an asset's `type` is not `image`, or the body is not JSON
`429`	`rate_limit_error`	Over your workspace's rate limit; wait `Retry-After`, then retry
`529`	`overloaded_error`	No ready capacity for the model right now; wait `Retry-After`, then retry