HTTP API

Every endpoint, which ones are public, and what write requests must carry.

All

The desktop app serves a plain HTTP API on port 8787 (falling back to 8788, then 8789). Only two endpoints are public; everything else requires the bearer token.

Endpoints

Method	Path	Auth	Purpose
POST	/api/pair	public	Exchange a 6-digit code for a token
GET	/api/status	public	Status, host, default/active agent, session, agents
GET	/api/protocol/state	read	Protocol state snapshot
GET	/api/agents	read	Detected agents with installed / active / version / workdir
POST	/api/agents/default	write	Set the default agent
GET	/api/agents/:id/models	read	Providers, active and preferred model ids
POST	/api/agents/:id/switch	write	Switch the active agent
POST	/api/agents/models/default	write	Set preferred model and provider
POST	/api/message	write	Submit a task; may return pending_approval
GET	/api/message/:id	read	Poll a task's state and result
POST	/api/session/start	write	Start a session
POST	/api/session/stop	write	Stop a session
POST	/api/discovery/refresh	write	Force a fresh agent probe
GET, POST	/api/approvals/mode	read / write	Read or set the approval mode
GET	/api/approvals	read	List pending approvals
POST	/api/approvals/:id	write	approve / deny / always_approve
GET, POST	/api/conversations	read / write	List or create conversations
GET, PATCH, DELETE	/api/conversations/:id	read / write	Read, update or delete one conversation
POST	/api/conversations/:id/activate	write	Make a conversation active
GET	/api/folders/roots	read	Root folders: home plus drive letters
GET	/api/folders	read	Browse a directory with pagination
POST	/api/agents/workdir	write	Set or clear an agent's working directory

Authentication

POST /api/pair and GET /api/status are public.
Every other endpoint requires Authorization: Bearer <token>.
Write operations additionally require X-BrewPing-Timestamp (within ±120s) and a never-before-used X-BrewPing-Nonce.
GET requests skip the timestamp and nonce checks.
Unauthenticated requests to protected endpoints are rejected with 401.

Limits

Request bodies are capped at 8 MB; larger requests get 413.
Responses are sent with Connection: close.
Nonce memory holds at most 2048 values; when full, the oldest half is evicted.
Unknown paths return a plain not found response.

bash

# Public: read the status without a token
curl http://192.168.1.20:8787/api/status

# Authenticated read
curl http://192.168.1.20:8787/api/agents \
  -H 'Authorization: Bearer <token>'

# Authenticated write
curl -X POST http://192.168.1.20:8787/api/discovery/refresh \
  -H 'Authorization: Bearer <token>' \
  -H 'X-BrewPing-Timestamp: 1780000000' \
  -H 'X-BrewPing-Nonce: 9b21ff...'

CLI reference

Troubleshooting