Quickstart
Your first typed decision
The following examples show the contract shape. These templates require an authorized API key; sign in with an email link or Google, create a key in the dashboard and redeem an invite code or top up from EUR 1.
New EUR accounts: your first API key comes with a one-time EUR 0.50 credit (verified e-mail, limited to 36 credits per 7 days, valid 30 days, not combined with other credits; Terms 5.3(e)). At today's list price that is several million input tokens on s1-pro.
Set DECISIONMODELS_API_KEY to a key from your dashboard. Never put a real API key in source control or a browser bundle.
Set the key in your shell first; every curl example below reads it:
export DECISIONMODELS_API_KEY="paste-your-key-here"Text bundles
Ask up to three questions about one state
s1-pro and reax-1 accept up to three named text questions in the same questions map. Shared text is billed once; each question adds prompt tokens. The model tokenizer determines the billed total, capped at the model’s input limit (8,192 to 28,672 tokens for each question, including its state, depending on the model; see the limits table). Each question is evaluated separately; bundling does not promise a speedup.
s1-fast and s1-vision accept one question. A bundle can return a retryable 503 model_unavailable or capacity_limit when capacity is busy. EU requests have priority. Reusing an idempotency key returns the original usage receipt without another charge; original answers are not kept in the usage database.
01 / Request and response
Click through the sample decisions
These samples each contain one typed question. s1-pro and reax-1 support up to three; s1-fast and s1-vision support one. Choose a sample to see its request body and the shape of its response.
{
"model": "s1-fast",
"state": "Mia owns a red bicycle.",
"questions": {
"color": {
"type": "choice",
"instructions": "Which color is the bicycle?",
"criteria": {"red": null, "blue": null}
}
}
}{
"id": "dec_example",
"model": "s1-fast",
"answers": {
"color": { "type": "choice", "choice": "red", "confidence": 0.91,
"probabilities": { "red": 0.91, "blue": 0.09 } }
},
"usage": { "input_tokens": 328, "output_tokens": 0, "decisions": 1 },
"tier": "eu"
}{"model":"s1-fast","state":{"message":"I need to update my invoice address.","account_type":"business"},"questions":{"route":{"type":"choice","instructions":"Choose the support queue that best fits the request.","criteria":{"billing":null,"technical":null,"account":null}}}}{"id":"dec_route","model":"s1-fast","answers":{"route":{"type":"choice","choice":"billing","confidence":0.87,"probabilities":{"billing":0.87,"technical":0.09,"account":0.04}}},"usage":{"input_tokens":351,"output_tokens":0,"decisions":1},"tier":"eu"}{"model":"s1-fast","state":{"action":"delete_workspace","actor_role":"viewer"},"questions":{"allowed":{"type":"noul","instructions":"Is this action allowed under the stated role policy?"}}}{"id":"dec_guard","model":"s1-fast","answers":{"allowed":{"type":"noul","noul":0.04}},"usage":{"input_tokens":298,"output_tokens":0,"decisions":1},"tier":"eu"}{"model":"s1-pro","state":{"draft":"Short release note draft","rubric":"Clarity and factual support"},"questions":{"quality":{"type":"score","instructions":"Rate the draft against the rubric.","criteria":["low","medium","high"]}}}{"id":"dec_score","model":"s1-pro","answers":{"quality":{"type":"score","score":1.57,"confidence":0.71,"legend":{"0":"low","1":"medium","2":"high"},"probabilities":{"0":0.05,"1":0.33,"2":0.62}}},"usage":{"input_tokens":512,"output_tokens":0,"decisions":1},"tier":"eu"}02 / Call it from your stack
Copyable examples in seven languages
Every sample sends the same request: one choice question against s1-fast on the EU tier. Keep the key in an environment variable.
curl https://api.decisionmodels.io/v1/systemone \
-H "Authorization: Bearer $DECISIONMODELS_API_KEY" \
-H "Content-Type: application/json" \
-H "S1-Region: eu" \
-d '{ "model": "s1-fast", "state": "Mia owns a red bicycle.", "questions": { "color": { "type": "choice", "instructions": "Which color is the bicycle?", "criteria": {"red": null, "blue": null} } }}'import os
import requests
response = requests.post(
"https://api.decisionmodels.io/v1/systemone",
headers={
"Authorization": f"Bearer {os.environ['DECISIONMODELS_API_KEY']}",
"Content-Type": "application/json",
"S1-Region": "eu",
},
json={
"model": "s1-fast",
"state": "Mia owns a red bicycle.",
"questions": {
"color": {
"type": "choice",
"instructions": "Which color is the bicycle?",
"criteria": {"red": None, "blue": None},
}
},
},
timeout=30,
)
print(response.json())const response = await fetch("https://api.decisionmodels.io/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
"Content-Type": "application/json",
"S1-Region": "eu",
},
body: JSON.stringify({
model: "s1-fast",
state: "Mia owns a red bicycle.",
questions: {
color: { type: "choice", instructions: "Which color is the bicycle?",
criteria: { red: null, blue: null } },
},
}),
});
if (!response.ok) throw new Error("HTTP " + response.status);
const result = await response.json();
console.log(result.answers.color);type DecisionAnswer = {
type: "noul" | "choice" | "score";
choice?: string;
noul?: number;
score?: number;
confidence?: number;
legend?: Record<string, string>;
probabilities?: Record<string, number>;
};
type DecisionResponse = {
id: string;
model: string;
answers: Record<string, DecisionAnswer>;
usage: { input_tokens: number; output_tokens: number; decisions: number };
tier: "eu" | "global";
};
const response = await fetch("https://api.decisionmodels.io/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
"Content-Type": "application/json",
"S1-Region": "eu",
},
body: JSON.stringify({
model: "s1-fast",
state: "Mia owns a red bicycle.",
questions: {
color: { type: "choice", instructions: "Which color is the bicycle?",
criteria: { red: null, blue: null } },
},
}),
});
if (!response.ok) throw new Error("HTTP " + response.status);
const result = (await response.json()) as DecisionResponse;
console.log(result.answers.color);// cargo add reqwest --features json
// cargo add tokio --features full
// cargo add serde_json
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = reqwest::Client::new();
let body = serde_json::json!({
"model": "s1-fast",
"state": "Mia owns a red bicycle.",
"questions": {
"color": { "type": "choice",
"instructions": "Which color is the bicycle?",
"criteria": { "red": null, "blue": null } }
}
});
let response = client
.post("https://api.decisionmodels.io/v1/systemone")
.bearer_auth(std::env::var("DECISIONMODELS_API_KEY").expect("DECISIONMODELS_API_KEY"))
.header("S1-Region", "eu")
.json(&body)
.send().await?;
println!("{}", response.text().await?);
Ok(())
}using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
"Bearer " + Environment.GetEnvironmentVariable("DECISIONMODELS_API_KEY"));
client.DefaultRequestHeaders.Add("S1-Region", "eu");
var body = new {
model = "s1-fast",
state = "Mia owns a red bicycle.",
questions = new {
color = new { type = "choice",
instructions = "Which color is the bicycle?",
criteria = new { red = (string?)null, blue = (string?)null } }
}
};
var response = await client.PostAsJsonAsync(
"https://api.decisionmodels.io/v1/systemone", body);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class DecisionModelsQuickstart {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
String body = """
{"model":"s1-fast","state":"Mia owns a red bicycle.",
"questions":{"color":{"type":"choice",
"instructions":"Which color is the bicycle?",
"criteria":{"red":null,"blue":null}}}}""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.decisionmodels.io/v1/systemone"))
.header("Authorization", "Bearer " + System.getenv("DECISIONMODELS_API_KEY"))
.header("Content-Type", "application/json")
.header("S1-Region", "eu")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
System.out.println(client.send(request,
HttpResponse.BodyHandlers.ofString()).body());
}
}No credit yet? The API answers 402 insufficient_credit with a link to top up from EUR 1.
Responses are illustrative contract shapes, not measured model output. Usage receipts carry the actual input-token count and, when billing is enabled, the exact integer nanos charge.
03 / Image decision
Decide about one image with s1-vision
Send exactly one PNG, JPEG or WebP image as a base64 data URL or a public HTTPS URL (at most 4 MiB decoded, 2,000,000 pixels) with model s1-vision, a state and one question. The image counts as the input tokens the model actually reads (typically ~300–450). A request that contains an image is billed at the s1-vision image rate for all its input tokens (text and image positions); text-only s1-vision requests use the s1-vision text rate. An HTTPS URL is fetched once by the gateway and not written to its logs or usage database.
IMG=$(base64 -w0 photo.jpg)
curl https://api.decisionmodels.io/v1/multimodal \
-H "Authorization: Bearer $DECISIONMODELS_API_KEY" \
-H "Content-Type: application/json" \
-H "S1-Region: eu" \
-d '{
"model": "s1-vision",
"state": "Customer return request: item arrived damaged.",
"questions": {
"damage": {
"type": "choice",
"instructions": "What does the photo show?",
"criteria": {"visible_damage": null, "no_damage": null, "not_the_product": null}
}
},
"images": ["data:image/jpeg;base64,'"$IMG"'"]
}'import base64, os, requests
with open("photo.jpg", "rb") as f:
image = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()
response = requests.post(
"https://api.decisionmodels.io/v1/multimodal",
headers={
"Authorization": f"Bearer {os.environ['DECISIONMODELS_API_KEY']}",
"S1-Region": "eu",
},
json={
"model": "s1-vision",
"state": "Customer return request: item arrived damaged.",
"questions": {
"damage": {
"type": "choice",
"instructions": "What does the photo show?",
"criteria": {"visible_damage": None, "no_damage": None, "not_the_product": None},
}
},
"images": [image],
},
timeout=30,
)
response.raise_for_status()
print(response.json()["answers"]["damage"])import { readFile } from "node:fs/promises";
const image = "data:image/jpeg;base64," + (await readFile("photo.jpg")).toString("base64");
const response = await fetch("https://api.decisionmodels.io/v1/multimodal", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
"Content-Type": "application/json",
"S1-Region": "eu",
},
body: JSON.stringify({
model: "s1-vision",
state: "Customer return request: item arrived damaged.",
questions: {
damage: {
type: "choice",
instructions: "What does the photo show?",
criteria: { visible_damage: null, no_damage: null, not_the_product: null },
},
},
images: [image],
}),
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log((await response.json()).answers.damage);https://api.system1models.ai keeps working.