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

# Publish a provider catalog

> Publish V1, V1.1 or V1.2 model feeds with normalized service-tier offers, data policies and rate limits.

Approved providers can update offers for existing public canonical models through their catalog feed or provider settings. New canonical models require approval. Each catalog is a complete snapshot: removing an offer retires that feed-managed offer and preserves its pricing history.

## Choose a format

Existing V1 feeds continue to work without changes. An unversioned `{"data": [...]}` document, or one declaring `"schema_version": "1.0"`, uses the existing standard-tier format.

V1.1 declares `"schema_version": "1.1"` and publishes `service_tiers` inside each model. The importer selects the format from the document. URL query parameters such as `?format=phaseo-v1.1` are optional conventions for your endpoint; Phaseo does not infer a version from the URL.

Download the [V1 schema](https://phaseo.app/api/internal/provider-catalog/schema), [V1.1 schema](https://phaseo.app/api/internal/provider-catalog/schema?version=1.1) or [V1.2 schema](https://phaseo.app/api/internal/provider-catalog/schema?version=1.2). Unsupported versions are rejected explicitly.

### V1.2 data policies

V1.2 adds capability-specific training and retention declarations to each service tier. You can publish V1.2 at any time. Phaseo validates declarations on import, but they grant no guarantee until Phaseo approves your policy source. V1 and V1.1 feeds remain supported.

V1.2 also accepts optional model-level or tier-level `declarations` for model identity, typed input/output limits, parameter descriptions, scoped pricing and capacity, discounts, and deployment details. These are validated and retained for review. They do not automatically enable parameters or change billable prices, capacity enforcement or residency guarantees. Validation feedback identifies stored declarations; continue publishing effective prices and capabilities through their existing fields.

Set `schema_version` to `"1.2"` and add a `data_policy` object to each applicable tier:

```json theme={null}
{
  "capabilities": [{
    "id": "text.generate",
    "training_policy": "no_train",
    "retention_mode": "none",
    "retention_days": 0,
    "zero_data_retention": true,
    "zdr_eligibility": "eligible",
    "requirements": { "contract_mode": "none", "account_settings": [] },
    "privacy_policy_url": "https://provider.example/privacy",
    "terms_of_service_url": "https://provider.example/terms"
  }]
}
```

This example is the tier's `data_policy` value, not a complete feed. Capability IDs are canonical: use `text.generate` even when the model declares `responses` or `chat.completions`.

The declaration covers both prompts and outputs across the upstream processing chain. It does not describe billing metadata. Training values are `unknown`, `may_train`, `no_train`, `opt_out_available`, and `enterprise_no_train`. Retention modes are `unknown`, `none`, `transient`, `fixed`, and `until_deleted`. Use zero days for none, a positive maximum duration for transient/fixed, and null for unknown/until-deleted.

Declare required agreements with `contract_mode`: `none`, `customer_agreement`, or `enterprise_agreement`. Required account settings are objects with `id`, `description`, and HTTPS `documentation_url` in the `account_settings` array. Conditional programmes use `zdr_eligibility: "conditional"` and cannot declare an active true guarantee. They remain informational until Phaseo can verify fulfilment.

Phaseo approves the policy source independently. The feed cannot mark a declaration verified. This release grants active ZDR only for unconditional text generation on non-batch offers, with no training and no content retention. Hosting a model yourself does not by itself declare ZDR.

After an offer adopts feed-managed policy, setting false, sending null, omitting its declaration, or downgrading the feed version withdraws that guarantee. Manual Phaseo overrides are maintained separately. Positive declarations expire after 24 hours without successful catalog validation; approval revocation does not require a new provider fetch.

## Publish normalized tiers

| Tier | Meaning |
| - | - |
| `standard` | Normal synchronous execution; required for every model. |
| `fast` | A faster or priority offer. Provider names such as HighSpeed stay in the upstream model ID. |
| `ultrafast` | A separate, higher-speed offer when supported. |
| `flex` | A flexible, lower-priority synchronous offer. |
| `batch` | Asynchronous execution through the Batch API. Requires a batch capability. |

Do not use provider-specific tier names as normalized IDs. `priority` remains a supported caller alias for Fast; catalogs publish `fast`.

Fast, Ultrafast and Flex selection is supported on text generation requests. Batch runs through the separate Batch API and still requires an installed provider Batch integration; publishing a tier does not install that integration. For uploaded provider-native files, use the declared Batch model ID or submit requests inline so Phaseo can translate it.

Use the same canonical model ID for its service tiers. Different models need separate canonical identities. Tiers inherit the model's capabilities, limits and release schedule. Each tier declares its own upstream model ID, availability and effective pricing.

```json theme={null}
{
  "schema_version": "1.1",
  "data": [{
    "id": "your-provider/example-model",
    "name": "Example model",
    "capabilities": ["chat.completions"],
    "service_tiers": [{
      "service_tier": "standard",
      "provider_model_slug": "example-model",
      "availability": "ready",
      "pricing": [{
        "meter_key": "input_text_tokens",
        "modality": "text",
        "direction": "input",
        "unit": "token",
        "unit_quantity": 1000000,
        "price_nanos": 100000000,
        "display_label": "Input",
        "display_unit": "1M tokens"
      }, {
        "meter_key": "output_text_tokens",
        "modality": "text",
        "direction": "output",
        "unit": "token",
        "unit_quantity": 1000000,
        "price_nanos": 200000000,
        "display_label": "Output",
        "display_unit": "1M tokens"
      }]
    }]
  }]
}
```

To add Fast, add another tier object with `"service_tier": "fast"`, its effective prices, and a distinct upstream model ID for that offer. If the provider selects its lane using a native parameter instead, use the same upstream model ID and declare `"upstream_service_tier": "priority"` or `"fast"`. Omit that field when the model ID selects the lane. Standard accepts `default` or `standard`; Flex and Ultrafast accept their corresponding values. Phaseo rejects nonstandard synchronous tiers that have no distinct model ID or native selector.

Every tier needs explicit pricing, including output and any cache/media meters you bill. Zero prices are valid; negative prices, unknown meters, duplicate tiers and conditional rates are rejected. `price_nanos` remains the effective price after promotions. Publish a new snapshot when rates change; Phaseo keeps previous effective prices.

## Declare rate limits

Declare the request and token limits your platform applies to Phaseo's account in an optional top-level `rate_limits` array. It works the same way in V1 and V1.1 documents. Leave out `model` for a limit across all of your models, or set it to the upstream `provider_model_slug` of any model or tier in the same document.

```json theme={null}
{
  "schema_version": "1.1",
  "data": [{ "id": "your-provider/example-model", "...": "..." }],
  "rate_limits": [
    { "requests_per_minute": 600, "tokens_per_minute": 2000000 },
    { "model": "example-model", "requests_per_day": 100000, "tokens_per_day": 500000000 }
  ]
}
```

Each entry accepts `requests_per_minute`, `requests_per_day`, `tokens_per_minute` and `tokens_per_day`. Each value is a positive integer or `null`, and each entry needs at least one value. Phaseo counts each limit globally across all of its traffic to you. A model limit applies in addition to the limit across all models.

Limits never block requests. As an offer's traffic approaches a limit, Phaseo sends it a gradually smaller share. Once the limit is reached, Phaseo ranks the offer below other providers until the limit resets. A value that is too low only reduces your own share of traffic. For that reason, limits apply without review once your provider application is approved, usually within a minute.

When the array is present, it replaces your declared limits each time a changed feed imports successfully. An empty array removes them. Omit `rate_limits` to keep the limits you manage in provider settings. Phaseo rejects the whole snapshot, and keeps your current catalog and limits, if an entry names a model that is not in the document, repeats a scope, or uses a value that is not a positive integer. The rejection appears as **Changes requested**.

You can also edit limits in **Provider settings → Your models → Rate limits**. Those edits save separately from catalog changes. The catalog editor does not accept `rate_limits`.

## Update and verify

Polling and signed catalog-change webhooks accept both versions through the same onboarding and refresh flow. In provider settings, select a tier before editing its upstream ID, availability or prices. Adding another tier changes the saved catalog to V1.1.

The catalog does not add an inference adapter or credentials. A provider and its advertised capabilities must be integrated before routing is enabled. Batch pricing does not make Batch available on synchronous chat endpoints.

An unavailable canonical model or unknown publisher mapping is shown as **Changes requested** without preventing valid models from importing. Check the provider dashboard for model-specific reasons.

For API-fed catalogs, dashboard edits are persistent overrides. Imports update fields without overrides. Select **Use feed value** to remove an override and resume following that field. The dashboard shows the latest feed value, effective value, editor and time; catalog activity records edits and reversions. Models added manually remain local offers. Removing a model from the feed retires that feed offer even if some of its fields were edited. Existing manual-only catalogs remain supported.


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