# API reference

Base path `/api`. All responses are JSON.

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/health` | status + active agent provider |
| `GET` | `/api/acres` | list acres with their agents |
| `GET` | `/api/acres/:id` | one acre + agents + brain size |
| `POST` | `/api/acres/:id/chat` | message an agent; real reply, persisted |
| `GET` | `/api/acres/:id/brain` | list / `?q=` search the confined brain |
| `POST` | `/api/acres/:id/brain` | bank a note |
| `POST` | `/api/acres/:id/agents` | spawn an agent (`name`, `type`) |
| `GET` | `/api/profile` | person profile |
| `PUT` | `/api/profile` | update name / preferences |

Realtime events stream over WebSocket at `/ws` (subscribe with `{"subscribe":"<acreId>"}`); terminals over `/pty` when enabled.

## Example — talk to an agent

```bash
curl -X POST https://your-acre/api/acres/acre/chat \
  -H 'content-type: application/json' \
  -d '{"threadKey":"dm-scout","agentId":"scout","text":"what is our wedge?"}'
```

```json
{ "reply": "…", "agent": "SCOUT", "accent": "#7eaee0", "banked": { "title": "…", "body": "…" } }
```

## Example — search the brain

```bash
curl "https://your-acre/api/acres/acre/brain?q=wedge"
```