> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prem.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Decisions
> Answer typed decision questions with probabilities over a TypeSafe-compatible API.
## Zero Data Retention
This is a Zero Data Retention route. Prem sends the request to a trusted partner. Prem does not keep your prompts or completions, and the partner does not keep them.
Your content is plaintext at the Prem API Gateway and at the partner. There is no client-side encryption and no Trusted Execution Environment.
See [ZDR vs Confidential](/zdr/comparison).
## Base URL
```text theme={"system"}
https://gateway.prem.io/typesafe/v1/systemone
```
Authenticate with a standard Prem API key in the `Authorization: Bearer` header. The key must have the `chats.completion` scope. No client KEK is used on this route.
```bash theme={"system"}
curl https://gateway.prem.io/typesafe/v1/systemone \
-H "Authorization: Bearer $PREM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "dgemma", "state": "x", "questions": {"a": {"type": "noul", "instructions": "y"}}}'
```
## Request shape
The request uses a TypeSafe-compatible API, so the official [TypeSafe client](https://www.npmjs.com/package/@typesafe-ai/sdk) works against this route. Set its base URL to `https://gateway.prem.io/typesafe`. The client appends `/v1/systemone` and `/v1/models`.
```typescript theme={"system"}
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient({
apiKey: process.env.PREM_API_KEY,
baseURL: "https://gateway.prem.io/typesafe",
defaultModel: "dgemma",
});
const res = await client.systemOne({
state: "Customer says: 'I was charged twice for one subscription this month.'",
questions: {
category: choice("What is this ticket about?", { billing: null, technical: null, other: null }),
urgent: noul("Is this request urgent?"),
severity: score("How severe is this issue?", ["not severe", "mild", "moderate", "severe", "critical"] as const),
},
});
console.log(res.answers.category.choice, res.answers.urgent.noul, res.answers.severity.score);
```
It is not the OpenAI Chat Completions shape, so an OpenAI client does not work against this route.
| Field | Required | Description |
| ----------- | -------- | --------------------------------------------------------------------------------------------- |
| `model` | yes | Model name from `GET /typesafe/v1/models`. |
| `state` | yes | The context the questions are asked about. A string, object, array, number, boolean, or null. |
| `questions` | yes | A map of question id to a typed question. |
| `images` | no | At most one base64 image data URL. |
| `videos` | no | At most one base64 MP4 data URL. A `dgemma` extension. |
| `samples` | no | Number of reads to average. |
| `steps` | no | Number of denoising steps. |
| `provider` | no | Pin the request to one of the model's configured backends. |
Each question carries `type`, `instructions`, and `criteria`:
| `type` | `criteria` | Answer field |
| -------- | ------------------------------------------- | ------------------------------------------------ |
| `choice` | A map of 1 to 26 labels to descriptions | `choice`, `probabilities`, `confidence` |
| `noul` | Optional. Descriptions for the two outcomes | `noul` |
| `score` | An ordered list of 2 to 10 levels | `score`, `legend`, `probabilities`, `confidence` |
## Response shape
| Field | Description |
| ------------- | ------------------------------------------------------------- |
| `model` | The resolved model name. |
| `answers` | One entry per question id, keyed by the id that you sent. |
| `usage` | `input_tokens` and `output_tokens` for the request. |
| `diagnostics` | Engine detail for the call. Informational, and it can change. |
Read `answers` by your own question ids. A `noul` answer puts its scalar in `noul`; a `noul` answer has no `probabilities` field. A `score` answer reports the probability-weighted mean over the zero-indexed levels.
The values in `probabilities` are normalized scores over the supplied labels. They are not calibrated correctness estimates, and label order can change the prediction. See the guide's [current limits](/guides/decisions#current-limits).
## Media input
Use `images` or `videos`, not both in one request.
* `images` holds at most one base64 image data URL. The image is placed ahead of the state.
* `videos` holds at most one base64 MP4 data URL, up to 10 MiB, 30 seconds, and 1920 x 1080 pixels. Four frames are sampled and audio is not processed. This is a `dgemma` extension and is not part of the base request shape. Use a raw JSON request if your HTTP client does not expose the field.
## Streaming
This route is non-streaming. A `stream` field is not supported. The call returns one JSON object.
## Model availability
Send a model that `GET /typesafe/v1/models` returns for your API key. `dgemma` is served through this route and is not available on the chat completions routes. A chat model on this route returns a validation error. See [Models & Pricing](/models-and-pricing).
## Limits
* Up to 16 questions per request.
* `choice` holds 1 to 26 criteria. `score` holds 2 to 10 levels.
* At most one image or one video per request.
* Questions are independent. One question cannot read another question or its answer.
* Up to 4 concurrent requests per key before a 429.
## Related
Worked examples for each question type.
What Prem records and what the partner records.
## OpenAPI
````yaml post /typesafe/v1/systemone
openapi: 3.1.0
info:
title: Prem API
description: Reference documentation for the Prem API.
version: 1.0.0
termsOfService: https://prem.io/terms
contact:
name: API Support
url: https://help.prem.io
email: support@premai.io
servers:
- url: https://gateway.prem.io
description: Production API server
security: []
paths:
/typesafe/v1/systemone:
post:
tags:
- Inference
- dev-api
summary: Create a structured decision
description: >-
Answer typed questions (choice, noul, score) about a state.
TypeSafe-compatible (SystemOne), so the official SDK can use this
endpoint directly. Not end-to-end encrypted.
operationId: createSystemOneDecision
requestBody:
required: true
content:
application/json:
schema:
type: object
description: SystemOne decision request.
properties:
model:
type: string
description: Model name, as listed by `GET /typesafe/v1/models`.
state:
type:
- string
- object
- array
- number
- boolean
- 'null'
description: Context the questions are asked about.
questions:
type: object
description: Map of question id to a typed question.
additionalProperties:
type: object
images:
type: array
description: Optional. At most one base64 image data URL.
items:
type: string
samples:
type: integer
steps:
type: integer
provider:
type: string
description: >-
Optional. Pin the request to one of the model's configured
backends. Omit to let the platform choose.
videos:
type: array
maxItems: 1
description: >-
Optional dgemma extension: one inline MP4, up to 10 MiB, 30
seconds and 1920 x 1080 pixels. Four frames are sampled;
audio is not processed. Cannot be combined with images. Use
a raw JSON request if your SDK does not expose this field.
items:
type: string
pattern: ^data:video/mp4;base64,
example: data:video/mp4;base64,
required:
- model
- state
- questions
additionalProperties: true
responses:
'200':
description: A decision with per-question answers and probabilities.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'502':
$ref: '#/components/responses/502'
'503':
$ref: '#/components/responses/503'
security:
- BearerAuth: []
ApiKeyAuth: []
components:
responses:
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: Useful informaiton, not always present, to debug the response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it when
talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
'401':
description: Access token is missing or invalid
content:
application/json:
schema:
allOf:
- type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: >-
Useful informaiton, not always present, to debug the
response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it
when talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
- properties:
status:
type: integer
enum:
- 401
'403':
description: You do not have the required permissions to access this resource
content:
application/json:
schema:
allOf:
- type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: >-
Useful informaiton, not always present, to debug the
response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it
when talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
- properties:
status:
type: integer
enum:
- 403
'404':
description: Resource not found
content:
application/json:
schema:
allOf:
- type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: >-
Useful informaiton, not always present, to debug the
response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it
when talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
- properties:
status:
type: integer
enum:
- 404
'429':
description: Too many requests
content:
application/json:
schema:
type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: Useful informaiton, not always present, to debug the response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it when
talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
'502':
description: Upstream service failed
content:
application/json:
schema:
type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: Useful informaiton, not always present, to debug the response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it when
talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
'503':
description: Service temporarily unavailable
content:
application/json:
schema:
type: object
properties:
status:
type: integer
enum:
- 400
- 401
- 403
- 404
- 429
- 502
- 503
description: Status code of the response
data:
type:
- object
- 'null'
description: Response data containing the requested object
error:
type:
- string
- 'null'
examples:
- Some error message
description: Error message of the response, human readable
message:
type: 'null'
env:
type: string
enum:
- development
- production
description: API environment
log:
type:
- string
- object
- 'null'
examples:
- request_id: req_1234567890
- Some pertinent log message
description: Useful informaiton, not always present, to debug the response
validator:
type:
- object
- array
- 'null'
examples:
- email: Invalid email address
password: Password is required
description: >-
Validator response object, each key is the field name and
value is the error message
support_id:
type:
- string
- 'null'
format: uuid
examples:
- support_uuidv7-something-else
description: >-
Support ID linked to the response, used to identify it when
talking with our team
required:
- status
- error
- message
- env
- log
- support_id
additionalProperties: false
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Send your access token as header Authorization: Bearer {accessToken}'
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Your API key that starts with sk_live or sk_test. You can create yours
at go.prem.io/api-keys.
````