API reference

The full machine-readable spec is published at /openapi.yaml. Personal API tokens (csk_…) are accepted on the endpoints listed below; the complete spec also contains native app endpoints with different authentication and response contracts. Unlisted routes are not part of this supported personal messaging contract.

Conversation IDs and content

Personal-token responses contain readable names and message text. No decryption workflow or bootstrap request is needed. id androomId both identify the Matrix conversation, for example!conversation:matrix.chesly.app. Use roomId for lookup, message history, and sending. URL-encode it in paths.

senderId and recipientId are stable network identities represented as Matrix IDs. direction is incoming or outgoing and includes your linked account identities. A display name or phone label does not prove a real-world identity. For groups or unknown partners, recipientId is null; review the conversation and its member IDs.

Room lists can omit recipient and member IDs because the inbox lazy-loads them. Call GET /api/rooms/:roomId before approval to refresh current joined members and resolve the direct recipient. If a direct recipient is still null, verify the conversation in Chesly before sending.

Rooms

  • GET /api/roomsList connected conversations with readable names
  • GET /api/rooms/:roomIdGet one conversation and its recipient identity
  • POST /api/rooms/:roomId/messagesSend approved text with content and txnId

Room lists accept limit (1 to 100), sortBy(recent or unread), and archived (false, true, or all). Default: 50 recent non-archived rooms, with pinned rooms first. Pass nextCursor as cursor with the same filters until null. The inbox can change during pagination; deduplicate by roomId.

Messages

  • GET /api/messagesRead history with optional roomId, cursor, and limit

With roomId, messages are newest first in that conversation. Without it, scans walk conversations by ID, each newest first; each page belongs to one conversation. This is not a global chronological feed. Follow nextCursor even after an empty page. Keep the roomId filter unchanged. Personal tokens use opaque cursors, not timestamps.

Each message includes eventId, roomId,senderId, text, content,direction, isMine, and a timestamp in milliseconds. Redacted messages have empty text. Search these pages in your local client. Legacy native encrypted archives are a separate response contract.

Real-time sync

  • GET /api/syncConversation change notifications. Refresh the affected room and message history through the readable routes; reconnects should trigger a fresh scan

Email

  • GET /api/email/threadsList threads
  • GET /api/email/messages/:idGet a message
  • POST /api/email/composeSend, reply, or forward
  • PUT /api/email/threads/:idRead, star, archive, and delete actions
  • POST /api/email/labels, signaturesFull read and write

Reminders

  • GET /api/remindersList
  • POST /api/remindersCreate
  • PUT /api/reminders/:idUpdate
  • DELETE /api/reminders/:idDelete

Bridges (read-only)

  • GET /api/bridgesList connected accounts
  • GET /api/bridges/configuredAvailable platforms
  • GET /api/bridges/dashboardHealth and connection status
  • GET /api/bridges/chat-countsVisible non-archived conversation counts, matching GET /api/rooms

For the full schema (request and response shapes, error envelopes, date formats), parse /openapi.yaml with your tool of choice: Postman, Insomnia, Bruno, or any OpenAPI-compatible client.