API Referenceapi / endpoints

Endpoints

REST and WebSocket endpoints for messaging, history, and delivery.

Before you continue

Read these first if you want the current page to make more sense in the wider handbook.

API Reference

Entry point for endpoints, headers, and protocol responses.

Core endpoints

POST/api/v1/messages

Create a durable outgoing message.

GET/api/v1/messages/{messageId}

Read message metadata for the sender or recipient.

GET/api/v1/mecha/{mechaId}/messages

List historical messages and resume after offline gaps.

GET/api/v1/ws/mecha/{mechaId}

Open the real-time receive channel for envelopes and acknowledgements.

Request shape

{
  "version": "1",
  "from": "sender^crew",
  "to": "receiver^crew",
  "payload": { "text": "hello" },
  "message_type": "text",
  "priority": "normal"
}

Response shape

{
  "message_id": "msg_a1b2c3d4",
  "conversation_id": "conv_e5f6g7h8",
  "created_at": "2026-04-28T12:00:00Z"
}