Decisions API Documentation: Request Format, Question Types, and a Working Example

Launch note: OpenAI Decisions API is coming soon. Until OpenAI publishes its final public contract, the examples in this article use the currently available Jev AI format—shared state, typed questions, and structured answers—to demonstrate how a decision API works. These examples explain the integration pattern; they are not an official OpenAI request schema.

If you are looking for decisions api documentation or a decisions api example, the core idea is simple: send a piece of application state, describe one or more bounded questions, and receive typed answers that your code can inspect. The result is designed for classification, routing, scoring, safety checks, and other places where software needs a signal rather than another paragraph of generated text.

This guide turns the public Decisions API documentation into a practical implementation path. It covers the REST endpoint, request fields, Choice / Score / Noul questions, a complete support-ticket example, response handling, and the controls you should keep in your own application. Field availability and model behavior can change, so check the live docs before shipping a critical workflow.

Table of contents

• What Decisions API does
• The request format
• State: give every question the right context
• Question types: Choice, Score, and Noul
• A complete Decisions API example
• Reading the structured response
• Asking multiple questions in one request
• Error handling, retries, and uncertainty
• From playground to production
• When to use a decision API
• Frequently asked questions

What Decisions API does

A conventional chat request asks a model to generate language. A decision request asks the model to make a small, explicit judgment that the surrounding program can use. The application defines the question and the answer space; the model supplies the semantic signal; deterministic code owns the final action.

The public Decisions API currently exposes a single evaluation endpoint:

POST https://decisionapi.net/v1/systemone

Requests use a server-side API key in the Authorization header and a JSON body with three required top-level fields:

• model: the available decision model that should evaluate the request.
• state: the text, object, or array of text that provides the shared context.
• questions: a map of named questions to evaluate against that state.

The question keys are application-owned identifiers. They are returned under the same keys, which makes it easier to connect an answer to the branch that consumes it. The keys are not sent to the underlying model as hidden instructions; the question content lives in instructions and, when needed, criteria.

The endpoint is intentionally narrow. It is not a chat assistant, a database, or an authorization service. It can tell your application that a support ticket looks like billing, that a proposed action appears risky, or that a piece of evidence supports a claim. Your application must still validate data, check permissions, apply thresholds, and decide what is allowed to happen.

The request format

The smallest valid request looks like this:

{
  "model": "typesafe/jev-1.13",
  "state": "Help! My payouts have been failing for 3 days.",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this message convey urgency?"
    }
  }
}

The request should be sent with these headers:

Authorization: Bearer <API_KEY>
Content-Type: application/json

Keep the API key on your server. Do not put it in browser JavaScript, a public repository, a client-side environment variable, or a prompt that can be shown to an end user. A browser can call your own backend, and your backend can call the Decisions API.

The model value must match an available model ID. The live model list is the source of truth for current availability and supported question types. Different models may have different latency, price, language coverage, and quality characteristics, so store the model ID with your evaluation logs.

Keep state small and relevant

state is the context every question reads. It may be:

• a string for a simple ticket, message, or claim;
• a JSON object for records with named fields;
• an array of text items when several snippets should be considered together.

Include the minimum evidence needed for the question. A support-routing question may need the customer message, product area, account tier, and recent events. It usually does not need the entire account history or an unrelated conversation archive. Smaller state is easier to audit, cheaper to send, and less likely to introduce distracting evidence.

The current documentation describes text, JSON objects, and arrays of text as supported input forms. Do not assume that image, audio, or video inputs are supported just because a different model or product can handle them; verify the current endpoint contract first.

Ask one bounded question at a time

Good questions have a clear decision target and a finite interpretation:

• Which approved team should handle this case?
• How severe is the issue on the defined scale?
• Does the proposed tool call require human review?

Avoid combining unrelated decisions in one instruction, such as “classify the ticket, decide whether to refund, and draft a reply.” Split those into separate questions and keep the refund decision behind deterministic permissions and, where needed, a human approval step.

Question types: Choice, Score, and Noul

Decisions API uses three practical question shapes. They are visualized below as a branching choice, an ordered scale, and a yes-or-no probability. The exact supported types depend on the selected model.

Choice: select one allowed label

Use choice when the application needs one answer from a predefined set, such as billing, technical, sales, or manual_review. The criteria object maps each option to a description. Descriptions make the boundary between options explicit and give reviewers something concrete to evaluate.

{
  "type": "choice",
  "instructions": "Which team should handle this customer message?",
  "criteria": {
    "billing": "Payments, invoices, refunds, or duplicate charges",
    "technical": "Bugs, outages, API failures, or integration problems",
    "sales": "Pricing, upgrades, new accounts, or plan questions",
    "manual_review": "The message does not fit the approved routes"
  }
}

Always include a fallback when real-world inputs may not fit the first three categories. A fallback is safer than forcing an unfamiliar case into a plausible but wrong queue.

Score: rate an ordered rubric

Use score when the answer represents a position on an ordered scale: urgency, completeness, risk, satisfaction, or relevance. criteria is an ordered array from low to high. The returned score can be probability-weighted, so it may fall between the discrete levels.

{
  "type": "score",
  "instructions": "How urgent is this support request?",
  "criteria": [
    "No operational impact",
    "Work is slowed but a workaround exists",
    "A customer or internal workflow is blocked",
    "Time-sensitive incident with material business impact"
  ]
}

The labels need operational definitions. “Low,” “medium,” and “high” mean different things to different teams unless you explain what changes at each level.

Noul: ask a focused yes-or-no question

Use noul for a binary judgment. The noul value is the probability that the answer is yes, from 0 to 1. Optional criteria describe what true and false mean in your workflow.

{
  "type": "noul",
  "instructions": "Does this request need immediate human attention?",
  "criteria": {
    "true": "The request is explicitly time-sensitive or blocks a critical workflow",
    "false": "The request is not time-sensitive and can follow the normal queue"
  }
}

Noul is useful for evidence checks, approval gates, moderation signals, and escalation criteria. It is not a guarantee of correctness. Treat the returned probability as an input to a policy, not as permission to skip one.

A complete Decisions API example

Here is a realistic example: route a support message, score its urgency, and decide whether it needs immediate human review. All three questions read the same state and are evaluated in parallel.

1. Define the request

{
  "model": "typesafe/jev-1.13",
  "state": {
    "message": "I was charged twice for my annual plan and need a refund before payroll closes today.",
    "customer_tier": "business",
    "recent_events": ["payment_succeeded", "payment_succeeded"]
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which approved team should own this support case?",
      "criteria": {
        "billing": "Payments, invoices, refunds, or duplicate charges",
        "technical": "Bugs, outages, API failures, or integration problems",
        "account": "Login, identity, permissions, or account access",
        "manual_review": "The case is ambiguous or outside the approved routes"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this case for operations?",
      "criteria": [
        "Normal queue",
        "Needs same-day attention",
        "Customer workflow is blocked",
        "Critical and time-sensitive"
      ]
    },
    "needs_human_now": {
      "type": "noul",
      "instructions": "Does this case need immediate human attention?",
      "criteria": {
        "true": "A time-sensitive business impact or sensitive refund decision is present",
        "false": "The case can be handled by the normal support workflow"
      }
    }
  }
}

2. Call the endpoint from a server

The following Node.js example keeps the secret in DECISIONS_API_KEY and treats the remote response as unknown data until it passes local validation.

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

if (!response.ok) {
  throw new Error(`Decisions API failed with ${response.status}`);
}

const result: unknown = await response.json();

If your product has a backend framework, wrap this call in a small provider adapter. Keep transport errors, validation errors, and low-confidence results separate. A timeout is not the same thing as a confident false, and an unknown choice is not the same thing as manual_review unless your code explicitly makes that mapping.

3. Apply policy to the result

For example, your application might route the case to billing, raise the priority, and send it to a human queue when the Noul probability is above a threshold. The model does not directly refund the customer or change a ticket.

const answers = readAndValidateAnswers(result);

if (answers.department.choice === 'manual_review') {
  return sendToHumanQueue('Unapproved or ambiguous route');
}

if (answers.needs_human_now.noul >= 0.8) {
  return sendToHumanQueue('High-probability urgent case', answers);
}

return routeTo(answers.department.choice, {
  urgency: answers.urgency.score,
  source: 'decisions-api',
});

This separation is the central production pattern: the decision model provides a signal, while the application owns authority, permissions, side effects, and audit records.

Reading the structured response

A minimal Noul response is shaped like this:

{
  "model": "typesafe/jev-1.13",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": {
    "input_tokens": 296,
    "output_tokens": 20
  }
}

The response contains the model used, an answers map keyed by your question IDs, and usage details. An answer carries a type that matches its question:

• Choice returns choice, per-option probabilities, and confidence.
• Score returns a probability-weighted score, a legend, per-level probabilities, and confidence.
• Noul returns noul, the probability that the answer is yes.

The probability and confidence fields are useful for thresholds, routing, selective automation, and evaluation. They are not business-accuracy guarantees. A model can be confidently wrong, and a well-calibrated probability still describes an estimate rather than a permission. Log the question version, criteria, model ID, raw answer, applied threshold, final action, and later human outcome so you can evaluate the complete system.

Asking multiple questions in one request

Multiple questions are evaluated against the same state in parallel. This is useful when a workflow needs several independent signals: a route, a priority score, and a review gate. It can reduce orchestration code and keep the evidence visible in one request.

Parallel questions do not mean that the questions should depend on one another. If question B needs the result of question A, make that dependency explicit in application code or use a second request with the new state. Keeping each question independent makes it easier to label examples, compare models, and identify which judgment caused a bad branch.

Name question IDs for machines, not prose paragraphs: department, urgency, needs_human_now, or evidence_supported. Keep the meaning stable. If you change a rubric or criteria description, version the question definition so historical results remain interpretable.

Error handling, retries, and uncertainty

Build around ordinary HTTP failures and malformed or unexpected results. A practical client should:

1. reject missing or empty API keys before sending a request;
2. set a bounded timeout and record the request ID when the service returns one;
3. retry only transient transport or server failures, with a small exponential backoff;
4. avoid blindly retrying validation errors or an invalid question definition;
5. treat missing answers, unknown choices, and impossible scores as validation failures;
6. route high-risk or low-confidence cases to a safe fallback;
7. redact sensitive state from logs while preserving enough metadata for debugging.

The fallback should be a real product path: a human queue, a deterministic rule, a delayed retry, or a request for more information. It should not silently execute a more dangerous action. If an API request fails while deciding whether a destructive tool call is safe, fail closed and require confirmation.

From playground to production

The Decisions API playground is useful for turning a vague automation idea into a concrete state and question. Start with examples that are easy, ambiguous, and adversarial. Change one input at a time. Record which answer a trusted reviewer would choose, not only whether the output looks plausible.

Before production, create a small evaluation set that represents the real distribution of your workflow:

• ordinary cases that should automate;
• boundary cases between two labels;
• incomplete or contradictory state;
• sensitive cases that always need review;
• adversarial wording and prompt-injection attempts;
• cases where the correct answer is the fallback.

Measure route accuracy, score agreement, false-allow and false-block rates, review volume, latency, token usage, and cost per completed business action. Tune thresholds against the cost of mistakes, not against a generic confidence target. A payment approval, a moderation decision, and a low-risk content tag should not share the same automation threshold.

Store API keys in server-side secrets. Validate the response with a runtime schema. Keep a deterministic allowlist for models, routes, tools, and side effects. Record enough context to reproduce a decision without retaining more personal data than your policy allows. Re-check the live workflow guidance and endpoint reference when the product contract changes.

The service can be tested with welcome credits, and the current pricing options describe credit packs and concurrency limits. Treat those values as operational inputs that may change; do not hard-code them into an application policy.

When to use a decision API

Decisions API is a good fit when:

• the application can enumerate the acceptable outcomes;
• the input is shared across several small questions;
• the result will be consumed by code rather than read as a final answer;
• you can define what uncertainty and fallback mean;
• the business action remains under application control.

Use a general language model when the product needs drafting, explanation, synthesis, open-ended research, or a plan that cannot be reduced to a small answer space. Many real systems use both: a general model handles language-heavy understanding, while a fast decision layer classifies, routes, scores, or checks a narrow condition before code acts.

The most useful mental model is:

state + bounded question -> typed decision -> local policy -> action or review

The API makes the first arrow easier to integrate. It does not remove the last two arrows from your responsibility.

Frequently asked questions

Is Decisions API a chat API?

No. It is designed for structured decisions such as a selected label, an ordered score, or a yes-or-no probability. Use a chat or generation API when you need prose, explanation, or open-ended reasoning.

Which endpoint should I call?

The public endpoint documented by DecisionsApi is POST https://decisionapi.net/v1/systemone. Send a model, state, and questions map with a server-side Bearer API key. Verify the current API reference before production deployment.

Can one request contain multiple questions?

Yes. Questions share the same state and are evaluated in parallel. Give each question a stable ID and validate every answer independently.

Is a high probability the same as accuracy?

No. Probability and confidence help you build thresholds and review paths, but they are not guarantees. Evaluate calibration and business outcomes on labeled examples from your own workflow.

Can Decisions API execute a refund or a tool call?

Your application can use an answer to choose a path, but the model should not be your only authorization layer. Keep permissions, allowlists, confirmation requirements, and side effects in deterministic application code.

What makes a good Decisions API example?

A good example includes the real state shape, one bounded question, an explicit answer space or rubric, the request body, the response shape, and the local policy that consumes the answer. The support-routing example above includes all six so it can be adapted without hiding the safety boundary.

Conclusion

The practical Decisions API contract is small: choose an available model, send the smallest useful state, define typed questions, inspect structured answers, and let your application decide what happens next. Start in the playground, validate a labeled set of real cases, keep the API key on the server, and introduce human review wherever the cost of a wrong decision is high.

That approach gives developers a clear path from a Decisions API example to a maintainable production integration without confusing model judgment with business authority.