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

# Connect Dedicated Model Deployments

> Add a private OpenAI-compatible endpoint to your workspace model catalogue.

Private Models let your team call a dedicated or self-hosted deployment through the normal Phaseo API. The model appears only to authenticated members of the workspace and can be used anywhere you would use a public model ID.

Typical sources include dedicated deployments on Baseten, Modal, RunPod, Fireworks, or Together, plus services running vLLM or another OpenAI-compatible server.

## Before you start

Your deployment must provide:

* a public HTTPS base URL;
* an OpenAI-compatible `/chat/completions` endpoint;
* Bearer-token authentication; and
* an upstream model or deployment ID accepted by that endpoint.

Support for `/responses` is optional. Leave it disabled unless the deployment explicitly implements that endpoint.

> [!WARNING]
>
> Private Models do not adapt native-only provider protocols or custom authentication schemes. Put an OpenAI-compatible layer in front of those deployments or use a supported Phaseo provider integration.

## Connect a deployment

**1. Open Private Models**

Open **Dashboard → Settings → Workspace → Private Models**, then select **Add model**. You must be a workspace owner or admin. From the CLI, run `phaseo private-models create` with the same fields and pass the credential with `--credential-stdin`.

**2. Name the model**

Choose an existing catalogue model to add this deployment to its provider list, or enter a short model slug such as `legal-assistant`. If no catalogue model has that unique slug, Phaseo combines the trusted workspace namespace with it:

```text theme={null}
acme/legal-assistant
```

You cannot choose or replace the workspace namespace. Exact catalogue IDs attach to that model without changing its public identity.

**3. Configure the endpoint**

Enter the base URL before the inference path. For example, use:

```text theme={null}
https://model.example.com/v1
```

Do not include `/chat/completions` or `/responses`. Enter the exact upstream model or deployment ID separately; Phaseo substitutes it when forwarding requests.

**4. Store the credential**

Enter the deployment's API key. Phaseo encrypts the credential and never returns it after saving. You can replace it later from the model's settings page.

**5. Call the model**

Use the generated model ID with the regular Chat Completions endpoint:

```bash cURL theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "acme/legal-assistant",
    "messages": [{"role": "user", "content": "Summarize this contract."}]
  }'
```

The calling API key must belong to the same workspace as the private model.

## How routing works

Private models use the same Phaseo request surface as catalogue models. A standalone workspace model routes only to its configured endpoint. An endpoint attached to a catalogue model joins that model's provider list according to its **Preferred**, **Normal pool**, or **Fallback only** routing policy. Phaseo sends the stored credential as a Bearer token and substitutes the configured upstream model ID.

A private model does not become a public provider route and is not visible to other workspaces. Enabled private models are included in the authenticated model catalogue and appear under the **Private** filter.

> [!NOTE]
>
> After adding or enabling a private deployment on an existing catalogue model, allow 5–10 seconds for the change to propagate through the API layer before testing its routing. During this window, requests may continue to use the model's existing public providers. Requests already in flight are not rerouted.

## Provider examples

| Deployment | What to enter |
| - | - |
| Baseten dedicated endpoint | Its OpenAI-compatible base URL, deployment model ID, and API key |
| Modal web endpoint | A public HTTPS endpoint that implements the OpenAI Chat Completions contract |
| RunPod serverless endpoint | An OpenAI-compatible proxy URL and Bearer credential |
| Fireworks or Together dedicated deployment | The dedicated OpenAI-compatible URL and provider model ID |
| vLLM | The public URL ending at `/v1` and the model name served by vLLM |

Provider products and URL formats can change. Confirm the base URL, model ID, authentication method, and supported endpoints in the provider's current deployment documentation.

## Manage private models through the API

Server-side administration can use the [Private Models API](https://phaseo.app/docs/v1/api-reference/endpoint/private-models-list.md) with a management key carrying `private_models:read`, `private_models:write`, or `private_models:delete` as needed.

Create and update requests accept `model_reference`, either an exact catalogue model ID or a short slug. Phaseo derives `model_id`; clients cannot submit it directly. Use `host_provider_id` for an existing Phaseo provider, or `custom_provider_name` and optional `custom_provider_url` for another operator.

## Troubleshooting

* **404 from the provider:** Check that the base URL stops before the inference path.
* **Unknown model:** Copy the provider's upstream deployment ID into **Upstream model ID**. Do not use the Phaseo workspace model ID there.
* **Unauthorized upstream request:** Replace the stored credential and confirm the provider accepts Bearer authentication.
* **Chat works but Responses fails:** Disable **Responses API** unless the provider implements `/responses` natively.
* **Model missing from the catalogue:** Confirm the model is enabled and the caller is authenticated to the same workspace.


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