System One Decisions

System One is a decision model. You send your application’s current state and a set of questions, and it answers each one with a typed result you can check in code, such as a choice with a probability for every option. Use it when your application has to make a decision, for example routing, triage, moderation or picking the next step in a workflow, and you would otherwise have to parse free text.

Prerequisites

A Gloo AI Studio account
Your API key from the API Credentials page
Authentication setup - Complete the Authentication Tutorial first

Quick start

URL: https://platform.ai.gloo.com/xds/v2/sys1 Operation: POST

curl -X POST 'https://platform.ai.gloo.com/xds/v2/sys1' \
  -H "Authorization: Bearer ${GLOO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "state": {
      "ticket": "I was charged twice for my subscription this month.",
      "customer_tier": "pro"
    },
    "questions": {
      "category": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
          "billing": "Payments, invoices, refunds, or charges.",
          "technical": "Bugs, errors, or how the product works.",
          "account": "Login, profile, or account settings."
        }
      },
      "wants_refund": {
        "type": "noul",
        "instructions": "The customer is asking for their money back."
      }
    }
  }'

import os, requests

resp = requests.post(
    "https://platform.ai.gloo.com/xds/v2/sys1",
    headers={"Authorization": f"Bearer {os.environ['GLOO_API_KEY']}"},
    json={
        "state": {
            "ticket": "I was charged twice for my subscription this month.",
            "customer_tier": "pro",
        },
        "questions": {
            "category": {
                "type": "choice",
                "instructions": "Which team should handle this ticket?",
                "criteria": {
                    "billing": "Payments, invoices, refunds, or charges.",
                    "technical": "Bugs, errors, or how the product works.",
                    "account": "Login, profile, or account settings.",
                },
            },
            "wants_refund": {
                "type": "noul",
                "instructions": "The customer is asking for their money back.",
            },
        },
    },
    timeout=30,
)
resp.raise_for_status()
answers = resp.json()["answers"]
print(answers["category"]["choice"], answers["wants_refund"]["noul"])

const resp = await fetch("https://platform.ai.gloo.com/xds/v2/sys1", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GLOO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    state: {
      ticket: "I was charged twice for my subscription this month.",
      customer_tier: "pro",
    },
    questions: {
      category: {
        type: "choice",
        instructions: "Which team should handle this ticket?",
        criteria: {
          billing: "Payments, invoices, refunds, or charges.",
          technical: "Bugs, errors, or how the product works.",
          account: "Login, profile, or account settings.",
        },
      },
      wants_refund: {
        type: "noul",
        instructions: "The customer is asking for their money back.",
      },
    },
  }),
});
if (!resp.ok) {
  throw new Error(`System One returned ${resp.status}: ${await resp.text()}`);
}
const { answers } = await resp.json();
console.log(answers.category.choice, answers.wants_refund.noul);

Example response

{
  "id": "gen-dec-1793981370-uOwFt34AIeyibLNhYu26",
  "model": "typesafe/jev-1.13-20260917",
  "provider": "TypeSafe",
  "answers": {
    "category": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1,
      "probabilities": { "account": 0, "billing": 1, "technical": 0 }
    },
    "wants_refund": { "type": "noul", "noul": 0.66 }
  },
  "usage": { "input_tokens": 386, "output_tokens": 58 }
}

Question types

Type	Ask it when	`criteria`	Answer
`choice`	One of several options applies.	Required. Maps each option key to a description of when to pick it.	`choice`, `confidence` and `probabilities`
`noul`	A statement is either true or false of the state.	Optional.	`noul`, the probability from 0 to 1 that the statement is true

Writing questions

Give each question a key that is unique in questions. The key appears again in answers.
Write instructions as the question for a choice, and as a statement that is true or false for a noul.
Write choice criteria that do not overlap, and add a fallback option such as "other" or "none" so the model does not have to force a choice.
Put everything the model needs in state. It can be a string, or a JSON object or array of related context. A structured object keeps separate facts separate.
Act on the numbers rather than on the top answer alone. For example, act automatically only above 0.9 and send anything lower to a person. Identical requests can return slightly different probabilities.

Request parameters

Field	Type	Required	Description
`state`	string, object or array	Yes	The content System One reads to answer the questions.
`questions`	object	Yes	Map of question key to question object.
`questions.<key>.type`	string	Yes	`choice` or `noul`.
`questions.<key>.instructions`	string	Yes	The question or statement to evaluate.
`questions.<key>.criteria`	object	For `choice`	Map of option key to a description of when to pick it.
`session_id`	string	No	Your session identifier, for correlation. Up to 256 characters.
`user`	string	No	Your end-user reference.
`trace`	object	No	Your trace data.

The service drops any other top-level field, including assets, so images are not accepted. You cannot select the model: Gloo AI chooses it, ignores any model you send, and returns the version that answered in the response.

Response fields

Field	Type	Description
`id`	string	The identifier of this decision.
`model`	string	The versioned model that answered.
`provider`	string	The provider that served the model.
`answers`	object	One entry for each key in your `questions`.
`answers.<key>.type`	string	The question type.
`answers.<key>.choice`	string	`choice` only. The option key the model picked.
`answers.<key>.probabilities`	object	`choice` only. Option key to probability.
`answers.<key>.confidence`	number	`choice` only. The model’s confidence in its choice. This is a separate value from the chosen option’s probability.
`answers.<key>.noul`	number	`noul` only. The probability that the statement is true.
`usage.input_tokens`	integer	Input tokens.
`usage.output_tokens`	integer	Output tokens.

Responses are JSON, not a stream.

Data retention

System One requests are always sent with zero data retention required. You do not need to set anything, and no request field can turn it off.

Pricing

System One is billed to your organization per token at the provider’s list rate, with no markup. For the current model, TypeSafe Jev 1.13, that is $0.042 per million input tokens with no charge for output tokens. The cost is not returned in usage.

Errors

Use the HTTP status to decide what to do. When Gloo refuses a request, the body looks like this:

{
  "error": {
    "message": "state is required",
    "type": "invalid_request_error",
    "code": 1001,
    "fault": "client",
    "retryable": false
  }
}

Missing or invalid credentials and errors from the provider use other shapes, so do not rely on these fields being present.

Status	Cause	Retry?
`400`	The body is not a single JSON object, `state` is missing, `questions` is not an object, or the provider rejected a question.	No. Fix the request.
`401`	The API key is missing or not valid.	No.
`402`	Your organization is out of credit.	Not until you add credit.
`403`	The provider refused the content of the request, or your organization has no active billing account.	No.
`413`	The request body is larger than 32 MB.	No. Reduce the size.
`429`	Your organization reached its spending limit, or the provider is rate limiting the model. If `error.type` is `billing_error`, it is the spending limit. Anything else is a rate limit.	Spending limit: not until it is resolved. Rate limit: yes, after the time in the `Retry-After` header if present, otherwise with backoff.
`5xx`	The service or the provider is temporarily unavailable.	Yes, with backoff.

See the error reference for general guidance.

Next steps

API Reference: System One Decisions

The full request and response schemas.

Start Here

Inference and APIs

Data Engine

Studio

Gloo Code

Learn More

Legacy

System One Decisions

Prerequisites

Quick start

Example response

Question types

Writing questions

Request parameters

Response fields

Data retention

Pricing

Errors

Next steps

API Reference: System One Decisions

​Prerequisites

​Quick start

​Example response

​Question types

​Writing questions

​Request parameters

​Response fields

​Data retention

​Pricing

​Errors

​Next steps

API Reference: System One Decisions

Prerequisites

Quick start

Example response

Question types

Writing questions

Request parameters

Response fields

Data retention

Pricing

Errors

Next steps