# REST API Overview

## Base URL

```
https://api.chaser.sh
```

Interactive API documentation:
- OpenAPI spec: `https://api.chaser.sh/api-docs/openapi.json`
- Swagger UI: `https://api.chaser.sh/swagger-ui`

## Authentication

All `/v1/*` routes require a bearer token:

```http
Authorization: Bearer sk_your_key_here
```

Accepted token types:
- **API keys** (`sk_...`)
- **JWT access tokens** (from OAuth login)

## Account selection

Select the active account context with:

```http
X-Chaser-Account: <account_id_or_name>
```

Accepts: account ID, exact account name, or `personal`. If omitted, your personal account is used.

All resources (sessions, workspaces, jobs, webhooks, audit) are scoped to the active account.

## Session endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/sessions` | POST | Create a session |
| `/v1/sessions` | GET | List sessions |
| `/v1/sessions/{id}` | GET | Get session details |
| `/v1/sessions/{id}` | DELETE | Terminate session |
| `/v1/sessions/bulk-terminate` | POST | Terminate multiple sessions |
| `/v1/sessions/{id}/pty` | GET | WebSocket PTY upgrade |
| `/v1/sessions/{id}/resize` | POST | Resize PTY |

### Session gateway

Access session services through:
- **Subdomain:** `https://<session_id>.chaser.sh/`
- **Path:** `https://api.chaser.sh/s/<session_id>/`

## Execution endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/exec` | POST | Auto-spawn sandbox and execute |
| `/v1/sessions/{id}/exec` | POST | Execute in existing session |
| `/v1/sessions/{id}/self-test` | POST | Runtime diagnostics |
| `/v1/sessions/{id}/commands` | GET | List background commands |
| `/v1/sessions/{id}/commands/{cid}` | GET | Get command status |
| `/v1/sessions/{id}/commands/{cid}/stream` | GET | Stream output (SSE) |
| `/v1/sessions/{id}/commands/{cid}/stdin` | POST | Send stdin input |
| `/v1/sessions/{id}/commands/{cid}/kill` | POST | Signal the process |

## File transfer endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/sessions/{id}/upload` | POST | Upload file (multipart) |
| `/v1/sessions/{id}/download` | GET | Download file |

File transfer is sandbox-only, with a 16 MB per-file limit.

## Workspace endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/workspaces` | POST | Create workspace |
| `/v1/workspaces` | GET | List workspaces |
| `/v1/workspaces/import` | POST | Import from GitHub |
| `/v1/workspaces/bulk-delete` | POST | Bulk delete |
| `/v1/workspaces/{ws}` | DELETE | Delete workspace |
| `/v1/workspaces/{ws}/name` | PUT | Set/clear name |
| `/v1/workspaces/{ws}/template` | PUT | Toggle template |
| `/v1/workspaces/{ws}/snapshots` | GET | List snapshots |
| `/v1/workspaces/{ws}/snapshots` | POST | Create snapshot |
| `/v1/workspaces/{ws}/snapshots/{name}/restore` | POST | Restore snapshot |
| `/v1/workspaces/{ws}/snapshots/{name}` | DELETE | Delete snapshot |

## Job endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/jobs` | POST | Create a job |
| `/v1/jobs` | GET | List jobs |
| `/v1/jobs/kinds` | GET | List available job kinds |
| `/v1/jobs/{id}` | GET | Get job details |
| `/v1/jobs/{id}/cancel` | POST | Cancel job |
| `/v1/jobs/{id}/retry` | POST | Retry job |

## Account endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/accounts` | GET | List accounts |
| `/v1/accounts/current` | GET | Current account details |
| `/v1/accounts/organizations` | POST | Create organization |
| `/v1/accounts/current/members` | GET | List members |
| `/v1/accounts/current/members` | POST | Add member |
| `/v1/accounts/current/members/{uid}` | PATCH | Update member role |
| `/v1/accounts/current/members/{uid}` | DELETE | Remove member |
| `/v1/accounts/current/service-accounts` | GET | List service accounts |
| `/v1/accounts/current/service-accounts` | POST | Create service account |
| `/v1/accounts/current/service-accounts/{said}` | DELETE | Delete service account |
| `/v1/accounts/current/service-accounts/{said}/keys` | GET | List SA keys |
| `/v1/accounts/current/service-accounts/{said}/keys` | POST | Create SA key |
| `/v1/accounts/current/service-accounts/{said}/keys/{kid}` | DELETE | Revoke SA key |

## Key and SSH endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/keys` | GET | List API keys |
| `/v1/keys` | POST | Create API key |
| `/v1/keys/{id}` | DELETE | Revoke API key |
| `/v1/ssh-keys` | GET | List SSH keys |
| `/v1/ssh-keys` | POST | Register SSH key |
| `/v1/ssh-keys/{id}` | DELETE | Delete SSH key |

## Webhook endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/webhooks` | GET | List webhooks |
| `/v1/webhooks` | POST | Create webhook |
| `/v1/webhooks/{id}` | DELETE | Delete webhook |
| `/v1/webhooks/deliveries` | GET | List deliveries |
| `/v1/webhooks/deliveries/{did}` | GET | Get delivery details |
| `/v1/webhooks/deliveries/{did}/replay` | POST | Replay delivery |
| `/v1/webhooks/deliveries/{did}/discard` | POST | Discard delivery |

## Billing endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/billing/summary` | GET | Billing summary for active account |
| `/v1/billing/account` | POST | Update billing configuration |
| `/v1/billing/checkout` | POST | Create Stripe checkout session |

## Audit endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/audit/events` | GET | List audit events |

## MCP endpoint

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/mcp` | POST | MCP JSON-RPC (tools/list, tools/call) |

## Auth endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/register` | POST | Register with email/password |
| `/auth/login` | POST | Login with email/password |
| `/auth/google/login` | GET | Google OAuth login |
| `/auth/google/callback` | GET | Google OAuth callback |
| `/auth/github/login` | GET | GitHub OAuth login |
| `/auth/github/callback` | GET | GitHub OAuth callback |
| `/auth/codex/login-url` | GET | Codex OAuth login URL |
| `/auth/codex/callback` | GET/POST | Codex OAuth callback |
| `/auth/me` | GET | Current user info |

## Assistant endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/assistants` | POST | Create assistant |
| `/v1/assistants` | GET | List assistants |
| `/v1/assistants/{id}` | GET | Get assistant |
| `/v1/assistants/{id}` | PATCH | Update assistant |
| `/v1/assistants/{id}/pause` | POST | Pause assistant |
| `/v1/assistants/{id}/resume` | POST | Resume assistant |
| `/v1/assistants/{id}/channels` | POST | Add channel binding |
| `/v1/assistants/{id}/channels/{bid}` | DELETE | Remove binding |
| `/v1/assistants/credentials` | PUT | Store credential |
| `/v1/assistants/resolve-credential` | POST | Resolve credential |
| `/v1/assistants/resolve-channel` | POST | Resolve channel |
| `/v1/assistants/{id}/runtime-state` | GET | Get runtime state |
| `/v1/assistants/{id}/runtime-state` | PUT | Update runtime state |
| `/v1/assistants/{id}/usage-events` | POST | Record usage event |
| `/v1/assistants/{id}/usage-events` | GET | List usage events |
| `/v1/assistants/{id}/config-change-requests` | POST | Propose config change |
| `/v1/assistants/{id}/config-change-requests/{rid}/approve` | POST | Approve change |
| `/v1/assistants/{id}/config-change-requests/{rid}/deny` | POST | Deny change |

## Scoped API keys

API keys can be created with specific permission scopes:

`sessions.read`, `sessions.write`, `workspaces.read`, `workspaces.write`, `exec.write`, `files.read`, `files.write`, `keys.read`, `keys.write`, `billing.read`, `billing.write`, `audit.read`, `webhooks.read`, `webhooks.write`

Keys created without scopes have full access. Keys are bound to the account selected at creation time.

## Rate limiting

Write-heavy endpoints return `429 Too Many Requests` when rate limits are exceeded. Responses include:

- `Retry-After`
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`
- `X-RateLimit-Scope` (`principal` or `account`)

Rate-limited surfaces: session mutations, workspace mutations, exec, file transfer, jobs, MCP, and webhook mutations.