Skip to main content
POST
Create message
/v1/messages accepts Anthropic Messages API payloads and returns Anthropic-formatted responses.

Streaming

Set stream: true to receive server-sent events in Anthropic format (message_start, content_block_*, message_delta, message_stop).

Mid-conversation system messages

Add a role: "system" message to messages for an instruction that applies from that point in the conversation. The top-level system field stays the same, so a cached prefix still hits.
  • A system message takes a string or text blocks. It must come straight after a user turn (or an assistant turn ending in a server tool result) and be the last message or be followed by an assistant turn. Other positions return a 400.
  • Claude Fable 5 and 5.1, Mythos 5 and 5.1, Opus 4.8, Opus 5 and 5.5, Sonnet 5.5 and Haiku 5.5 receive it in place. Other Claude models, including Sonnet 5, and every Claude model on Microsoft Foundry receive it as part of the top-level system prompt. Other providers receive it as a system message, the same as one sent to Chat Completions.
  • clear_at, output_config, and tool_addition or tool_removal blocks are not supported.

Notes

  • Anthropic tool-use fields are supported.
  • stream: true also works with tool loops. For gateway-managed server tools, Phaseo may materialize the upstream tool-call turn, continue the loop, and re-emit a synthetic stream.
  • The Anthropic-native web search tool shape is also accepted directly in tools, for example type: "web_search_20250305".
  • The X-Phaseo-Strictness header controls how unsupported parameters are handled.

Server tools

/v1/messages also supports these gateway-managed server tools:
  • gateway:datetime
  • phaseo:web_search
  • phaseo:web_fetch
  • phaseo:advisor
  • phaseo:image_generation
Phaseo rewrites these tools to Anthropic-compatible format upstream, executes them server-side, and continues the tool loop. When a compatible Anthropic model/provider pair supports native web search, you can also pass the native tool definition through directly:
Provider routing still filters for web_search_options support before execution.

Datetime example

When used, the usage.server_tool_use.* counters report server-tool invocations.

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
max_tokens
integer
required
Required range: x >= 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.

system
service_tier
enum<string>

Selects a supported routing or pricing tier on compatible text APIs.

Available options:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
standard_only
temperature
number
Required range: 0 <= x <= 1
top_p
number
Required range: 0 <= x <= 1
top_k
integer
Required range: x >= 1
tools
object[]

Anthropic-compatible tools plus gateway-managed server tools.

tool_choice

Anthropic tool choice object/string. Gateway-managed server tool names are also accepted and rewritten by the gateway.

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.

stream
boolean
metadata
object
session_id
string

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

Maximum string length: 256
reasoning
object
context_management
object

Anthropic context editing. edits takes clear_tool_uses_* and clear_thinking_* strategies and is sent to Anthropic with its beta header. Other providers run the request without it and list context_management in X-Phaseo-Dropped-Params. Compaction edits (compact_*) return 400.

user
string

End-user identifier, as on Chat Completions. Claude models receive it as metadata.user_id unless metadata.user_id is set.

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.

stop_sequences
string[]
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.

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

Message response

id
string
type
string
role
enum<string>
Available options:
assistant
model
string
content
object[]
stop_reason
string
stop_sequence
string
usage
object
context_management
object

Present when the request used context_management and Anthropic applied an edit. applied_edits lists each edit with what it cleared. Streams carry it on the final message_delta event.

Last modified on October 22, 2026