Decisions API

The Decisions API evaluates text or structured JSON evidence against named questions. It returns probabilities and structured answers for your application to interpret. It does not run an Agent, select an activity, execute tools, or fetch documents and images supplied as URLs.

Use authenticated Clear Ideas API requests. Account model policy, provider-key preference, and AI credit checks apply.

Check Availability

GET /ai/decisions/capabilities

A successful response identifies the supported model:

{"model":"gpt-6-luna"}

The server must have an OpenAI connection that can access Decisions. A model-policy restriction, missing required provider key, or unavailable provider can prevent access. This check verifies configuration and authorization; a subsequent provider request can still fail.

Submit a Decision

POST /ai/decisions
Content-Type: application/json

{
  "model": "gpt-6-luna",
  "input": {"paid": false, "daysOverdue": 12},
  "questions": [
    {
      "type": "predicate",
      "name": "payment.overdue",
      "instructions": "The invoice is overdue when it is unpaid and daysOverdue is greater than zero."
    }
  ]
}

model may be omitted; it defaults to gpt-6-luna. Other model identifiers are rejected. input is a nonempty text string or a JSON object. Put the evidence in this field rather than relying on implicit Site or chat context.

An illustrative response is:

{
  "model": "gpt-6-luna",
  "answers": [
    {"type": "predicate", "name": "payment.overdue", "probability": 0.98}
  ],
  "usage": {
    "input_tokens": 250,
    "output_tokens": 0,
    "total_tokens": 250,
    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0}
  },
  "trace": {
    "id": "860aac81-5fe5-4c29-a74f-f605026dc315",
    "providerRequestId": null,
    "provider": "openai",
    "endpoint": "/v1/decisions",
    "durationMs": 120
  }
}

Use the returned probability with an application-defined threshold. A predicate answer is not an automatically applied Boolean action.

Question Types

Every question requires type, a unique name, and instructions.

For example, a choice question can use:

{
  "type": "choice",
  "name": "payment.priority",
  "instructions": "Choose the collection priority from the invoice evidence.",
  "choices": [{"value":"standard"}, {"value":"urgent"}]
}

A score is the probability-weighted average of the level indexes, so it can be fractional. Three levels have indexes 0, 1, and 2; they do not create an arbitrary numeric range.

An answer can instead be {"type":"refusal","name":"payment.priority"}. Handle refusal explicitly. Answers follow the question order, and the server validates names, types, alternatives, probability totals, and score consistency before returning a successful result.

Request Limits

• 1–400 questions per request.
• Question names match ^[a-z][a-z0-9._-]{0,95}$ and must be unique.
• Instructions and optional alternative descriptions: 1–20,000 characters after trimming.
• Choice values and score labels: 1–1,000 characters; alternatives must be unique.
• The entire normalized request must fit within 256,000 UTF-8 bytes, including questions and evidence. The text-input field also has a 256,000-character schema limit; the byte limit still applies.
• Structured input must be finite, acyclic JSON, with bounded nesting and complexity.

Caller-supplied provider URLs, keys, tools, and extra request fields are rejected. Configure provider access through AI Connections.

Failures and Credits

The provider request has a 30-second timeout and no automatic provider retry. Provider rate limiting returns 429; unavailable or unauthorized provider access can return 503; an invalid provider answer returns 502. Treat these as failed decisions rather than selecting a default action silently.

Usage is recorded as a Decisions operation. Managed-provider credits are calculated from input tokens, with separate cached-input and cache-write rates; output tokens are not charged by the Decisions credit calculation. Customer-key inference is billed directly by the provider. A provider response with valid usage can still incur recorded usage when its answer fails validation.

See AI Credits and Model Policy.