Decisions API

Use the Decisions API for fast, structured judgments rather than generated text. It evaluates a state and optional images, then returns typed answers and probabilities your code can use directly.

subq-snap-preview is a System One model built for routing, guardrails, triage, and other fast decisions.

POST /v1/systemone

Request

The JSON body requires:

model — use subq-snap-preview.
state — the text, object, or array to evaluate.
questions — one or more named noul, choice, or score questions. Each uses instructions and type-specific criteria, which can contain strings, objects, or arrays. Answer keys match the question names.

Optional:

images — up to 4 images to evaluate alongside state. See Images.

Noul

A noul is a yes/no gate. Its answer is noul, the probability of yes from 0 to 1. Optional criteria.true and criteria.false describe both outcomes.

Choice

A choice selects one named option. Define up to 255 options in criteria; each option's description may be null. The answer includes choice, a probability for every option, and confidence.

Score

A score uses 2–10 ordered levels. The answer includes a probability-weighted score, so it can fall between levels, plus legend, probabilities, and confidence.

Images

{
  "images": [
    { "mediaType": "image/jpeg", "base64": "/9j/4AAQSkZJRgABAQAA..." }
  ]
}

mediaType — image/png, image/jpeg, or image/webp.
base64 — the file bytes as one line of base64, without a data: prefix. URLs, data: URLs, and bare base64 strings fail the request.
Send up to 4 images. Each image can be up to 4 MiB decoded, with an 8 MiB decoded total.
Each image uses about 64–256 image tokens, not the base64 text. These tokens and the request text count toward the model's context window. The request body can be up to 13 MiB.
Video is not supported. Sample up to 4 frames and send them as images.

import { readFileSync } from "node:fs";

const baseURL = "https://api.subq.ai/v1";

// The ticket note. The photo carries the rest: which device, and what shape it is.
const state = "The number row stopped working.";

// Plain base64 of the file bytes. No data: URL prefix.
// PNG, JPEG, or WebP, at most 4 MiB decoded per image.
const photo = readFileSync("./keyboard.jpg").toString("base64");

// One question per judgment. Every question sees the note and every image.
const questions = {
  shows_keyboard: {
    type: "noul",
    instructions: "Does the photo show a keyboard?",
    criteria: {
      true: "A keyboard is the main object",
      false: "No keyboard is visible",
    },
  },
  layout: {
    type: "choice",
    instructions: "Which keyboard layout is in the photo?",
    criteria: {
      full_size: "Desktop keyboard with a numeric keypad",
      tenkeyless: "Desktop keyboard with no numeric keypad",
      laptop: "Built into a laptop",
      not_a_keyboard: null,
    },
  },
  wear: {
    type: "score",
    instructions: "How worn does the keyboard look?",
    criteria: ["Looks new", "Everyday wear", "Replace it"],
  },
};

const response = await fetch(`${baseURL}/systemone`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUBQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "subq-snap-preview",
    state,
    images: [{ mediaType: "image/jpeg", base64: photo }],
    questions,
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(
    `${response.status} ${error.detail.error_type}: ${error.detail.message}`,
  );
}

const result = await response.json();
const { shows_keyboard, layout, wear } = result.answers;

// A photo that is not a keyboard, or an unsure layout, goes back to the employee.
if (
  shows_keyboard.noul < 0.5 ||
  layout.confidence < 0.6 ||
  layout.choice === "not_a_keyboard"
) {
  console.log("Ask for a clearer photo of the keyboard.");
} else {
  const condition = wear.legend[String(Math.round(wear.score))];
  console.log(`Keyboard: ${layout.choice} (${condition})`);
}

TypeScriptPython

An invalid image fails with 422 validation_error. A file over 4 MiB:

{
  "detail": {
    "error_type": "validation_error",
    "message": "images/0: image must not exceed 4 MiB decoded."
  }
}

Bytes that do not match mediaType fail the same way: images/0: image bytes must match the PNG, JPEG, or WebP mediaType. The same status covers a URL or data: prefix, a bad decode, more than 4 images, or more than 8 MiB decoded in total.

Stored decisions include their images and follow your data-retention policy.

Response

{
  "model": "subq-snap-preview",
  "answers": {
    "escalate": {
      "type": "noul",
      "noul": 0.92
    },
    "queue": {
      "type": "choice",
      "choice": "nurse_line",
      "probabilities": {
        "nurse_line": 1,
        "primary_care": 0,
        "pharmacy": 0,
        "front_desk": 0
      },
      "confidence": 1
    },
    "acuity": {
      "type": "score",
      "score": 1.86,
      "legend": {
        "0": "Within a week",
        "1": "Within a day",
        "2": "Within an hour"
      },
      "probabilities": {
        "0": 0,
        "1": 0.13,
        "2": 0.87
      },
      "confidence": 0.79
    }
  },
  "usage": {
    "input_tokens": 477,
    "output_tokens": 88
  }
}

usage reports the tokens billed for the request.

Errors

Errors use a detail object:

{
  "detail": {
    "error_type": "validation_error",
    "message": "questions/queue: must have required property 'criteria'"
  }
}

401 — missing or invalid credentials.
402 — insufficient credits.
403 — the API key cannot use the requested model.
422 — invalid request (including an invalid or oversized image) or a model that is not a decision model.
429 — rate limit exceeded.
503 — service temporarily unavailable.

To extract fields rather than make a decision, use Structured outputs.