Your first API call

Before you start

The models with a live playground on this site can also be called from your own code, through the inference API. The System One Engine keeps them loaded, so they answer at once.

You need an API key. Create one at Settings → API. A key starts with s1_pat_ and is shown once, so copy it then. It can call models and nothing else: it cannot publish, and it cannot see private models. Keep it on your server, never in a web page.

Call a model over HTTP

Put the key in an environment variable, and send a state and two questions:

export SYSTEMONE_API_KEY=s1_pat_...
curl https://api.systemonemodels.tech/v1/systemone \
  -H "Authorization: Bearer $SYSTEMONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "supersonic-labs/julia-1",
       "state": "Customer: I was charged twice and want my money back.",
       "questions": {"intent": {"type": "choice",
                                "instructions": "What does the customer want?",
                                "criteria": ["refund", "track delivery", "cancel order"]},
                     "angry": {"type": "noul", "instructions": "The customer is angry."}}}'

Each question has an id you choose (intent, angry), a type and instructions. A choice question lists its options in criteria. The answers come back under the same ids:

{
  "model": "supersonic-labs/julia-1",
  "answers": {
    "intent": { "type": "choice", "choice": "refund",
                "probabilities": { "refund": 0.93, "track delivery": 0.02, "cancel order": 0.05 } },
    "angry": { "type": "noul", "noul": 0.71 }
  },
  "usage": { "input_tokens": 212, "output_tokens": 0, "decisions": 2 }
}

The numbers here are an example; yours will differ. The answer also names the version and checkpoint that answered, and how long it took, in latency_ms.

Call it from Python

The systemonemodels package, version 0.4 or later, has a client for the same API:

from systemone import Client

client = Client()  # reads SYSTEMONE_API_KEY
result = client.decide(
    "supersonic-labs/julia-1",
    "Customer: I was charged twice and want my money back.",
    {
        "intent": {
            "type": "choice",
            "instructions": "What does the customer want?",
            "criteria": ["refund", "track delivery", "cancel order"],
        },
        "angry": {"type": "noul", "instructions": "The customer is angry."},
    },
)

intent = result["answers"]["intent"]
if intent["probabilities"]["refund"] > 0.9:
    print("refunds queue")
else:
    print("a person")

The last four lines are the point of a calibrated answer: your code decides how far to trust the model.

The request and the answer follow OpenDXP, the open standard from lesson 3, so the same request works on any OpenDXP server, including one on your own machine (lesson 6).

Which models, and how many calls

GET /v1/systemone/models lists the models you can call and whether each is ready. It needs no key, and client.served_models() returns the same list.

A decision is one question answered, so the request above uses two. A request the model could not answer costs nothing. Days and months are UTC.

Plan	Decisions	Requests
Free	500 a day	60 a minute
Developer	100,000 a month	600 a minute
Enterprise	By agreement	3,000 a minute

Every answer carries X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset headers, client.usage() shows what is left of your plan, and Settings → API shows your calls by day, model and key.

When something goes wrong

Errors come back as JSON with a code:

Status	code	What to do
401	unauthorized	Send a valid key as Authorization: Bearer …
404	model_not_served	Pick a model from GET /v1/systemone/models
429	rate_limited, quota_exceeded	Wait Retry-After seconds, or until your plan renews
503	starting, busy	Try again after Retry-After seconds