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

# REST API

> Drive BossMode programmatically from any HTTP client. Authenticate with x-bossmode-token, respect per-route rate limits, and consume the full Pro API surface.

# REST API

Plain HTTP with an `x-bossmode-token` header. Every surface BossMode offers — context, directives, approvals, reports, packs, devices, revenue events, guardian, AvatarCzar — is reachable over standard HTTPS and rate-limited per workspace.

Reach for the REST API when your caller is your own Node or Python pipeline, a CI runner shipping without Node installed, or any integration where adding an MCP host or the CLI would be overkill. The same `x-bossmode-token` used by the CLI and the MCP server works here — one token, three surfaces.

## Base URL

```
https://bossmode.ing
```

## Authentication

All Pro API routes require the `x-bossmode-token` header:

```bash theme={null}
curl -H "x-bossmode-token: YOUR_TOKEN_HERE" \
  https://bossmode.ing/api/pro/context
```

Obtain your token from the workspace settings page at `bossmode.ing/app/<workspace>/settings/api`.

Unauthenticated requests to Pro routes return `401 Unauthorized`. Admin routes (`/api/admin/*`) use a separate admin session cookie — not the Pro token.

## Rate limits

Rate limits are applied per IP per route. Limits are sourced from `lib/api-rate-limit.ts`.

| Route                              | Limit  | Window |
| ---------------------------------- | ------ | ------ |
| `/api/pro/context`                 | 60 req | 60 s   |
| `/api/pro/profile`                 | 20 req | 60 s   |
| `/api/pro/bootstrap`               | 20 req | 60 s   |
| `/api/pro/feed`                    | 30 req | 60 s   |
| `/api/pro/metrics`                 | 30 req | 60 s   |
| `/api/pro/revenue-events`          | 30 req | 60 s   |
| `/api/pro/ack`                     | 30 req | 60 s   |
| `/api/pro/approvals`               | 30 req | 60 s   |
| `/api/pro/work-packets`            | 20 req | 60 s   |
| `/api/pro/audit-feed`              | 30 req | 60 s   |
| `/api/pro/standing-orders`         | 30 req | 60 s   |
| `/api/pro/skill-packs`             | 30 req | 60 s   |
| `/api/pro/directive`               | 20 req | 60 s   |
| `/api/pro/family/comment`          | 30 req | 60 s   |
| `/api/pro/guardian/checkpoint`     | 30 req | 60 s   |
| `/api/pro/guardian/killswitch`     | 30 req | 60 s   |
| `/api/pro/guardian/preflight`      | 60 req | 60 s   |
| `/api/pro/guardian/revert`         | 20 req | 60 s   |
| `/api/pro/consigliere/chat`        | 30 req | 60 s   |
| `/api/pro/engines`                 | 30 req | 60 s   |
| `/api/pro/avatarczar/avatar`       | 5 req  | 60 s   |
| `/api/pro/avatarczar/intelligence` | 5 req  | 60 s   |
| `/api/pro/avatarczar/induction`    | 60 req | 60 s   |
| `/api/pro/avatarczar/webhooks`     | 5 req  | 60 s   |
| `/api/pro/escalations/decide`      | 20 req | 60 s   |
| `/api/pro/subscription/verify`     | 60 req | 60 min |
| `/api/local/hydrate`               | 5 req  | 60 min |

When a limit is exceeded the response is `429 Too Many Requests` with headers:

```
Retry-After: <seconds>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: 0
```

## OpenAPI spec

An OpenAPI spec is not currently served at `/openapi.json`. The route table below is maintained from `lib/api-rate-limit.ts`, which is the source of truth.

## Common routes

| Route                          | Method     | Description                                                                                              |
| ------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------- |
| `/api/pro/context`             | GET        | Full consigliere brief (signals, packets, standing orders, metrics, audit, guardian, AvatarCzar persona) |
| `/api/pro/profile`             | GET        | Operator profile — autonomy settings, installed packs, tier, device list                                 |
| `/api/pro/feed`                | GET        | Activity feed                                                                                            |
| `/api/pro/metrics`             | GET        | Revenue and performance metrics                                                                          |
| `/api/pro/revenue-events`      | POST       | Log a revenue event                                                                                      |
| `/api/pro/ack`                 | POST       | Acknowledge a signal                                                                                     |
| `/api/pro/directive`           | POST       | Submit a boss directive                                                                                  |
| `/api/pro/approvals`           | GET / POST | List pending approvals / approve or reject                                                               |
| `/api/pro/work-packets`        | GET        | List work packets                                                                                        |
| `/api/pro/audit-feed`          | GET        | Agent action log                                                                                         |
| `/api/pro/standing-orders`     | GET        | Active standing orders                                                                                   |
| `/api/pro/guardian/killswitch` | POST       | Trigger the guardian kill switch                                                                         |
| `/api/pro/guardian/revert`     | POST       | Restore after a kill switch                                                                              |
| `/api/pro/consigliere/chat`    | POST       | Send a message to the local consigliere                                                                  |

## Error shape

```json theme={null}
{
  "error": "unauthorized",
  "reason": "invalid_token",
  "requestId": "..."
}
```

Always include `requestId` when filing a support ticket.

## Idempotency

Mutation endpoints accept `Idempotency-Key` headers. Replaying a request with the same key returns the original result without double-executing. Keys are good for 24 hours.

## Timestamps

All timestamps are Unix milliseconds (`Date.now()` in JavaScript). Same shape in Convex and in the API.

## Example: pull the full brief

```bash theme={null}
curl -sS -H "x-bossmode-token: $BOSSMODE_TOKEN" \
  https://bossmode.ing/api/pro/context | jq .
```

Response includes signals, work packets, standing orders, metrics, audit feed, guardian state, and the AvatarCzar persona payload — everything the consigliere reads to decide what to do next.

## Example: queue a directive

```bash theme={null}
curl -sS -X POST -H "x-bossmode-token: $BOSSMODE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text":"draft the weekly brief for Tuesday"}' \
  https://bossmode.ing/api/pro/directive
```

The response returns `{ directiveId, approvalId, status: "pending_approval" }`. Approve via `/api/pro/approvals` or the CLI.