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

# Custom Providers

> Register, list, and delete your own OpenAI-compatible model endpoints (bring-your-own models).

Register any **OpenAI-compatible** chat-completions endpoint as a custom provider, then reference its models by the namespaced id `custom:<providerId>:<modelId>` in a [model plan](/api-reference/keys/model-plan) or on an [orchestrator-graph](/api-reference/keys/orchestrator-graph) Model node. Prompts to your own models are **free** and never draw Theo credits — you pay your provider directly.

## Authentication

Requires an API key with `billing` scope.

## Register a provider

`POST /api/v1/custom-providers`

<ParamField body="name" type="string" required>Display name (1–120 chars).</ParamField>
<ParamField body="base_url" type="string" required>The endpoint base URL — must be `http(s)`.</ParamField>
<ParamField body="api_key" type="string" required>The provider's API key. Stored encrypted; never returned by the API.</ParamField>

<ParamField body="models" type="object[]" required>
  1–50 models. Each: `{ id, label, contextWindow? }`.

  <Expandable title="model fields">
    <ParamField body="id" type="string" required>The raw model id sent to your endpoint (1–200 chars).</ParamField>
    <ParamField body="label" type="string" required>Display label (1–120 chars).</ParamField>

    <ParamField body="contextWindow" type="integer">
      Optional declared context window in tokens. When set, Theo's context-window guard can catch oversize requests to this model **before** they reach your endpoint (and route around it when a larger model is available on the key). Omit if unknown — the model is then treated as unbounded and passes the guard through.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="local" type="boolean">
  On-device / on-prem: reachable only from a linked desktop, never dispatched from the cloud. Default `false`.
</ParamField>

Returns `{ id }` — the provider id. Reference a model as `custom:<id>:<modelId>`.

## List providers

`GET /api/v1/custom-providers` → `{ providers: [{ id, name, base_url, models }] }`. API keys are never included.

## Delete a provider

`DELETE /api/v1/custom-providers/{id}` → `{ deleted: true }`.

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/custom-providers \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My vLLM",
      "base_url": "https://llm.example.com/v1",
      "api_key": "sk-...",
      "models": [{ "id": "my-llama-70b", "label": "Llama 70B", "contextWindow": 131072 }]
    }'
  ```
</CodeGroup>

Then pin it on a key:

```ts theme={null}
await theo.keys.setModelPlan("KEY_ID", {
  single_model: { upstream_id: "custom:PROVIDER_ID:my-llama-70b" },
});
```