> ## Documentation Index > Fetch the complete documentation index at: https://docs.opentype.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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](/reference/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. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/runs openapi: 3.1.0 info: title: OpenType API version: 0.1.0 license: name: Apache-2.0 description: >- The OpenType HTTP API: decision runs on Neon 1.1, API keys, usage, quota and billing. Every `/v1` route takes `Authorization: Bearer `, where the credential is an API key (`otsk_` followed by 64 hex characters) or a console session token. Amounts are integers in micro-USD (1,000,000 = 1 US dollar). Errors share one envelope, `{"error": {"code", "message", "request_id"}}`. Stripe is named only where it hosts checkout, the billing portal and receipts. servers: - url: https://api.opentype.dev description: Production - url: https://api.opentype.dev description: Production security: - bearer: [] - bearer: [] tags: - name: runs description: Create, list, retrieve and stream runs. - name: keys description: Create, list, rotate and revoke API keys. - name: usage description: Usage rollups, the daily series, the ledger and quota. - name: billing description: Credit balance, checkout, the billing portal and auto-recharge. - name: health description: Public liveness and readiness checks. - name: router description: >- Model Router: classify a task with Neon 1.1 and pick a model from the benchmark catalog. paths: /v1/runs: post: tags: - runs summary: Create a run description: >- 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](/reference/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. operationId: create_run parameters: - name: Idempotency-Key in: header description: >- 1 to 255 bytes of visible ASCII text, unique per logical request. Reuse it only to retry the same body. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRunRequest' required: true responses: '200': description: >- The settled run: a fresh run, or the replay of a terminal run (`replayed: true`). content: application/json: schema: $ref: '#/components/schemas/RunResponse' headers: Server-Timing: description: >- Time per phase in milliseconds: `admit;dur=…, upstream;dur=…, gateway;dur=…, total;dur=…`. schema: type: string '202': description: >- The replay of a run that is still `pending`. Send the request again with a new `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/RunResponse' headers: Server-Timing: description: >- Time per phase in milliseconds: `admit;dur=…, upstream;dur=…, gateway;dur=…, total;dur=…`. schema: type: string '400': description: >- `invalid_body`, `idempotency_key_required`, `invalid_idempotency_key`, `invalid_verdict_schema`, `invalid_decision_questions` or `unknown_model`. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '401': description: >- `missing_credentials` (no bearer credential) or `invalid_credential` (malformed, unknown or revoked). content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '402': description: >- `insufficient_credits`: your available credit does not cover the run's hold. Buy credit or enable auto-recharge; the same key is reusable. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '403': description: >- `scope_denied`: the credential lacks `runs_write`. A session without an organization gets `no_active_organization`. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '409': description: >- `idempotency_conflict`: this key was already used with a different body. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '413': description: >- `body_too_large` (over 4 MiB) or `input_too_large` (the input estimate is over 262,144 tokens for a decision run, or over 64,000 tokens for a verdict run). content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '429': description: >- `organization_spend_quota_exhausted` or `organization_token_quota_exhausted`: the quota for this period cannot cover the run. The same key is reusable. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '500': description: '`internal_error`: an unexpected failure. Report the `request_id`.' content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '503': description: >- The run could not be served: `no_route_available`, `decision_unavailable`, `budget_exhausted`, `verdict_schema_violation` (with `violations`), `catalog_unavailable`, `not_configured`, `database_unavailable`, `provider_unauthorized`, `provider_rate_limited`, `provider_rejected_request`, `provider_unavailable` or `provider_malformed_response`. Also `auth_not_configured` or `trust_keys_unavailable` when credentials cannot be verified. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '504': description: '`deadline_exceeded`: the run''s deadline passed before it finished.' content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' security: - bearer: [] - bearer: [] components: schemas: CreateRunRequest: type: object description: >- 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`. required: - max_output_tokens properties: kind: $ref: '#/components/schemas/RunKind' description: >- `decision` or `verdict`. Defaults to `verdict`, so send `decision` explicitly for a decision run. system: type: - string - 'null' messages: type: array items: $ref: '#/components/schemas/RunMessage' description: Verdict runs only, and required for them. At least one prompt turn. schema: description: >- 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: description: >- 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: type: - string - 'null' description: Decision runs only. Context that applies to every question. questions: type: - object - 'null' description: >- 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`. additionalProperties: $ref: '#/components/schemas/DecisionQuestionRequest' propertyNames: type: string draws: type: - integer - 'null' format: int32 description: >- Decision runs only. Independent reads to average, 1 to 8. Defaults to 1. minimum: 0 think_tokens: type: - integer - 'null' format: int32 description: >- Decision runs only. Tokens the model may think before answering, 0 to 4096. Defaults to 0. The thought text is never returned. minimum: 0 model: type: - string - 'null' description: >- 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: type: array items: $ref: '#/components/schemas/CapabilityHint' description: >- Optional routing hints. At most 7, no duplicates. Hints can only narrow routing. Hint errors are reported as `invalid_verdict_schema` on either kind. max_output_tokens: type: integer format: int32 description: >- Required. Output tokens the run may generate, greater than 0. Counts toward the token quota estimate. minimum: 0 deadline_ms: type: - integer - 'null' format: int64 description: >- 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`. minimum: 0 question_order: type: - array - 'null' items: type: string description: >- Decision runs only. Your question order; it must name exactly the keys of `questions`. Defaults to sorted key order. additionalProperties: false RunResponse: type: object description: >- 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. required: - run_id - kind - state - input_digest - replayed properties: run_id: type: string description: '`run_` followed by 32 hex characters.' kind: $ref: '#/components/schemas/RunKind' description: >- Which kind of answer this run produces: look at `verdict` or at `decision`. state: $ref: '#/components/schemas/RunStateResponse' input_digest: type: string description: 64-character hex SHA-256 of the normalized input, kind and contract. output_digest: type: - string - 'null' verdict: description: >- Completed verdict runs: your JSON document, validated against your schema. decision: oneOf: - type: 'null' - $ref: '#/components/schemas/DecisionResponse' description: The decision's answer set. Present on a completed decision run. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/UsageResponse' cost_micros: type: - integer - 'null' format: int64 minimum: 0 cost_basis: oneOf: - type: 'null' - $ref: '#/components/schemas/CostBasis' description: >- Whether `cost_micros` was reported by the model service or estimated from the price list. Present exactly when `cost_micros` is. schema_enforcement: oneOf: - type: 'null' - $ref: '#/components/schemas/SchemaEnforcementResponse' description: >- What constrained the verdict. Present on a fresh verdict run; absent on a replay and on a list row. replayed: type: boolean description: >- `true` whenever the body came from storage: every replay, retrieve, stream and list row. A replay is never charged again. RunsErrorBody: type: object description: The error envelope, shared by every route. Branch on `error.code`. required: - error properties: error: $ref: '#/components/schemas/RunsErrorDetail' RunKind: type: string description: >- `decision`: probabilities over closed answer sets. `verdict`: one JSON document validated against your schema. enum: - verdict - decision RunMessage: type: object description: One prompt turn. Unknown keys are refused. required: - role - content properties: role: $ref: '#/components/schemas/MessageRole' content: type: string additionalProperties: false DecisionQuestionRequest: oneOf: - allOf: - $ref: '#/components/schemas/SharedQuestionFields' - type: object required: - instructions properties: instructions: type: string criteria: oneOf: - type: 'null' - $ref: '#/components/schemas/NoulCriteria' description: Optional descriptions of what each side means. - type: object description: A yes/no question. The answer is P(yes). required: - type properties: type: type: string enum: - noul description: >- A yes/no question. Its answer names are `yes` and `no`; the answer's `probability` is P(yes). - allOf: - $ref: '#/components/schemas/SharedQuestionFields' - type: object required: - instructions - criteria properties: instructions: type: string criteria: type: object additionalProperties: type: - string - 'null' propertyNames: type: string - type: object description: >- A closed option set: option name to an optional description. The name is what an answer and an `ask_if` compare against. required: - type properties: type: type: string enum: - choice description: A closed option set. The option names are the answer names. - allOf: - $ref: '#/components/schemas/SharedQuestionFields' - type: object required: - instructions - criteria properties: instructions: type: string criteria: type: array items: type: string - type: object description: >- An ordered set of levels. The order is the level order, and the index is the meaningful key of the answer. required: - type properties: type: type: string enum: - score description: Ordered levels. Answers are keyed by 0-based level index. description: >- One question, selected by `type`: `noul` (yes or no), `choice` (a closed option set) or `score` (ordered levels). Each needs 2 to 20 alternatives with unique names; `noul` always has 2. Unknown keys are refused. CapabilityHint: type: string description: A routing capability. A hint can only narrow the routes considered. enum: - chat - reasoning - tools - vision - streaming - embedding - structured_read RunStateResponse: type: string enum: - pending - running - completed - failed DecisionResponse: type: object description: A decision's answers. required: - answers - draws - read properties: answers: description: >- One answer per question, keyed by your question ids. Shapes by `type`: `noul` has `probability`, which is P(yes); `choice` has `choice`, `probabilities` keyed by option name, and `confidence`; `score` has `score` (the expected 0-based level index), `legend`, `probabilities` keyed by index, and `confidence`; `skipped` has `because` (`question`, `answered` when known, `required`) when an `ask_if` failed. Any answer may carry `label_mass` and `answered_within_labels`. Every probability and confidence is between 0 and 1. draws: type: integer format: int32 description: Reads averaged. minimum: 0 read: $ref: '#/components/schemas/DecisionReadResponse' description: >- What constrained the answers. Only `slot_constrained` is produced today. model: type: - string - 'null' description: 'Live responses only. The model that served the run: `neon-1.1`.' example: neon-1.1 stages: type: array items: type: array items: type: string description: >- Live responses only. Question ids per stage, in the order the stages ran. thought_tokens: type: - integer - 'null' format: int32 description: >- Live responses only, when thought tokens were generated. The thought text is never returned. minimum: 0 thought_closed: type: - boolean - 'null' UsageResponse: type: object description: Tokens the run used. required: - input_tokens - output_tokens properties: input_tokens: type: integer format: int64 minimum: 0 output_tokens: type: integer format: int64 minimum: 0 CostBasis: type: string description: >- `provider_reported`: the usage the model reported. `estimated`: the pre-call estimate at list prices. enum: - provider_reported - estimated SchemaEnforcementResponse: type: string description: >- `unconstrained`: only the server's own validation bound the answer. `requested`: the schema was offered to the model but did not bind it. `forced`: the model was compelled into the schema slot, unchecked upstream. `enforced`: decoding was constrained to the schema. Every returned verdict passed validation, whatever this says. enum: - unconstrained - requested - forced - enforced RunsErrorDetail: type: object required: - code - message - request_id properties: code: type: string description: Stable snake_case code. The only field to branch on. message: type: string request_id: type: string violations: type: array items: type: string description: >- Only on `verdict_schema_violation`: up to 10 JSON Pointers into the rejected document. MessageRole: type: string enum: - user - assistant SharedQuestionFields: type: object description: Optional fields every question type accepts. properties: depends_on: type: array items: type: string description: >- Ids of other questions in this set that must be answered in an earlier stage. Cycles are refused. ask_if: type: object description: >- Question id to the answer names that make this question worth asking. When the condition fails, the answer is `skipped`. additionalProperties: type: array items: type: string propertyNames: type: string alone: type: boolean description: Read this question on its own rather than jointly with its stage. additionalProperties: false NoulCriteria: type: object description: What each side of a yes/no question means. Both are optional. properties: 'true': type: - string - 'null' 'false': type: - string - 'null' additionalProperties: false DecisionReadResponse: type: string description: >- What constrained a decision's answers: `slot_constrained` when the model could only answer inside the closed answer set, `reconstructed` when the answers were read back from its output. enum: - slot_constrained - reconstructed securitySchemes: bearer: type: http scheme: bearer description: An API key (otsk_ + 64 hex) or a console session token. ````