API
Send, list, bulk, webhooks, and the tool catalog for the communications service.
Discovery and ops
| Path | Method | Notes |
|---|---|---|
/ | GET | Service discovery (enveloped) |
/api-docs | GET | Swagger UI |
/openapi.yaml, /openapi.json | GET | Spec from binary |
/healthz | GET | Liveness |
/readyz | GET | Readiness (Postgres ping) |
Versioned API
| Path | Method | Purpose |
|---|---|---|
/v1/channels | GET | Channel list + available |
/v1/tools | GET | Committed tool catalog |
/v1/messages | POST | One send |
/v1/messages/{id} | GET | One message + provider_message_id |
/v1/announcements | POST | Bulk send |
/v1/announcements/{id} | GET | Blast status |
/v1/conversations | GET | List threads |
/v1/conversations/{id} | GET | Thread + messages |
/v1/conversations/{id}/link | POST | Attach agent_id |
/v1/webhooks/twilio | POST | Inbound SMS |
/v1/webhooks/mailgun | POST | Inbound email. Recipient ${slug}@ on the agent domain links the thread |
Enveloped All /v1/* JSON uses the Response envelope: The template service wraps every JSON response in {header, payload}. A success payload is {data} (a record or a list) plus optional meta.pagination; accounting still returns bare bodies and RFC 9457 errors until the divergence is resolved..
Webhooks are form posts and are not enveloped.
Authorization is Cedar: The authorization engine; each service embeds a Cedar policy and evaluates every mutating request against the actor's principal record.: communications::Send, communications::Announce,
communications::Read, communications::LinkAgent. Webhooks are off Cedar. The shared
service token (X-Flow-Service-Token) is accepted the same way foundry accepts it, so
the harness can send. For SMS, from may be omitted; the service uses TWILIO_FROM_NUMBER.
For email, from may be omitted; the service uses MAILGUN_FROM. The harness sends
agent mail as the agent's mailbox (${slug}@ the agent domain) instead.
Headers
| Header | Required | Purpose |
|---|---|---|
Idempotency-Key | Every mutating /v1/* command | Stable across retries |
Content-Type | POST JSON | application/json |
X-Dev-Principal | local DEV_AUTH=1 only | The caller email |
X-Flow-Service-Token | cluster service-to-service | Shared token; actor is system |
Events carry ids only: conversation.message.sent, conversation.message.received,
announcement.created, announcement.completed.