跳到导航

Decision API Reference

Text evaluation contracts, accounting, and errors for Decisions and System One
Experimental. These contracts require a worker with decision-scoring support.

NVIDIA Dynamo exposes two non-streaming text-evaluation contracts. For runnable curl and SDK examples, see the Decision Model API guide.

Contracts

PropertyOpenAI DecisionsJev System One
RoutePOST /v1/decisionsPOST /v1/systemone
ClientOfficial OpenAI Python SDKOfficial Jev/TypeSafe Python SDK
Shared inputinputstate
QuestionsOrdered array with optional nameObject keyed by question name
Classificationtype: "choice", choices with typed string/boolean valuestype: "choice", string-valued criteria keys
Binary judgmenttype: "predicate"; answer has probabilitytype: "noul"; answer has noul
Ordered scorelevels containing labels; answer has a zero-based expected scoreOrdered criteria; answer has expected score and an index-to-label legend
Choice count2–255 before backend/tokenizer limits1–255 before backend/tokenizer limits
Score level count2–101–10
AnswersArray in question order; preserves omitted, empty, and duplicate names; can include type: "refusal"Object keyed by question name; a refusal produces an error instead
DistributionsOrdered arrays of value/probability entriesProbability maps keyed by choice or score index
SDK base_urlAPI root, including /v1Server origin, without /v1

The public contracts are the supported text-evaluation subset of OpenAI Decisions and Jev/TypeSafe System One. Do not send SGLang-native /v1/decisions request fields to Dynamo. Neither route accepts nvext, including {} or {"format":"oai"}.

Use the exact model alias returned by GET /v1/models. Supported inputs, candidate counts, and accounting depend on the model/executor profile. Dynamo currently admits at most 128 questions per request, subject to independent aggregate resource limits. These APIs accept text inputs; image, audio, and video inputs are not supported by the documented profiles.

Usage

Input usage counts rendered prompts across question executions, not only the shared input text. SGLang scores without decoding output tokens. OpenAI total_tokens is the sum of input_tokens and output_tokens. Cache-read values come from backend counters or a profile verified to perform no cache reads; Dynamo returns 500 rather than reporting an unmeasured read count as zero. Questions in one request can reuse cached prefixes, but separate requests do not share them.

Dynamo currently always returns usage.input_tokens_details.cache_write_tokens: 0 because cache-write usage is not measured. This value does not mean that caching is disabled or that no KV blocks were written. The current Decisions response schema requires an integer, so omission, null, and "N/A" are not supported. Use cached_tokens for measured cache reads; it is separate from the unmeasured write count.

Answer Statistics

x_label_mass is a Dynamo extension on Jev answers reporting candidate vocabulary mass, not another conditional choice probability. It is not added to OpenAI answer objects. confidence is an executor-derived statistic, not a calibrated probability of correctness.

Errors and Headers

OutcomeOpenAI DecisionsJev System One
Invalid or unsupported request shape400422
Executor refused a question200 with a type: "refusal" answer422, code decision_refused
Unknown model404404
Registered model lacks decision capability400400
Eligible worker unavailable503503
Invalid backend scoring result or usage500500
Admission capacity exhaustedConfigured overload status, default 529Configured overload status, default 529
Request deadline exceeded504504

An OpenAI refusal is an answer variant, not an HTTP error. If an executor refuses any Jev question, Dynamo returns decision_refused for the request rather than a partial answer object.

Capacity responses have code rate_limit_exceeded and Retry-After: 1; status alone does not identify overload. OpenAI errors use a nested error object; Jev uses top-level error fields. Responses expose x-request-id and x-typesafe-request-id.

For enablement, admission limits, and cache isolation, see Decision API Configuration. For backend-specific requirements, see the SGLang guide.