canonical: https://jentic.com/apis/mattermost.com/mattermost

# Mattermost API

Jentic publishes the only available OpenAPI specification for Mattermost API, keeping it validated and agent-ready. Mattermost is an open-source, self-hosted team-collaboration platform with HTTP and WebSocket APIs at `your-mattermost-url/api/v4`. The spec covers the core flows used by clients and bots: user authentication and identity, team and channel access, post creation, and basic file and preference operations. It is intended for developers building Mattermost integrations, internal bots, and AI agents that participate in Mattermost teams. Authentication uses bearer session tokens or personal access tokens.

## For AI agents

Authenticate users, fetch team and channel context, and post messages on a self-hosted Mattermost server with bearer-token auth.

## Scope

Does not handle WebSocket event streams, server administration, or plugin management - use for the v4 REST surface (auth, users, teams, channels, posts) only.

## Capabilities

- Authenticate a user via login and obtain a session bearer token
- Fetch the authenticated user's identity via the `me` endpoint
- List teams and channels the authenticated user belongs to
- Create posts in a Mattermost channel
- Resolve user identity for downstream activity records
- Bootstrap an integration's session against a Mattermost server URL

## Use cases

### CI Status Bot

Engineering teams running self-hosted Mattermost want CI build statuses posted to a dedicated channel. The bot logs in once with a personal access token, fetches the right team and channel ID, and then creates posts whenever the CI pipeline emits a status. Posts typically include build URL, branch, and outcome.

Example prompt: Authenticate via `POST /users/login`, locate the channel id, then call `POST /posts` with the channel_id and the build summary message.

### Identity-Aware Internal Tool

Internal admin tools running alongside Mattermost can use the chat session to identify the operator. The tool calls `GET /users/me` to confirm the logged-in user and uses the result to drive permissions in the tool itself, avoiding a separate auth system for internal-only utilities.

Example prompt: Call `GET /users/me` with the bearer token to retrieve the authenticated user's id, email, and role membership.

### Team and Channel Discovery

Onboarding scripts that provision new bots or integrations need to enumerate teams and channels to find the correct destination. The `/teams` and `/channels` endpoints expose this listing, and a typical onboarding script caches the IDs locally so subsequent posts can skip the lookup step.

Example prompt: Call `GET /teams` followed by `GET /channels` to build a `{team_name > channel_ids}` map for the integration's config.

### AI Agent in Mattermost

An AI agent that posts summaries or answers questions in a Mattermost channel can use Jentic to call the right operations on demand. Jentic stores the session or personal access token in the vault and exposes login, identity, and post operations via intent search, removing per-server auth boilerplate.

Example prompt: Search Jentic for 'post message to mattermost channel', load the `/posts` schema, and execute it with the channel_id and message body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /users/login | Authenticate and obtain a session token |
| GET | /users/me | Fetch the authenticated user |
| GET | /users | List users on the server |
| GET | /teams | List teams |
| GET | /channels | List channels |
| POST | /posts | Create a post in a channel |

## Key resources

- **Users** — Authenticate, fetch the current user, and list users on the server.
- **Teams** — List and inspect Mattermost teams accessible to the authenticated user.
- **Channels** — List channels available within teams.
- **Posts** — Create posts in channels.

## Why Jentic

- **Setup:** Wiring the Mattermost API by hand means handling bearer token auth, resolving the {serverUrl} host for your instance, and mapping the v4 REST surface yourself. Through Jentic you install once, import the Mattermost API from the API Directory, store the personal access token once, and your agent calls it.
- **Permission scoping:** The target for Mattermost posts travels in the request body rather than the URL path, so you limit the agent to the operations it needs, such as listing teams and channels or creating a post. It calls only the operations you allow, so anything you leave out stays unreachable.
- **Credential handling:** Your Mattermost personal access token is stored once, encrypted, by your own Jentic One instance and applied as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'post a message to a Mattermost channel' or 'list Mattermost teams', and Jentic returns the matching Mattermost operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Slack API** — Slack is a hosted team-chat platform with a similar channel-and-post model.
- **Discord API** — Discord offers community-focused chat with guilds, voice, and bot APIs.
- **Matrix Client-Server API** — Matrix is an open, federated chat protocol with self-hostable homeservers.
- **Zulip API** — Zulip is an open-source team chat focused on threaded conversations.

## FAQ

### Why is there no official OpenAPI spec for Mattermost API?

Mattermost publishes its API documentation as a custom site rather than a single OpenAPI document. Jentic generates and maintains an OpenAPI specification so AI agents and developers can call the Mattermost API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Mattermost API use?

Mattermost uses HTTP bearer tokens in the `Authorization: Bearer ...` header. Tokens are issued either by `POST /users/login` (session token) or as personal access tokens generated in the Mattermost UI. Through Jentic, both are stored encrypted in your Jentic One instance.

### Can I post a message to a channel with the Mattermost API?

Yes. `POST /posts` creates a new post in a channel. Provide the `channel_id` and `message` body in the JSON payload, plus an optional `root_id` to make the post a reply within an existing thread.

### What are the rate limits for the Mattermost API?

Mattermost rate limits are configured per server by the admin and enforced via `X-Ratelimit-Limit`, `X-Ratelimit-Remaining`, and `X-Ratelimit-Reset` response headers. The default is 10 requests per second per user; on `429 Too Many Requests`, back off until the reset window elapses.

### How do I send a Mattermost post through Jentic?

Run `pip install jentic`, then use Jentic's search with the query 'post message to mattermost channel'. Jentic loads the `/posts` operation schema and your agent executes it with the channel_id and message - Jentic injects the bearer token automatically.

### Does the API work against a self-hosted Mattermost server?

Yes. The base URL is parameterised as `https://{serverUrl}/api/v4`, so the same operations work against the public Mattermost cloud, an internal enterprise install, or a developer's local instance running on `http://localhost:8065`.

### Can I limit what my agent is allowed to do with the Mattermost API?

Yes. Because you self-host Jentic One, your own rules decide which Mattermost operations and credentials the agent may use, and it calls only the operations you allow. You can restrict it to just what a task needs, such as listing teams and channels or fetching the current user, while withholding the ability to create posts. The post target travels in the request body rather than the URL path, so any operation you leave out, including POST /posts, stays unreachable to the agent.