> ## Documentation Index > Fetch the complete documentation index at: https://docs.torchcast.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a decision > Answers every question about `state` with probabilities. Each successful call is charged by its billable input tokens; a retried request is a new request and is charged again. ## OpenAPI ````yaml /openapi.json post /v1/decisions openapi: 3.1.0 info: title: Torchcast Decision API version: 1.0.0 description: >- Calibrated probabilities for yes/no, multiple-choice and ordinal questions about a piece of text, using the standard decisions API request and response shape. servers: - url: https://api.torchcast.ai security: - bearerAuth: [] paths: /v1/decisions: post: summary: Create a decision description: >- Answers every question about `state` with probabilities. Each successful call is charged by its billable input tokens; a retried request is a new request and is charged again. operationId: createDecision requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DecisionRequest' examples: defect_sentiment_severity: summary: Defect, sentiment and severity value: model: torchcast-decider-latest state: >- The app crashes every time I open the settings page. Very frustrating. questions: defect: type: noul instructions: Is this a product defect? criteria: 'true': The customer describes a bug in the product. 'false': >- Anything else, such as a question or a feature request. sentiment: type: choice instructions: What is the customer's sentiment? criteria: positive: Happy with the product. mixed: Both happy and unhappy. negative: Unhappy with the product. severity: type: score instructions: How severe is the issue? criteria: - Cosmetic - Inconvenient - Product unusable responses: '200': description: The answers. Charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/DecisionResponse' examples: defect_sentiment_severity: summary: Defect, sentiment and severity value: model: torchcast-decider-4b-v1-1-api-1 answers: defect: type: noul noul: 0.94 sentiment: type: choice choice: mixed confidence: 0.93 probabilities: positive: 0.02 mixed: 0.95 negative: 0.03 severity: type: score score: 1.78 confidence: 0.78 legend: '0': Cosmetic '1': Inconvenient '2': Product unusable probabilities: '0': 0.008 '1': 0.199 '2': 0.792 usage: input_tokens: 367 output_tokens: 3 '400': description: >- Invalid request, unknown model, or input rejected by the model. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: summary: Schema or limit violation value: error: message: A score question needs 1 to 10 levels. type: invalid_request_error code: invalid_request param: questions.severity.criteria invalid_json: summary: Unparseable JSON value: error: message: The request body is not valid JSON. type: invalid_request_error code: invalid_request param: body invalid_model: summary: Unknown model id value: error: message: The requested model does not exist. type: invalid_request_error code: invalid_model param: model valid_models: - torchcast-decider-latest - torchcast-decider-4b-v1-1-api-1 backend_rejected_input: summary: >- Input rejected by the model, such as one over its input-length limit value: error: message: The model rejected the request input. type: invalid_request_error code: invalid_request '401': description: Missing, invalid, expired or revoked API key. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_api_key: summary: Missing, invalid, expired or revoked key value: error: message: >- Invalid API key. The key may be missing, revoked or expired; send an active Decision API key as a bearer token. type: authentication_error code: invalid_api_key '402': description: >- The balance or the key's spend limit cannot cover the request. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_balance: summary: Balance cannot cover the request value: error: message: >- Insufficient balance for this request. Add credits to continue. type: billing_error code: insufficient_balance required_usd: '0.000150' available_usd: '0.000000' topup_url: null insufficient_balance_with_topup: summary: Balance cannot cover the request (console top-ups available) value: error: message: >- Insufficient balance for this request. Add credits to continue. type: billing_error code: insufficient_balance required_usd: '0.000150' available_usd: '0.000000' topup_url: https://console.torchcast.ai/console/billing key_limit_reached: summary: Key spend limit reached (daily limit) value: error: message: >- This API key has reached its spend limit for the current period. type: billing_error code: key_limit_reached limit_usd: '5.000000' resets_at: '2026-10-13T00:00:00Z' key_limit_reached_lifetime: summary: Key spend limit reached (lifetime limit) value: error: message: >- This API key has reached its spend limit for the current period. type: billing_error code: key_limit_reached limit_usd: '5.000000' resets_at: null '410': description: >- The pinned model id is retired; move to `replacement_model`, or to another id from `GET /v1/models` when it is null. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: model_retired: summary: Retired pinned id value: error: message: The requested model has been retired. type: invalid_request_error code: model_retired replacement_model: torchcast-decider-4b-v1-1-api-1 '413': description: The request body is too large. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: request_too_large: summary: Body over the limit value: error: message: The request body is too large. type: invalid_request_error code: request_too_large param: body '429': description: >- Rate limit exceeded or model at capacity; retry after `Retry-After` seconds. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: summary: Rate limit exceeded value: error: message: Rate limit exceeded. Retry after the indicated delay. type: rate_limit_error code: rate_limited capacity_exceeded: summary: Model at capacity value: error: message: >- The model is at capacity. Retry after the indicated delay. type: rate_limit_error code: capacity_exceeded '500': description: Internal error. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: summary: Internal error value: error: message: Internal error. type: api_error code: internal_error '502': description: The model returned an invalid response. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: upstream_error: summary: Invalid model response value: error: message: The model backend returned an invalid response. type: api_error code: upstream_error '503': description: The model is temporarily unavailable. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: model_unavailable: summary: Model unavailable value: error: message: The requested model is temporarily unavailable. type: api_error code: model_unavailable '504': description: The model did not answer in time. Not charged. headers: x-request-id: $ref: '#/components/headers/RequestId' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-used: $ref: '#/components/headers/x-ratelimit-used' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Error' examples: upstream_timeout: summary: Model timed out value: error: message: The model backend did not answer in time. type: api_error code: upstream_timeout components: schemas: DecisionRequest: title: Decision request type: object additionalProperties: false required: - model - state - questions properties: model: type: string minLength: 1 state: anyOf: - type: string minLength: 1 - type: object minProperties: 1 - type: array minItems: 1 questions: type: object minProperties: 1 maxProperties: 128 propertyNames: pattern: ^[A-Za-z0-9_-]{1,64}$ not: pattern: |+ additionalProperties: oneOf: - type: object additionalProperties: false required: - type properties: type: const: noul instructions: type: - string - object - array - 'null' criteria: type: object additionalProperties: false properties: 'true': type: - string - object - array - 'null' 'false': type: - string - object - array - 'null' anyOf: - required: - instructions properties: instructions: not: type: 'null' - required: - criteria - type: object additionalProperties: false required: - type - criteria properties: type: const: choice instructions: type: - string - object - array - 'null' criteria: type: object minProperties: 1 maxProperties: 255 propertyNames: minLength: 1 maxLength: 128 additionalProperties: type: - string - object - array - 'null' - type: object additionalProperties: false required: - type - criteria properties: type: const: score instructions: type: - string - object - array - 'null' criteria: type: array minItems: 1 maxItems: 10 items: type: - string - object - array description: >- A decision request: one `state` and up to 128 named questions about it. Unknown fields are rejected. DecisionResponse: type: object additionalProperties: false required: - model - answers - usage properties: model: type: string description: >- The pinned model id that answered, also when the request named an alias. answers: type: object description: One answer per question, keyed by question name. minProperties: 1 maxProperties: 128 additionalProperties: $ref: '#/components/schemas/Answer' usage: $ref: '#/components/schemas/Usage' Error: type: object additionalProperties: false required: - error properties: error: type: object required: - message - type - code properties: message: type: string description: Human-readable. Never contains request input. type: enum: - invalid_request_error - authentication_error - billing_error - rate_limit_error - api_error code: type: string param: type: string description: >- Path of the offending field, such as `questions.severity.criteria`. Never a value. valid_models: type: array items: type: string replacement_model: type: - string - 'null' required_usd: type: string pattern: ^-?[0-9]+\.[0-9]{6}$ available_usd: type: string pattern: ^-?[0-9]+\.[0-9]{6}$ topup_url: type: - string - 'null' description: >- Console page for adding credit; null while console top-ups are not available. limit_usd: type: string pattern: ^-?[0-9]+\.[0-9]{6}$ resets_at: type: - string - 'null' format: date-time description: >- Start of the key's next spend period, in UTC; null for a lifetime limit. Answer: oneOf: - $ref: '#/components/schemas/NoulAnswer' - $ref: '#/components/schemas/ChoiceAnswer' - $ref: '#/components/schemas/ScoreAnswer' Usage: type: object additionalProperties: false required: - input_tokens - output_tokens properties: input_tokens: type: integer minimum: 0 description: >- Billable input tokens: the `state` counted once plus all `instructions` and `criteria` content. output_tokens: type: integer minimum: 0 description: Reported for information; not billed. NoulAnswer: type: object description: The probability that the answer to a yes/no question is yes. additionalProperties: false required: - type - noul properties: type: const: noul noul: type: number minimum: 0 maximum: 1 ChoiceAnswer: type: object description: >- The most likely option, the model's confidence in it, and the probability of every option, keyed by option name. additionalProperties: false required: - type - choice - confidence - probabilities properties: type: const: choice choice: type: string confidence: type: number minimum: 0 maximum: 1 probabilities: type: object minProperties: 1 maxProperties: 255 additionalProperties: type: number minimum: 0 maximum: 1 ScoreAnswer: type: object description: >- The probability-weighted average of the level indexes as `score`, its `confidence`, the request's level labels as `legend`, and the probability of each level. `legend` and `probabilities` are keyed by the 0-based level index as a string. additionalProperties: false required: - type - score - confidence - legend - probabilities properties: type: const: score score: type: number minimum: 0 maximum: 9 confidence: type: number minimum: 0 maximum: 1 legend: type: object minProperties: 1 maxProperties: 10 propertyNames: pattern: ^[0-9]$ maxLength: 1 additionalProperties: type: - string - object - array probabilities: type: object minProperties: 1 maxProperties: 10 propertyNames: pattern: ^[0-9]$ maxLength: 1 additionalProperties: type: number minimum: 0 maximum: 1 headers: RequestId: description: Unique id of this request (`req_...`). Quote it to support. required: true schema: type: string x-ratelimit-limit: description: >- Requests allowed per second by the tighter of the key and account limits. Sent on every response once the API key is accepted (a body over the global size limit is refused before the key is checked). schema: type: string x-ratelimit-remaining: description: >- Requests left in the current one-second window. Sent on every response once the API key is accepted (a body over the global size limit is refused before the key is checked). schema: type: string x-ratelimit-used: description: >- Requests made in the current window. Sent on every response once the API key is accepted (a body over the global size limit is refused before the key is checked). schema: type: string x-ratelimit-reset: description: >- Whole seconds until the current window resets. Sent on every response once the API key is accepted (a body over the global size limit is refused before the key is checked). schema: type: string RetryAfter: description: Seconds to wait before retrying. required: true schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: A Decision API key from the console (starts with `tcd_`). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.