Decisions

Overview

The decisions endpoint answers a list of questions about one input. Instead of generated text, you get one typed answer per question, each with a probability. Use it for routing, classification, scoring and other decision points in your application, where you need a predictable answer rather than prose. Send the endpoint an input, the fully qualified state you’d like to ask questions about, and a list of questions, each of which takes one of the following three forms:

Type	Asks	Request fields	Answer fields
`predicate`	Is this true?	`instructions`	`probability`
`choice`	Which of these options is it?	`instructions`, `choices` (at least 2, with unique `value`s)	`choice`, `probabilities`, `confidence`
`score`	Where does it fall on a scale?	`instructions`, `levels` (2 to 10)	`score`, `probabilities`, `confidence`

Models

Model	Provider	Regions	Input
`gpt-6-luna`	OpenAI	US, global	Text; `instructions` can include images
`jev-1.13.0`	Typesafe AI (Jev)	US	Text only

Use the exact model ID. Model aliases aren’t accepted on this endpoint.

Jev is an opt-in provider and is disabled by default. To use jev-1.13.0, review and accept the Jev opt-in terms on the Data Controls page in your dashboard. Until you do, requests to Jev return 400 with a link to that page.

Make a request

This example asks three questions about a support call transcript.

curl -X POST "https://llm-gateway.assemblyai.com/v1/decisions" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "Agent: Thanks for calling Northwind Internet, this is Priya. Can I get your account number?\nCustomer: Sure, it'\''s 4471-2209.\nAgent: Thanks. And can you confirm the address on the account?\nCustomer: 18 Harbor Lane. My internet has dropped three times today and I work from home.\nAgent: I'\''m sorry about that. There'\''s an outage in your area. A technician is already on it, and it should be fixed by 5 PM.\nCustomer: Okay, that'\''s fine. Thanks for letting me know.",
    "questions": [
      {
        "type": "predicate",
        "name": "confirmed_account_details",
        "instructions": "Did the agent ask the caller to confirm their account details?"
      },
      {
        "type": "choice",
        "name": "call_outcome",
        "instructions": "How did the call end?",
        "choices": [
          {"value": "resolved", "description": "The issue was fixed or fully answered on the call"},
          {"value": "follow_up", "description": "The customer was told the issue will be fixed later"},
          {"value": "escalated", "description": "The call was transferred or escalated"}
        ]
      },
      {
        "type": "score",
        "name": "customer_sentiment",
        "instructions": "How did the customer feel at the end of the call?",
        "levels": [
          {"label": "negative", "description": "Upset or frustrated"},
          {"label": "neutral", "description": "Neither upset nor pleased"},
          {"label": "positive", "description": "Satisfied or thankful"}
        ]
      }
    ]
  }'

import requests

transcript = (
    "Agent: Thanks for calling Northwind Internet, this is Priya. Can I get your account number?\n"
    "Customer: Sure, it's 4471-2209.\n"
    "Agent: Thanks. And can you confirm the address on the account?\n"
    "Customer: 18 Harbor Lane. My internet has dropped three times today and I work from home.\n"
    "Agent: I'm sorry about that. There's an outage in your area. A technician is already on it, and it should be fixed by 5 PM.\n"
    "Customer: Okay, that's fine. Thanks for letting me know."
)

response = requests.post(
    "https://llm-gateway.assemblyai.com/v1/decisions",
    headers={"authorization": "<YOUR_API_KEY>"},
    json={
        "model": "gpt-6-luna",
        "input": transcript,
        "questions": [
            {
                "type": "predicate",
                "name": "confirmed_account_details",
                "instructions": "Did the agent ask the caller to confirm their account details?",
            },
            {
                "type": "choice",
                "name": "call_outcome",
                "instructions": "How did the call end?",
                "choices": [
                    {"value": "resolved", "description": "The issue was fixed or fully answered on the call"},
                    {"value": "follow_up", "description": "The customer was told the issue will be fixed later"},
                    {"value": "escalated", "description": "The call was transferred or escalated"},
                ],
            },
            {
                "type": "score",
                "name": "customer_sentiment",
                "instructions": "How did the customer feel at the end of the call?",
                "levels": [
                    {"label": "negative", "description": "Upset or frustrated"},
                    {"label": "neutral", "description": "Neither upset nor pleased"},
                    {"label": "positive", "description": "Satisfied or thankful"},
                ],
            },
        ],
    },
)

for answer in response.json()["answers"]:
    print(answer)

input is the evidence every question is asked about. It can be a string, such as a transcript’s text, or an array of user messages made of input_text parts. instructions can be a string, or an array of input_text parts (and input_image parts on gpt-6-luna).

Read the response

Answers come back in the order the questions were asked. The response also includes request_id, model and usage, which are omitted here.

{
  "answers": [
    {"type": "predicate", "name": "confirmed_account_details", "probability": 1},
    {
      "type": "choice",
      "name": "call_outcome",
      "choice": "follow_up",
      "probabilities": [
        {"value": "resolved", "probability": 0.01},
        {"value": "follow_up", "probability": 0.99},
        {"value": "escalated", "probability": 0}
      ],
      "confidence": 0.99
    },
    {
      "type": "score",
      "name": "customer_sentiment",
      "score": 1.99,
      "probabilities": [
        {"value": 0, "label": "negative", "probability": 0},
        {"value": 1, "label": "neutral", "probability": 0.01},
        {"value": 2, "label": "positive", "probability": 0.99}
      ],
      "confidence": 0.99
    }
  ]
}

predicate: probability is the probability that the statement is true.
choice: choice is the most likely option. probabilities lists every option in the order you gave them.
score: score is the expected level index, weighted by probability, so it can fall between levels. For a single level, take the one with the highest probability in probabilities. Each entry’s value is the level’s index.

Fallbacks

Decisions supports fallbacks. A fallback can omit input and questions, which it inherits from the main request. Nested fallbacks aren’t supported, and fallback_config.depth can be at most 2.

{
  "model": "gpt-6-luna",
  "input": "...",
  "questions": [...],
  "fallbacks": [{"model": "jev-1.13.0"}]
}

A fallback to Jev requires the Jev opt-in. If the request uses image parts, the Jev fallback can’t run them.

Regions and global routing

Decisions is available on the US endpoint (https://llm-gateway.assemblyai.com/v1). It isn’t available on the EU endpoint. Set model_region to "global" to use global routing with gpt-6-luna. Jev doesn’t support global routing. A fallback uses the main request’s model_region unless it sets its own.

Prompt caching

gpt-6-luna caches the input automatically, so requests that reuse the same input with different questions read it from the cache. Set prompt_cache_key to keep requests that should share a cache together. Cached tokens are reported in usage.input_tokens_details.cached_tokens. See Prompt caching.

Limits and errors

A request can have 1 to 400 questions. Question names must be unique.
Unknown request fields are rejected.
Invalid requests return 400, with every problem listed in metadata.errors.

See Rate limits and Troubleshooting for other status codes.

API reference

See Create a decision for every request and response field.

Getting started

Gateway features

Chat completions

API reference

Voice AI Guides

Decisions

Overview

Models

Make a request

Read the response

Fallbacks

Regions and global routing

Prompt caching

Limits and errors

API reference

​Overview

​Models

​Make a request

​Read the response

​Fallbacks

​Regions and global routing

​Prompt caching

​Limits and errors

​API reference

Overview

Models

Make a request

Read the response

Fallbacks

Regions and global routing

Prompt caching

Limits and errors

API reference