Skip to main content
POST
Create chat completion

Server tools

/v1/chat/completions supports regular function tools and these gateway-managed server tools:
  • gateway:datetime
  • phaseo:web_search
  • phaseo:web_fetch
  • phaseo:advisor
  • phaseo:image_generation

Datetime example

When a server tool is used, usage includes:
phaseo:web_search adds server_tool_use.web_search_requests, server_tool_use.web_search_results, and server_tool_use.web_search_extra_results. phaseo:web_fetch adds server_tool_use.web_fetch_requests.

Streaming note

stream: true is also supported. For gateway-managed server tools, Phaseo may materialize the upstream tool-call turn and re-emit a synthetic stream after continuing the loop.

Reasoning in tool loops

Reasoning models return their reasoning on the assistant message in two fields:
  • reasoning_content: the reasoning text, where the provider returns any.
  • reasoning_details: an array of reasoning blocks in the format OpenRouter uses. Each entry has a type of reasoning.text, reasoning.summary or reasoning.encrypted, an index, and a format naming the provider family, for example anthropic-claude-v1 or google-gemini-v1.
Entries can carry provider state that the model needs on the next step of a tool loop:
  • Claude thinking signatures, in signature on reasoning.text entries.
  • Claude redacted thinking and OpenAI encrypted reasoning, in data on reasoning.encrypted entries.
  • Gemini thought signatures, in data on reasoning.encrypted entries whose id is the tool call they belong to.
When streaming, a reasoning_details delta arrives once each reasoning block is complete. To keep the model’s reasoning between steps, send the assistant message back with its reasoning_details unchanged. signature and data values are opaque and record the provider and model that produced them. Phaseo sends them only to that provider family and model, so a fallback to another provider drops them rather than failing. Claude models in manual thinking mode need their thinking back to keep thinking during a tool loop; if it is missing, that step runs without thinking.

Authorizations

Authorization
string
header
required

Bearer token authentication

Body

application/json

An optional top-level field sent as null is treated as unset, the same as leaving it out.

model
string
required
messages
object[]
required
Minimum array length: 1
models
string[]

Optional ordered fallback models tried after model. model is required and is always the primary model. When an attempt fails with 429, 500, 502, 503, or 504, the next entry is tried; other errors are returned unchanged. Accepts up to 25 model IDs or presets; duplicates and entries equal to model are ignored. Each attempt is validated, logged, and billed as its own request, and the response model field and routing trace show the model that served the request. Streaming requests fall back only before the first byte, and video and music jobs fall back only at submission. Batch, realtime, and council requests reject models. Fallbacks set on a dynamic route take precedence, and phaseo/auto cannot be combined with models.

Required array length: 1 - 25 elements
Minimum string length: 1
Example:
prompt
object

Fills in the prompt template saved on a preset. Leave out model or set it to the same reference, and send an empty conversation or the turns to add after the template.

reasoning
object
reasoning_effort
enum<string>

OpenAI-compatible alias for reasoning.effort.

Available options:
none,
instant,
minimal,
low,
medium,
high,
xhigh,
max
frequency_penalty
number
Required range: -2 <= x <= 2
logit_bias
object
max_completion_tokens
integer
Required range: x >= 1
max_tokens
integer
Required range: x >= 1
metadata
object
session_id
string

Unique identifier for grouping related requests (for example, a conversation or agent workflow) for observability.

Maximum string length: 256
presence_penalty
number
Required range: -2 <= x <= 2
seed
integer
Required range: -9223372036854776000 <= x <= 9223372036854776000
store
boolean
stream
boolean
default:false
stream_options
object
temperature
number
default:1
Required range: 0 <= x <= 2
tools
object[]

Tool definitions for model function calls and gateway server tools. Built-in server tools include datetime, web search, web fetch, Advisor, Subagent, Fusion, model search, image generation, and patch creation.

max_tool_calls
integer
Required range: x >= 1
parallel_tool_calls
boolean
default:true
tool_choice

Tool selection strategy. Phaseo server-tool types are accepted and rewritten into upstream function/tool targets. An allowed_tools object is sent as is to OpenAI, with every tool. Other providers are sent only the allowed tools and its mode (auto or required), or a forced call when required allows exactly one tool. If allowed_tools lists a tool that tools does not define, only OpenAI can serve the request; otherwise it returns a 400 error.

Available options:
auto,
none,
required,
phaseo:datetime,
phaseo:web_search,
phaseo:web_fetch,
phaseo:subagent,
phaseo:fusion,
phaseo:search_models,
gateway:datetime,
gateway:web_search,
gateway:web_fetch
plugins
object[]

Gateway plugins for this request. web adds web search and web-fetch adds page fetching to any model; response-healing repairs malformed JSON in buffered structured-output responses. Workspace and preset defaults are merged with this list. An unknown plugin id returns 400 unknown_gateway_plugin.

Adds the phaseo:web_search server tool to the request, so any model can search the web. The request runs, and searches are counted and billed, exactly as with a phaseo:web_search tool. If the request already has a web search tool, the plugin adds nothing. Other options are ignored.

logprobs
boolean
default:false
top_logprobs
integer
Required range: 0 <= x <= 20
top_p
number
Required range: 0 <= x <= 1
stop
response_format
modalities
enum<string>[]
Available options:
text,
image,
audio
image_config
object
usage
boolean
provider

Provider selector. Use a string for a single provider, or routing options such as { "only": ["groq"] }.

Available options:
openai,
anthropic,
google-ai-studio,
gemini,
mistral,
x-ai,
xai,
groq,
together
provider_options
object

Optional provider-specific options.

user_id
string
user
string
include_reasoning
boolean

Accepted for compatibility. Reasoning is returned whenever the model produces it (reasoning_content and reasoning_details), whatever this is set to.

prediction
object

Predicted output, for faster responses when most of the reply is known in advance. Forwarded to OpenAI, Mistral and Moonshot models; other providers ignore it.

service_tier
enum<string> | null

Selects a supported routing or pricing tier. auto (or null) asks for no particular tier and is routed and billed as if the field were unset; scale is treated as default, the standard tier.

Available options:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
scale
prompt_cache_key
string | null

Groups related requests so they stay on the provider that holds their prompt cache. Phaseo sends a hash of your workspace and this key upstream, never the raw key.

prompt_cache_retention
enum<string>

Prompt cache retention for OpenAI and Azure OpenAI models before GPT-5.6. Takes precedence over provider_options.openai.prompt_cache_retention.

Available options:
in_memory,
24h
prompt_cache_options
object

Prompt cache mode and TTL for OpenAI and Azure OpenAI GPT-5.6 and later (ttl 30m, or 12h on OpenAI) and for DeepInfra (ttl 5m or 1h). Removed for other providers.

cache_control
object

Prompt cache control. Use type ephemeral with an optional ttl of 5m or 1h. scope applies only to a top-level Claude cache policy. Amazon Bedrock and Google Vertex AI cache Claude 3.7 Sonnet, 3.5 Sonnet and 3 Opus for 5 minutes only; there the ttl is removed and a removed 1h is reported in X-Phaseo-Dropped-Params as cache_control.ttl.

safety_identifier
string | null
meta
boolean
default:false
echo_upstream_request
boolean
debug
object

Gateway debug controls. These flags are never forwarded upstream.

Response

Chat completion response

id
string
nativeResponseId
string | null
object
string
created
integer
model
string
provider
string
choices
object[]
usage
object
Last modified on October 18, 2026