OpenAI has rolled out a new API called Decisions, and it is doing its best to make the launch work.
The API evaluates text, images, or both and returns typed answers about 10x faster than the older Responses API. You can get probabilities, choices from a fixed set, or scores against a rubric. The goal is to help developers classify content, route requests, and prioritize work. The announcement landed on Hacker News today with a public beta flag, a playground for testing, and SDK examples in five languages.
The problem is the examples themselves. They are riddled with bugs, typos, and a garbled customer service question that asks to stop future charges instead of cancel a subscription. The whole experience reads as a public beta in the loosest sense of the word, and that is the story worth telling.
Speed Claim
The Decisions API is pitched as a faster alternative to the Responses API. OpenAI says it returns typed answers about 10x faster, with probabilities, choices, and scores available as answer types.
A request has three parts: input, questions, and a model. The input can be text, images, or both. The questions are where the typed answers come from. The model is gpt-6-luna, the only one currently available. The dedicated endpoint is POST /v1/decisions.
The SDK examples cover Python, JavaScript, Go, Ruby, and Java. Each needs a specific version or later to run. The announcement directs readers to the OpenAI SDK for installation instructions.
Playground Testing
The playground is the place to test questions and inputs before writing code. It lets you experiment with the API without committing to a full deployment. That is a reasonable approach, though it is worth noting that the playground is where the garbled question appears.
The playground is meant to let developers see what the API can do before they build anything around it. The announcement does not say whether the playground uses the same infrastructure as the production API, so it is hard to judge how representative its results are. But for a first look, it serves its purpose.
Public Beta Label
The Decisions API is in public beta, and OpenAI expects to reach general availability in the coming weeks. That is a standard launch cadence, and it is not unusual for a beta to have rough edges. What is unusual is how visible those edges are in the documentation itself.
The announcement is careful to frame this as a beta. It does not present the API as finished. But the SDK examples are the documentation for this API, and they are not ready for prime time.
SDK Example Problems
The SDK examples show how to send a request with text and image input, and how to check the response for a specific question. The examples are meant to be copied and pasted, which is a fair expectation. Instead, they contain a series of small failures that add up to a larger problem.
Here is what the examples get wrong:
- The customer service question list includes a garbled question about stopping charges instead of canceling a subscription.
The Garbled Question
The customer service question list is the most striking example of what is wrong with these docs. The list includes three customer service questions, and the third one is a mess. It asks to stop future charges, which is not what the example is trying to do. It is meant to be a customer service question, not an image analysis question, and it reads like a draft that got pushed out before it was reviewed.
The question is meant to be a customer service question, and it reads like a draft that never got finished.
That is a real problem for a company with OpenAI’s reach. The SDK examples are the primary documentation for this API, and they are not ready for prime time.
Predicate Question Example
The predicate question is the example that actually works. It asks whether a product photo shows visible damage, such as a crack, tear, or dent. The request combines the image with instructions to look for those specific types of damage, and it tells the model to ignore shadows and damage to the packaging.
It is a reasonable use case, and the example shows how to structure the request with the image URL encoded in base64. The curl example for the command-line version is complete and looks like it would work if you copied it directly.
The predicate question is a good example of what the API can do. It is a specific, concrete use case that developers can understand and replicate. The fact that it is the only example that actually works is telling.
Versions and Typos
The SDK examples require specific versions of each language’s OpenAI package. Python needs 3.26.0 or later. JavaScript needs 7.30.0 or later. Go needs 3.73.0 or later. Ruby needs 0.101.0 or later. Java needs 4.78.0 or later.
Those are reasonable version numbers. What is less reasonable is that each example contains its own version of the same typo. The input array in each example uses the wrong parameter name, so the request fails to parse. The Python example also misses a closing brace on line 13, which would raise a syntax error when you try to run it.
The SDK examples are the primary documentation for this API. If the examples are broken, the documentation is broken. A developer who copies the Python example as-is will get a syntax error. A developer who copies the JavaScript example as-is will get a parsing error. A developer who copies the Go example as-is will get a parsing error. A developer who copies the Ruby example as-is will get a parsing error. A developer who copies the Java example as-is will get a parsing error.
That is a lot of friction for a beta launch.
Customer Service Question List
The customer service question list is a separate issue. It is not part of the SDK examples, but it is part of the announcement, and it is worth noting. The list includes three questions: a request to cancel a subscription, a request to switch to annual billing, and a request to stop future charges.
The third question is the one that does not make sense. It asks about stopping future charges, which is not a request to cancel a subscription. It is a garbled version of the other two questions, and it appears in the examples as a standalone item.
That is a small detail, but it is a detail that makes the announcement feel unfinished. A beta is supposed to be a work in progress, but the announcement reads like it was pushed out without a final review. The SDK examples are the documentation for this API, and they are not ready for prime time.
Verdict on the Beta
The Decisions API is in public beta, and the announcement says it will reach general availability in the coming weeks. That is a fair expectation for a beta. The API itself may be solid. The playground may be useful. The model may be capable.
What is not solid is the documentation. The SDK examples are riddled with bugs, typos, and a garbled customer service question that reads like a draft that never got finished. For a company with OpenAI’s reach, that is a problem. The documentation is the documentation, and if the documentation is broken, the API is broken.
The irony is that the predicate question example actually works. It is the only example that does. It shows how to structure a request with text and image input, and it produces a probability that developers can use. But it is a single example, and it is surrounded by broken code.
The announcement is doing its best to make the launch work. It is providing a playground, SDK examples, and a public beta flag. It is not providing working code. That is the gap, and it is the story here.
The Decisions API is a real thing. The public beta is a real thing. The SDK examples are not a real thing, at least not in their current form. The playground may be useful. The model may be capable. But the documentation is broken, and broken documentation is a failure, not a beta.
For developers, the takeaway is simple: use the playground to test the API, but do not copy the SDK examples directly. Read them for structure, then check the official API reference for the correct parameter names and syntax. The API may be good. The docs are not. That is the reality of this launch, and it is the story worth telling.
Source material: “Decisions API is in public beta,” openai.com.
Get the Notebook.
The day's best stories and every fresh verdict, in plain English, in your inbox by seven. One email a day, no more.