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

# List models

> Browse gateway-native models through Phaseo Gateway, including optional non-routable availability details.

By default, this endpoint only returns models that are currently routable. Set `availability=all` to include models that are known but not currently available.

Catalogue responses are cached for five minutes and may be served for another five minutes while the cache revalidates. This applies to the JSON, RSS, and Atom representations of the current catalogue; the release feed has its own shorter polling cache.

`GET /models/me` is reserved for future guardrail-aware filtering of models for the current caller. It currently returns `501 not implemented`, so use `GET /models` for the shared gateway catalogue today.

## OpenAI format

Use `GET /v1/models?format=openai` for clients that expect OpenAI's model-list response. The default `format=json` returns Phaseo's richer model metadata.

```bash theme={null}
curl 'https://api.phaseo.app/v1/models?format=openai' \
  -H 'Authorization: Bearer YOUR_PHASEO_API_KEY'
```

```json theme={null}
{
  "object": "list",
  "data": [
    { "id": "openai/gpt-4o-mini", "object": "model", "created": 1721260800, "owned_by": "openai" }
  ]
}
```

OpenAI format uses the same authentication, regional availability, workspace private models, and filters as native JSON. It returns all matching models unless you supply `limit`; `offset` still applies. IDs stay in Phaseo's canonical form for inference. `created` uses the catalogue release date, or `0` when unknown; `owned_by` uses the catalogue organization, `private` for workspace models, or `phaseo` when unknown.

## Caching the model list

JSON and OpenAI-format responses include a weak `ETag` header (`W/"…"`). It changes when the models on the page, `limit`, `offset`, `total`, or the format change. It ignores `gateway_region`, so the same catalogue served from another region has the same `ETag`. That is why it is weak: responses that share it are equivalent, but their bytes can differ. RSS, Atom, and error responses do not include one.

Send the saved value back unchanged in `If-None-Match`. If the catalogue has not changed, the response is `304 Not Modified` with no body and repeats the `ETag`, `Cache-Control`, and `Vary` headers. Otherwise you get a normal `200` with the new list and a new `ETag`. `If-None-Match` also accepts a comma-separated list and `*`, and the comparison is weak, so the value matches with or without its `W/` prefix.

```ts theme={null}
let etag: string | null = null;
let models: unknown[] = [];

async function refreshModels() {
  const response = await fetch("https://api.phaseo.app/v1/models?limit=250", {
    headers: {
      Authorization: `Bearer ${process.env.PHASEO_API_KEY}`,
      ...(etag ? { "If-None-Match": etag } : {}),
    },
  });
  if (response.status === 304) return models; // Unchanged; a 304 has no body.
  if (!response.ok) throw new Error(`Model list request failed: ${response.status}`);
  etag = response.headers.get("ETag");
  models = (await response.json()).models;
  return models;
}
```

A `304` saves transfer and parsing, because it has no body. The server still evaluates the request: it loads the catalogue and recomputes the `ETag`. Polling about every 15 minutes is therefore appropriate, downloading the list again only when the catalogue changes. Keep one `ETag` per request URL, because each page, filter set, and format has its own value.

### Service tiers per offer

Each entry in `offers` includes `service_tiers`, the [service tiers](https://phaseo.app/docs/v1/guides/service-tiers.md) that provider offer accepts. It is an alphabetically sorted subset of `flex`, `priority`, `standard`, and `ultrafast`, where `priority` is the Fast tier. A tier is listed when the provider route has active, currently effective pricing for it, and a route that serves one tier only lists just that tier. Some tiers may also be available through separate tier-specific provider routes that are not listed. Prices under `pricing` remain standard-tier prices.

## Useful filters

* `endpoints` uses public names like `chat.completions`, `responses`, and `messages`
* `status` filters by model lifecycle, for example `active`, `deprecated`, or `retired`
* `provider` filters by public provider ID, for example `openai`, `anthropic`, or `google_vertex`
* `provider_status` filters the provider rollout tier, for example `active`, `beta`, `alpha`, or `not_ready`
* `provider_routing_status` filters provider-level routing state
* `model_routing_status` filters model-level routing state
* `capability_status` filters provider capability state for the requested endpoint mapping
* `provider_availability_status` filters provider-side availability, for example `active`, `coming_soon`, or `inactive`
* `provider_availability_reason` filters provider-side availability reason, for example `preview_only`, `provider_not_ready`, `gated`, `access_limited`, or `region_limited`
* `organisation` filters by the public model ID prefix, for example `anthropic` in `anthropic/claude-3-haiku`
* `availability=active` is the default
* `availability=all` includes models or providers that are `coming_soon`, `inactive`, or not yet publicly routable
* `input_modalities` is an alias for `input_types`
* `output_modalities` is an alias for `output_types`
* `supported_parameters` is an alias for `params`

To inspect the endpoint contract for one model, call `GET /models/{author}/{slug}/endpoints`. The response separates provider routes and includes the public path, modalities, supported parameter detail, availability, routing state, provider model slug, and pricing summary for each row.

Provider entries can also include:

* `availability_status`
* `availability_reason`
* `provider_status`
* `provider_routing_status`
* `model_routing_status`
* `capability_status`

### Response

```json theme={null}
{
  "ok": true,
  "privacy_scope": "shared",
  "availability_mode": "all",
  "limit": 50,
  "offset": 0,
  "total": 99,
  "models": [
    {
      "id": "anthropic/claude-3-haiku",
      "canonical_slug": "anthropic/claude-3-haiku",
      "model_id": "anthropic/claude-3-haiku",
      "name": "anthropic/claude-3-haiku",
      "description": "anthropic/claude-3-haiku via Phaseo Gateway. Supports chat.completions, messages, responses.",
      "created": null,
      "release_date": null,
      "deprecation_date": null,
      "retirement_date": null,
      "status": "active",
      "availability": {
        "status": "coming_soon",
        "provider_count": 1,
        "active_provider_count": 0,
        "inactive_provider_count": 0
      },
      "organisation_id": "anthropic",
      "organisation_name": null,
      "organisation_colour": null,
      "aliases": [],
      "endpoints": ["chat.completions", "messages", "responses"],
      "input_types": ["text"],
      "output_types": ["text"],
      "architecture": {
        "modality": "text->text",
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": null,
        "instruct_type": "chat"
      },
      "providers": [
        {
          "api_provider_id": "anthropic",
          "api_provider_name": "Anthropic",
          "provider_model_slug": "claude-3-haiku-20240307",
          "is_active_gateway": false,
          "availability_status": "coming_soon",
          "availability_reason": "preview_only",
          "provider_status": "beta",
          "provider_routing_status": "active",
          "model_routing_status": "active",
          "capability_status": "coming_soon",
          "effective_from": "2026-06-01T00:00:00Z",
          "effective_to": null,
          "endpoints": ["responses"],
          "input_modalities": ["text"],
          "output_modalities": ["text"],
          "params": [
            "max_tokens",
            "response_format",
            "stop",
            "structured_outputs",
            "temperature",
            "tool_choice",
            "tools",
            "top_k",
            "top_p"
          ],
          "supported_parameters": [
            "max_tokens",
            "response_format",
            "stop",
            "structured_outputs",
            "temperature",
            "tool_choice",
            "tools",
            "top_k",
            "top_p"
          ],
          "supported_parameters_detail": {
            "temperature": {
              "supported": true,
              "type": "number",
              "minimum": 0,
              "maximum": 2
            }
          }
        }
      ],
      "supported_params": [
        "max_tokens",
        "response_format",
        "stop",
        "structured_outputs",
        "temperature",
        "tool_choice",
        "tools",
        "top_k",
        "top_p"
      ],
      "supported_params_detail": {
        "temperature": {
          "supported": true,
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "providers": ["openai"]
        }
      },
      "supported_parameters": [
        "max_tokens",
        "response_format",
        "stop",
        "structured_outputs",
        "temperature",
        "tool_choice",
        "tools",
        "top_k",
        "top_p"
      ],
      "supported_parameters_detail": {
        "temperature": {
          "supported": true,
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "providers": ["openai"]
        }
      },
      "top_provider_id": null,
      "top_provider": {
        "context_length": null,
        "max_completion_tokens": null,
        "is_moderated": false
      },
      "pricing": {
        "prompt": null,
        "completion": null,
        "request": null,
        "image": null,
        "input_cache_read": null,
        "input_cache_write": null,
        "web_search": null
      },
      "pricing_detail": {
        "pricing_plan": "standard",
        "meters": {}
      },
      "per_request_limits": null
    }
  ]
}
```

`availability_reason` is the single-field explanation for why a provider entry is active, preview-only, or inactive.


## OpenAPI

````yaml openapi/v1/openapi.yaml GET /models
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:
  /models:
    get:
      tags:
        - Gateway
      summary: List gateway models
      description: >-
        Returns shared non-hidden gateway models. Defaults to currently publicly
        routable models; use availability=all to include non-routable
        availability records. Use format=openai for an OpenAI-compatible model
        list. OpenAI format returns all filtered models by default; an explicit
        limit and offset can still select a page.
      operationId: listModels
      parameters:
        - name: search
          in: query
          description: >-
            Case-insensitive search across model ids, names, descriptions, and
            organisations.
          schema:
            type: string
            maxLength: 200
        - name: provider_search
          in: query
          description: Case-insensitive provider or model-organisation search.
          schema:
            type: string
            maxLength: 100
        - name: input_modality
          in: query
          description: Require a supported input modality.
          schema:
            type: string
            enum:
              - text
              - image
              - audio
              - video
        - name: minimum_context_tokens
          in: query
          description: Require at least this many input context tokens.
          schema:
            type: number
            minimum: 0
        - name: maximum_input_price_per_million
          in: query
          description: Maximum USD input-token price per million tokens.
          schema:
            type: number
            minimum: 0
        - name: gateway_available_only
          in: query
          description: Return only models with at least one routable gateway offer.
          schema:
            type: boolean
            default: false
        - name: sort_by
          in: query
          description: Field used to order model discovery results.
          schema:
            type: string
            enum:
              - relevance
              - input_price
              - output_price
              - context_length
              - provider_count
            default: relevance
        - name: sort_order
          in: query
          description: >-
            Optional sort direction. Price sorts default to ascending; other
            numeric sorts default to descending.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: endpoints
          in: query
          description: Filter by endpoints
          schema:
            type: array
            items:
              type: string
        - name: organisation
          in: query
          description: Filter by organisation
          schema:
            oneOf:
              - $ref: '#/components/schemas/OrganisationId'
              - type: array
                items:
                  $ref: '#/components/schemas/OrganisationId'
        - name: provider
          in: query
          description: Filter by provider id
          schema:
            type: array
            items:
              type: string
        - name: provider_status
          in: query
          description: Filter by provider rollout status
          schema:
            type: array
            items:
              type: string
        - name: provider_routing_status
          in: query
          description: Filter by provider routing status
          schema:
            type: array
            items:
              type: string
        - name: model_routing_status
          in: query
          description: Filter by model routing status
          schema:
            type: array
            items:
              type: string
        - name: capability_status
          in: query
          description: Filter by provider capability status
          schema:
            type: array
            items:
              type: string
        - name: provider_availability_status
          in: query
          description: Filter by provider availability status
          schema:
            type: array
            items:
              type: string
        - name: provider_availability_reason
          in: query
          description: Filter by provider availability reason
          schema:
            type: array
            items:
              type: string
        - name: status
          in: query
          description: Filter by model status
          schema:
            type: array
            items:
              type: string
        - name: input_types
          in: query
          description: Filter by input types
          schema:
            type: array
            items:
              type: string
        - name: input_modalities
          in: query
          description: Public alias for input_types.
          schema:
            type: array
            items:
              type: string
        - name: output_types
          in: query
          description: Filter by output types
          schema:
            type: array
            items:
              type: string
        - name: output_modalities
          in: query
          description: Public alias for output_types.
          schema:
            type: array
            items:
              type: string
        - name: params
          in: query
          description: Filter by params
          schema:
            type: array
            items:
              type: string
        - name: supported_parameters
          in: query
          description: Public alias for params.
          schema:
            type: array
            items:
              type: string
        - name: availability
          in: query
          description: >-
            Availability filter. active returns publicly routable models only;
            all includes non-routable availability records.
          schema:
            type: string
            enum:
              - active
              - all
            default: active
        - name: limit
          in: query
          description: Limit the number of results
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 250
        - name: offset
          in: query
          description: Offset for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 5000
        - name: format
          in: query
          description: >-
            Response format. Defaults to Phaseo-native json. OpenAI format
            returns the complete filtered list unless limit is supplied.
          schema:
            type: string
            enum:
              - json
              - openai
              - rss
              - atom
            default: json
        - name: feed
          in: query
          description: Alias for format. Accepts json, rss, or atom.
          schema:
            type: string
            enum:
              - json
              - rss
              - atom
        - name: If-None-Match
          in: header
          required: false
          description: >-
            ETag from an earlier JSON or OpenAI-format response for the same
            URL. If it still matches, the response is 304 Not Modified with no
            body. Accepts a comma-separated list, weak (W/) validators, and *.
          schema:
            type: string
      responses:
        '200':
          description: List of models
          headers:
            ETag:
              $ref: '#/components/headers/ModelListETag'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GatewayModelsResponse'
                  - $ref: '#/components/schemas/OpenAIModelsResponse'
            application/rss+xml:
              schema:
                type: string
                description: RSS 2.0 XML feed
            application/atom+xml:
              schema:
                type: string
                description: Atom XML feed
        '304':
          description: >-
            Not modified. If-None-Match still matches the current model list, so
            the response has no body. It repeats the ETag, Cache-Control, and
            Vary headers of the 200 response.
          headers:
            ETag:
              $ref: '#/components/headers/ModelListETag'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      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:
    OrganisationId:
      type: string
      description: Organisation identifier.
      enum:
        - 01-ai
        - adept
        - ai21
        - aion-labs
        - aisingapore
        - alibaba
        - allenai
        - amazon
        - anthracite-org
        - anthropic
        - arcee-ai
        - baai
        - baichuan
        - baidu
        - bigcode
        - black-forest-labs
        - bytedance
        - bytedance-seed
        - cogito
        - cognitivecomputations
        - cohere
        - crofai
        - cursor
        - cyfragovpl
        - databricks
        - dealignai
        - decart
        - deepseek
        - dots-studio
        - early-access
        - eleven-labs
        - essential-ai
        - fastino
        - fish-audio
        - github
        - google
        - gryphe
        - hexgrad
        - ibm
        - ibm-granite
        - inception
        - inclusionai
        - inference-net
        - inflection
        - intfloat
        - jetbrains
        - kblab
        - kling
        - kuaishou
        - kwaipilot
        - kwaivgi
        - lg
        - lightricks
        - liquid-ai
        - mancer
        - medaibase
        - meituan
        - meta
        - microsoft
        - mindai
        - minimax
        - mistral
        - mistralai
        - moonshotai
        - morph
        - naver-hyperclova
        - near-ai
        - nex-agi
        - nous
        - nousresearch
        - novasearch
        - nvidia
        - openai
        - openbmb
        - opencompass
        - opengvlab
        - orcarouter
        - ornith
        - perceptron
        - perplexity
        - phala
        - pixverse
        - poe
        - poolside
        - prime-intellect
        - prism-ml
        - qwen
        - reka
        - relace
        - runway
        - sakana
        - sao10k
        - sapiens-ai
        - sentence-transformers
        - sference
        - shanghai-ai-laboratory
        - shengshu-ai
        - snowflake
        - sourceful
        - spacex-ai
        - speakleash
        - stability-ai
        - stealth
        - stepfun
        - suno
        - tencent
        - thedrummer
        - thinking-machines
        - undi95
        - upstage
        - venice
        - vercel
        - villanova-ai
        - voyage
        - windsurf
        - writer
        - xai
        - xgenerationlab
        - xiaomi
        - z-ai
        - zyphra
    GatewayModelsResponse:
      type: object
      required:
        - ok
        - availability_mode
        - limit
        - offset
        - total
        - models
      properties:
        ok:
          type: boolean
          example: true
        availability_mode:
          type: string
          enum:
            - active
            - all
          example: active
        limit:
          type: integer
          minimum: 1
          maximum: 250
          example: 50
        offset:
          type: integer
          minimum: 0
          maximum: 5000
          example: 0
        total:
          type: integer
          minimum: 0
          example: 128
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
      additionalProperties: false
    OpenAIModelsResponse:
      type: object
      required:
        - object
        - data
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/OpenAIModel'
      additionalProperties: false
    InvalidRequestResponse:
      type: object
      required:
        - ok
        - error
        - message
      properties:
        ok:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: string
          example: invalid_request
        message:
          type: string
          example: Invalid request parameters.
        max_offset:
          type: integer
          minimum: 0
      additionalProperties: true
    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
    Model:
      type: object
      required:
        - id
        - base_model_id
        - variant
        - variants
        - name
        - description
        - organization
        - aliases
        - lifecycle
        - modalities
        - limits
        - capabilities
        - availability
        - pricing
        - offers
      properties:
        id:
          type: string
        base_model_id:
          type: string
        variant:
          type: string
        variants:
          type: object
          additionalProperties:
            type: object
            required:
              - model_id
              - name
            properties:
              model_id:
                type: string
              name:
                type: string
        name:
          type: string
        description:
          type: string
        organization:
          $ref: '#/components/schemas/GatewayModelOrganization'
        aliases:
          type: array
          items:
            type: string
        lifecycle:
          $ref: '#/components/schemas/GatewayModelLifecycle'
        modalities:
          $ref: '#/components/schemas/GatewayModalities'
        limits:
          $ref: '#/components/schemas/GatewayModelLimits'
        capabilities:
          $ref: '#/components/schemas/GatewayCapabilities'
        availability:
          $ref: '#/components/schemas/ModelAvailability'
        pricing:
          $ref: '#/components/schemas/GatewayPricing'
        offers:
          type: array
          items:
            $ref: '#/components/schemas/GatewayModelOffer'
      additionalProperties: false
    OpenAIModel:
      type: object
      required:
        - id
        - object
        - created
        - owned_by
      properties:
        id:
          type: string
          description: Canonical Phaseo model ID to use for inference.
          example: openai/gpt-4o-mini
        object:
          type: string
          enum:
            - model
        created:
          type: integer
          description: Release timestamp in Unix seconds, or 0 when unknown.
          minimum: 0
        owned_by:
          type: string
          description: >-
            Catalogue organization ID, private for workspace models, or phaseo
            when unknown.
          example: openai
      additionalProperties: false
    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
    GatewayModelOrganization:
      type: object
      nullable: true
      required:
        - id
        - name
        - color
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        color:
          type: string
          nullable: true
    GatewayModelLifecycle:
      type: object
      required:
        - status
        - released_at
        - deprecated_at
        - retires_at
        - replacement_id
        - message
      properties:
        status:
          type: string
          enum:
            - active
            - deprecated
            - retired
          nullable: true
        released_at:
          type: string
          nullable: true
        deprecated_at:
          type: string
          nullable: true
        retires_at:
          type: string
          nullable: true
        replacement_id:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
    GatewayModalities:
      type: object
      required:
        - input
        - output
      properties:
        input:
          type: array
          items:
            type: string
        output:
          type: array
          items:
            type: string
    GatewayModelLimits:
      type: object
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
        output_tokens:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
    GatewayCapabilities:
      type: object
      required:
        - parameters
        - parameter_details
      properties:
        endpoints:
          type: array
          items:
            type: string
        parameters:
          type: array
          items:
            type: string
        parameter_details:
          $ref: '#/components/schemas/SupportedParameterDetails'
    ModelAvailability:
      type: object
      required:
        - status
        - provider_count
        - active_provider_count
        - coming_soon_provider_count
        - inactive_provider_count
      properties:
        status:
          type: string
          enum:
            - active
            - coming_soon
            - inactive
            - not_listed
        provider_count:
          type: integer
          minimum: 0
        active_provider_count:
          type: integer
          minimum: 0
        coming_soon_provider_count:
          type: integer
          minimum: 0
        inactive_provider_count:
          type: integer
          minimum: 0
    GatewayPricing:
      type: object
      required:
        - pricing_plan
        - meters
      properties:
        pricing_plan:
          type: string
          enum:
            - standard
        meters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GatewayPricingMeter'
    GatewayModelOffer:
      type: object
      required:
        - provider
        - model
        - status
        - status_reason
        - routable
        - endpoints
        - modalities
        - capabilities
        - routing
        - effective
        - pricing
      properties:
        provider:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
              nullable: true
        model:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - active
            - coming_soon
            - inactive
        status_reason:
          $ref: '#/components/schemas/GatewayProviderAvailabilityReason'
        routable:
          type: boolean
        endpoints:
          type: array
          items:
            type: string
        modalities:
          $ref: '#/components/schemas/GatewayModalities'
        capabilities:
          $ref: '#/components/schemas/GatewayCapabilities'
        service_tiers:
          type: array
          description: >-
            Service tiers this offer accepts, sorted alphabetically. A tier is
            listed when the provider route has active, currently effective
            pricing for it; priority is the Fast tier. Other tiers may also be
            available through separate tier-specific provider routes.
          items:
            type: string
            enum:
              - flex
              - priority
              - standard
              - ultrafast
        routing:
          type: object
          required:
            - provider
            - model
            - capability
          properties:
            provider:
              $ref: '#/components/schemas/GatewayRoutingStatus'
            model:
              $ref: '#/components/schemas/GatewayRoutingStatus'
            capability:
              $ref: '#/components/schemas/GatewayCapabilityStatus'
        effective:
          type: object
          required:
            - from
            - to
          properties:
            from:
              type: string
              nullable: true
            to:
              type: string
              nullable: true
        pricing:
          $ref: '#/components/schemas/GatewayPricing'
    SupportedParameterDetails:
      type: object
      description: >-
        Structured constraints and provider support for request parameters,
        keyed by parameter name.
      additionalProperties:
        type: object
        additionalProperties: true
    GatewayPricingMeter:
      type: object
      nullable: true
      required:
        - provider_id
        - unit
        - unit_size
        - price_per_unit
        - currency
      properties:
        provider_id:
          type: string
        unit:
          type: string
        unit_size:
          type: number
          minimum: 0
          exclusiveMinimum: true
        price_per_unit:
          type: string
        currency:
          type: string
          enum:
            - USD
    GatewayProviderAvailabilityReason:
      type: string
      enum:
        - active
        - preview_only
        - gated
        - access_limited
        - region_limited
        - project_limited
        - paused
        - soft_blocked
        - deranked_lvl1
        - deranked_lvl2
        - deranked_lvl3
        - internal_testing
        - scheduled
        - coming_soon
        - provider_disabled
        - model_disabled
        - capability_disabled
        - provider_not_ready
        - provider_inactive
        - inactive
        - retired
    GatewayRoutingStatus:
      type: string
      enum:
        - active
        - deranked_lvl1
        - deranked_lvl2
        - deranked_lvl3
        - disabled
    GatewayCapabilityStatus:
      type: string
      enum:
        - active
        - coming_soon
        - deranked_lvl1
        - deranked_lvl2
        - deranked_lvl3
        - disabled
        - internal_testing
  headers:
    ModelListETag:
      description: >-
        Weak validator (W/ prefix) for the model list at this URL, covering the
        page, limit, offset, total, and format. It ignores gateway_region, so
        the same catalogue served from another region has the same value;
        responses that share it are equivalent, but their bytes can differ. Not
        sent with RSS, Atom, or error responses.
      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.