Skip to main content
POST
Create response

Server tools

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

Datetime example

When a server tool is used, usage includes the matching usage.server_tool_use.* counters.
  • gateway:datetime -> datetime_requests
  • phaseo:web_search -> web_search_requests, web_search_results, web_search_extra_results
  • phaseo:web_fetch -> web_fetch_requests
  • phaseo:advisor -> advisor_requests
  • phaseo:image_generation -> image_generation_requests
  • phaseo:apply_patch -> apply_patch_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

On OpenAI, Azure OpenAI and xAI, Phaseo sends Responses requests upstream with store: false, so a model’s reasoning continues between tool-loop steps only through the reasoning output items. Each reasoning item has an id, summary and content. When the provider returns reasoning state, the item also has encrypted_content:
  • OpenAI, Azure OpenAI and xAI encrypted reasoning. Phaseo requests it with include: ["reasoning.encrypted_content"] for reasoning models.
  • Claude thinking signatures and redacted thinking.
  • Gemini thought signatures, including a separate reasoning item placed just before the function call a signature belongs to.
Streaming responses carry the same items on response.output_item.done and response.completed. To continue a tool loop, send every output item back in input, including reasoning items, unchanged. encrypted_content is opaque and records the provider and model that produced it. Phaseo sends it only to that provider family and model, so a fallback to another provider drops it rather than failing.

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
input
required
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.

background
boolean
include
string[]
instructions
string
max_output_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
parallel_tool_calls
boolean
previous_response_id
string

Not supported. Phaseo does not store responses, so requests that set previous_response_id or conversation return 400 unsupported_param. Send the full conversation in input.

reasoning
object
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
store
boolean
stream
boolean
temperature
number
Required range: 0 <= x <= 2
text
object
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.

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
tools
object[]

Tool definitions for model function calls and gateway server tools. Built-in gateway server tools are gateway:datetime, gateway:web_search, and gateway:web_fetch.

top_p
number
Required range: 0 <= x <= 1
truncation
enum<string>
Available options:
auto,
disabled
user
string
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
modalities
enum<string>[]
Available options:
text,
image,
audio
image_config
object
provider_options
object

Optional provider-specific options.

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

Gateway debug controls. These flags are never forwarded upstream.

provider
object

Provider routing preferences for gateway selection.

Response

Response

id
string
object
string
created
integer
model
string
provider
string
provider_id
string
nativeResponseId
string | null
status
enum<string>
Available options:
completed,
failed,
incomplete
finish_reason
string | null
meta
object
cost_nanos
number
cost_cents
integer
currency
string
pricing_lines
object[]
output
object[]
output_items
object[]
content
object[]
role
string
stop_reason
string
type
string
usage
object
Last modified on October 18, 2026