Reference

REST API

Everything the dashboard does is available over the API. Authenticate with a bearer key and the surface is small on purpose.

Authentication

Mint an API key in Settings → API Keys and pass it as a bearer token. Keys are sha256-hashed at rest and can be revoked at any time.

Authorization: Bearer bp_<your-api-key>

Endpoints

Method	Path	Description
POST	/v1/runs	Create a run. Body: { task, output? }. Returns 201 with the run id and status.
GET	/v1/runs	List your runs. Query: ?limit=&status= for filtering.
GET	/v1/runs/:id	Fetch a run — status, steps, cost, and output. Safe to poll.
DELETE	/v1/runs/:id	Cancel a running run. Emits run.cancelled.

Create a run

curl -X POST https://api.browserpilot.example/v1/runs \
  -H "Authorization: Bearer $BROWSERPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "task": "List the top 5 stories and their points",
        "output": { "stories": [{ "title": "", "points": 0 }] }
      }'

Errors

Errors use standard HTTP status codes: 400 for validation, 401 for a missing or invalid key, 404 for an unknown run, and 429 when a run would exceed your plan quota.