Quickstart
Your first typed decision
The following examples show the contract shape. These templates require an authorized API key; sign in with Google, create a key in the dashboard and your first 100M input tokens are free.
Illustrative example
Set SYSTEM1_API_KEY to a key from your dashboard. Never put a real API key in source control or a browser bundle.
01 / Request and response
Click through the sample decisions
Each request contains exactly one typed question. Choose a sample to see its request body and the shape of its response.
Request · POST /v1/systemone
{
"model": "s1-fast",
"state": "Mia owns a red bicycle.",
"questions": {
"color": {
"type": "choice",
"instructions": "Which color is the bicycle?",
"criteria": {"red": null, "blue": null}
}
}
}Response · illustrative
{
"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"
}Request · POST /v1/systemone
{"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}}}}Response · illustrative
{"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"}Request · POST /v1/systemone
{"model":"s1-fast","state":{"action":"delete_workspace","actor_role":"viewer"},"questions":{"allowed":{"type":"noul","instructions":"Is this action allowed under the stated role policy?"}}}Response · illustrative
{"id":"dec_guard","model":"s1-fast","answers":{"allowed":{"type":"noul","noul":0.04}},"usage":{"input_tokens":298,"output_tokens":0,"decisions":1},"tier":"eu"}Request · POST /v1/systemone
{"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"]}}}Response · illustrative
{"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 · illustrative
curl https://api.system1models.ai/v1/systemone \
-H "Authorization: Bearer $SYSTEM1_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} } }}'Python · illustrative
import os
import requests
response = requests.post(
"https://api.system1models.ai/v1/systemone",
headers={
"Authorization": f"Bearer {os.environ['SYSTEM1_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())JavaScript · illustrative
const response = await fetch("https://api.system1models.ai/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.SYSTEM1_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);TypeScript · illustrative
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.system1models.ai/v1/systemone", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.SYSTEM1_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);Rust · illustrative
// 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.system1models.ai/v1/systemone")
.bearer_auth(std::env::var("SYSTEM1_API_KEY").expect("SYSTEM1_API_KEY"))
.header("S1-Region", "eu")
.json(&body)
.send().await?;
println!("{}", response.text().await?);
Ok(())
}C# · illustrative
using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
"Bearer " + Environment.GetEnvironmentVariable("SYSTEM1_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.system1models.ai/v1/systemone", body);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());Java · illustrative
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class System1Quickstart {
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.system1models.ai/v1/systemone"))
.header("Authorization", "Bearer " + System.getenv("SYSTEM1_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());
}
}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.