Control API reference
The route families for workspace controls, devices, reports and provider traffic.
On this page
Authenticate for the route you need
Human-facing /v1 routes accept an authenticated Clerk session or a Leash human access token. The browser uses the application's protected proxy and session handling; do not put LEASH_API_TOKEN in public JavaScript. Device-facing routes require a device token, while gateway calls require a virtual key.
Use the actual control-plane origin for your deployment. The local API is http://127.0.0.1:8788. JSON mutations use Content-Type: application/json. Cookie-based browser mutations are protected by same-origin checks.
curl --fail \
-H "Authorization: Bearer $LEASH_USER_TOKEN" \
"https://YOUR_DOMAIN/v1/overview"Workspace control routes
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/me | Identity, workspace and role |
| GET | /v1/overview | Dashboard aggregates |
| GET | /v1/status | Proxy / workspace status |
| GET | /v1/sessions | Visible sessions |
| GET | /v1/sessions/:id | Session detail |
| POST | /v1/sessions/:id/kill | Kill one session |
| POST | /v1/sessions/:id/resume | Resume a session |
| POST | /v1/kill-all | Workspace panic |
| POST | /v1/resume-all | Clear panic latch |
| GET / POST | /v1/budgets | Read or set budget rules |
curl --fail -X POST \
-H "Authorization: Bearer $LEASH_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"scopeType":"org","period":"day","limitUsd":25,"action":"block"}' \
"https://YOUR_DOMAIN/v1/budgets"Device transport routes
Prefer the CLI agent loop over implementing transport yourself: it persists acknowledgements, retries metadata sync and applies remote policy safely. Device isolation is enforced by the token's workspace and device, not caller-supplied tenant IDs.
| Method | Path | Credential / purpose |
|---|---|---|
| POST | /v1/devices | Human owner/admin; issue one-time device token |
| GET | /v1/devices | Human account; list workspace devices |
| POST | /v1/devices/:id/revoke | Human administrator; revoke device |
| GET | /v1/devices/me | Device; verify identity |
| POST | /v1/devices/me/sync | Device; batched metadata upload |
| GET | /v1/devices/me/commands | Device; poll queued commands |
| POST | /v1/devices/me/commands/:id/ack | Device; acknowledge executed command |
Reports and gateway
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/reports | Report gallery |
| GET | /v1/reports/:id | Private report |
| POST | /v1/reports/:id/share | Create or revoke aggregate share |
| GET | /r/:id | Public report only if explicitly shared |
| GET | /v1/export?format=csv | Usage export under history limits |
| POST | /v1/reconciliation | Provider CSV comparison |
| GET | /v1/gateway | Shared mode and gateway configuration |
| POST | /gateway/openai/v1/responses | OpenAI-compatible Responses request |
| POST | /gateway/anthropic/v1/messages | Anthropic-compatible Messages request |