OpenAI Decisions API tutorial: your first decision call

Step 1 — get a key

Open the playground and press Run once — a guest session, an API key, and 1 free credit are created for you automatically. For production work, sign in and create a named key in the dashboard under API keys. Keys are sent in the Authorization Bearer header..

Keep the key server-side. Every request that carries it is billed to your balance, so never ship it in browser code or a public repo.

Step 2 — send the first request

A decision request has three fields: model (decisions-1 or decisions-latest), state (the context the model reads — a string, JSON object, or array of text), and questions (a map of 1 to 6 question ids). Write the real question in instructions — the id is only the label your answer comes back under.

A noul question is a yes/no judgment: the answer field noul is the probability that the statement is true.

curl https://decisions-api.net/api/v1/decisions \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "decisions-1",
  "state": "I was charged twice for my subscription this morning.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}'

Step 3 — add a choice question

A choice question picks one label from a list you define. criteria is an object of 2 to 8 option ids, each with a short description — the description is what the model reads, so write it like a routing rule.

A score question works the same way but takes an ordered array of 2 to 10 level descriptions, lowest first. You can mix all three types in one call, up to six questions total.

{
  "team": {
    "type": "choice",
    "instructions": "Which team should own this ticket?",
    "criteria": {
      "payments": "Checkout, billing, or payment processing.",
      "frontend": "Rendering or browser behavior.",
      "account": "Login, permissions, or profile."
    }
  }
}

Step 4 — read the probabilities

A successful response carries model, answers keyed by your question ids, usage, and credits_used. A noul answer is just the probability. A choice answer includes the winning choice, a probability for every option, and a confidence value.

The runner-up matters as much as the winner. Two options near 0.5 each is a different situation than 0.9 versus 0.1 — treat close calls as review candidates, not confident picks.

{
  "model": "decisions-1",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "credits_used": 1
}

Step 5 — set a threshold and handle errors

Pick a confidence threshold from your own traffic: accept above it, route the rest to a person. Start high (0.7–0.8) and lower it only after reviewing the cases that fell short.

402 means the balance is empty; 429 or 502 mean retry later — failed calls are not billed. 422 is a body validation error and the message names the field.

const res = await fetch('https://decisions-api.net/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})

if (res.status === 402) { /* out of credits */ }
if (res.status === 429 || res.status === 502) { /* retry later */ }

const { answers } = await res.json()
const team = answers.team

if (team.type === 'choice' && team.confidence >= 0.7) {
  routeTo(team.choice)          // confident: auto-assign
} else {
  queueForHuman(team)           // low confidence or near-tie: review
}

FAQ