> ## 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 response

> Creates a response using the Responses API.

## 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

```bash theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "stream": false,
    "input": [
      { "role": "user", "content": "Give me the current datetime in Asia/Tokyo." }
    ],
    "tools": [
      {
        "type": "gateway:datetime",
        "parameters": { "timezone": "Asia/Tokyo" }
      }
    ],
    "tool_choice": "auto"
  }'
```

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.


## OpenAPI

````yaml openapi/v1/openapi.yaml POST /responses
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:
  /responses:
    post:
      tags:
        - Gateway
      summary: Create response
      description: Creates a response using the Responses API.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              datetimeServerTool:
                summary: Built-in datetime server tool
                value:
                  model: openai/gpt-5-nano
                  stream: false
                  input:
                    - role: user
                      content: Give me the current datetime in Asia/Tokyo.
                  tools:
                    - type: gateway:datetime
                      parameters:
                        timezone: Asia/Tokyo
                  tool_choice: auto
      responses:
        '200':
          description: 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/ResponsesResponse'
        '429':
          $ref: '#/components/responses/UpstreamRateLimited'
      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:
    ResponsesRequest:
      type: object
      description: >-
        An optional top-level field sent as `null` is treated as unset, the same
        as leaving it out.
      required:
        - model
        - input
      properties:
        model:
          type: string
        models:
          $ref: '#/components/schemas/ModelFallbacks'
        prompt:
          $ref: '#/components/schemas/PromptTemplateReference'
        input:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputItem'
            - type: object
        background:
          type: boolean
        include:
          type: array
          items:
            type: string
        instructions:
          type: string
        max_output_tokens:
          type: integer
          minimum: 1
        metadata:
          type: object
          additionalProperties:
            type: string
        session_id:
          type: string
          maxLength: 256
          description: >-
            Unique identifier for grouping related requests (for example, a
            conversation or agent workflow) for observability.
        parallel_tool_calls:
          type: boolean
        previous_response_id:
          type: string
          description: >-
            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:
          $ref: '#/components/schemas/OpenAIReasoningConfig'
        service_tier:
          type: string
          nullable: true
          description: >-
            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.
          enum:
            - standard
            - default
            - fast
            - ultrafast
            - priority
            - flex
            - batch
            - auto
            - scale
        store:
          type: boolean
        stream:
          type: boolean
        temperature:
          type: number
          minimum: 0
          maximum: 2
        text:
          type: object
        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'
        tool_choice:
          $ref: '#/components/schemas/TextToolChoice'
        tools:
          type: array
          description: >
            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`.
          items:
            $ref: '#/components/schemas/TextGenerateTool'
        top_p:
          type: number
          minimum: 0
          maximum: 1
        truncation:
          type: string
          enum:
            - auto
            - disabled
        user:
          type: string
        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.
        prompt_cache_retention:
          type: string
          enum:
            - in_memory
            - 24h
          description: >-
            Prompt cache retention for OpenAI and Azure OpenAI models before
            GPT-5.6. Takes precedence over
            provider_options.openai.prompt_cache_retention.
        prompt_cache_options:
          $ref: '#/components/schemas/PromptCacheOptions'
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        safety_identifier:
          type: string
          nullable: true
        modalities:
          type: array
          items:
            type: string
            enum:
              - text
              - image
              - audio
        image_config:
          $ref: '#/components/schemas/ImageConfig'
        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'
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        provider:
          type: string
        provider_id:
          type: string
        nativeResponseId:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - completed
            - failed
            - incomplete
        finish_reason:
          type: string
          nullable: true
        meta:
          type: object
          additionalProperties: true
        cost_nanos:
          type: number
        cost_cents:
          type: integer
        currency:
          type: string
        pricing_lines:
          type: array
          items:
            type: object
            additionalProperties: true
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        output_items:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        content:
          type: array
          items:
            type: object
        role:
          type: string
        stop_reason:
          type: string
        type:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
    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.
    ResponsesInputItem:
      type: object
      description: Responses API input item.
      properties:
        type:
          type: string
        id:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - developer
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
            - type: object
        summary:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesReasoningSummaryPart'
        encrypted_content:
          type: string
          description: >-
            Reasoning state from an earlier response, sent back unchanged. A raw
            value is read as OpenAI's unless format names another provider.
        signature:
          type: string
          description: >-
            On a reasoning item, a raw provider signature, such as a Claude
            thinking signature or a Gemini thought signature. Requires format.
        format:
          type: string
          description: >-
            On a reasoning item, the provider format of signature or
            encrypted_content.
          enum:
            - anthropic-claude-v1
            - openai-responses-v1
            - azure-openai-responses-v1
            - xai-responses-v1
            - google-gemini-v1
    OpenAIReasoningConfig:
      type: object
      properties:
        effort:
          type: string
          enum:
            - none
            - instant
            - 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
    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'
    TextToolChoice:
      description: >
        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.
      oneOf:
        - type: string
          enum:
            - 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
        - type: object
    TextGenerateTool:
      oneOf:
        - $ref: '#/components/schemas/FunctionToolDefinition'
        - $ref: '#/components/schemas/GatewayDatetimeToolDefinition'
        - $ref: '#/components/schemas/GatewayWebSearchToolDefinition'
        - $ref: '#/components/schemas/GatewayWebFetchToolDefinition'
        - $ref: '#/components/schemas/SubagentToolDefinition'
        - $ref: '#/components/schemas/FusionToolDefinition'
        - $ref: '#/components/schemas/SearchModelsToolDefinition'
        - $ref: '#/components/schemas/OpenAIWebSearchToolDefinition'
    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
    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
    ImageConfig:
      type: object
      properties:
        aspect_ratio:
          type: string
        image_size:
          type: string
          enum:
            - 0.5K
            - 1K
            - 2K
            - 4K
        include_rai_reason:
          type: boolean
        font_inputs:
          type: array
          items:
            type: object
            properties:
              font_url:
                type: string
                format: uri
              text:
                type: string
        super_resolution_references:
          type: array
          items:
            type: string
        reference_images:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    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
    ResponsesOutputItem:
      type: object
      description: Responses API output item.
      properties:
        type:
          type: string
        id:
          type: string
        role:
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputContentPart'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
        summary:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesReasoningSummaryPart'
        encrypted_content:
          type: string
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Input tokens, including cache reads and cache writes.
        prompt_tokens_details:
          $ref: '#/components/schemas/InputTokensDetails'
        completion_tokens:
          type: integer
        input_tokens:
          type: integer
          description: Input tokens, including cache reads and cache writes.
        input_tokens_details:
          $ref: '#/components/schemas/InputTokensDetails'
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        server_tool_use:
          $ref: '#/components/schemas/ServerToolUsage'
        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'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          description: >-
            The error object (`code`, `message`, `type`, `param` and optional
            `metadata`) that OpenAI-compatible SDKs read. Earlier responses
            returned the code string here; it is now also returned as top-level
            `code`.
          oneOf:
            - type: string
            - $ref: '#/components/schemas/ErrorObject'
          example:
            code: validation_error
            message: 'Unknown parameter: foo'
            type: invalid_request_error
            param: foo
        code:
          type: string
          description: The error code, the same value as `error.code`.
          example: validation_error
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ResponsesReasoningSummaryPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - summary_text
        text:
          type: string
    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
    FunctionToolDefinition:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
        async:
          type: boolean
          description: >-
            Lets supported OpenAI models continue while the caller executes this
            tool. Accepted on all text API surfaces and ignored by other
            providers.
        cache_control:
          $ref: '#/components/schemas/CacheControl'
        function:
          type: object
          required:
            - name
            - parameters
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object
      additionalProperties: true
    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
    OpenAIWebSearchToolDefinition:
      type: object
      description: >
        OpenAI's hosted web search tool. OpenAI, Azure OpenAI (Responses) and
        xAI run it natively. On models whose providers cannot run it, the
        gateway runs it as `phaseo:web_search`: `search_context_size`,
        `filters.allowed_domains`, `max_results` and `engine` carry over, and
        searches are billed as `phaseo:web_search` searches. Other OpenAI hosted
        tools (`file_search`, `code_interpreter`, `computer_use_preview`, `mcp`,
        `image_generation`, `shell`, `local_shell`, `apply_patch`) fail with 400
        `unsupported_hosted_tool` on models whose providers cannot run them.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - web_search
            - web_search_2025_08_26
            - web_search_preview
            - web_search_preview_2025_03_11
        search_context_size:
          type: string
          enum:
            - low
            - medium
            - high
        filters:
          type: object
          properties:
            allowed_domains:
              type: array
              items:
                type: string
        user_location:
          type: object
          additionalProperties: true
      additionalProperties: true
    ResponsesOutputContentPart:
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputTextPart'
        - $ref: '#/components/schemas/ResponsesReasoningTextPart'
        - $ref: '#/components/schemas/ResponsesOutputImagePart'
        - $ref: '#/components/schemas/ResponsesOutputAudioPart'
    InputTokensDetails:
      type: object
      description: Breakdown of the input tokens.
      properties:
        cached_tokens:
          type: integer
          description: Input tokens read from the provider's prompt cache.
        cache_write_tokens:
          type: integer
          description: Input tokens written to the provider's prompt cache.
        cache_write_tokens_details:
          $ref: '#/components/schemas/CacheWriteTokensDetails'
    ServerToolUsage:
      type: object
      properties:
        datetime_requests:
          type: integer
          minimum: 0
        web_search_requests:
          type: integer
          minimum: 0
        subagent_requests:
          type: integer
          minimum: 0
        fusion_requests:
          type: integer
          minimum: 0
        search_models_requests:
          type: integer
          minimum: 0
        web_fetch_requests:
          type: integer
          minimum: 0
        advisor_requests:
          type: integer
          minimum: 0
        image_generation_requests:
          type: integer
          minimum: 0
        apply_patch_requests:
          type: integer
          minimum: 0
      additionalProperties: false
    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
    ErrorObject:
      type: object
      description: >-
        A gateway error in the shape OpenAI's SDKs read. `type` is set from the
        HTTP status: invalid_request_error for most 4xx, authentication_error
        (401), insufficient_quota (402), permission_error (403), not_found_error
        (404), rate_limit_error (429), service_unavailable (503), overloaded
        (529) and server_error for other 5xx.
      required:
        - code
        - message
        - type
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable explanation of the failure.
          example: 'Unknown parameter: foo'
        type:
          type: string
          description: The error type, following OpenAI's documented error types.
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - insufficient_quota
            - server_error
            - service_unavailable
            - overloaded
          example: invalid_request_error
        param:
          type: string
          nullable: true
          description: The request parameter that caused the error, when known.
          example: foo
        metadata:
          type: object
          description: >-
            Structured detail also returned at the top level, such as the
            failing provider, `reason`, `failed_statuses`, `retry_after_seconds`
            or `upstream_error`.
          additionalProperties: true
      additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ResponsesOutputTextPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - output_text
        text:
          type: string
        annotations:
          type: array
          items:
            type: object
    ResponsesReasoningTextPart:
      type: object
      description: Reasoning text in the content of a reasoning output item.
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - reasoning_text
        text:
          type: string
    ResponsesOutputImagePart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - output_image
        b64_json:
          type: string
        image_url:
          type: object
          properties:
            url:
              type: string
        mime_type:
          type: string
      anyOf:
        - required:
            - b64_json
        - required:
            - image_url
    ResponsesOutputAudioPart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - output_audio
        b64_json:
          type: string
        audio_url:
          type: object
          properties:
            url:
              type: string
        mime_type:
          type: string
        format:
          type: string
          enum:
            - wav
            - mp3
            - flac
            - m4a
            - ogg
            - pcm16
            - pcm24
      anyOf:
        - required:
            - b64_json
        - required:
            - audio_url
    CacheWriteTokensDetails:
      type: object
      description: >-
        Cache writes split by lifetime, on Responses usage from OpenAI GPT-5.6
        and later. The two counts sum to cache_write_tokens. Not returned in
        Chat Completions prompt_tokens_details.
      properties:
        ttl_30m_tokens:
          type: integer
          description: >-
            Input tokens written to the cache with a 30-minute lifetime, billed
            at 1.25x the input rate.
        ttl_12h_tokens:
          type: integer
          description: >-
            Input tokens written to the cache with a 12-hour lifetime, billed at
            2.5x the input rate.
  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
    UpstreamRateLimitValue:
      description: >-
        BYOK-only provider quota metadata. Omitted for managed-provider
        requests.
      schema:
        type: string
  responses:
    UpstreamRateLimited:
      description: The selected upstream provider rate-limited the request.
      headers:
        Retry-After:
          description: Validated provider guidance in seconds before retrying.
          schema:
            type: integer
            minimum: 0
            maximum: 86400
        X-Phaseo-Upstream-RateLimit-Limit:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Remaining:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Reset:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Limit-Requests:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Remaining-Requests:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Reset-Requests:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Limit-Tokens:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Remaining-Tokens:
          $ref: '#/components/headers/UpstreamRateLimitValue'
        X-Phaseo-Upstream-RateLimit-Reset-Tokens:
          $ref: '#/components/headers/UpstreamRateLimitValue'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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.