---
title: Decisions API
description: >-
  Use the authenticated Decisions API for bounded predicate, choice, and score
  questions with validated probability results.
ogTitle: Decisions API
ogDescription: >-
  Request structured AI decisions using approved provider access, model policy,
  and Clear Ideas usage tracking.
ogImage: /assets/images/og/ai-decisions-api.webp
navigation:
  icon: fasl fa-code-branch
---

# 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

```http
GET /ai/decisions/capabilities
```

A successful response identifies the supported model:

```json
{"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

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

```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:

```json
{
  "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`.

| Type | Additional request fields | Answer |
| --- | --- | --- |
| `predicate` | None | `probability` between 0 and 1. |
| `choice` | `choices`: 2–255 objects with a unique string or Boolean `value` and optional `description`. | Selected `choice`, `confidence`, and a `probabilities` entry for each offered value. |
| `score` | `levels`: 2–255 objects with a unique `label` and optional `description`, ordered from lowest to highest. | Numeric `score`, `confidence`, and probabilities for zero-based level indexes and their labels. |

For example, a choice question can use:

```json
{
  "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](/ai/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](/ai/ai-credits) and [Model Policy](/ai/model-policy).