De REST API

Alles wat de Antimatter-apps doen verloopt via dezelfde HTTP API, dus je scripts kunnen hetzelfde. Deze pagina legt uit hoe je je identificeert, de bronnen die je het meest zult gebruiken, hoe antwoorden en fouten eruitzien en hoe je live gebeurtenissen volgt via de WebSocket.

Basis

• Basis-URL: https://chat.example.com/api/v4. Alle endpoints hieronder zijn relatief ten opzichte daarvan.
• Formaat: JSON in en uit, behalve bij het uploaden van bestanden (multipart). Stuur Content-Type: application/json.
• ID’s: elk object heeft een id van 26 tekens. Tijden zijn milliseconden sinds de Unix-epoch (create_at, update_at, delete_at; 0 betekent “niet verwijderd”).
• Gemeenschappen zijn teams: de API noemt ze teams, met een team_id.
• jezelf: overal waar een pad een user_id verwacht, betekent me de aangemelde gebruiker, zoals in GET /users/me.

De volledige lijst met eindpunten staat in de code van de server: de routes zijn gedefinieerd in server/channels/api4/*.go en de types in server/public/model. De OpenAPI-beschrijving in de map api/v4/source van het repository dekt de eindpunten die zijn overgenomen van Mattermost, en enkele toevoegingen van Antimatter: het verplaatsen van draadjes, modelverbindingen en berichtacties. De overige eindpunten zijn alleen in de code te vinden.

Authenticatie

Elk verzoek, behalve het aanmelden en enkele openbare endpoints, vereist een token in de Authorization-header:

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

Er worden drie soorten tokens daar geaccepteerd: persoonlijke toegangstokens, sessietokens en OAuth-toegangstokens. Ook Authorization: Token … wordt geaccepteerd. Tokens in de querystring (?access_token=) worden alleen geaccepteerd voor OAuth-toegangstokens.

Persoonlijke toegangstokens (aanbevolen voor scripts)

Een persoonlijke toegangstoken handelt in jouw naam, verloopt niet tenzij je een vervaldatum geeft en kan op elk moment worden ingetrokken. Persoonlijke toegangstokens zijn standaard uitgeschakeld:

1. Een systeembeheerder schakelt Persoonlijke toegangstokens inschakelen in via Systeemconsole › Integraties › Integratiebeheer (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Voor elke persoon die tokens mag aanmaken, opent een systeembeheerder Systeemconsole › Gebruikersbeheer › Gebruikers, kiest Rollen beheren in het menu van de persoon en vinkt Sta dit account toe om persoonlijke toegangstokens te genereren aan. Systeembeheerders kunnen ze altijd aanmaken.
3. De persoon opent de eigen avatar rechtsboven, daarna Profiel & instellingen › Beveiliging. Onder Persoonlijke toegangstokens beschrijft de persoon waar het token voor is en kiest Nieuw Token Aanmaken. Het token wordt slechts één keer getoond: kopieer het.

Met de API: POST /users/{user_id}/tokens met {"description": "backup script", "expires_at": 0} (expires_at in milliseconden; 0 voor geen). Het token-veld in de respons is het geheim; de id is wat je gebruikt om het te intrekken (POST /users/tokens/revoke met {"token_id": "…"}). Vanuit de opdrachtregel: amctl token generate <user> <description>.

Een systeembeheerder kan de levensduur van tokens beperken met Maximale levensduur persoonlijke toegangstokens (dagen) op dezelfde Systeemconsole-pagina.

Sessietokens

Inloggen met een wachtwoord geeft een sessietoken terug in de Token-responsheader, hetzelfde type sessie dat de apps gebruiken:

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

Voeg "token": "123456" toe voor een account met meervoudige verificatie. Sessies verlopen zoals de sessie-instellingen van de server voorschrijven, en het inlogpunt is rate-limited (5 verzoeken per seconde). POST /users/logout beëindigt de sessie.

OAuth 2.0-apps

Om mensen toe te staan in te loggen op uw toepassing met hun Antimatter-account, registreert u een OAuth 2.0-app. Antimatter is dan de OAuth-provider:

1. Aanzetten van OAuth 2.0 Service Provider moet ingeschakeld zijn (Systeemconsole › Integraties › Integratiebeheer, ServiceSettings.EnableOAuthServiceProvider, standaard ingeschakeld).
2. Iemand met het recht om OAuth-apps te beheren (standaard systeembeheerders) opent de eigen avatar, vervolgens Integraties › OAuth 2.0-apps, en voegt de app toe met de callback-URL’s. Ze krijgen een client ID en een client secret.
3. Uw applicatie stuurt mensen door naar https://chat.example.com/oauth/authorize met response_type=code, client_id, redirect_uri en state. PKCE met code_challenge_method=S256 wordt ondersteund.
4. Daarna wisselt het de code in bij POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, en daarna refresh_token om te vernieuwen) en roept het de API aan met Authorization: Bearer <access token>.

Gebruikers zien de apps waaraan ze toegang hebben gegeven in Profiel & instellingen › Beveiliging › Apps waaraan je toegang hebt gegeven.

Belangrijkste bronnen

Een bericht plaatsen

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"}'

Berichten zijn Markdown. Voeg "root_id" (het eerste bericht van een draadje) toe om in een draadje te antwoorden, "file_ids" voor bestanden en "props" voor bijlagen en andere extra's (zie Bijlagen).

Het ID van een kanaal vinden

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

De namen zijn die in de link van het kanaal: /lumen-labs/channels/ops-alerts.

Paginering

Lijst-endpoints accepteren page (vanaf 0) en per_page (standaard 60, maximaal 200). Blijf de volgende pagina opvragen totdat een pagina korter is dan per_page.

De berichten van een kanaal (GET /channels/{channel_id}/posts) accepteren ook since (een tijdstip: alles wat sindsdien is gewijzigd), of before en after (een bericht-ID). Ze worden teruggegeven als een lijst met berichten: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Fouten

Fouten gebruiken de gebruikelijke HTTP-statuscodes (400 ongeldige invoer, 401 niet aangemeld, 403 niet toegestaan, 404 niet gevonden, 501 functie uitgeschakeld) en een JSON-lichaam:

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

Gebruik id in uw code: message wordt vertaald naar de taal van de gebruiker. detailed_error is leeg, tenzij de server in ontwikkelaarsmodus draait (ServiceSettings.EnableDeveloper). Vermeld request_id bij de beheerder van de server: deze staat in de logs.

Snelheidslimieten

Snelheidsbeperking is standaard uitgeschakeld. Wanneer een systeembeheerder deze inschakelt (Systeemconsole › Omgeving › Snelheidsbeperking), krijgt elke client standaard 10 verzoeken per seconde met pieken van 100, geteld op IP-adres of op gebruiker. Antwoorden bevatten X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset; boven de limiet antwoordt de server met 429 en een Retry-After-header in seconden. Sommige eindpunten, zoals het aanmelden, hebben hun eigen limiet ongeacht de instelling.

Schrijf scripts die wachten en opnieuw proberen bij 429, en vermijd polling: gebruik in plaats daarvan de WebSocket.

De WebSocket-gebeurtenisstream

Maak een verbinding met wss://chat.example.com/api/v4/websocket. Authenticatie gebeurt via de Authorization: Bearer-header in het verzoek voor de verbinding, of door dit als eerste bericht te verzenden:

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

De server stuurt een hello-gebeurtenis, gevolgd door een gebeurtenis voor alles waarvoor u bevoegdheid heeft:

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

Merk op dat data.post het bericht is als een JSON-tekenreeks. Veelvoorkomende gebeurtenissen: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Apps sturen hun eigen gebeurtenissen, genaamd custom_<app id>_<event>.

U kunt ook acties verzenden, elk met een toenemende seq: user_typing met {"channel_id", "parent_id"}, of get_statuses. Herstel de verbinding wanneer deze verbroken is, en haal wat u hebt gemist op met since (zie Paginering).

Antimatter voegt de volgende gebeurtenissen toe: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated en category_overrides_updated.

Clientbibliotheken

• Ga: model.Client4 in server/public/model (import github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), daarna client.SetToken(token); model.NewWebSocketClient4(wsURL, token) volgt gebeurtenissen. De kopie van Antimatter voegt methoden toe voor de eigen eindpunten, zoals UpdateMessageRequest, PutPostOnTop en ExportChannel.
• TypeScript: de Client4-klasse van @mattermost/client, te vinden in webapp/platform/client, met de bijbehorende types in webapp/platform/types. De kopie in het repository van Antimatter bevat de eindpunten van Antimatter; het pakket dat Mattermost op npm publiceert, niet.

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)
}

Wat Antimatter aan de API toevoegt

Deze eindpunten en velden bestaan niet op een Mattermost-server. Ze vereisen allemaal een sessie.

Nieuwe velden

• Communities (Team, en PUT /teams/{team_id}/patch): all_channels_membership (iedereen is lid van elk kanaal dat ze mogen zien), default_channel_id (waar nieuwe leden terechtkomen; leeg betekent Algemeen), kind (community of workplace: in een workplace kunnen kanaalbeheerders hun kanalen ook archiveren; nieuwe communities krijgen het TeamSettings.DefaultCommunityKind van de server, standaard community), member_list_view (hoe de ledenlijst leden groepeert: choice, de standaard, laat elk lid kiezen; roles of teams is vast), hide_role_colors, require_team_badges, onboarding en autolinks (beide JSON-strings).
• Het standaardkanaal van een nieuwe community is general (Algemeen), niet town-square. De upgrade naar 0.9.0 hernoemt het town-square-kanaal van elke community naar general, waarbij de ID behouden blijft, tenzij de community al een general-kanaal heeft. De oude namen blijven werken: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square en het channel-veld van een inkomende webhook geven het standaardkanaal van de community terug als er geen kanaal met die naam bestaat. Gebruik in nieuwe code default_channel_id of de naam general.
• Kanaallinks: #channel-name koppelt een kanaal, net zoals ~channel-name. De channel_mentions-eigenschap van het bericht toont de kanalen die op die manier zijn gekoppeld; een #word zonder kanaalnaam blijft een hashtag. De webinterface en de mobiele app van Antimatter schrijven #name.
• Gearchiveerde Kanalen kunnen nog steeds nieuwe leden toevoegen (POST /channels/{channel_id}/members), die hun geschiedenis kunnen lezen. Niemand kan daar berichten plaatsen, reageren, vastmaken, een bericht bovenaan zetten, het kanaal hernoemen of de rollen van de leden wijzigen.
• Inlineresponses: een bericht met "props": {"reply_to": "<post id>"} citeert dat bericht uit hetzelfde kanaal. Voeg "reply_to_mention": false toe om de auteur niet te verwittigen. De server vult metadata.reply_to in met een korte beschrijving van het geciteerde bericht.
• Spoilers: "props": {"spoiler": true} verbergt de tekst en bestanden van een bericht tot de lezer kiest om ze te bekijken.
• Negeren en blokkeren zijn voorkeuren: categorie user_block, vernoemd naar het ID van de andere persoon, met de waarde ignore of block. Of een privébericht als verzoek wacht, staat in notify_props.dm_request van uw kanaallid (pending, accepted of dismissed).
• Berichtbijlagen kunnen stages en een chart bevatten: zie Kaarten.

Een draadje verplaatsen

POST /posts/{post_id}/move_to_channel verplaatst een draadje, het eerste bericht en alle antwoorden, naar een ander kanaal in dezelfde community. post_id kan het eerste bericht zijn of een willekeurig antwoord.

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 (verplicht): het kanaal waarnaar het draadje wordt verplaatst.
• flatten (standaard false): true maakt van de antwoorden gewone berichten in het doelkanaal in plaats van een draadje. Make it a channel in Fusion gebruikt dit.

De berichten behouden hun auteurs, tijdstippen, reacties en bestanden. Hun kopieën hebben de silent_notification-eigenschap, zodat ze niemand informeren. De oorspronkelijke berichten worden verwijderd. Het antwoord is het verplaatste eerste bericht, met zijn nieuwe ID.

Wie een draadje mag verplaatsen

• Je moet in staat zijn het draadje te lezen en in het doelkanaal te kunnen posten.
• De beheerders van het kanaal, de beheerders van de community, personen met Berichten beheren (delete_others_posts) in het kanaal en systeembeheerders mogen elk draadje verplaatsen.
• De auteur van het draadje mag het verplaatsen wanneer beide kanalen publiek zijn, of wanneer alle berichten in het draadje van hem/haar zijn. Anders is het antwoord 403 met de ID api.post.move_thread.private_needs_moderator.app_error.
• Beide kanalen moeten in dezelfde community zitten (geen privé- of groepsberichten), van elkaar verschillen en niet gearchiveerd zijn. Systeem- en burn-on-read-berichten kunnen niet worden verplaatst.
• Een draadje met meer dan WranglerSettings.MoveThreadMaxCount berichten (standaard 100; 0 voor geen limiet) wordt geweigerd.

De pointer en de notitie

De verplaatsing laat twee systeemmeldingen van het type system_wrangler achter: een pointer in het oude kanaal ("Een draadje met 13 berichten is verplaatst naar #target") en een notitie in het doelkanaal ("Dit draadje is verplaatst vanuit #source"), onder het verplaatste draadje of, met flatten, na de berichten. Naast de berichttekst laten de props een client de kanaalnaam als link weergeven:

• De pointer: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId en, voor een publiek doelkanaal, MovedThreadChannelName en MovedThreadChannelDisplayName.
• De notitie: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (de pointer), MovedFromPermalink en, voor een publiek bronkanaal, MovedFromChannelName en MovedFromChannelDisplayName.

Beide hebben ook een TranslationID. De naam van een privé-kanaal wordt weggelaten: lezers zien "ander kanaal". Mattermosts eigen POST /posts/{post_id}/move is in Antimatter uitgeschakeld; gebruik deze endpoint.

Modelverbindingen

Een modelverbinding is het adres en de sleutel van een AI-aanbieder, ingesteld door een beheerder. De AI-functies van de server en de apps die de AI-dienst aanroepen, gebruiken ze. Systeembeheerders beheren de serverbrede verbindingen (manage_ai_connections); de beheerders van een community beheren die van hun eigen community (manage_team_ai_connections). Sleutels zijn alleen-schrijfbaar: geen antwoord bevat er een, alleen api_key_set en api_key_last4.

De inhoud van een nieuwe verbinding:

{
  "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 of anthropic. scope is standaard server; het ID van een community maakt het de verbinding van die community. In limits betekent 0 geen limiet; verzoeken per minuut worden per server geteld, tokenbudgetten per kalendermaand (UTC) voor het hele cluster. sharing bepaalt welke communities een serverbrede verbinding mogen gebruiken (privé- en groepsberichten vereisen all_teams), en audience wie het mag gebruiken; gasten alleen met allow_guests. Wijzigingen worden in de auditlog geschreven. De beheerdersgids legt de instellingen uit: zie AI.