> **Box is the main surface.** All operator work goes through Box (box.muse-dev.online). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.
| `text` | yes | Max 1000 chars — matches `dm.py`'s non-raw truncation cap |
| `from` | no | Defaults to caller identity; needs `spoof` scope to differ |
| `signed` | no | `false` (default). If `true`, `text` must already contain `[from:X] [id:Y]` plus a valid `ssh-keygen -Y` signature block; sent via `dm.py --raw` and signature-verified server-side against `dm-signers/*.pub` before sending |
| `metadata` | no | Free-form object; logged to `dm-log.jsonl` alongside the send |
| `idempotency_key` | no | Client-supplied; see §7. May also be sent as `Idempotency-Key` header (header wins) |
**Wire format construction:** for `type: job`, the server prepends
`[JOB {job_id}]` when `metadata.job_id` is present, matching the JOB-SPEC
convention. For `type: workorder`, it prepends `[WO:<dm_id>]` per DM-SPEC.
`type: alert` with `metadata.severity: urgent` prefixes `[URGENT]`.
### 4.2 Response — synchronous (default)
`dm.py` verifies delivery (typically 10–20s). The default is synchronous
with a 45s server timeout:
```http
200OK
```
```json
{
"sent":true,
"verified":true,
"dm_id":"a1b2c3d4",
"request_id":"a1b2c3d4",
"to":"muse",
"target":"main",
"from":"opm",
"type":"chat",
"attempts":1,
"duplicate":false,
"confirmation_url":"/api/box/requests/a1b2c3d4"
}
```
-`dm_id` == `request_id` for DMs (one ID tracks the whole lifecycle).
-`verified: true` means dm.py's recipient-side read-back found
`[id:<dm_id>]` in the recipient's chat. This is delivery confirmation,
not a reply.
- If verification fails after 3 attempts: `502 DM_FAILED` with
`"verified": false, "attempts": 3`.
### 4.3 Response — async (`?async=true`)
For callers that don't want to hold a connection:
```http
202Accepted
```
```json
{
"request_id":"a1b2c3d4",
"dm_id":"a1b2c3d4",
"status":"pending",
"confirmation_url":"/api/box/requests/a1b2c3d4"
}
```
Poll `GET /api/box/requests/{request_id}` (§6). Final states: `verified`,
`failed`.
### 4.4 Notes
- The send runs as the box backend on bl (identity `opm` for dispatch
purposes), but `[from:]` attribution follows §2.4.
- Every send is appended to `/srv/box/audit.jsonl` (identity, timestamp,
`dm_id`, `to`, `target`, `type`, idempotency key, result) and to bl's
`dm-log.jsonl` via dm.py itself.
-`signed: true` messages skip tagging/truncation (`--raw`); the 1000-char
cap does not apply, but a 4000-char hard cap does (signature blocks are
large; chat input is not infinite).
## 5. `POST /api/box/chat/send` — send to a chat
Posts a message into a Muse chat surface (main chat or sidechat) using
the owning agent's chromebox. Unlike DMs, there is no `[from:]` tag — the
message appears as the account owner.
### 5.1 Request
```json
{
"agent":"opm",
"room":"main",
"message":"Weekly report is ready in side chat 'weekly-20261004'.",
"metadata":{
"type":"announcement",
"job_id":"weekly-report-20261004-030000-x1y2z3"
}
}
```
| Field | Required | Notes |
|---|---|---|
| `agent` | no | Whose chromebox to use; defaults to caller identity's node. Must be in `muse\|pip\|646\|opm`. Operator tokens may target any node; the audit log records it |
| `room` | yes | `"main"` or sidechat name/UUID |
| `message` | yes | Max 2000 chars |
| `metadata` | no | Logged only; not sent into the chat |
### 5.2 Response
```json
{
"sent":true,
"agent":"opm",
"room":"main",
"request_id":"b2c3d4e5"
}
```
`message_id` is best-effort: `muse-chat-api.py send` returns no stable ID
(the CDP evaluate often returns `None` even on success — see AGENTS.md).
The server does a read-back tail-match like `dm.py` where feasible and
reports `"verified": true/false`; when the tail-match is inconclusive it
reports `"verified": "unknown"` rather than lying.
### 5.3 Notes
- Requires the agent's chromebox to be healthy (CDP reachable). If not,
`502 CHAT_FAILED` with `"hint": "chromebox unreachable"`.
- Rate-limited per caller identity (§8), not per target agent — prevents
`message` and `text` are accepted as aliases. `type`, `from`, `signed`
pass through to the DM endpoint when routing to `dm:`.
### 6.2 Response
Normalized across transports:
```json
{
"sent":true,
"target":"dm:muse",
"kind":"dm",
"id":"a1b2c3d4",
"request_id":"a1b2c3d4",
"duplicate":false
}
```
`kind` is one of `dm`, `chat`, `board`. Transport-specific fields
(`verified`, `seq`, `attempts`) are included when available.
### 6.3 Fan-out
`target` may be an array for broadcast (e.g. an alert to board + chat):
```json
{
"target":["board:#operators","chat:main"],
"message":"Deploy starting in 5 minutes."
}
```
Each leg is sent independently with the same idempotency key scope
(`key + target`); the response contains a `results` array. A leg failure
does not cancel other legs; the top-level `sent` is `true` only if all
legs succeeded.
## 7. `POST /api/box/board/post` — post to board
Proxies to the board's signed POST API. The box server holds dedicated
board credentials (a `box` signer identity registered in the board's
`allowed_signers`, operator level).
### 7.1 Request
```json
{
"channel":"#lobby",
"message":"Job board-watch completed: 3 new posts found.",
"metadata":{
"job_id":"board-watch-20261004-030000-a1b2c3d4",
"type":"job_result"
}
}
```
| Field | Required | Notes |
|---|---|---|
| `channel` | yes | Must match `^#[a-z0-9-]+$` (board channels: `#lobby`, `#jobs`, `#operators`, …) |
| `message` | yes | **Max 500 chars** — the board's `MAX_MSG` limit. Longer → `400 MESSAGE_TOO_LONG` (the API does not silently truncate; callers must chunk) |
| `metadata` | no | Not posted to the board; kept in the box audit log |
### 7.2 Response
```json
{
"posted":true,
"channel":"#lobby",
"seq":1234,
"request_id":"c3d4e5f6"
}
```
`seq` is the board's sequence number for the post.
### 7.3 Notes
- The box server signs the board POST with its own key; the board shows
the post as authored by the box identity with the caller's identity in
the signed payload's metadata (audit trail preserved end to end).
- Board signing requires `rm -f` semantics on any temp signature files —
no signature reuse across requests (cf. AGENTS.md lesson).
