> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Create a message

> Anthropic-compatible Messages endpoint at /v1/messages.

`/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.

```bash theme={null}
curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-5.5",
    "max_tokens": 512,
    "system": "You are a code review assistant.",
    "messages": [
      { "role": "user", "content": "Review process() in utils.py." },
      { "role": "assistant", "content": "The loop is fine; the regex is compiled on every call." },
      { "role": "user", "content": "Now review the code that calls it." },
      { "role": "system", "content": "From now on, include type annotations in every suggestion." }
    ]
  }'
```

* 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.

## Native provider web search

When a compatible Anthropic model/provider pair supports native web search, you can also pass the native tool definition through directly:

```bash theme={null}
curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "messages": [
      { "role": "user", "content": "Find the latest Anthropic web search guidance." }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3,
        "allowed_domains": ["docs.anthropic.com"]
      }
    ],
    "tool_choice": { "type": "tool", "name": "web_search" }
  }'
```

Provider routing still filters for `web_search_options` support before execution.

### Datetime example

```bash theme={null}
curl https://api.phaseo.app/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 512,
    "stream": false,
    "messages": [
      { "role": "user", "content": "What time is it in America/New_York right now?" }
    ],
    "tools": [
      {
        "type": "gateway:datetime",
        "parameters": { "timezone": "America/New_York" }
      }
    ],
    "tool_choice": { "type": "auto" }
  }'
```

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


## OpenAPI

````yaml openapi/v1/openapi.yaml POST /messages
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Global routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /messages:
    post:
      tags:
        - Gateway
      summary: Create message
      description: Creates a message using the Anthropic Messages API.
      operationId: createAnthropicMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessagesRequest'
            examples:
              datetimeServerTool:
                summary: Built-in datetime server tool
                value:
                  model: anthropic/claude-sonnet-4
                  max_tokens: 512
                  stream: false
                  messages:
                    - role: user
                      content: What time is it in America/New_York right now?
                  tools:
                    - type: gateway:datetime
                      parameters:
                        timezone: America/New_York
                  tool_choice:
                    type: auto
      responses:
        '200':
          description: Message response
          headers:
            x-request-id:
              $ref: '#/components/headers/PublicRequestId'
            X-Phaseo-Requested-Model:
              $ref: '#/components/headers/RequestedModel'
            X-Phaseo-Model-Substitution:
              $ref: '#/components/headers/ModelSubstitution'
            X-Phaseo-Dropped-Params:
              $ref: '#/components/headers/DroppedParams'
            X-Phaseo-Spend-Warning:
              $ref: '#/components/headers/SpendWarning'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicMessagesResponse'
            text/event-stream:
              schema:
                type: string
      servers:
        - url: https://api.phaseo.app/v1
          description: Global routing
        - url: https://eu.api.phaseo.app/v1
          description: EU regional provider routing (text only)
        - url: https://us.api.phaseo.app/v1
          description: US regional provider routing (text only)
components:
  schemas:
    AnthropicMessagesRequest:
      type: object
      description: >-
        An optional top-level field sent as `null` is treated as unset, the same
        as leaving it out.
      required:
        - model
        - messages
        - max_tokens
      properties:
        model:
          type: string
        models:
          $ref: '#/components/schemas/ModelFallbacks'
        prompt:
          $ref: '#/components/schemas/PromptTemplateReference'
        system:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                  text:
                    type: string
                  cache_control:
                    $ref: '#/components/schemas/CacheControl'
        messages:
          type: array
          minItems: 1
          items:
            oneOf:
              - $ref: '#/components/schemas/AnthropicMessage'
              - $ref: '#/components/schemas/AnthropicSystemMessage'
            discriminator:
              propertyName: role
              mapping:
                user: '#/components/schemas/AnthropicMessage'
                assistant: '#/components/schemas/AnthropicMessage'
                system: '#/components/schemas/AnthropicSystemMessage'
        max_tokens:
          type: integer
          minimum: 1
        service_tier:
          type: string
          description: Selects a supported routing or pricing tier on compatible text APIs.
          enum:
            - standard
            - default
            - fast
            - ultrafast
            - priority
            - flex
            - batch
            - auto
            - standard_only
        temperature:
          type: number
          minimum: 0
          maximum: 1
        top_p:
          type: number
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          minimum: 1
        tools:
          type: array
          description: |
            Anthropic-compatible tools plus gateway-managed server tools.
          items:
            oneOf:
              - $ref: '#/components/schemas/AnthropicTool'
              - $ref: '#/components/schemas/GatewayDatetimeToolDefinition'
              - $ref: '#/components/schemas/GatewayWebSearchToolDefinition'
              - $ref: '#/components/schemas/GatewayWebFetchToolDefinition'
              - $ref: '#/components/schemas/SubagentToolDefinition'
              - $ref: '#/components/schemas/FusionToolDefinition'
              - $ref: '#/components/schemas/SearchModelsToolDefinition'
        tool_choice:
          description: >
            Anthropic tool choice object/string. Gateway-managed server tool
            names are also accepted and rewritten by the gateway.
          oneOf:
            - type: object
            - type: string
        plugins:
          type: array
          description: >
            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`.
          items:
            $ref: '#/components/schemas/GatewayPlugin'
        stream:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
        session_id:
          type: string
          maxLength: 256
          description: >-
            Unique identifier for grouping related requests (for example, a
            conversation or agent workflow) for observability.
        reasoning:
          $ref: '#/components/schemas/ReasoningConfig'
        context_management:
          type: object
          description: >-
            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.
          properties:
            edits:
              type: array
              items:
                type: object
                required:
                  - type
                properties:
                  type:
                    type: string
                additionalProperties: true
          additionalProperties: true
        user:
          type: string
          description: >-
            End-user identifier, as on Chat Completions. Claude models receive
            it as `metadata.user_id` unless `metadata.user_id` is set.
        prompt_cache_key:
          type: string
          nullable: true
          description: >-
            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:
          type: array
          items:
            type: string
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        provider_options:
          $ref: '#/components/schemas/ProviderOptions'
        usage:
          type: boolean
        meta:
          type: boolean
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    AnthropicMessagesResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        role:
          type: string
          enum:
            - assistant
        model:
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicContentBlock'
        stop_reason:
          type: string
        stop_sequence:
          type: string
        usage:
          $ref: '#/components/schemas/AnthropicUsage'
        context_management:
          type: object
          description: >-
            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.
          properties:
            applied_edits:
              type: array
              items:
                type: object
                additionalProperties: true
    ModelFallbacks:
      type: array
      minItems: 1
      maxItems: 25
      items:
        type: string
        minLength: 1
      description: >-
        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`.
      example:
        - anthropic/claude-sonnet-5-5
        - google/gemini-2.5-flash
    PromptTemplateReference:
      type: object
      description: >-
        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.
      required:
        - id
      properties:
        id:
          type: string
          description: >-
            Preset reference starting with @, such as @support-triage or
            @publisher/support-triage.
        variables:
          type: object
          additionalProperties: true
          description: >-
            Values for the template variables. Image variables take an https
            URL, a data URL or an image part.
        version:
          type: string
          maxLength: 64
          description: >-
            Runs this published version of the preset instead of the current
            one: its models, parameters and template. Use a version label such
            as v3, 1.2.0 or 2026.10.27, or a label such as production. The same
            as setting model to @support-triage@production.
    CacheControl:
      type: object
      description: >-
        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.
      properties:
        type:
          type: string
        ttl:
          type: string
        scope:
          type: string
      additionalProperties: true
    AnthropicMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicContentBlock'
    AnthropicSystemMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: >-
            Use `system` for an instruction that applies from this point in the
            conversation. A system message takes a string or text blocks, must
            come straight after a user turn (or an assistant turn ending in a
            server tool result), and must be the last message or be followed by
            an assistant turn.
          enum:
            - system
        content:
          oneOf:
            - type: string
            - type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/AnthropicSystemTextBlock'
      additionalProperties: false
    AnthropicTool:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        async:
          type: boolean
          description: >-
            Lets supported OpenAI models continue while the caller executes this
            tool. Ignored when routed to other providers.
        description:
          type: string
        input_schema:
          type: object
    GatewayDatetimeToolDefinition:
      type: object
      description: >
        Gateway-managed server tool. The gateway executes the datetime lookup
        and injects the result back into the model tool loop.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:datetime
            - gateway:datetime
        parameters:
          type: object
          properties:
            timezone:
              type: string
              description: IANA timezone name (for example Europe/London).
          additionalProperties: false
        timezone:
          type: string
          description: Legacy shortcut for default timezone (IANA).
      additionalProperties: false
    GatewayWebSearchToolDefinition:
      type: object
      description: >
        Gateway-managed server tool. The gateway executes a web search and
        injects normalized search results back into the model tool loop.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:web_search
            - gateway:web_search
        parameters:
          type: object
          properties:
            engine:
              type: string
              enum:
                - auto
                - native
                - exa
                - firecrawl
                - parallel
                - perplexity
                - tinyfish
            max_results:
              type: integer
              minimum: 1
              maximum: 25
            language:
              type: string
            page:
              type: integer
              minimum: 0
              maximum: 10
            include_text:
              type: boolean
            include_highlights:
              type: boolean
          additionalProperties: false
        max_results:
          type: integer
          minimum: 1
          maximum: 25
        engine:
          type: string
          enum:
            - auto
            - native
            - exa
            - firecrawl
            - parallel
            - perplexity
            - tinyfish
        language:
          type: string
        page:
          type: integer
          minimum: 0
          maximum: 10
        include_text:
          type: boolean
        include_highlights:
          type: boolean
      additionalProperties: false
    GatewayWebFetchToolDefinition:
      type: object
      description: >
        Gateway-managed server tool. The gateway fetches one HTTP(S) page,
        reduces it to bounded text, and injects the result back into the model
        tool loop.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:web_fetch
            - gateway:web_fetch
        parameters:
          type: object
          properties:
            max_chars:
              type: integer
              minimum: 1
              maximum: 100000
          additionalProperties: false
        max_chars:
          type: integer
          minimum: 1
          maximum: 100000
      additionalProperties: false
    SubagentToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:subagent
        parameters:
          type: object
          additionalProperties: true
    FusionToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:fusion
        parameters:
          type: object
          required:
            - analysis_models
          properties:
            analysis_models:
              type: array
              minItems: 2
              maxItems: 8
              items:
                type: string
            model:
              type: string
          additionalProperties: true
    SearchModelsToolDefinition:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - phaseo:search_models
        parameters:
          type: object
          properties:
            max_results:
              type: integer
              minimum: 1
              maximum: 20
    GatewayPlugin:
      oneOf:
        - $ref: '#/components/schemas/WebSearchPlugin'
        - $ref: '#/components/schemas/WebFetchPlugin'
        - $ref: '#/components/schemas/ResponseHealingPlugin'
      discriminator:
        propertyName: id
        mapping:
          web: '#/components/schemas/WebSearchPlugin'
          web-fetch: '#/components/schemas/WebFetchPlugin'
          response-healing: '#/components/schemas/ResponseHealingPlugin'
    ReasoningConfig:
      type: object
      properties:
        effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
            - max
          nullable: true
          description: >-
            Reasoning effort. When omitted or null, `max_tokens`, `enabled` or
            the model's own default decides how much the model reasons.
        mode:
          type: string
          enum:
            - standard
            - pro
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          default: auto
        enabled:
          type: boolean
        max_tokens:
          type: integer
          minimum: 0
    ProviderOptions:
      type: object
      description: Optional provider-specific options.
      properties:
        openai:
          type: object
          properties:
            context_management:
              type: object
              description: Optional OpenAI context management configuration.
              properties:
                type:
                  type: string
                  enum:
                    - compaction
                compact_threshold:
                  type: number
              required:
                - type
            prompt_cache_retention:
              type: string
            prompt_cache_options:
              $ref: '#/components/schemas/PromptCacheOptions'
        anthropic:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
        xai:
          type: object
          properties:
            conversation_id:
              type: string
              description: xAI conversation ID, sent as the x-grok-conv-id header.
        google:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
            cached_content:
              type: string
            cache_ttl:
              type: string
    DebugOptions:
      type: object
      description: Gateway debug controls. These flags are never forwarded upstream.
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    ProviderRoutingOptions:
      type: object
      description: Provider routing preferences for gateway selection.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: Include alpha providers in routing (off by default).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Allow fallback to another eligible provider after failure.
        require_parameters:
          type: boolean
          nullable: true
          description: Require provider support for requested parameters before routing.
        required_execution_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested execution region.
        required_data_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested data region.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: Restrict routing to providers that support zero data retention.
        data_collection:
          type: string
          nullable: true
          description: >-
            `allow` (the default) filters nothing. `deny` is not supported yet
            and returns 400 unsupported_routing_filter.
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
          description: >-
            `false` (the default) filters nothing. `true` is not supported yet
            and returns 400 unsupported_routing_filter.
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Rank providers for this request, for example by price, latency, or
            throughput.
        max_price:
          type: object
          properties:
            prompt:
              oneOf:
                - type: number
                - type: string
            completion:
              oneOf:
                - type: number
                - type: string
            image:
              oneOf:
                - type: number
                - type: string
            audio:
              oneOf:
                - type: number
                - type: string
            request:
              oneOf:
                - type: number
                - type: string
        preferred_min_throughput:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
        preferred_max_latency:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
    AnthropicContentBlock:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
            - image
            - tool_use
            - tool_result
        text:
          type: string
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        source:
          type: object
          properties:
            type:
              type: string
            media_type:
              type: string
            data:
              type: string
            url:
              type: string
        id:
          type: string
        name:
          type: string
        input:
          type: object
        tool_use_id:
          type: string
        content:
          type: string
    AnthropicUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: >-
            Uncached input tokens. As on Anthropic, this excludes cache reads
            and cache writes.
        cache_read_input_tokens:
          type: integer
          description: Input tokens read from the provider's prompt cache.
        cache_creation_input_tokens:
          type: integer
          description: Input tokens written to the provider's prompt cache.
        cache_creation:
          type: object
          description: Cache writes split by cache lifetime.
          properties:
            ephemeral_5m_input_tokens:
              type: integer
              description: Input tokens written with a 5-minute cache lifetime.
            ephemeral_1h_input_tokens:
              type: integer
              description: Input tokens written with a 1-hour cache lifetime.
        output_tokens:
          type: integer
        cost:
          type: number
          format: double
          description: >-
            What the request costs you, in US dollars: the amount charged to
            your credits, the same figure as `cost_nanos`, after any
            data-sharing discount or zero-output waiver. Returned on Chat
            Completions, Responses, Messages and embeddings responses once the
            request is priced. On a stream it is on the final usage frame (on
            Messages, the final `message_delta`) and covers the whole stream. A
            stream leaves it out when the charge is not known as that frame is
            sent: on a BYOK stream, whose service fee is worked out when the
            stream ends (`cost_details.upstream_inference_cost` gives the model
            price instead), and on a stream that has already failed, which is
            not charged.
          example: 0.001234567
        cost_details:
          $ref: '#/components/schemas/UsageCostDetails'
    AnthropicSystemTextBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    WebSearchPlugin:
      type: object
      description: >
        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.
      required:
        - id
      properties:
        id:
          type: string
          enum:
            - web
        enabled:
          type: boolean
          default: true
        engine:
          type: string
          enum:
            - auto
            - native
            - exa
            - firecrawl
            - parallel
            - perplexity
            - tinyfish
        max_results:
          type: integer
          minimum: 1
          maximum: 25
        max_uses:
          type: integer
          minimum: 1
        search_context_size:
          type: string
          enum:
            - low
            - medium
            - high
        include_domains:
          type: array
          items:
            type: string
        exclude_domains:
          type: array
          items:
            type: string
    WebFetchPlugin:
      type: object
      description: >
        Adds the `phaseo:web_fetch` server tool to the request, so any model can
        read web pages. The request runs, and fetches are counted and billed,
        exactly as with a `phaseo:web_fetch` tool. If the request already has a
        web fetch tool, the plugin adds nothing.
      required:
        - id
      properties:
        id:
          type: string
          enum:
            - web-fetch
        enabled:
          type: boolean
          default: true
        engine:
          type: string
          enum:
            - auto
            - native
            - direct
            - exa
            - firecrawl
            - parallel
        max_uses:
          type: integer
          minimum: 1
        max_content_tokens:
          type: integer
          minimum: 1
          maximum: 100000
        allowed_domains:
          type: array
          items:
            type: string
        blocked_domains:
          type: array
          items:
            type: string
    ResponseHealingPlugin:
      type: object
      description: >
        Repairs malformed JSON in buffered responses that requested
        `json_object` or `json_schema` output. Skipped on streams.
      required:
        - id
      properties:
        id:
          type: string
          enum:
            - response-healing
        enabled:
          type: boolean
          default: true
        mode:
          type: string
          enum:
            - safe
            - strict
          default: safe
    PromptCacheOptions:
      type: object
      description: >-
        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.
      properties:
        mode:
          type: string
          enum:
            - implicit
            - explicit
        ttl:
          type: string
          description: >-
            Minimum cache lifetime. OpenAI GPT-5.6 and later: 30m (default) or
            12h; a request asking for 12h runs on OpenAI's Responses API. Azure
            OpenAI: 30m. DeepInfra: 5m or 1h. A route that cannot take 12h
            receives the request without it, and the removal is reported in
            X-Phaseo-Dropped-Params.
      additionalProperties: true
    UsageCostDetails:
      type: object
      description: Breakdown of the request's cost.
      properties:
        upstream_inference_cost:
          type: number
          format: double
          nullable: true
          description: >-
            On a BYOK request, what the provider charges your own key for the
            inference, in US dollars, at the model's listed prices. Null when
            the request runs on Phaseo credits, where `cost` is the whole
            charge.
          example: null
  headers:
    PublicRequestId:
      description: >-
        Server-generated public request identifier. For inference requests, this
        is the generation ID used in response payloads and request logs.
        Caller-supplied x-request-id values do not replace it.
      schema:
        type: string
        pattern: ^G-[0-9A-HJKMNP-TV-Z]{26}$
    RequestedModel:
      description: >-
        The model the request asked for. Sent only when retired model routing
        answered the request with a replacement model.
      schema:
        type: string
    ModelSubstitution:
      description: >-
        Why and how the requested model was replaced, for example
        `reason=unserved; from=lab/old-model; to=lab/new-model`. Sent only when
        retired model routing answered the request with a replacement model.
      schema:
        type: string
    DroppedParams:
      description: >-
        Request parameters the client sent that the serving provider does not
        support, which the gateway removed instead of sending them upstream or
        rejecting the request, for example `top_k, min_p`. Sent only on
        successful responses, and only when at least one parameter from the
        request body was dropped. Parameters that come from a preset or a
        default value are not listed.
      schema:
        type: string
    SpendWarning:
      description: >-
        Sent while a spend rule that blocks covers the request and spend has
        passed its last alert threshold but not yet its block point. Lists up to
        three rules as rule_id, scope and resets_at, for example `rule_id=...;
        scope=workspace; resets_at=2026-11-01T00:00:00.000Z`. Once spend reaches
        the block point, requests in scope get a 429 with code
        spend_rule_blocked.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.