# API

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

Authenticate hosted management and inference calls with scoped API keys. Use separate tokens for self-hosted Relay.

Last updated: 2026-09-17

Use an API key to call AnchorShell without the dashboard.

## Hosted

1. Open **Account → API keys**.
2. Name your key. Enable **Allow management API access using my current permissions** if you need management operations; leave it unchecked for inference only.
3. Create the key and copy its secret once.

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

**Response — 200 OK**

Example enabled model; the catalog depends on your configuration.

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-5-mini",
      "object": "model",
      "owned_by": "anchorshell-relay"
    }
  ]
}
```

The same key can authenticate management calls when its scopes permit them:

```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
  }
]
```

Authorization uses the key owner's current user, organization, and permissions, narrowed by the key's selected scopes. Keys cannot grant access their owner lacks. Existing inference-only keys stay inference-only; create a management-enabled key when needed.

The public API origin is `https://api.anchorshell.com`: inference uses `/v1/*`, Relay management uses `/api/relay/*`, and account/team operations use `/api/account/*` and `/api/team/*`.

## Self-hosted

Use the independent inference token:

```bash
curl 'http://localhost:11730/v1/models' \
  -H 'Authorization: Bearer <RELAY_API_TOKEN>'
```

**Response — 200 OK**

Example enabled model; the catalog depends on your configuration.

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-5-mini",
      "object": "model",
      "owned_by": "anchorshell-relay"
    }
  ]
}
```

Use the management token for configuration:

```bash
curl 'http://localhost:11730/api/providers' \
  -H 'Authorization: Bearer <RELAY_ADMIN_TOKEN>'
```

**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
  }
]
```

For self-hosted equivalents of Relay management examples, replace `https://api.anchorshell.com/api/relay` with `http://localhost:11730/api` and use `<RELAY_ADMIN_TOKEN>`. Hosted account/team APIs and Smart Groups are not standalone features.

## Errors

- **401 Unauthorized:** missing, invalid, expired, disabled, or revoked API key.
- **403 Forbidden:** the key or its owner lacks permission, or the plan does not allow the operation.
- **400 Bad Request:** invalid input. **404 Not Found:** a resource is absent from your permitted scope where that operation supports a not-found response.
- **409 Conflict:** for example, a conflicting resource or an invitation beyond available team seats.
- Inference may also return **429** for capacity constraints or **5xx** for unavailable routing/upstream services. Inspect the response; do not blindly retry mutations.

Example hosted authentication failure:

```json
{
  "error": "authentication required"
}
```

Feature examples show successful responses. IDs are placeholders and samples marked “selected fields” are abbreviated, not exhaustive schemas. A **204 No Content** response has no JSON body.

## Reference

[Hosted OpenAPI](https://anchorshell.com/openapi.json) · [Self-hosted inference OpenAPI](https://anchorshell.com/openapi-self-hosted.json).

Password/email changes, session logout, and staff-only operations still require a browser session. API keys do not perform browser sign-in.

## Next

[Dashboard](https://anchorshell.com/docs/dashboard).