OpenAI Decisions API docs

Endpoint

Send POST /api/v1/decisions on this host. There is no chat-completions path and no streaming response. GET /api/v1/models lists the model id.

POST https://decisions-api.net/api/v1/decisions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Authentication

Put your dashboard key in Authorization: Bearer. A missing or rejected key returns 401. The playground creates a key for the signed-in account when you run a request.

Quickstart

Set DECISIONS_API_KEY to a key from your dashboard, then send the request below. New visitors get 1 free call, enough for one successful request.

curl https://decisions-api.net/api/v1/decisions \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "decisions-1",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}'

Use with AI coding tools

Copy a prompt with the full request contract, then paste it into Cursor, Claude Code, or ChatGPT together with your task. The same reference is at /llms.txt.

Request body

model is decisions-1 or decisions-latest. state is a string, JSON object, or array of text, up to 60,000 characters. questions is a map of 1 to 6 snake_case ids. The id is only the label your answer comes back under, not a question. Write the real question in instructions, as text of 1 to 2,000 characters.

{
  "model": "decisions-1",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}

Question types

Noul

type noul needs only instructions. The answer field noul is a probability from 0 to 1 that the statement is true. There is no separate confidence field. If you send criteria on a noul question, this endpoint ignores it.

Choice

type choice needs instructions and criteria, an object of 2 to 8 snake_case option ids mapped to descriptions of up to 300 characters. The answer includes choice, probabilities for every option, and confidence.

Score

type score needs instructions and criteria as an ordered array of 2 to 10 level descriptions, lowest first. The answer includes score, a legend of your levels, probabilities, and confidence.

Response

A successful body has model, answers keyed by your question ids, usage with input_tokens and output_tokens, and credits_used. model reports decisions-1 even if you sent decisions-latest. Below is an example response to the quickstart request, with usage left out.

{
  "model": "decisions-1",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "mixed",
      "probabilities": { "mixed": 0.79, "negative": 0.2, "positive": 0.01 },
      "confidence": 0.61
    },
    "needs_follow_up": { "type": "noul", "noul": 0.83 }
  },
  "credits_used": 1
}

Reading probabilities and confidence

Noul is the probability that the statement in instructions is true. Choice and Score return a probability for every option or level, plus confidence.

The runner-up is the signal for a handoff. When confidence is low or two options are close, send the case to a person or ask one more specific question. Do not lower a cutoff until you have looked at those close calls.

Limits

OpenAI Decisions API: what is documented so far

OpenAI announced its Decisions API at DevDay on 2026-09-29: a specialized GPT-6 Luna model that takes text or image context, a question, and a finite answer list, then returns an answer with confidence. It is in limited preview.

OpenAI has not published its request schema, SDK methods, rate limits, or pricing. Everything on this page documents this site's endpoint — do not read it as OpenAI documentation. When OpenAI's reference ships, the fields above describe the same decision pattern: context in, one of your answers out.

How this endpoint differs from the OpenAI Decisions API

OpenAI's Decisions API is a separate product in limited preview, and its request and response schema is not published. This site serves an independent endpoint built on the same decision pattern — a state, typed questions, and answers with per-option probabilities.

• Input: OpenAI's announcement describes text or image context; this endpoint takes text only — a string, JSON object, or array of text up to 60,000 characters.
• Model id: send decisions-1 or decisions-latest. A versioned id such as decisions-1.0 returns 422.
• Answers: OpenAI describes one answer plus a confidence score; this endpoint returns an answer per question id, with a probability for every option or level.
• Availability: OpenAI's Decisions API is in limited preview; this endpoint is callable today with a key from the dashboard.
• Billing: 1 credit per successful call on this site, whatever the token count. OpenAI has not published Decisions API pricing.

Errors

• 401 — missing or rejected API key.
• 402 — the key is valid and the balance cannot cover this call. A failed upstream call does not use a credit.
• 422 — the body failed validation. The message names the field.
• 429 — the decision service is rate limited. Retry later.
• 502 — the decision service did not return answers. No credit is used.