---
name: reference-coord-messages-api-shape
description: Coord /messages endpoint returns a paginated object {total,skip,limit,messages[]}, NOT a bare array; parse .messages[] and strip control chars before JSON parse
metadata:
  type: reference
---

The coordination API messages endpoint `GET http://172.16.3.30:8001/api/coord/messages?to_session=<SID>` returns a **paginated object**, not a bare array:

```json
{ "total": N, "skip": 0, "limit": M, "messages": [ {...}, ... ] }
```

**How to use it reliably:**
- Parse `.messages[]` (jq) / `data["messages"]` (python) — iterating the top-level object yields keys (strings), which is why a bare `.[]?` / `for m in data` fails with "no match" or `'str' object has no attribute 'get'`.
- Responses can contain **unescaped control chars** (U+0000-001F) that break `jq` and `json.loads` — strip them first (`tr -d '\000-\037'` or `re.sub(r"[\x00-\x1f]"," ", raw)`).
- The per-message `read` flag may be `null` on unread messages (not `false`); the server-side `&unread_only=true` filter has missed `read=null` messages — safest to fetch without it and filter client-side.
- Mark read: `PUT /api/coord/messages/<id>/read`.

Caused repeated mark-read failures across a session (2026-05-27) before the shape was pinned down. See the Session Start Protocol in [[CLAUDE.md]] for the coord workflow.