# Bridges

GET | POST /v1/organizations/bridges - list your Claude Code bridges or register one.

*ProxyLLM docs · https://proxyllm.ai/docs/api/bridges*

```
GET  /v1/organizations/bridges
POST /v1/organizations/bridges
```

Auth: **[account token](/docs/api/authentication)**. `rk_` or `sk_` can list; registering needs `sk_`. Normally you never call POST yourself; `npx proxyllm-bridge setup` does it for you ([Claude Code Bridge](/docs/claude-code)).

## List

```bash
curl https://api.proxyllm.ai/v1/organizations/bridges \
  -H "Authorization: Bearer rk_your_readonly_token"
```

```json
{
  "bridges": [
    {
      "id": "9c4e1f7b-...",
      "label": "claude-code-lab",
      "kind": "claude_code",
      "base_url": "https://bridge.example.com",
      "token_fingerprint": "b7c9",
      "cloud_provider": "digitalocean",
      "cloud_instance_id": "do-123456",
      "region": "nyc3",
      "status": "healthy",
      "plan_tier": null,
      "last_health_at": "2026-07-03T09:12:00.000Z",
      "last_error": null,
      "created_at": "2026-06-01T10:00:00.000Z",
      "updated_at": "2026-07-03T09:12:00.000Z"
    }
  ]
}
```

`status` is one of `unknown`, `provisioning`, `healthy`, `unhealthy`. Revoked bridges are excluded. The bridge's bearer token is never returned; `token_fingerprint` is its last 4 characters for recognition.

## Register

```bash
curl -X POST https://api.proxyllm.ai/v1/organizations/bridges \
  -H "Authorization: Bearer sk_your_account_token" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "claude-code-lab",
    "base_url": "https://bridge.example.com",
    "token": "pllb_9f2c81d4a7b3"
  }'
```

Request body:

| Field               | Type                            | Notes                                                               |
| ------------------- | ------------------------------- | ------------------------------------------------------------------- |
| `base_url`          | string, required                | `http://` or `https://` URL of your bridge.                         |
| `token`             | string, required                | The bridge's bearer token, at least 8 characters. Stored encrypted. |
| `label`             | string                          | Up to 80 characters. Defaults to `"Claude Code Bridge"`.            |
| `cloud_provider`    | string                          | Optional, for your own bookkeeping.                                 |
| `cloud_instance_id` | string                          | Optional.                                                           |
| `region`            | string                          | Optional.                                                           |
| `status`            | `"provisioning"` or `"unknown"` | Initial status. Defaults to `unknown`; health checks update it.     |

Response:

```json
{
  "bridge": {
    "id": "9c4e1f7b-...",
    "label": "claude-code-lab",
    "kind": "claude_code",
    "base_url": "https://bridge.example.com",
    "token_fingerprint": "a7b3",
    "cloud_provider": null,
    "cloud_instance_id": null,
    "region": null,
    "status": "unknown",
    "plan_tier": null,
    "last_health_at": null,
    "last_error": null,
    "created_at": "2026-07-03T10:00:00.000Z",
    "updated_at": "2026-07-03T10:00:00.000Z"
  }
}
```

## Errors

| Status | Code                    | When                                                                    |
| ------ | ----------------------- | ----------------------------------------------------------------------- |
| 400    | `bad_request`           | Invalid `base_url`, token shorter than 8 characters, or label too long. |
| 401    | (none)                  | No token sent.                                                          |
| 401    | `invalid_account_token` | Unknown or revoked token.                                               |
| 403    | `read_only_token`       | POST with an `rk_` token.                                               |
| 405    | `method_not_allowed`    | Method other than GET or POST.                                          |
| 500    | `server_error`          | The database write failed.                                              |