# OpenType Docs

> OpenType answers typed questions about your data in one model call per run. Send a state and a set of questions; get calibrated answers back.

- [OpenType documentation](https://docs.opentype.dev/index.md): OpenType answers typed yes/no, choice and score questions about a JSON state in one model call per run, with a calibrated probability for every answer.
- [Quickstart](https://docs.opentype.dev/getting-started/quickstart.md): Sign up, create an API key in the console, send your first decision run to OpenType, and read the probabilities it returns. About five minutes.
- [Create an account](https://docs.opentype.dev/getting-started/create-an-account.md): Sign up for OpenType, verify your email to receive $5 of free credit, and sign in to the console with a password, an email code, Google, or GitHub.
- [Runs](https://docs.opentype.dev/getting-started/runs.md): A run is one POST /v1/runs request and one stored record. Its kinds, its states, every field of the response, replays with Idempotency-Key, and stored runs.
- [Decision questions](https://docs.opentype.dev/getting-started/decision-questions.md): The noul, choice and score question types, depends_on, ask_if and alone, the bounds a question set must fit, stages, and the shape of every answer.
- [Models and pricing](https://docs.opentype.dev/getting-started/models-and-pricing.md): Neon 1.1, the model behind every decision run: its ids, its 262,144-token context, the $0.042 per million token price, and how the cost of a run is rounded.
- [Organizations and roles](https://docs.opentype.dev/getting-started/organizations-and-roles.md): What an OpenType organization owns, the five roles and the scopes each one holds, and why an API key can never hold more scopes than the person who created it.
- [Troubleshooting](https://docs.opentype.dev/getting-started/troubleshooting.md): Symptom, cause and fix for the OpenType API errors you are most likely to meet, with the request id to log for each one.
- [Frequently asked questions](https://docs.opentype.dev/getting-started/faq.md): Short answers on cost, the $5 sign-up credit, Neon 1.1, limits, key expiry and rotation, timeouts, verdict runs and streaming, each linking to its page.
- [Glossary](https://docs.opentype.dev/getting-started/glossary.md): The OpenType API terms you meet across these docs, from alternative to verdict run, in alphabetical order, each linked to the page that covers it.
- [The OpenType console](https://docs.opentype.dev/console/index.md): What the console at console.opentype.dev does: the Playground, API keys, Usage and Billing pages, what the header shows, and what your role lets you do.
- [Sign in to the console](https://docs.opentype.dev/console/sign-in.md): Sign in or sign up at console.opentype.dev with Google, GitHub, a password or an emailed code; verify your email, reset a password, pick an organization.
- [Playground](https://docs.opentype.dev/console/playground.md): Run a decision read by hand in the console: write a state and typed questions, read each answer and its cost, then copy the request as cURL.
- [API keys in the console](https://docs.opentype.dev/console/api-keys.md): Create an API key in two steps, copy its secret the one time it is shown, choose its scopes, read the keys table, and revoke a key from the console.
- [Usage in the console](https://docs.opentype.dev/console/usage.md): Read runs, tokens, spend and error rate over 24h, 7d or 30d on the console's Usage page, plus the period quota and one log row per model call.
- [Billing in the console](https://docs.opentype.dev/console/billing.md): Check your credit balance, add funds from $5 to $1,000, set auto-recharge, open cards and receipts, and read transactions on the console's Billing page.
- [Guides](https://docs.opentype.dev/guides/index.md): Task-based guides for OpenType: write decision runs, make requests safe to retry, control spend, and prepare an integration for production.
- [Decision runs](https://docs.opentype.dev/guides/decision-runs.md): Send a JSON state and typed questions to Neon 1.1 and get a probability for every answer: request fields, response, stages, costs and limits.
- [Yes/no questions (noul)](https://docs.opentype.dev/guides/noul-questions.md): Ask a yes/no question with a noul, read the probability of yes, and turn it into an action with a threshold that matches what a mistake costs you.
- [Choice questions](https://docs.opentype.dev/guides/choice-questions.md): Ask Neon 1.1 to pick one of 2 to 20 named options, and read the chosen option, a probability for every option, and a confidence.
- [Score questions](https://docs.opentype.dev/guides/score-questions.md): Rate a state on an ordered scale you define, and read the expected level, a probability for each level, and a confidence.
- [Conditional questions](https://docs.opentype.dev/guides/conditional-questions.md): Order questions with depends_on, ask a question only when another answer matches with ask_if, read skipped answers, and isolate a question with alone.
- [Verdict runs](https://docs.opentype.dev/guides/verdict-runs.md): The verdict run contract: messages and a JSON Schema in, one validated JSON document out. Neon 1.1 does not serve verdict runs today.
- [Model Router](https://docs.opentype.dev/guides/model-router.md): Classify a task with Neon 1.1 and pick the best model for it from a benchmark catalog: policies, task types, filters, the response, costs and limits.
- [Task types and policies](https://docs.opentype.dev/guides/router-task-types.md): The 27 task types the Model Router classifies into, their families, and the benchmarks and weights each one is ranked on, with how each policy uses them.
- [Idempotency](https://docs.opentype.dev/guides/idempotency.md): Every POST /v1/runs carries an Idempotency-Key. How replays, conflicts and pending runs work, and when to reuse a key or mint a new one.
- [Error handling](https://docs.opentype.dev/guides/error-handling.md): Read the error envelope, branch on code, decide what to retry, and drop in a retry helper for POST /v1/runs in TypeScript or Python.
- [Polling for a run](https://docs.opentype.dev/guides/polling.md): POST /v1/runs waits for the answer. Recover a run with GET /v1/runs/{run_id} after a timeout, and tell a slow run from one that will stay pending.
- [Streaming a run's state](https://docs.opentype.dev/guides/streaming.md): GET /v1/runs/{run_id}/stream returns a one-shot server-sent events snapshot of a stored run. What it sends, what it does not, and how to read it.
- [Pagination and time windows](https://docs.opentype.dev/guides/pagination.md): Page through GET /v1/runs with limit and offset, and walk the usage ledger with start_at and end_at windows. Limits, order, and the traps.
- [Credits and billing](https://docs.opentype.dev/guides/credits-and-billing.md): How prepaid credit works: read your balance and transactions, buy credit through checkout, open the billing portal, and what a run is charged.
- [Auto-recharge](https://docs.opentype.dev/guides/auto-recharge.md): Keep your credit balance funded automatically: set a threshold and an amount, save a card, and know exactly when a charge happens.
- [Handling insufficient credits](https://docs.opentype.dev/guides/handling-insufficient-credits.md): Why a run gets 402 insufficient_credits, what the refusal leaves behind, and code that stops, alerts and retries with the same key after a top-up.
- [Usage reporting](https://docs.opentype.dev/guides/usage-reporting.md): Read your organization's runs, tokens and spend: totals for a window, a daily series, the per-call ledger, and the cost of one run.
- [Spend limits and quotas](https://docs.opentype.dev/guides/spend-limits-and-quotas.md): Read your organization's period spend and token limits with GET /v1/quota, and handle the two 429 quota refusals on POST /v1/runs.
- [Key rotation](https://docs.opentype.dev/guides/key-rotation.md): Replace an API key secret without downtime: overlap a new key and revoke the old one, or rotate in place when a secret leaks. Both patterns, step by step.
- [Production checklist](https://docs.opentype.dev/guides/production-checklist.md): What to settle before OpenType runs carry real traffic: keys and scopes, idempotency, timeouts, error handling, credit, quota and a rotation plan.
- [Code examples](https://docs.opentype.dev/guides/code-examples.md): Complete clients in shell, TypeScript and Python: a decision run with an idempotency key, error parsing, retries, request-id logging and answer reading.
- [Security](https://docs.opentype.dev/security/index.md): How OpenType authenticates requests, stores API keys, limits what each key can do with scopes, and handles the data you send in a run.
- [Authentication](https://docs.opentype.dev/security/authentication.md): Send an API key as a bearer credential, tell keys from console sessions, and fix every 401, 403 and 503 an auth check can return.
- [API key security](https://docs.opentype.dev/security/api-key-security.md): How OpenType stores API keys, why the secret is shown once, how to revoke and rotate keys, and what to do when a secret leaks.
- [Scopes and roles](https://docs.opentype.dev/security/scopes-and-roles.md): Give each API key the least privilege it needs: the nine scopes, the role-to-scope table, the creator ceiling, and service-account keys.
- [Data handling](https://docs.opentype.dev/security/data-handling.md): What OpenType sends to the model, what a run keeps and returns, who can read it, and how keys and session tokens are kept out of logs.
- [Reference](https://docs.opentype.dev/reference/index.md): The rules every OpenType API request follows: conventions, request ids, scopes, errors, problem codes, limits, and the changelog.
- [API conventions](https://docs.opentype.dev/reference/conventions.md): Base URL, JSON rules, id formats, timestamps, half-open time windows, micro-USD amounts, the body cap, and CORS for the OpenType API.
- [Request ids](https://docs.opentype.dev/reference/request-ids.md): How the x-request-id header works: send your own id or let OpenType mint one, read it on every response, and quote it when you report a problem.
- [Scopes](https://docs.opentype.dev/reference/scopes.md): The nine OpenType scopes, the routes each one unlocks, the scopes each organization role holds, and the rules for giving scopes to an API key.
- [Errors](https://docs.opentype.dev/reference/errors.md): The OpenType error envelope, what each HTTP status means, plain-text rejections, and how to retry a failed request without paying twice.
- [Problem codes](https://docs.opentype.dev/problems/index.md): Every OpenType error code: its HTTP status, whether a retry can help, what it means in one line, and the page that explains how to fix it.
- [invalid_body](https://docs.opentype.dev/problems/invalid_body.md): HTTP 400 on the runs routes: the body or query string does not fit the contract. Every message, what causes it, and how to fix it.
- [idempotency_key_required](https://docs.opentype.dev/problems/idempotency_key_required.md): HTTP 400 on POST /v1/runs: the request has no Idempotency-Key header. Why the header is required and how to choose a key.
- [invalid_idempotency_key](https://docs.opentype.dev/problems/invalid_idempotency_key.md): HTTP 400 on POST /v1/runs: the Idempotency-Key header is empty, longer than 255 bytes, or not printable ASCII. How to build a valid key.
- [invalid_run_id](https://docs.opentype.dev/problems/invalid_run_id.md): HTTP 400 on GET /v1/runs/{run_id} and its stream: the path value is not run_ followed by a UUID. Which forms are accepted and how to fix it.
- [invalid_verdict_schema](https://docs.opentype.dev/problems/invalid_verdict_schema.md): HTTP 400 on POST /v1/runs: the verdict schema or the capability hints were refused. Every reason, the bounds behind it, and how to fix it.
- [invalid_decision_questions](https://docs.opentype.dev/problems/invalid_decision_questions.md): HTTP 400 on POST /v1/runs: the decision question set was refused. Every reason, the bound behind it, and how to fix the questions.
- [unknown_model](https://docs.opentype.dev/problems/unknown_model.md): HTTP 400 on POST /v1/runs: a decision run named a model other than neon-1.1 or neon-latest. Which model ids are accepted and how to fix it.
- [invalid_parameter](https://docs.opentype.dev/problems/invalid_parameter.md): HTTP 400 on the usage routes: a bad time window, ledger limit or run id. Every message, the accepted formats, and how to fix the query.
- [invalid_amount](https://docs.opentype.dev/problems/invalid_amount.md): HTTP 400 on checkout and auto-recharge: an amount out of bounds, not whole cents, a threshold too high, or a missing value. Every message and fix.
- [empty_scopes](https://docs.opentype.dev/problems/empty_scopes.md): HTTP 400 on POST /v1/keys: the new key requested no scopes. The nine scopes, common scope sets, and how to create a working key.
- [secret_in_path](https://docs.opentype.dev/problems/secret_in_path.md): HTTP 400 on the key routes: a key secret was sent in the URL instead of the key id. Rotate that key now, then call again with its key_ id.
- [malformed_key_id](https://docs.opentype.dev/problems/malformed_key_id.md): HTTP 400 on the key routes: the path value does not start with key_. Where to find a key's id and how to call the route correctly.
- [missing_credentials](https://docs.opentype.dev/problems/missing_credentials.md): HTTP 401 on every protected route: no Authorization header, a scheme other than Bearer, or an empty token. How to send an API key correctly.
- [invalid_credential](https://docs.opentype.dev/problems/invalid_credential.md): HTTP 401 on every protected route: the API key is malformed, unknown or revoked, or the session has expired. How to find which, and fix it.
- [insufficient_credits](https://docs.opentype.dev/problems/insufficient_credits.md): HTTP 402 on POST /v1/runs: the organization's credit cannot cover the run's hold. How the check works, how to add credit, and safe retries.
- [no_active_organization](https://docs.opentype.dev/problems/no_active_organization.md): HTTP 403: a console session has no active organization. Why API keys never get it, and how to sign in to an organization.
- [scope_denied](https://docs.opentype.dev/problems/scope_denied.md): HTTP 403: the credential is valid but lacks the scope this route needs. Which scope each route needs, which roles hold it, and how to fix it.
- [scope_exceeds_creator](https://docs.opentype.dev/problems/scope_exceeds_creator.md): HTTP 403 on POST /v1/keys: the new key asked for a scope the caller does not hold. Why keys cannot exceed their creator, and how to fix it.
- [principal_is_not_the_caller](https://docs.opentype.dev/problems/principal_is_not_the_caller.md): HTTP 403 on POST /v1/keys: the new key was set to act as another user. Who a key can act as, and how to create a service-account key instead.
- [run_not_found](https://docs.opentype.dev/problems/run_not_found.md): HTTP 404 on run and run-usage lookups: no run with that id exists in your organization. Common causes and how to find the right run.
- [key_not_found](https://docs.opentype.dev/problems/key_not_found.md): HTTP 404 on the key routes: no key with that id exists in your organization. Common causes and how to find the right key id.
- [idempotency_conflict](https://docs.opentype.dev/problems/idempotency_conflict.md): HTTP 409 on POST /v1/runs: this Idempotency-Key was already used with a different body. What counts as the same body, and when to mint a new key.
- [key_revoked](https://docs.opentype.dev/problems/key_revoked.md): HTTP 409 on POST /v1/keys/{key_id}/rotate: a revoked key cannot be rotated. Why revocation is final and how to replace the key.
- [body_too_large](https://docs.opentype.dev/problems/body_too_large.md): HTTP 413 on POST /v1/runs: the request body is over 4 MiB. What counts toward the cap, how to shrink the body, and what other routes return.
- [input_too_large](https://docs.opentype.dev/problems/input_too_large.md): HTTP 413 on POST /v1/runs: the estimated input is over the token ceiling, or does not fit Neon 1.1's context. How the estimate works and how to fix it.
- [organization_spend_quota_exhausted](https://docs.opentype.dev/problems/organization_spend_quota_exhausted.md): HTTP 429 on POST /v1/runs: the 20,000-micro per-request ceiling exceeds the spend left in this quota period. How the check works and what to do.
- [organization_token_quota_exhausted](https://docs.opentype.dev/problems/organization_token_quota_exhausted.md): HTTP 429 on POST /v1/runs: the run's estimated tokens exceed the tokens left in this quota period. How the estimate works and what to do.
- [internal_error](https://docs.opentype.dev/problems/internal_error.md): HTTP 500 on POST /v1/runs: the run reached a state the service does not expect. Retry once with a new Idempotency-Key and report the request_id.
- [no_route_available](https://docs.opentype.dev/problems/no_route_available.md): HTTP 503 on POST /v1/runs: no model can serve this run. Every verdict run returns it today, because Neon 1.1 serves decision runs only.
- [decision_unavailable](https://docs.opentype.dev/problems/decision_unavailable.md): HTTP 503 on POST /v1/runs: the decision run could not be served. Common causes are labels that are not single tokens or a set that does not fit.
- [budget_exhausted](https://docs.opentype.dev/problems/budget_exhausted.md): HTTP 503 on POST /v1/runs: the run's own spend budget cannot cover the model call. Shrink the input or max_output_tokens and retry with a new key.
- [verdict_schema_violation](https://docs.opentype.dev/problems/verdict_schema_violation.md): HTTP 503 on POST /v1/runs: the model's verdict still broke your schema after the permitted attempts. Read the violations array and loosen the schema.
- [catalog_unavailable](https://docs.opentype.dev/problems/catalog_unavailable.md): HTTP 503 on POST /v1/runs: the service could not read its model list, so it could not choose a model. Retry with backoff and a new Idempotency-Key.
- [provider_unauthorized](https://docs.opentype.dev/problems/provider_unauthorized.md): HTTP 503 on POST /v1/runs: the model service refused OpenType's own credentials. Not your API key. Retry later with a new Idempotency-Key.
- [provider_rate_limited](https://docs.opentype.dev/problems/provider_rate_limited.md): HTTP 503 on POST /v1/runs: the model service was rate-limiting OpenType on every route tried. Not a limit on your account. Retry with backoff.
- [provider_rejected_request](https://docs.opentype.dev/problems/provider_rejected_request.md): HTTP 503 on POST /v1/runs: the model service refused a verdict request as invalid. Retry with a new key; if it repeats, report the request_id.
- [provider_unavailable](https://docs.opentype.dev/problems/provider_unavailable.md): HTTP 503 on POST /v1/runs: the model service failed or could not be reached on every route tried. Retry with backoff and a new Idempotency-Key.
- [provider_malformed_response](https://docs.opentype.dev/problems/provider_malformed_response.md): HTTP 503 on POST /v1/runs: the model's output could not be decoded. The call is still billed. Report the request_id and retry with a new key.
- [not_configured](https://docs.opentype.dev/problems/not_configured.md): HTTP 503 on /v1/runs routes: something the run needs is not configured on the service. Retry later; nothing in your request causes it.
- [database_unavailable](https://docs.opentype.dev/problems/database_unavailable.md): HTTP 503: the data store could not be reached or returned a record it could not read. Retry with backoff; on POST /v1/runs check replays.
- [database_not_configured](https://docs.opentype.dev/problems/database_not_configured.md): HTTP 503 on keys, usage, quota and billing routes: the service has no data store configured. Retry later; your request is fine.
- [billing_not_configured](https://docs.opentype.dev/problems/billing_not_configured.md): HTTP 503 on /v1/billing routes: billing is not configured on the service, so balance, checkout, portal and auto-recharge are unavailable.
- [stripe_unavailable](https://docs.opentype.dev/problems/stripe_unavailable.md): HTTP 503 on checkout and portal: the payment provider was unreachable or gave an unexpected answer. Nothing was charged. Retry with backoff.
- [auth_not_configured](https://docs.opentype.dev/problems/auth_not_configured.md): HTTP 503 on any protected route: the service has no verifier for this kind of credential. Check your key starts with otsk_, then retry later.
- [trust_keys_unavailable](https://docs.opentype.dev/problems/trust_keys_unavailable.md): HTTP 503 on any protected route: the service could not verify your credential because its key store or signing keys were unavailable. Retry.
- [deadline_exceeded](https://docs.opentype.dev/problems/deadline_exceeded.md): HTTP 504 on POST /v1/runs: the run's deadline passed before it finished. Raise deadline_ms (up to 150,000) or shrink the input, then retry with a new key.
- [Limits](https://docs.opentype.dev/reference/limits.md): Every numeric limit in the OpenType API: body size, 256k-token decisions, deadlines, question and schema bounds, spend ceilings, lists and quotas.
- [Changelog](https://docs.opentype.dev/reference/changelog.md): Dated changes to the OpenType API contract, the Neon 1.1 model and account features, with links to the pages that explain each change in full.
- [API reference](https://docs.opentype.dev/api-reference/introduction.md): Base URL, bearer auth, the Idempotency-Key on runs, the error envelope, request ids, micro-USD amounts and pagination for every OpenType endpoint.
- [Create a run](https://docs.opentype.dev/api-reference/runs/create.md): Submits a run and returns its answer. The call is synchronous: it returns once the run has settled. Requires `runs_write`.
- [List runs](https://docs.opentype.dev/api-reference/runs/list.md): Lists your organization's runs, newest first. Requires `runs_read`.
- [Retrieve a run](https://docs.opentype.dev/api-reference/runs/retrieve.md): Reads one run from stored state. Requires `runs_read`. Never calls the model, so reading a run is free.
- [Stream a run](https://docs.opentype.dev/api-reference/runs/stream.md): Returns the run's stored state as server-sent events, then closes. Requires `runs_read`. Never calls the model, so it cannot charge.
- [Select a model](https://docs.opentype.dev/api-reference/router/select.md): Classifies a task with Neon 1.1 and selects a model from the benchmark catalog. Requires `runs_write`.
- [List task types](https://docs.opentype.dev/api-reference/router/task-types.md): The task types the router classifies into, their families, and the benchmarks each one is scored on. Requires `runs_read`.
- [List router models](https://docs.opentype.dev/api-reference/router/models.md): The benchmark catalog the router selects from: prices, speed, context, modalities and benchmark scores per model. Requires `runs_read`.
- [Create an API key](https://docs.opentype.dev/api-reference/keys/create.md): Creates a key and returns its secret once, in `secret`. Store it now: no other response carries it, and a lost secret is rotated, not recovered.
- [List API keys](https://docs.opentype.dev/api-reference/keys/list.md)
- [Retrieve an API key](https://docs.opentype.dev/api-reference/keys/retrieve.md)
- [Rotate an API key](https://docs.opentype.dev/api-reference/keys/rotate.md): Issues a new secret for the same key `id`, name and scopes, and returns it once. Requires `keys_write`.
- [Revoke an API key](https://docs.opentype.dev/api-reference/keys/revoke.md): Revokes a key. It stops authenticating immediately. Requires `keys_write`.
- [Usage rollup](https://docs.opentype.dev/api-reference/usage/rollup.md): Run counts, tokens and spend for your organization over a window. Requires `usage_read`.
- [Daily usage](https://docs.opentype.dev/api-reference/usage/daily.md): One row per UTC day: runs created that day, their tokens and their spend. Requires `usage_read`.
- [Usage ledger](https://docs.opentype.dev/api-reference/usage/ledger.md): The spend and token ledger: one entry per model attempt, newest first. Requires `usage_read`.
- [Run usage](https://docs.opentype.dev/api-reference/usage/run.md): One run's tokens, spend and spend ceiling, with the attempts that produced them. Requires `usage_read`.
- [Quota](https://docs.opentype.dev/api-reference/usage/quota.md): Your organization's quota limits for the current period, the UTC calendar month, and what is left. These are the numbers run admission enforces. Requires `usage_read`. Takes no parameters.
- [Get billing](https://docs.opentype.dev/api-reference/billing/get.md)
- [Create a checkout](https://docs.opentype.dev/api-reference/billing/checkout.md): Creates a Stripe Checkout page for a credit purchase and returns its URL. Requires `billing_write`.
- [Open the billing portal](https://docs.opentype.dev/api-reference/billing/portal.md)
- [Set auto-recharge](https://docs.opentype.dev/api-reference/billing/auto-recharge.md): Stores auto-recharge settings and returns the updated billing state. Requires `billing_write`.
- [Liveness](https://docs.opentype.dev/api-reference/health/liveness.md)
- [Readiness](https://docs.opentype.dev/api-reference/health/readiness.md)

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)