The power-user probe. A read-only exploration of the Merus Messages API — which endpoints respond, what fields each returns, what the link-to-case action expects. Run once to document the API; the documentation becomes the foundation for the real skills. This is a developer tool, not a daily one.
At the prompt:
aaicase> discover messages api
aaicase> explore messages
aaicase> find messages endpointThe skill walks through a series of candidate API endpoints, records which ones respond with real data versus which error out, samples the field structure of working endpoints, and writes a discovery summary to ~/.aaicase/messages-api-discovery.json. The output is a map of the Messages API as it actually behaves on this firm’s Merus instance — which is the input to writing or fixing the message-handling skills.
The Merus Messages module is undocumented. When AAI needed to build process messages, check my email, and the message-filing flow, the first step was figuring out what the API even supported — which endpoints existed, what the message schema looked like, how to link a message to a case.
Rather than guess (and ship skills built on wrong assumptions), the approach was: probe the live API systematically, document what works, then build the real skills against the documented behavior. This skill is that probe. It’s the reconnaissance that precedes the construction.
The probe sends GET requests and harmless empty-body POST requests (to see what error a write endpoint returns, which reveals what fields it expects — without actually completing the write). It never sends a complete, valid write. Discovering the API and exercising it are different operations; this skill only does the former.
The actual filing — linking a message to a case, creating activities — happens in process messages, which was built using the output of this probe.
The probe walks four categories of candidate endpoints:
| Category | Candidates tried |
|---|---|
| List endpoints | /messages/index, /messages/inbox, /emails/index, and other CakePHP-style patterns Merus uses elsewhere |
| View-one endpoints | /messages/view/[id], /messages/[id], query-param variants — to find how to read a single message in detail |
| Link/file actions | /messages/edit, /messages/linkToCase, /messages/file, /messages/save — probed with empty bodies to see what fields they demand |
| Field structure | On the working list endpoint, samples one message to document all its fields and their types |
For each candidate it records the HTTP status and the first chunk of the response. A clean 200 with data means the endpoint works; an error reveals either that it doesn’t exist or what it needs.
This is the single most important thing the probe taught us, and it’s why the probe matters. A naive reading of “insufficient privileges” would conclude “the endpoint exists but I need higher access — ask the firm admin.” That conclusion is usually wrong. The error is Merus’s generic 404-equivalent.
The only reliable signal that an endpoint works is a successful response — data, {"success":1}, or a returned id. The probe treats “insufficient privileges” as “endpoint probably doesn’t exist” and keeps looking, rather than stopping to request access that wouldn’t help.
This lesson is now documented in reference/api-reference.md and applies across every AAI skill that touches Merus — not just messages.
A concrete example of why systematic probing matters: for a long time AAI believed the Merus API didn’t expose email body content — /messages/index returns only metadata (sender, subject, date), and /messages/view/[numeric-id] returns an “insufficient privileges” / “deleted” error for every message.
That belief was wrong. Careful probing revealed the body IS available — the endpoint just expects the string message_id as a query parameter, not the numeric id as a path segment:
GET /messages/view?message_id=<url-encoded-string-id>That returns the full Message object with body (full HTML), recipient_header_cc, recipient_header_bcc, reply_to, in_reply_to, attachments, and more — everything process messages now uses to read email bodies and reconstruct threads. The discovery skill is exactly the tool for finding this kind of thing: the difference between “the API can’t do X” and “I was calling it wrong.”
The probe writes a structured discovery file:
~/.aaicase/messages-api-discovery.jsonContaining:
/messages/index)This file is the reference that the message-handling skills are built against. When an attorney runs process messages, they’re running a skill whose correctness traces back to what this probe documented.
Run it when:
Don’t run it for:
It’s on the skills list for completeness and for the rare moment a power user or maintainer needs it — not because attorneys run it day to day.
That doesn’t mean every endpoint is permission-blocked — it’s the generic error for nonexistent endpoints (see above). Look for the one or two endpoints that returned actual data; those are the real ones.
The skill writes to ~/.aaicase/messages-api-discovery.json at the end. If the probe crashed mid-run, the file may be missing or partial. Re-run; the probe is idempotent and read-only, so re-running is safe.
It shouldn’t — the skill is read-only by design. If you suspect a message was changed, it wasn’t this skill; check the audit log for what touched it. The probe only sends GETs and empty-body POSTs (which return errors, not successful writes).
Don’t do it through this skill — it’s deliberately read-only. Use process messages on a single message, which does the real filing with the full approval-and-verify flow.
The discovery file is a point-in-time snapshot. If Merus updated their API, the file may be stale. Re-run the probe to refresh it, and update reference/api-reference.md if the behavior genuinely changed.
Part of AAI for MerusCase — code-guarded AI case intelligence for California Workers’ Comp attorneys.