Browse the docs

API reference

Messages

Conversations, channels and the messages in them, limited to rooms the token's person can reach.

List conversations

GET/v1/conversations

The 40 most recently active conversations the caller participates in, with unread and mention counts and the last message. kind is direct, group or channel.

Requires messages.read

Request

curl "https://atrix.dev/api/v1/conversations" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "items": [
    {
      "id": "cm3k9x2ab0001qz8f7h2l4n6p",
      "kind": "direct",
      "slug": null,
      "isPrivate": false,
      "muted": false,
      "pinnedAt": null,
      "mutedUntil": null,
      "markedUnread": false,
      "mentions": 0,
      "lastFrom": {
        "id": "cm3k8w1zz0004qz8fa1b2c3d4",
        "name": "Sara Khan"
      },
      "lastKind": "text",
      "title": "Sara Khan",
      "people": [
        {
          "id": "cm3k8w1zz0004qz8fa1b2c3d4",
          "name": "Sara Khan",
          "image": null,
          "lastSeenAt": "2026-10-27T08:41:00.000Z"
        }
      ],
      "last": "Sara Khan: Shipping the fix after lunch",
      "at": "2026-10-27T08:40:12.000Z",
      "unread": 2
    }
  ]
}

Start a conversation

POST/v1/conversations

Opens a direct or group conversation with the given members. A direct conversation with someone you already talk to returns the existing one.

Requires messages.write

Body

memberIdsstring[]required
1 to 20 member ids in this workspace, excluding revoked and service members.
titlestring
Optional group title, up to 80 characters.

Request

curl -X POST "https://atrix.dev/api/v1/conversations" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "memberIds": [] }'

Response

{
  "ok": true,
  "conversationId": "cm3k9x2ab0001qz8f7h2l4n6p"
}

List channels

GET/v1/channels

Up to 100 unarchived channels: every public one plus private ones the caller is in. joined says whether the caller is a member.

Requires messages.read

Request

curl "https://atrix.dev/api/v1/channels" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "channels": [
    {
      "id": "cm3ka0c7d0002qz8fq9r8s7t6",
      "title": "launch",
      "slug": "launch",
      "topic": "Everything for the November launch",
      "isPrivate": false,
      "members": 7,
      "joined": true,
      "at": "2026-10-26T17:02:44.000Z"
    }
  ]
}

Create a channel

POST/v1/channels

Creates a channel whose slug is derived from the name, with the caller as its first member. Refused if a channel with that slug already exists.

Requires messages.write

Body

namestringrequired
2 to 60 characters; becomes the slug.
isPrivateboolean
When true, only members can read the channel.
projectIdstring
A product in this workspace the channel is about.

Request

curl -X POST "https://atrix.dev/api/v1/channels" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "…" }'

Response

{
  "ok": true,
  "conversationId": "cm3ka0c7d0002qz8fq9r8s7t6",
  "slug": "launch"
}

List messages

GET/v1/conversations/{id}/messages

A page of up to 60 messages with replies, reactions, files and parsed blocks, plus the caller's lastReadAt from before this request. With q, returns up to 40 matches instead.

Requires messages.read

Path parameters

idstringrequired
The conversation's id.

Query parameters

beforestring
A message id; returns the page of messages older than it.
aroundstring
A message id; returns the page ending at that message.
qstring
Search within this conversation; 2 characters or more.

Request

curl "https://atrix.dev/api/v1/conversations/ID/messages" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "messages": [
    {
      "id": "cm3kb4f1g0007qz8fm2n3o4p5",
      "body": "Shipping the fix after **lunch**",
      "at": "2026-10-27T08:40:12.000Z",
      "editedAt": null,
      "blocks": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Shipping the fix after "
            },
            {
              "type": "strong",
              "children": [
                {
                  "type": "text",
                  "text": "lunch"
                }
              ]
            }
          ]
        }
      ],
      "pinned": false,
      "deleted": false,
      "removedBy": null,
      "parentId": null,
      "author": {
        "id": "cm3k8w1zz0004qz8fa1b2c3d4",
        "name": "Sara Khan",
        "image": null
      },
      "mine": false,
      "files": [],
      "reactions": [
        {
          "emoji": "👍",
          "count": 1,
          "mine": true
        }
      ],
      "replyCount": 0,
      "replies": []
    }
  ],
  "hasOlder": true,
  "hasNewer": false,
  "lastReadAt": "2026-10-27T07:58:00.000Z",
  "muted": false,
  "people": [
    {
      "id": "cm3k8w1zz0004qz8fa1b2c3d4",
      "name": "Sara Khan",
      "image": null,
      "lastSeenAt": "2026-10-27T08:41:00.000Z"
    }
  ]
}

Send a message

POST/v1/conversations/{id}/messages

Posts a message, or a one-level reply when parentId is set. Sending again with the same clientKey returns the first message instead of posting twice.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.

Body

bodystringrequired
1 to 4000 characters.
parentIdstring
The top-level message this replies to.
clientKeystring
Your own 8 to 64 character key for this message, making retries safe.

Request

curl -X POST "https://atrix.dev/api/v1/conversations/ID/messages" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "…" }'

Response

{
  "ok": true,
  "messageId": "cm3kb4f1g0007qz8fm2n3o4p5"
}

Edit a message

PATCH/v1/conversations/{id}/messages/{messageId}

Replaces the text of a message the caller wrote. Deleted messages cannot be edited.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.
messageIdstringrequired
The message's id.

Body

bodystringrequired
The new text, 1 to 4000 characters.

Request

curl -X PATCH "https://atrix.dev/api/v1/conversations/ID/messages/MESSAGEID" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "…" }'

Response

{
  "ok": true,
  "editedAt": "2026-10-27T08:45:30.000Z"
}

Delete a message

DELETE/v1/conversations/{id}/messages/{messageId}

Deletes a message the caller wrote, leaving a tombstone in the conversation. Deleting an already-deleted message succeeds.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.
messageIdstringrequired
The message's id.

Request

curl -X DELETE "https://atrix.dev/api/v1/conversations/ID/messages/MESSAGEID" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "ok": true
}

Toggle a reaction

POST/v1/conversations/{id}/messages/{messageId}/reactions

Adds the caller's reaction, or removes it if they already reacted with that emoji. The emoji must be pictographic characters only.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.
messageIdstringrequired
The message's id.

Body

emojistringrequired
A single emoji, e.g. 👍.

Request

curl -X POST "https://atrix.dev/api/v1/conversations/ID/messages/MESSAGEID/reactions" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "…" }'

Response

{
  "ok": true
}

Toggle a pin

POST/v1/conversations/{id}/messages/{messageId}/pin

Pins the message, or unpins it if already pinned; pinned is the new state. The caller must be a member, and a conversation holds at most 12 pins.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.
messageIdstringrequired
The message's id.

Request

curl -X POST "https://atrix.dev/api/v1/conversations/ID/messages/MESSAGEID/pin" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "ok": true,
  "pinned": true
}

List pinned messages

GET/v1/conversations/{id}/pins

Up to 50 pinned, undeleted messages in the conversation, most recently pinned first.

Requires messages.read

Path parameters

idstringrequired
The conversation's id.

Request

curl "https://atrix.dev/api/v1/conversations/ID/pins" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "pins": [
    {
      "id": "cm3kb4f1g0007qz8fm2n3o4p5",
      "body": "Launch checklist lives on the Launch page",
      "blocks": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Launch checklist lives on the Launch page"
            }
          ]
        }
      ],
      "at": "2026-10-20T10:12:00.000Z",
      "pinnedAt": "2026-10-20T10:15:41.000Z",
      "author": {
        "id": "cm3k8w1zz0004qz8fa1b2c3d4",
        "name": "Sara Khan",
        "image": null
      }
    }
  ]
}

Join or add members

POST/v1/conversations/{id}/members

With memberIds, adds those people to a group or channel the caller is in and returns added. Without it, joins the caller to the channel and returns { ok: true }.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.

Body

memberIdsstring[]
1 to 50 member ids to add; omit to join the channel yourself.

Request

curl -X POST "https://atrix.dev/api/v1/conversations/ID/members" \
  -H "Authorization: Bearer $ATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "memberIds": [] }'

Response

{
  "ok": true,
  "added": 2
}

Leave a conversation

DELETE/v1/conversations/{id}/members

Removes the caller from a group or channel. A direct conversation cannot be left.

Requires messages.write

Path parameters

idstringrequired
The conversation's id.

Request

curl -X DELETE "https://atrix.dev/api/v1/conversations/ID/members" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "ok": true
}

Mark as read

POST/v1/conversations/{id}/read

Moves the caller's read marker to now and clears their unread mentions in the conversation.

Requires messages.read

Path parameters

idstringrequired
The conversation's id.

Request

curl -X POST "https://atrix.dev/api/v1/conversations/ID/read" \
  -H "Authorization: Bearer $ATRIX_TOKEN"

Response

{
  "ok": true,
  "readAt": "2026-10-27T08:46:02.000Z"
}