{"slug": "practical-use-cases-for-openai-s-decisions-api", "title": "Practical use cases for OpenAI's Decisions API", "summary": "OpenAI's Decisions API, accessed through AI SDK's experimental_decide function and AI Gateway, lets applications return a choice, score, or probability for repeated judgment tasks such as matching feature requests to roadmap themes and checking incident handoffs for missing context. The API's yes/no question type is called a predicate, mapped to boolean in AI SDK decisions, while choice questions select an allowed option and score questions assess evidence against ordered levels. A handoff-check example using GPT-6 Luna Decisions on AI Gateway requires Node.js 22.18 or later and the ai and @ai-sdk/gateway packages.", "body_md": "[OpenAI's Decisions API](https://vercel.com/i/what-is-openai-decisions-api) can help applications organize feature requests, assess incident handoffs, and flag documentation that needs review. You supply evidence and define the question's possible answers. The model returns a choice, score, or probability that your code can use to suggest a next step.\n\nThe useful starting point is a judgment someone already makes repeatedly. Write down the evidence they need and what a correct answer would change in the workflow, then test whether the model makes that judgment on representative examples.\n\n## [Copy link to heading](#which-question-type-fits-each-use-case)Which question type fits each use case?\n\nOpenAI calls its yes/no question type a `predicate`. Through [AI SDK decisions](https://ai-sdk.dev/docs/ai-sdk-core/decisions), the corresponding type is `boolean`; both return the probability that the statement is true. Choice questions select an allowed option, and Score questions assess evidence against ordered levels.\n\nThese are workflow designs to evaluate against your own examples. Their usefulness depends on the question definitions and the evidence your application supplies.\n\n## [Copy link to heading](#1.-match-feature-requests-to-roadmap-themes)1. Match feature requests to roadmap themes\n\nFeature requests often describe a proposed solution without naming the underlying need. For example, \"Let me send my saved view to a teammate\" describes sharing an existing view, which may fit a collaboration theme.\n\nSupply the request alongside your current theme definitions. Ask, \"Which theme best matches the outcome this person wants?\" Define collaboration around sharing work with others and reporting around producing or inspecting summaries. Include an `outside_themes` option for a clear request that doesn't fit, and `needs_context` when the goal is unclear.\n\nThe selected theme can become a suggestion beside the request. Product staff can correct it before using grouped requests to assess demand.\n\n## [Copy link to heading](#2.-check-incident-handoffs-for-missing-context)2. Check incident handoffs for missing context\n\n\"Rolled back, looks better\" leaves the next responder guessing about the original impact and what still needs attention. An effective handoff states what customers experienced, describes the attempted mitigation and its outcome, and names the next action's owner.\n\nAsk separate questions about those requirements. For example, a Boolean question can check whether customer impact is described, while a Score question assesses coverage of the whole handoff. The application can show these assessments beside the note, prompting its author to check the requirements and add missing context before transferring responsibility.\n\n### [Copy link to heading](#try-a-handoff-check-through-ai-gateway)Try a handoff check through AI Gateway\n\nWith Node.js 22.18 or later, install the packages for the experimental decision API. Use **ai**\n\n```\nnpm install ai @ai-sdk/gateway\n```\n\nFollow the [decision quickstart](https://vercel.com/docs/ai-gateway/getting-started/decision) to configure server authentication with **AI_GATEWAY_API_KEY**[Vercel OIDC](https://vercel.com/docs/ai-gateway/authentication-and-byok/oidc).\n\nThis example uses [GPT-6 Luna Decisions on AI Gateway](https://vercel.com/ai-gateway/models/gpt-6-luna-decisions). It prints three assessments of a fictional handoff without changing the incident or notifying another responder.\n\n``` js\nimport { experimental_decide as decide } from 'ai';import { gateway } from '@ai-sdk/gateway';\nconst handoff = `Checkout requests failed for about 10% of customers.Rolling back the payment adapter restored checkout success rates.Maya will watch the checkout error dashboard until 15:00 UTC andreopen the investigation if the error rate exceeds 2%.`;\ntry {  const result = await decide({    model: gateway.decisionModel('openai/gpt-6-luna-decisions'),    state: handoff,    questions: {      impactDescribed: {        type: 'boolean',        instructions:          'Does the note describe an effect on customers or their work? ' +          'An internal alert without a described customer effect does not count.',      },      nextStep: {        type: 'choice',        instructions: 'Which next step does the note explicitly describe?',        criteria: {          investigate: 'A concrete diagnostic or repair action is the next step.',          monitor: 'Observe a named signal after a mitigation or recovery.',          clarify: 'The next step is absent, vague, or contradictory.',        },      },      coverage: {        type: 'score',        instructions:          'Assess how completely the note documents customer impact, ' +          'attempted mitigation and its outcome, and a next action with an owner. ' +          'Judge only what is written; do not assume omitted information.',        criteria: [          'None of those handoff requirements is meaningfully documented.',          'Some requirements are documented, but at least one is missing.',          'All requirements are documented, including an owner for the next action.',        ],      },    },    maxRetries: 0,    abortSignal: AbortSignal.timeout(30_000),  });\n  console.log(JSON.stringify(result.answers, null, 2));} catch {  console.error('Handoff assessment failed. Keep the note available for review.');  process.exitCode = 1;}\n```\n\nSave the example as `review-handoff.mjs` and run `node review-handoff.mjs` with your API key exported in the shell. If the key is in `.env.local`, add Node's `--env-file=.env.local` option before the filename.\n\nFor local OIDC, run `vercel link` to connect your working directory to a Vercel project, then `vercel env pull .env.local` to download its environment variables, including the OIDC token. Use the same Node option to load that file, and rerun the pull command when the token expires.\n\nRead `impactDescribed.probability` as the probability that the note describes customer impact. The `nextStep.choice` value classifies the action written in the note. Neither answer establishes that the service has recovered.\n\nThe coverage rubric has indices 0, 1, and 2. Its score is a probability-weighted position on those levels and can fall between them. Display the score with the rubric and original text so the reviewer can inspect the judgment. The example has no automatic acceptance threshold; choose one only after testing reviewed handoffs, including notes with a convincing recovery claim but no owner.\n\n## [Copy link to heading](#3.-identify-contradictions-between-documentation-pages)3. Identify contradictions between documentation pages\n\nSuppose an installation guide says a service reloads configuration automatically, but a troubleshooting page instructs users to restart it after the same change. An editor needs to know whether the pages disagree or describe different conditions.\n\nProvide both passages with their product versions and deployment context. Ask which relationship applies: `consistent`, `conflicting`, or `insufficient_context`. Define conflict as incompatible instructions for the same supported situation. Differences between a hosted deployment and a local process should not count as a contradiction when each page states that scope.\n\nSend suspected conflicts to the owner of the affected documentation. Include both source passages in the review item. The answer identifies a possible inconsistency; deciding which instruction is correct still requires implementation evidence or a verified procedure.\n\n## [Copy link to heading](#4.-assess-whether-a-migration-guide-covers-required-changes)4. Assess whether a migration guide covers required changes\n\nMigration instructions can mention a new configuration name while omitting what readers must do with an existing value. To check coverage, supply the guide with the actual migration requirements, including any conditions under which a step applies.\n\nFor a fictional SDK update, one requirement might be, \"Move the timeout from the client constructor to each request, preserving its value.\" Ask how fully the guide explains that requirement, using levels such as absent, mentioned without actionable instructions, and explained with an applicable before-and-after example.\n\nDefine one question per requirement so a strong configuration section cannot hide missing instructions elsewhere. Each question can share the same guide text. Use the returned scores to prioritize editorial work, then execute the documented migration against a sample project to check that the instructions work.\n\n## [Copy link to heading](#5.-decide-whether-to-ask-a-follow-up-question)5. Decide whether to ask a follow-up question\n\nBefore preparing a data export, an assistant may need a workspace and a date range. If the conversation says \"Export last month's data\" and the account has several workspaces, choosing one silently could produce the wrong file.\n\nResolve exact values in code first, including relative dates in the user's timezone and any structured workspace selection. Supply the remaining conversation context and ask, \"Has the user unambiguously identified which workspace to export?\" Define references such as \"the same workspace as before\" using the actual conversation history available to the application.\n\nIf the evidence is insufficient, your application can ask a prepared clarification question. Decisions API returns the assessment; a template or separate language-model call writes the follow-up. Check the user's access to the chosen workspace before starting the export, regardless of the model's answer.\n\n## [Copy link to heading](#6.-check-screenshots-against-submission-requirements)6. Check screenshots against submission requirements\n\nWhen reporting a failed deployment, users sometimes attach a project overview instead of the failure details. You could ask a Predicate question such as, \"Does the screenshot visibly include both the deployment status and an error message?\" When the returned probability is low, prompt the submitter to inspect the attachment before sending the report.\n\nOpenAI's direct Decisions endpoint [accepts image input alongside text](https://developers.openai.com/api/docs/guides/decisions). Send the screenshot as an inline base64 data URL with an `input_image` part and supply the visible-content requirements in the question. Gateway's [OpenAI-compatible Decisions endpoint](https://vercel.com/docs/ai-gateway/sdks-and-apis/openai-decisions) currently accepts text only, so this image workflow requires direct OpenAI access.\n\nTest cropped images, small text, and screenshots of successful deployments as well as clear failures. Keep an option to submit for human review when the image is unreadable or the reported problem doesn't produce an error message.\n\n## [Copy link to heading](#7.-triage-github-pull-requests-by-review-needs)7. Triage GitHub pull requests by review needs\n\nSome changes need a compatibility review even when the diff is small. Renaming an exported configuration field, for example, can require callers to update their code.\n\nSupply the changed code and relevant interface documentation, then ask which review track fits the visible change. An independent Predicate question can assess whether existing callers need migration guidance. Include a review outcome for diffs that don't provide enough context to judge the effect.\n\nThe [pull request triage tutorial](https://vercel.com/i/triage-github-pull-requests-openai-decisions-api) shows how to collect GitHub evidence and interpret the returned answers. Use those answers to organize review while keeping repository checks and reviewer approval responsible for merging the change.\n\n## [Copy link to heading](#what-should-stay-outside-the-model's-decision)What should stay outside the model's decision?\n\nFixed requirements belong in application code. Field presence, file-size limits, and permissions can be checked directly. Use a decision model where satisfying the requirement depends on interpreting the supplied content, such as whether an incident note explains the customer impact.\n\nProbability describes the model's prediction about the stated question. Set acceptance rules using labeled examples and the consequences of an incorrect answer. Keep a completed assessment that requests clarification distinguishable from a failed request. Refused questions have no usable answer, and AI SDK rejects the call if any question is refused.\n\nThe API also cannot inspect material your application hasn't supplied. Documentation comparisons need the relevant passages and scope, while a migration review needs the requirements against which the guide should be assessed. Preserve that evidence with the result so a reviewer can correct the judgment.\n\n## [Copy link to heading](#when-should-you-compare-openai's-decisions-api-with-jev)When should you compare OpenAI's Decisions API with Jev?\n\nFor the text-based workflows above, you can also evaluate Jev through AI Gateway. The AI SDK example can use `typesafe-ai/jev` with the same question definitions, letting you compare both models against the same handoff notes and rubric.\n\nIf your application already uses Jev, include its current results as the baseline. Compare the judgments with reviewed examples and check how each model's probabilities affect your acceptance rules. Matching answer formats don't establish that an existing threshold will work equally well with both models.\n\nThe [OpenAI Decisions API vs. Jev comparison](https://vercel.com/i/openai-decisions-api-vs-jev) covers input support, response formats, and confidence handling when choosing an integration.\n\n## [Copy link to heading](#frequently-asked-questions)Frequently asked questions\n\n### [Copy link to heading](#which-openai-decisions-api-use-case-should-i-try-first)Which OpenAI Decisions API use case should I try first?\n\nStart with a repeated review task for which you already have examples and agreed criteria, such as checking incident handoffs. Use the first integration to suggest assessments beside the original evidence, then compare its judgments with those of your reviewers before automating a follow-up action.\n\n### [Copy link to heading](#can-one-request-assess-several-aspects-of-the-same-input)Can one request assess several aspects of the same input?\n\nYes. OpenAI's Decisions API supports multiple independent questions about shared input. Give each question the evidence it needs; if a later question depends on an earlier answer, have your application make separate calls.\n\n### [Copy link to heading](#can-the-api-explain-what-is-missing-or-rewrite-the-input)Can the API explain what is missing or rewrite the input?\n\nNo. Its typed answers provide selections, scores, and probabilities rather than a written explanation or revision. Use individual questions to identify which requirement needs attention, then let a person or a separate generation step revise the content.\n\n### [Copy link to heading](#do-these-use-cases-require-training-a-custom-model)Do these use cases require training a custom model?\n\nYou can start by defining questions and allowed answers in the request, without training a custom model. You still need representative examples with reviewed answers to assess whether the model and question definitions meet the workflow's requirements.\n\n### [Copy link to heading](#does-a-low-boolean-probability-mean-the-answer-is-uncertain)Does a low Boolean probability mean the answer is uncertain?\n\nNo. Low probability indicates that the stated condition is unlikely to be true. In the handoff example, that means the note probably does not describe customer impact; it does not indicate whether the real incident affected customers.", "url": "https://wpnews.pro/news/practical-use-cases-for-openai-s-decisions-api", "canonical_source": "https://vercel.com/i/openai-decisions-api-use-cases", "published_at": "2026-10-08 02:55:56+00:00", "updated_at": "2026-10-08 03:18:48.917507+00:00", "lang": "en", "topics": ["ai-products", "ai-tools", "developer-tools", "large-language-models", "artificial-intelligence"], "entities": ["OpenAI", "Decisions API", "AI SDK", "AI Gateway", "Vercel", "GPT-6 Luna Decisions", "Node.js 22.18"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/practical-use-cases-for-openai-s-decisions-api", "markdown": "https://wpnews.pro/news/practical-use-cases-for-openai-s-decisions-api.md", "text": "https://wpnews.pro/news/practical-use-cases-for-openai-s-decisions-api.txt", "jsonld": "https://wpnews.pro/news/practical-use-cases-for-openai-s-decisions-api.jsonld"}}