Runs

Create a run

Submits a run and returns its answer. The call is synchronous: it returns once the run has settled. Requires runs_write.

Neon 1.1 serves decision runs ("kind": "decision"), with up to 262,144 input tokens. A verdict run currently answers 503 no_route_available.

Idempotency-Key is required. Replaying a key with the same body returns the stored run with replayed: true and never charges again: 200 when the stored run is terminal (a failed run replays as 200 with state: "failed"), 202 when it is still pending. The same key with a different body is 409 idempotency_conflict. Keys are scoped to your organization and never expire. After a 5xx or 504, retry with a new key.

While it runs, a run holds its whole spend ceiling (at most 20,000 micro-USD) against your credit and quota; settlement charges the actual cost. See Errors for every refusal.

The response carries a Server-Timing header with the time spent per phase, in milliseconds: admit;dur=…, upstream;dur=…, gateway;dur=…, total;dur=…. upstream is the model call; gateway is everything else.

POST

runs

Create a run

curl --request POST \
  --url https://api.opentype.dev/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "max_output_tokens": 1,
  "instructions": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({max_output_tokens: 1, instructions: '<string>'})
};

fetch('https://api.opentype.dev/v1/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.opentype.dev/v1/runs"

payload = {
    "max_output_tokens": 1,
    "instructions": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "run_id": "<string>",
  "kind": "verdict",
  "state": "pending",
  "input_digest": "<string>",
  "replayed": true,
  "output_digest": "<string>",
  "verdict": "<unknown>",
  "decision": {
    "answers": "<unknown>",
    "draws": 1,
    "read": "slot_constrained",
    "model": "neon-1.1",
    "stages": [
      [
        "<string>"
      ]
    ],
    "thought_tokens": 1,
    "thought_closed": true
  },
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1
  },
  "cost_micros": 1,
  "cost_basis": "provider_reported",
  "schema_enforcement": "unconstrained"
}

{
  "run_id": "<string>",
  "kind": "verdict",
  "state": "pending",
  "input_digest": "<string>",
  "replayed": true,
  "output_digest": "<string>",
  "verdict": "<unknown>",
  "decision": {
    "answers": "<unknown>",
    "draws": 1,
    "read": "slot_constrained",
    "model": "neon-1.1",
    "stages": [
      [
        "<string>"
      ]
    ],
    "thought_tokens": 1,
    "thought_closed": true
  },
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1
  },
  "cost_micros": 1,
  "cost_basis": "provider_reported",
  "schema_enforcement": "unconstrained"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

Authorizations

Authorization

string

header

required

An API key (otsk_ + 64 hex) or a console session token.

Headers

Idempotency-Key

string

required

1 to 255 bytes of visible ASCII text, unique per logical request. Reuse it only to retry the same body.

Body

application/json

A run. kind selects a decision (state plus questions) or a verdict (messages plus schema), and defaults to verdict. max_output_tokens is required on every run. Unknown fields are refused, and a field that belongs to the other kind is 400 invalid_body.

max_output_tokens

integer<int32>

required

Required. Output tokens the run may generate, greater than 0. Counts toward the token quota estimate.

Required range: x >= 0

kind

enum<string>

decision or verdict. Defaults to verdict, so send decision explicitly for a decision run.

Available options:

verdict,

decision

system

string | null

messages

object[]

Verdict runs only, and required for them. At least one prompt turn.

Show child attributes

schema

any

Verdict runs only, and required for them. The JSON Schema the verdict must satisfy: an object of at most 32 KiB, nesting depth 12, 64 subschemas and 512 properties, pattern values of at most 256 characters, and only local # references. Out of bounds is 400 invalid_verdict_schema.

state

any

Decision runs only, and required for them. What is being decided about: any JSON value. A string is sent as-is; anything else as its JSON text.

instructions

string | null

Decision runs only. Context that applies to every question.

questions

object | null

Decision runs only, and required for them. 1 to 64 questions keyed by your own ids. An id must be non-empty and must not contain : or a newline. Out of bounds is 400 invalid_decision_questions.

Show child attributes

draws

integer<int32> | null

Decision runs only. Independent reads to average, 1 to 8. Defaults to 1.

Required range: x >= 0

think_tokens

integer<int32> | null

Decision runs only. Tokens the model may think before answering, 0 to 4096. Defaults to 0. The thought text is never returned.

Required range: x >= 0

model

string | null

Decision runs only. neon-1.1, or neon-latest, which resolves to neon-1.1. Any other value is 400 unknown_model.

Example:

"neon-1.1"

capability_hint

enum<string>[]

Optional routing hints. At most 7, no duplicates. Hints can only narrow routing. Hint errors are reported as invalid_verdict_schema on either kind.

A routing capability. A hint can only narrow the routes considered.

Available options:

chat,

reasoning,

tools,

vision,

streaming,

embedding,

structured_read

deadline_ms

integer<int64> | null

Time budget in milliseconds. A verdict run defaults to 30,000 and is clamped to 1 to 120,000. A decision run defaults to 30,000 plus 120,000 per 262,144 input tokens and is clamped to 1 to 150,000. Past it the run is 504 deadline_exceeded.

Required range: x >= 0

question_order

string[] | null

Decision runs only. Your question order; it must name exactly the keys of questions. Defaults to sorted key order.

Response

The settled run: a fresh run, or the replay of a terminal run (replayed: true).

A run. A completed run carries verdict or decision, never both. Absent optional fields are omitted, not null. Stored reads (replays, retrieve, stream, list rows) omit cost_basis and schema_enforcement; list rows also omit the answer, usage and cost.

run_id

string

required

run_ followed by 32 hex characters.

kind

enum<string>

required

Which kind of answer this run produces: look at verdict or at decision.

Available options:

verdict,

decision

state

enum<string>

required

Available options:

pending,

running,

completed,

failed

input_digest

string

required

64-character hex SHA-256 of the normalized input, kind and contract.

replayed

boolean

required

true whenever the body came from storage: every replay, retrieve, stream and list row. A replay is never charged again.

output_digest

string | null

verdict

any

Completed verdict runs: your JSON document, validated against your schema.

decision

null | object

The decision's answer set. Present on a completed decision run.

Show child attributes

usage

null | object

Tokens the run used.

Show child attributes

cost_micros

integer<int64> | null

Required range: x >= 0

cost_basis

null | enum<string>

Whether cost_micros was reported by the model service or estimated from the price list. Present exactly when cost_micros is.

Available options:

provider_reported,

estimated

schema_enforcement

null | enum<string>

What constrained the verdict. Present on a fresh verdict run; absent on a replay and on a list row.

Available options:

unconstrained,

requested,

forced,

enforced

Create a run

curl --request POST \
  --url https://api.opentype.dev/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "max_output_tokens": 1,
  "instructions": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({max_output_tokens: 1, instructions: '<string>'})
};

fetch('https://api.opentype.dev/v1/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.opentype.dev/v1/runs"

payload = {
    "max_output_tokens": 1,
    "instructions": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "run_id": "<string>",
  "kind": "verdict",
  "state": "pending",
  "input_digest": "<string>",
  "replayed": true,
  "output_digest": "<string>",
  "verdict": "<unknown>",
  "decision": {
    "answers": "<unknown>",
    "draws": 1,
    "read": "slot_constrained",
    "model": "neon-1.1",
    "stages": [
      [
        "<string>"
      ]
    ],
    "thought_tokens": 1,
    "thought_closed": true
  },
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1
  },
  "cost_micros": 1,
  "cost_basis": "provider_reported",
  "schema_enforcement": "unconstrained"
}

{
  "run_id": "<string>",
  "kind": "verdict",
  "state": "pending",
  "input_digest": "<string>",
  "replayed": true,
  "output_digest": "<string>",
  "verdict": "<unknown>",
  "decision": {
    "answers": "<unknown>",
    "draws": 1,
    "read": "slot_constrained",
    "model": "neon-1.1",
    "stages": [
      [
        "<string>"
      ]
    ],
    "thought_tokens": 1,
    "thought_closed": true
  },
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1
  },
  "cost_micros": 1,
  "cost_basis": "provider_reported",
  "schema_enforcement": "unconstrained"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "violations": [
      "<string>"
    ]
  }
}

Overview

Runs

Model Router

API keys

Usage and quota

Billing

Health

Create a run

Authorizations

Headers

Body

Response