> For the complete documentation index, see [llms.txt](https://docs.parasail.io/parasail-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parasail.io/parasail-docs/api-reference/systemone.md).

# System One

Send state and named questions to decision models with the System One API.

Decision models evaluate a shared `state` and return typed answers to named `questions`. Use them for classification, scoring, and yes/no decisions. See [Decision models](https://docs.parasail.io/parasail-docs/guides/decision-models.md) to configure a deployment and try it in the playground.

## Endpoint

```
POST https://api.parasail.io/v1/systemone
```

The selected deployment must serve this endpoint. A chat model doesn't become a decision model by changing the request URL.

System One is **not an OpenAI-compatible chat endpoint**. Send JSON over HTTP rather than calling `client.chat.completions.create`. The request uses `state` and `questions`, not `messages`, and the response uses `answers`, not `choices`.

## Authentication

Use a Parasail API key in the `Authorization: Bearer` header. The examples read it from the `PARASAIL_API_KEY` environment variable. See [Authentication](https://docs.parasail.io/parasail-docs/api-reference/authentication.md) to create and store a key. Keep API keys on your server, not in browser code.

## Send a request

Save the following JSON as `request.json`. Replace `decision-model` with the **served model ID or alias** shown for your deployment. It is an example alias, not a public model listing. A model's Hugging Face repository ID isn't necessarily its served ID.

```json
{
  "model": "decision-model",
  "state": "Our checkout has returned 500 errors since the latest deployment. Customers cannot complete purchases.",
  "questions": {
    "category": {
      "type": "choice",
      "instructions": "Which label best fits this support ticket?",
      "criteria": {
        "billing": "Payments, refunds, and invoices",
        "bug": "Software errors, crashes, or broken features",
        "account": "Login, password, or account access"
      }
    }
  }
}
```

Each example sends that same file. The 30-second timeout is a client setting for the example, not a service limit.

### cURL

```bash
curl --fail-with-body --max-time 30 \
  https://api.parasail.io/v1/systemone \
  -H "Authorization: Bearer $PARASAIL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
```

### Python

Install HTTPX with `pip install httpx`, then run this script from the directory containing `request.json`:

```python
import json
import os
from pathlib import Path

import httpx

request = json.loads(Path("request.json").read_text(encoding="utf-8"))
response = httpx.post(
    "https://api.parasail.io/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['PARASAIL_API_KEY']}"},
    json=request,
    timeout=30.0,
)
response.raise_for_status()
print(json.dumps(response.json()["answers"], indent=2))
```

### JavaScript

Use Node.js 20 or later. Save this as `decision.mjs` beside `request.json` and run `node decision.mjs`:

```javascript
import { readFile } from 'node:fs/promises';

const apiKey = process.env.PARASAIL_API_KEY;
if (!apiKey) throw new Error('Set PARASAIL_API_KEY before running this example.');

const request = JSON.parse(await readFile('request.json', 'utf8'));
const response = await fetch('https://api.parasail.io/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(request),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const result = await response.json();
console.log(result.answers);
```

## Request fields

| Field                           | Type                     | Required             | Description                                                                                          |
| ------------------------------- | ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `model`                         | string                   | Yes                  | Served model ID or alias for a deployment that supports System One                                   |
| `state`                         | string, object, or array | Yes                  | Shared context evaluated by every question; an array is context, not a batch of independent requests |
| `questions`                     | object                   | Yes                  | Named questions; each key identifies its answer in the response                                      |
| `questions.<name>.type`         | string                   | Yes                  | `choice`, `score`, or `noul`                                                                         |
| `questions.<name>.instructions` | string                   | Use in each question | What the model should decide about the state                                                         |
| `questions.<name>.criteria`     | object or array          | Depends on type      | Allowed choices or ordered score levels, described below                                             |
| `images`                        | array                    | No                   | Inline base64 images, only when the deployed model supports them; follow that model's image format   |
| `keep_alive`                    | string                   | No                   | Runtime-specific option forwarded to the model server; support and behavior depend on that server    |

The model server validates question details and optional fields. Support for an optional field isn't a guarantee that every decision model accepts it. `keep_alive` doesn't change Parasail's deployment lifecycle or billing policy.

### Question types

| Type     | Criteria                                    | Result                                                                                                         |
| -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `choice` | Object mapping option names to descriptions | Selected `choice`, per-option `probabilities`, and `confidence`                                                |
| `score`  | Ordered array of level descriptions         | Numeric `score`, per-level `probabilities`, `confidence`, and a `legend` mapping level indexes to descriptions |
| `noul`   | Not required                                | `noul`: probability from 0 to 1 that the statement in `instructions` is true                                   |

For example, replace the `questions` object in `request.json` with this object to ask about urgency and follow-up:

```json
{
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this support ticket?",
    "criteria": [
      "Cosmetic issue with no effect on functionality",
      "Degraded feature with a workaround",
      "Blocking issue with no workaround"
    ]
  },
  "needs_followup": {
    "type": "noul",
    "instructions": "Does this ticket require a response from the support team?"
  }
}
```

Score levels start at index zero. In this example, scores range from 0 to 2 and can be fractional. `noul` returns a probability, not a Boolean. Don't treat `confidence` as the selected option's probability or as a guarantee of correctness. For question semantics, see TypeSafe's [question types](https://docs.typesafe.ai/primitives) and [score reference](https://docs.typesafe.ai/primitives/score). Use Parasail's URL and authentication when calling models on Parasail.

## Response

The following is an illustrative response to the category question, not a guaranteed prediction:

```json
{
  "model": "decision-model",
  "answers": {
    "category": {
      "type": "choice",
      "choice": "bug",
      "probabilities": {
        "billing": 0.0125,
        "bug": 0.9781,
        "account": 0.0094
      },
      "confidence": 0.8906
    }
  },
  "usage": {
    "input_tokens": 174,
    "output_tokens": 1
  }
}
```

Answer keys match the question names you supplied. Parasail preserves the model's answer fields and returns the requested model alias. Read `answers.category.choice` for the selected category; don't parse a chat message.

When supplied by the model server, `usage.input_tokens` and `usage.output_tokens` report input and output token counts. Missing usage means unknown, not zero. Billing follows your deployment's pricing: token-based products use its token rates, while Dedicated Instances use GPU-time pricing. See [Pricing](https://docs.parasail.io/parasail-docs/billing/pricing.md).

## Streaming and chat parameters

System One returns a single JSON response. Omit `stream`; `stream: true` returns HTTP `400`. Don't send chat-specific fields such as `messages`, `stream_options`, `temperature`, or `max_tokens` as substitutes for System One questions.

## Errors

| Status               | Meaning and action                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `400`                | Invalid JSON or `stream: true`; correct the request before retrying                           |
| `401`                | Missing or invalid API key; check authentication                                              |
| `422`                | Missing `model`; send the served ID explicitly                                                |
| `404`                | Model or route not found; check the alias and whether the model server serves `/v1/systemone` |
| `429`                | Capacity exceeded; follow the retry guidance                                                  |
| `503`                | No serving replicas available; check deployment readiness                                     |
| Other `4xx` or `5xx` | Model-server or gateway error; inspect the response body for details                          |

An unknown model can also produce HTTP `500` on some gateway versions. Check the model ID before treating repeated `500` responses as transient errors. See [Retries and idempotency](https://docs.parasail.io/parasail-docs/operate-in-production/retries-and-idempotency.md) for production retry guidance.

## Next steps

* [Decision models](https://docs.parasail.io/parasail-docs/guides/decision-models.md)—deployment configuration, playground, and interpreting answers
* [Models endpoint](https://docs.parasail.io/parasail-docs/api-reference/models-endpoint.md)—find model IDs available to your account
* [Structured output](https://docs.parasail.io/parasail-docs/guides/structured-output.md)—JSON output from a generative chat model instead of a decision model
