Chat Completions API

Body Parameters

stream

Stream the response as it is generated.

true—The response is sent via Server-Sent Events as tokens are generated (default).
false—The full response is returned in a single JSON payload.

temperature

Controls randomness. Higher values make output more random, lower values make it more focused and deterministic.

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. Valid values: [0, 2].

top_p

Nucleus sampling. Considers only tokens with the top_p probability mass.

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. Valid values: (0, 1].

tool_choice

Controls which tools the model may call.

"none"—The model will not call any tools and will generate a response directly.
"auto"—The model decides whether to invoke one or more tools or generate a response directly. This is the default when tools are provided.
"required"—Behaves identically to "auto". Full enforcement of required tool calls is a known limitation and is planned for a future release.
Any other string—Treated as "none". The model will not call any tools.
(omitted)—Defaults to "auto" behaviour.
Object — Restricts the model to a subset of the provided tools. Only tools present in both the allowlist and the tools array are visible to the model. Useful when you want to vary available tools across requests without changing the tools payload, preserving prompt cache. Constraints:
- type must be "allowed_tools"
- mode must be "auto"
- Each entry in tools must include type and name
json
```
{
  "type": "allowed_tools",
  "mode": "auto",
  "tools": [
    {"type": "function", "name": "get_weather"},
    {"type": "function", "name": "get_horoscope"}
  ]
}
```

tools

Defines the tools available to the model.

If omitted, the model has access to both agentaus_web_search and agentaus_web_fetch by default.
Two built-in tools are available:
agentaus_web_search—Searches the web for current information using a query string. Returns up to 10 results with titles, URLs, and content snippets.
agentaus_web_fetch—Fetches and extracts the full text content of a specific URL. Designed to be used after agentaus_web_search to read a discovered page.
Each built-in tool is an object with a type field set to either "agentaus_web_search" or "agentaus_web_fetch". Example:

json

{"type": "agentaus_web_fetch"}

Custom tools must set type to "function" and include a function object containing name, description, parameters, and required. Example:

json

{
  "type": "function",
  "function": {
    "name": "get_exchange_rate",
    "description": "Get the exchange rate between two currencies",
    "parameters": {
      "type": "object",
      "properties": {
        "from": {"type": "string", "description": "Source currency code"},
        "to": {"type": "string", "description": "Target currency code"}
      },
      "required": ["from", "to"]
    }
  }
}

When the model responds with a tool call, only one tool call is returned per response.
Mixing built-in and custom tools in the same request is not yet supported.

Response

The API returns a JSON object with the following fields:

choicesarray

Array of completion choices (currently always one element).

createdinteger

Unix timestamp of when the completion was created.

idstring

Unique completion identifier.

modelstring

Model used (e.g. agentaus).

objectstring

Always chat.completion.

usageobject

Token usage statistics for the request.

choices

Each object in the array

indexinteger

Index of the choice.

finish_reasonstring

Reason the model stopped: stop (final answer) or tool_calls (model wants to call a tool).

logprobsnull

Always null.

messageobject

The generated message.

message

contentstring | null

The generated text, or null when finish_reason is tool_calls.

refusalstring | null

Refusal message, if the model declined to answer.

rolestring

Always assistant.

tool_callsarray

Array of tool call objects, present only when finish_reason is tool_calls.

Each object in the array

idstring

Identifier of the tool call.

typestring

Always function.

functionobject

The function the model wants to call.

namestring

Name of the function to call.

argumentsstring

Arguments as a JSON-encoded string.

usage

input_tokensinteger

Total number of input tokens processed.

output_tokensinteger

Number of tokens generated in the response.

Two response shapes

Read finish_reason first — it tells you which of the two payloads you are holding.

finish_reason: "stop"

No tool call triggered, or built-in tools were used. The answer is final.

content: The response text
tool_calls: []

finish_reason: "tool_calls"

A custom function tool was invoked by the model. Run it and send the result back.

content: null
tool_calls: Function name and arguments

Chat Completions API

On this page