The REST API

Everything the Antimatter apps do goes through the same HTTP API, so your scripts can do it too. This page explains how to authenticate, the resources you will use most, how responses and errors look, and how to follow events live over the WebSocket.

Basics

• Base URL: https://chat.example.com/api/v4. All endpoints below are relative to it.
• Format: JSON in and out, except file uploads (multipart). Send Content-Type: application/json.
• IDs: every object has a 26-character id. Times are milliseconds since the Unix epoch (create_at, update_at, delete_at; 0 means "not deleted").
• Communities are teams: the API calls them teams, with a team_id.
• Yourself: wherever a path takes a user_id, me means the signed-in user, as in GET /users/me.

The full list of endpoints is in the server's code: the routes are declared in server/channels/api4/*.go and the types in server/public/model. The OpenAPI description in the repository's api/v4/source folder covers the endpoints inherited from Mattermost, and some of Antimatter's additions: moving threads, model connections, agents, community rules, focus mode and message actions. The others are only in the code.

Authentication

Every request, except signing in and a few public endpoints, needs a token in the Authorization header:

curl -H "Authorization: Bearer $TOKEN" https://chat.example.com/api/v4/users/me

Three kinds of token are accepted there: personal access tokens, session tokens and OAuth access tokens. Authorization: Token … is accepted too. Tokens in the query string (?access_token=) are only accepted for OAuth access tokens.

Personal access tokens (recommended for scripts)

A personal access token acts as you, does not expire unless you give it an expiry date, and can be revoked at any time. Personal access tokens are off by default:

1. A system admin turns on Enable Personal Access Tokens in System Console › Integrations › Integration Management (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. For each person who may create tokens, a system admin opens System Console › User Management › Users, chooses Manage roles in the person's menu and ticks Allow this account to generate personal access tokens. System admins can always create them.
3. The person opens their avatar at the top right, then Profile & settings › Security. Under Personal access tokens, they describe what the token is for and choose Create token. The token is shown once: copy it.

With the API: POST /users/{user_id}/tokens with {"description": "backup script", "expires_at": 0} (expires_at in milliseconds; 0 for none). The response's token field is the secret; its id is what you use to revoke it (POST /users/tokens/revoke with {"token_id": "…"}). From the command line: amctl token generate <user> <description>.

A system admin can cap token lifetimes with Maximum Personal Access Token Lifetime (days) on the same System Console page.

Session tokens

Signing in with a password returns a session token in the Token response header, the same kind of session the apps use:

curl -i -X POST https://chat.example.com/api/v4/users/login \
  -H 'Content-Type: application/json' \
  -d '{"login_id": "maya", "password": "…"}'

Add "token": "123456" for an account with multi-factor authentication. Sessions expire as the server's session settings say, and the login endpoint is rate limited (5 requests per second). POST /users/logout ends the session.

OAuth 2.0 apps

To let people sign in to your application with their Antimatter account, register an OAuth 2.0 app. Antimatter is then the OAuth provider:

1. Enable OAuth 2.0 Service Provider must be on (System Console › Integrations › Integration Management, ServiceSettings.EnableOAuthServiceProvider, on by default).
2. Someone with the right to manage OAuth apps (system admins by default) opens Integrations › OAuth 2.0 apps (community menu › Community settings › Integrations), and adds the app with its callback URLs. They get a client ID and a client secret.
3. Your application sends people to https://chat.example.com/oauth/authorize with response_type=code, client_id, redirect_uri and state. PKCE with code_challenge_method=S256 is supported.
4. It exchanges the code at POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, then refresh_token to renew), and calls the API with Authorization: Bearer <access token>.

People see the apps they authorised in Profile & settings › Security › Apps you authorized.

Main resources

Post a message

curl -X POST https://chat.example.com/api/v4/posts \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$CHANNEL_ID'", "message": "Backup finished: **42 GB** in 3 min"}'

Messages are Markdown. Add "root_id" (the first post of a thread) to reply in a thread, "file_ids" for files and "props" for attachments and other extras (see Attachments).

Find a channel's ID

curl -H "Authorization: Bearer $TOKEN" \
  https://chat.example.com/api/v4/teams/name/lumen-labs/channels/name/ops-alerts

The names are those in the channel's link: /lumen-labs/channels/ops-alerts.

Pagination

List endpoints take page (from 0) and per_page (60 by default, at most 200). Keep asking for the next page until a page comes back shorter than per_page.

A channel's messages (GET /channels/{channel_id}/posts) also take since (a time: everything changed since then), or before and after (a post ID). They come back as a post list: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Errors

Errors use the usual HTTP status codes (400 bad input, 401 not signed in, 403 not allowed, 404 not found, 501 feature turned off) and a JSON body:

{
  "id": "api.context.permissions.app_error",
  "message": "You do not have the appropriate permissions.",
  "detailed_error": "",
  "request_id": "jz8zm5nunpbt8f3gpqsz5dq6so",
  "status_code": 403
}

Use id in your code: message is translated into the user's language. detailed_error is empty unless the server runs in developer mode (ServiceSettings.EnableDeveloper). Quote request_id to the server's admin: it is in the logs.

Rate limits

Rate limiting is off by default. When a system admin turns it on (System Console › Environment › Rate Limiting), each client gets 10 requests per second with bursts of 100 by default, counted by IP address or by user. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit, the server answers 429 with a Retry-After header in seconds. Some endpoints, such as signing in, have their own limit whatever the setting.

Write scripts that wait and retry on 429, and avoid polling: follow the WebSocket instead.

The WebSocket event stream

Connect to wss://chat.example.com/api/v4/websocket. Authenticate either with the Authorization: Bearer header on the connection request, or by sending this as the first message:

{"seq": 1, "action": "authentication_challenge", "data": {"token": "…"}}

The server sends a hello event, then an event for everything you are allowed to see:

{
  "event": "posted",
  "data": {"channel_id": "…", "channel_type": "O", "post": "{\"id\":\"…\",\"message\":\"Hello\",…}"},
  "broadcast": {"channel_id": "…", "team_id": "", "user_id": "", "omit_users": null},
  "seq": 4
}

Note that data.post is the post as a JSON string. Common events: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Apps send their own events, named custom_<app id>_<event>.

You can also send actions, each with an increasing seq: user_typing with {"channel_id", "parent_id"}, or get_statuses. Reconnect when the connection drops, and fetch what you missed with since (see Pagination).

Antimatter adds these events: agent_activity_changed and agent_post_stream (see Agents), ai_tools_changed (see Agents), community_rules_updated and community_rules_accepted (see Community rules), focus_ended (see Focus mode), community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated and category_overrides_updated. A new sign-in to your own account sends session_created to your other sessions (session_id, create_at, platform, os, browser, mobile; never a token), and handling its warning sends session_revoked or session_acknowledged (session_id) to all of them.

Client libraries

• Go: model.Client4 in server/public/model (import github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), then client.SetToken(token); model.NewWebSocketClient4(wsURL, token) follows events. Antimatter's copy adds methods for its own endpoints, such as UpdateMessageRequest, PutPostOnTop and ExportChannel.
• TypeScript: the Client4 class of @mattermost/client, in webapp/platform/client, with its types in webapp/platform/types. The copy in Antimatter's repository includes Antimatter's endpoints; the package published on npm by Mattermost does not.

package main

import (
	"context"
	"log"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client("https://chat.example.com")
	client.SetToken("…")
	post, _, err := client.CreatePost(context.Background(), &model.Post{
		ChannelId: "…",
		Message:   "Hello from Go",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("posted", post.Id)
}

What Antimatter adds to the API

These endpoints and fields don't exist on a Mattermost server. All of them need a session.

New fields

• Communities (Team, and PUT /teams/{team_id}/patch): all_channels_membership (everyone is in every channel they may see), default_channel_id (where newcomers land), welcome_channel_id (where its join and leave messages go, empty for none), kind (community or workplace, shown in the interface as Guild and Workspace: a guild also turns all_channels_membership on; new communities get the server's TeamSettings.DefaultCommunityKind, community/Guild by default), member_list_view (how the member list groups members: choice, the default, lets each member choose; roles or teams fixes it), hide_role_colors, require_team_badges, name_display (how the community shows people: empty for the server's default), onboarding and autolinks (both JSON strings).
• The default channel of a new community is general (General), not town-square. The 0.9.0 upgrade renames each community's town-square to general, keeping its ID, unless the community already has a general channel. Old names keep working: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square and an incoming webhook's channel give the community's default channel when no channel has that name. Use default_channel_id, or the name general, in new code.
• Channel links: #channel-name links a channel, as ~channel-name does. The post's channel_mentions prop lists the channels linked either way; a #word that names no channel stays a hashtag. Antimatter's web interface and mobile app write #name.
• Archived channels still take new members (POST /channels/{channel_id}/members), who can read their history. Nobody can post, react, pin, put a message on top, rename the channel or change its members' roles there.
• Inline replies: a post with "props": {"reply_to": "<post id>"} quotes that message of the same channel. Add "reply_to_mention": false to leave its author unnotified. The server fills metadata.reply_to with a short description of the quoted message.
• Spoilers: "props": {"spoiler": true} hides a post's text and files until the reader chooses to see them.
• Ignoring and blocking are preferences: category user_block, named after the other person's ID, with the value ignore or block. Whether a direct message waits as a request is in your channel member's notify_props.dm_request (pending, accepted or dismissed).
• Message attachments can carry stages and a chart: see Cards.
• Channels (Channel): every community channel's props always carries am_type (text, voice or forum), am_mode, am_root_posts (members or moderators) and am_preset (the matching preset's ID, or empty for custom settings), and, for forums, am_forum_view (topics or imageboard). A payload without am_type means it wasn't filled in, never that the channel is text. Direct and group messages carry none of this. See Channel types.

Channel types

A community channel is text, voice or forum (its type, fixed when it's created), in one of its type's modes, with settings on top. A preset is a named bundle of a mode and settings that a client offers as one choice; presets aren't stored, so a channel's preset (am_preset) is derived from its settings, and reads "" when they match no preset ("Custom").

Creating and changing a channel's type

POST /channels reads props.am_preset (expanded first), then the individual props.am_type, am_mode, am_root_posts and am_forum_view on top of it; any other am_ prop is dropped. Creating a voice channel while the Voice Channels app isn't active is refused (400 api.channel.type.voice_unavailable.app_error); creating a direct or group message with type props is refused (api.channel.type.direct.app_error).

curl -X POST https://chat.example.com/api/v4/channels \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"team_id": "'$TEAM_ID'", "name": "help-desk", "display_name": "Help desk", "type": "O",
       "props": {"am_preset": "forum_qa"}}'

PUT /channels/{channel_id}/type changes the preset or the settings of an existing channel: {"preset"?, "mode"?, "root_posts"?, "view"?}, the preset expanded first as at creation. It needs manage_public_channel_properties or manage_private_channel_properties in the channel (audit event updateChannelType), and answers the filled-in channel. A body that names another type is refused (api.channel.type.fixed.app_error): the type itself never changes. Other errors: api.channel.type.invalid.app_error (an unknown value, a mode that isn't of the channel's type, or a view on a non-forum).

Bulk import and export (amctl import bulk) carry the same four fields on a channel's line: am_type, am_mode, am_root_posts, am_forum_view. A channel line without them imports as a plain text Chat channel, as before channel types.

Who starts conversations or opens topics

Posting a root message (as distinct from a reply) needs the permission create_root_post, shown in the overrides editor as Start conversations (text, voice) or Open topics (forums). No role holds it: before overrides, everyone who may post has it where root_posts is members, and only the channel's moderators (system admins, community admins, channel admins, and anyone with Manage messages there) where it is moderators. A role or person override on create_root_post then applies on top, as for any permission. A reply (root_id set) needs only the ordinary right to post.

A root post that fails this gets 403: app.post.root_posts.moderators_only.app_error when root_posts is moderators and the poster doesn't moderate the channel, or app.post.root_posts.denied.app_error for an override deny. This is checked for the REST API, bots, incoming and outgoing webhooks (on the hook's creator) and slash command responses; posts from apps (the plugin API) and the copies of a moved thread aren't (the person moving a thread is checked there instead). Bulk import skips it too.

Forums take only topics

In a forum, a root post needs props.am_thread_title (its topic's title), trimmed, 1 to 100 characters, from every source, apps and moved threads included: missing gets 400 app.post.forum.title_required.app_error, too long app.post.forum.title_too_long.app_error. Replies need no title, and any title sent on a reply is dropped. Editing a topic's root without a title, or with an empty one, keeps its existing title; a non-empty one renames it. Moving a thread into a forum (below) needs a title too, from the request or the thread's own.

A Q&A topic's accepted answer (am_accepted_answer, a reply's ID) and an Ideas topic's status (am_topic_status, with am_topic_status_by and am_topic_status_at) are written only by PATCH /posts/{post_id}/topic; any of these three sent on create, update or patch, by a client or an app, is dropped, and the stored value is kept.

List a forum's topics

GET /channels/{channel_id}/topics?sort=votes&per_page=25

Needs the right to read the channel. Query parameters:

• sort: activity (default), newest, votes, unanswered (Q&A only) or status (Ideas only).
• answered (true/false, Q&A) and status (one of open, planned, in_progress, done, declined, Ideas): filter by these. Using either outside its mode is 400.
• mine=true: only the topics you started. following=true: only the ones you follow.
• q: matches the title or the first post's text, up to 200 characters.
• before: the previous page's next_cursor. per_page: 25 by default, 100 at most. replies: 0 to 5 of each topic's latest replies, for an image-board view.

Answer: {"topics": [{"post", "reply_count", "last_reply_at", "participant_ids", "votes", "accepted_answer_id", "status", "on_top", "replies": [post, …]}], "next_cursor"}. Votes are 👍 reactions (+1 and thumbsup counted together), minus the topic's own author; accepted_answer_id is given in Q&A forums only, status in Ideas forums only. Topics on top of the channel come first.

Accept an answer, or set a topic's status

curl -X PATCH https://chat.example.com/api/v4/posts/$POST_ID/topic \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"accepted_answer_id": "'$REPLY_ID'"}'

post_id must be a forum topic's root post, else 400 app.topic.not_a_topic.app_error. accepted_answer_id (a reply's ID, or "" to take it back) needs a Q&A forum; status needs an Ideas forum; either in the wrong mode is 400 app.topic.mode.app_error.

• Accepting an answer: the topic's asker (while they may still post there) or a channel moderator; otherwise 403 app.topic.accept.not_allowed.app_error. The reply must be a live, non-system reply of that topic, or 400 app.topic.accept.not_a_reply.app_error. Deleting the accepted reply clears the answer.
• Setting a status: channel moderators only, else 403 app.topic.status.not_allowed.app_error; an unknown value is 400 app.topic.status.invalid.app_error.

Each change posts a system reply in the topic (telling its followers) and answers with the topic's root post, as it now stands. In an Ideas forum, voting for a topic also makes you follow it.

Move a thread

POST /posts/{post_id}/move_to_channel moves a thread, its first message and all its replies, to another channel of the same community. post_id can be the first message or any reply.

curl -X POST https://chat.example.com/api/v4/posts/$POST_ID/move_to_channel \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$TARGET_CHANNEL_ID'", "flatten": false}'

• channel_id (required): the channel the thread moves to.
• flatten (default false): true makes the replies messages of the target channel instead of a thread. Fusion's Make it a channel uses it. Refused when the target is a forum (400 app.post.move_thread.forum_flatten.app_error): its replies would become topics without titles.
• title: the topic's title, when the target is a forum. Without it, the thread's own title is kept, if it has one; missing either way is 400 app.post.move_thread.forum_title_required.app_error. Ignored for a target that isn't a forum.

The messages keep their authors, times, reactions and files. Their copies carry the silent_notification prop, so they notify nobody. The original messages are deleted. The answer is the moved first message, with its new ID.

Who may move a thread

• You must be able to read the thread and to post in the target channel.
• The channel's admins, the community's admins, people with Manage messages (delete_others_posts) in the channel, and system admins may move any thread.
• The thread's author may move it when both channels are public, or when every message of the thread is theirs. Otherwise the answer is 403 with the ID api.post.move_thread.private_needs_moderator.app_error.
• Both channels must be in the same community (no direct or group messages), different, and not archived. System messages and burn-on-read messages can't be moved.
• A thread longer than WranglerSettings.MoveThreadMaxCount messages (100 by default; 0 for no limit) is refused.

The pointer and the note

The move leaves two system messages of type system_wrangler: a pointer in the old channel ("A thread with 13 messages has been moved to #target") and a note in the target ("This thread was moved from #source"), under the moved thread or, with flatten, after its messages. Besides the message text, their props let a client draw the channel name as a link:

• The pointer: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId, and, for a public target, MovedThreadChannelName and MovedThreadChannelDisplayName.
• The note: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (the pointer), MovedFromPermalink, and, for a public source, MovedFromChannelName and MovedFromChannelDisplayName.

Both also have a TranslationID. A private channel's name is left out: readers see "another channel". Mattermost's own POST /posts/{post_id}/move stays off in Antimatter; use this endpoint.

Community rules

A community's admins can make its members agree to its rules before they post in its channels. While the rules are on, a member who hasn't agreed to the current version can't post, reply, send files, schedule, edit or restore a message, or run a command that posts in the community's channels: the server answers 403 with the ID api.post.community_rules_not_accepted, and a scheduled message due then fails with the error code community_rules_not_accepted. Reading, reactions, and direct and group messages aren't held back; neither are bots, incoming webhooks, system messages, and the community's admins (manage_team, which system admins have too).

The community_rules_updated event goes to the community when an admin saves the rules (team_id, enabled, version), and community_rules_accepted to the one who agreed, on all their sessions (team_id, version).

Focus mode

Focus mode is Do not disturb with an end time: notifications are muted (no push, email, desktop or persistent notifications, urgent messages included), the reason becomes the custom status with the 🎯 emoji (dart), expiring at the end, and Antimatter's apps hide the person's own unread badges. Only the person themself can use these endpoints (me or their own ID): nobody else, system admins included, may start, end or read someone's focus or its summary.

While someone focuses, their user has the prop focus_until (milliseconds), which clients use to show the focusing status; it can't be changed through the profile. The focus ends when the person ends it, when its time comes (within a minute), or when they pick a status themself, which then stays. Otherwise the status and custom status from before come back. All their sessions then get the focus_ended event, with start_at, end_at and ended_by (user, timer or status).

Model connections

A model connection is an AI provider's address and key, set up by an admin. The server's AI features and the apps that call the AI service use them. System admins manage the server-wide connections (manage_ai_connections); a community's admins manage their community's own (manage_team_ai_connections). Keys are write-only: no answer carries one, only api_key_set and api_key_last4.

The body of a new connection:

{
  "name": "Local models",
  "scope": "server",
  "provider": "openai_compatible",
  "base_url": "http://llm.internal:8000/v1",
  "api_key": "…",
  "extra_headers": {},
  "models": {"chat": "qwen3-32b", "embeddings": "", "transcription": "", "decisions": ""},
  "limits": {"requests_per_minute": 0, "monthly_token_budget": 0, "per_user_requests_per_minute": 0, "per_user_monthly_token_budget": 0},
  "sharing": {"all_teams": true, "team_ids": []},
  "audience": {"everyone": true, "group_ids": [], "roles": [], "allow_guests": false}
}

provider is openai_compatible or anthropic. scope defaults to server; a community's ID makes it that community's connection. In limits, 0 means no limit; requests per minute are counted on each server, token budgets per calendar month (UTC) for the whole cluster. sharing says which communities may use a server-wide connection (direct and group messages need all_teams), and audience who may use it; guests only with allow_guests. Changes are written to the audit log. The admin guide explains the settings: see AI.

Agents

An agent is a bot account of the kind agent (is_agent on its user), with its settings: its scope (server, or a community's ID), built-in or external, and for a built-in agent its model connection, model, system prompt and reasoning. System admins manage the server-wide agents (manage_system), a community's admins their community's (manage_team); on top of that, manage_own_agent for an agent they made and manage_others_agent for the others. The agent's ID in these paths is its user ID. Running an external agent, and how a built-in agent's status is set, is explained in Bots; PUT /users/{user_id}/status and the custom status endpoints refuse a built-in agent's ID, for system admins too (403, api.status.agent.app_error).

The body of a new agent:

{
  "username": "researcher",
  "display_name": "Researcher",
  "description": "Answers with sources",
  "scope": "server",
  "external": false,
  "connection_id": "…",
  "model": "",
  "system_prompt": "You research questions and answer with sources.",
  "reasoning": {"enabled": false, "effort": "", "budget_tokens": 0},
  "max_tool_turns": 0,
  "access": {"everyone": true, "team_ids": [], "channel_ids": [], "roles": [], "user_ids": [], "allow_guests": false}
}

An empty model uses the connection's chat model. access.channel_ids means the members of those channels. An external agent has no connection, model or system prompt. GET /agents lists the agents you may talk to, as the AI chat app reads them.

The assistant

The assistant (see AI) gives each signed-in person their own feed of cards for a channel they may read: a member, for private channels, direct and group messages. Base path /api/v4/assistant. Every route is the caller's own: nobody reads or changes another person's feed, a card ID that isn't theirs is 404, and bots and deactivated accounts get 403.

Three WebSocket events, each to the one person's own clients only (never a channel or a community): assistant_card_added ({"channel_id", "card"}), assistant_card_updated (dismissed, pinned, unpinned or posted, from any of their clients; same data), and assistant_offer_updated, sent to everyone who has that offer's card, each with their own view of it ({"channel_id", "card_id", "offer"}).

A trusted app's own post can start the assistant like a person's message (AssistantSettings.TriggeringApps): see Trusted apps.