# Providers

Canonical HTML: https://anchorshell.com/docs/providers

Understand providers, credentials, and configured models; add them in the dashboard or through the API.

Last updated: 2026-09-17

A **Provider** is the upstream service Relay calls. A **Credential** authenticates Relay to that service. A **Model** is a configured upstream model, with its supported request type, pricing, and limits.

Clients use the model's displayed `provider/model` call name. Configuring several providers lets [Groups](https://anchorshell.com/docs/groups) choose among their models.

## Dashboard

1. In **Providers**, choose **Add API Key Provider** to open Setup.
2. Import the provider's curl request or enter its connection details. Add its API key in the credential field.
3. Review the model, request type, pricing, and available limits; save the configuration.
4. On Providers, use **Add model** to add another model to that provider. Edit, duplicate, or delete through the row actions.

Hosted **Subscription Plan Providers** use a separate account-connection flow. OpenAI Codex is available where enabled: authorize the account, verify it, then enable discovered models. This does not mean arbitrary subscriptions are supported. Ordinary API-key providers remain available when self-hosting.

## API

Use a key with the relevant permissions; see [API authentication](https://anchorshell.com/docs/api). Replace placeholders with IDs from the corresponding list or create response.

Management requires `relay:providers:read` or `relay:providers:manage`. List and create responses contain public `id` values. There is currently no separate `GET /providers/<PROVIDER_ID>` or `GET /endpoints/<MODEL_ID>`; find the item in its list response.

### List providers

```bash
curl 'https://api.anchorshell.com/api/relay/providers' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
[
  {
    "id": "<PROVIDER_ID>",
    "name": "OpenAI",
    "slug": "openai",
    "base_url": "https://api.openai.com/v1",
    "auth_mode": "bearer_static",
    "enabled": true
  }
]
```

### Create a provider

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/providers' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "OpenAI",
  "base_url": "https://api.openai.com/v1",
  "auth_mode": "bearer_static",
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<PROVIDER_ID>",
  "name": "OpenAI",
  "slug": "openai",
  "base_url": "https://api.openai.com/v1",
  "auth_mode": "bearer_static",
  "enabled": true
}
```

### Update a provider

```bash
curl -X PUT 'https://api.anchorshell.com/api/relay/providers/<PROVIDER_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "OpenAI production",
  "base_url": "https://api.openai.com/v1",
  "auth_mode": "bearer_static",
  "enabled": true
}'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<PROVIDER_ID>",
  "name": "OpenAI production",
  "slug": "openai",
  "base_url": "https://api.openai.com/v1",
  "auth_mode": "bearer_static",
  "enabled": true
}
```

### Save a credential

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/credentials' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider_id": "<PROVIDER_ID>",
  "name": "OpenAI key",
  "secret": "<PROVIDER_API_KEY>",
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<CREDENTIAL_ID>",
  "provider_id": "<PROVIDER_ID>",
  "name": "OpenAI key",
  "has_secret": true,
  "enabled": true
}
```

The credential response exposes metadata, not its secret. Save its `id` for the model.

### List models

```bash
curl 'https://api.anchorshell.com/api/relay/endpoints' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
[
  {
    "id": "<MODEL_ID>",
    "provider_id": "<PROVIDER_ID>",
    "credential_id": "<CREDENTIAL_ID>",
    "name": "gpt-5-mini",
    "upstream_model": "gpt-5-mini",
    "route_kind": "chat",
    "enabled": true
  }
]
```

### Create a model

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/endpoints' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider_id": "<PROVIDER_ID>",
  "credential_id": "<CREDENTIAL_ID>",
  "name": "gpt-5-mini",
  "upstream_model": "gpt-5-mini",
  "route_kind": "chat",
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<MODEL_ID>",
  "provider_id": "<PROVIDER_ID>",
  "credential_id": "<CREDENTIAL_ID>",
  "name": "gpt-5-mini",
  "upstream_model": "gpt-5-mini",
  "route_kind": "chat",
  "enabled": true
}
```

Use an upstream model your provider account can access.

### Update a model

```bash
curl -X PUT 'https://api.anchorshell.com/api/relay/endpoints/<MODEL_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Support model",
  "upstream_model": "gpt-5-mini",
  "route_kind": "chat",
  "enabled": true
}'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<MODEL_ID>",
  "provider_id": "<PROVIDER_ID>",
  "credential_id": "<CREDENTIAL_ID>",
  "name": "Support model",
  "upstream_model": "gpt-5-mini",
  "route_kind": "chat",
  "enabled": true
}
```

### Delete a model

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/endpoints/<MODEL_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

### Delete a provider

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/providers/<PROVIDER_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

Deletion removes that resource from routing. Check affected groups before deleting.

## Next

[Groups](https://anchorshell.com/docs/groups).