REST-API:et

Allt som Antimatter-apparna gör går genom samma HTTP-API, så dina skript kan göra detsamma. På den här sidan förklaras hur du autentiserar, vilka resurser du kommer att använda oftast, hur svar och fel ser ut och hur du kan följa händelser i realtid via WebSocket.

Grundläggande

• Grund-URL: https://chat.example.com/api/v4. Alla slutpunkter nedan är relativa till den.
• Format: JSON in och ut, förutom filuppladdningar (multipart). Skicka Content-Type: application/json.
• ID:er: varje objekt har en 26 tecken lång id. Tider anges i millisekunder sedan Unix-epoken (create_at, update_at, delete_at; 0 betyder "inte raderad").
• Community är team: API:et kallar dem teams, med ett team_id.
• Du själv: där en sökväg tar ett user_id betyder me den inloggade användaren, som i GET /users/me.

Den fullständiga listan över slutpunkter finns i serverns kod: rutorna är deklarera i server/channels/api4/*.go och typerna i server/public/model. OpenAPI-beskrivningen i repositoryns mapp api/v4/source täcker slutpunkterna som är ärfta från Mattermost, samt några av Antimatters tillägg: flytt av trådar, modellanslutningar och meddelandehandlingar. De övriga finns endast i koden.

Autentisering

Varje begäran, förutom inloggning och några publika slutpunkter, kräver en token i Authorization-rubriken:

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

Tre typer av token accepteras där: personliga access-tokens, sessionstokens och OAuth-access-tokens. Authorization: Token … accepteras också. Tokens i frågesträngen (?access_token=) accepteras endast för OAuth-access-tokens.

Personliga access-tokens (rekommenderas för skript)

En personlig access-token agerar som du, går inte ut om du inte ger den en utgångsdatum och kan återskapas när som helst. Personliga access-tokens är avstängda som standard:

1. En systemadministratör aktiverar Aktivera Personliga Access-tokens i Systemkonsol › Integrationer › Hantera integrationer (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. För varje person som kan skapa token öppnar en systemadministratör Systemkonsol › Hantera användare › Användare, väljer Hantera roller i personens meny och markerar Aktivera Personliga Access-tokens. Systemadministratörer kan alltid skapa dem.
3. Personen öppnar sin avatar i övre högra hörnet och väljer sedan Profil & inställningar › Säkerhet. Under Aktivera Personliga Access-tokens beskriver de vad token är avsett för och väljer Skapa nytt token. Token visas endast en gång: kopiera den.

Med API:et: POST /users/{user_id}/tokens med {"description": "backup script", "expires_at": 0} (expires_at i millisekunder; 0 för ingen). Svarets token-fält är hemligheten; dess id är det du använder för att ångra det (POST /users/tokens/revoke med {"token_id": "…"}). Från kommandoraden: amctl token generate <user> <description>.

En systemadministratör kan begränsa token giltighetstider med Maximal giltighetstid för personliga åtkomsttoken (dagar) på samma Systemkonsol-sida.

Sessionstoken

Inloggning med lösenord returnerar en sessionstoken i Token-responsrätt, samma typ av session som apparna använder:

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

Lägg till "token": "123456" för ett konto med multifaktorautentisering. Sessioner upphör enligt serverns sessionsinställningar, och inloggningsändpunkten är hastighetsbegränsad (5 begäranden per sekund). POST /users/logout avslutar sessionen.

OAuth 2.0-appar

För att låta personer logga in i din applikation med deras Antimatter-konto, registrera en OAuth 2.0-app. Antimatter är då OAuth-leverantören:

1. Aktiverar OAuth 2.0 Service Provider måste vara på (Systemkonsol › Integrationer › Hantera integrationer, ServiceSettings.EnableOAuthServiceProvider, på som standard).
2. Någon med rätt att hantera OAuth-appar (systemadministratörer som standard) öppnar sin avatar, väljer Integrationer › OAuth 2.0-appar och lägger till appen med dess callback-URL:er. De får ett klient-ID och ett klienthemligt.
3. Din applikation skickar användare till https://chat.example.com/oauth/authorize med response_type=code, client_id, redirect_uri och state. PKCE med code_challenge_method=S256 stöds.
4. Den byter koden mot POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, sedan refresh_token för att förnya) och anropar API:et med Authorization: Bearer <access token>.

Användare ser de appar de har godkänt under Profil & inställningar › Säkerhet › Appar du har godkänt.

Huvudresurser

Skicka ett meddelande

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

Meddelanden är Markdown. Lägg till "root_id" (det första inlägget i en tråd) för att svara i en tråd, "file_ids" för filer och "props" för bilagor och andra tillägg (se Bilagor).

Hitta en kanals ID

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

Namnen är de som finns i kanalens länk: /lumen-labs/channels/ops-alerts.

Paginering

List-endpoints tar page (från 0) och per_page (60 som standard, högst 200). Fortsätt att be om nästa sida tills en sida kommer tillbaka som är kortare än per_page.

En kanals meddelanden (GET /channels/{channel_id}/posts) tar även since (en tidpunkt: allt som ändrats sedan dess) eller before och after (ett inläggs-ID). De returneras som en lista med inlägg: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Fel

Fel använder vanliga HTTP-statuskoder (400 felaktig indata, 401 inte inloggad, 403 inte tillåtet, 404 inte hittad, 501 funktion avstängd) och en JSON-kropp:

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

Använd id i din kod: message översätts till användarens språk. detailed_error är tomt om inte servern körs i utvecklarläge (ServiceSettings.EnableDeveloper). Citera request_id till serverns administratör: den finns i loggarna.

Begränsa

Begränsning är avstängd som standard. När en systemadministratör aktiverar den (Systemkonsol › Miljö › Begränsa) får varje klient 10 begäranden per sekund med burstar på 100 som standard, räknat per IP-adress eller per användare. Svar bär X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset; över gränsen svarar servern med 429 med en Retry-After-rubrik i sekunder. Vissa ändpunkter, som inloggning, har sin egen gräns oavsett inställning.

Skriv skript som väntar och försöker igen vid 429, och undvik polling: följ WebSocket i stället.

WebSocket-händelseströmmen

Anslut till wss://chat.example.com/api/v4/websocket. Autentisera antingen med Authorization: Bearer-rubriken i anslutningsbegärandet, eller genom att skicka detta som det första meddelandet:

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

Servern skickar en hello-händelse, sedan en händelse för allt du har tillgång till:

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

Observera att data.post är meddelandet som en JSON-sträng. Vanliga händelser: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Appar skickar egna händelser, namngivna custom_<app id>_<event>.

Du kan också skicka åtgärder, var och en med ett ökande seq: user_typing med {"channel_id", "parent_id"}, eller get_statuses. Återanslut när anslutningen går ner, och hämta det du missade med since (se Paginering).

Antimatter lägger till dessa händelser: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated och category_overrides_updated.

Klientbibliotek

• Go: model.Client4 i server/public/model (importera github.com/mattermost/mattermost/server/public/model). Använd model.NewAPIv4Client(url) och sedan client.SetToken(token); model.NewWebSocketClient4(wsURL, token) följer händelser. Antimatters kopia lägger till metoder för egna slutpunkter, såsom UpdateMessageRequest, PutPostOnTop och ExportChannel.
• TypeScript: klassen Client4 i @mattermost/client, i webapp/platform/client, med dess typer i webapp/platform/types. Kopian i Antimatters repository innehåller Antimatters slutpunkter; paketet som publicerats på npm av Mattermost gör det inte.

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

Vad Antimatter lägger till i API:et

Dessa slutpunkter och fält finns inte på en Mattermost-server. Alla kräver en session.

Nya fält

• Gemenskaper (Team, och PUT /teams/{team_id}/patch): all_channels_membership (alla är i varje kanal de kan se), default_channel_id (där nya användare hamnar; tomt betyder General), kind (community eller workplace: i en workplace kan kanaladministratörer också arkivera sina kanaler; nya gemenskaper får serverns TeamSettings.DefaultCommunityKind, community som standard), member_list_view (hur medlemslistan grupperar medlemmar: choice, standard, låter varje medlem välja; roles eller teams fixerar det), hide_role_colors, require_team_badges, onboarding och autolinks (båda JSON-strängar).
• Standardkanalen i en ny community är general (General), inte town-square. Uppgraderingen till 0.9.0 byter namn på varje communitys town-square till general och behåller dess ID, om inte communityn redan har en general-kanal. Gamla namn fungerar fortfarande: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square och en inkommande webhooks channel ger communityns standardkanal när ingen kanal har det namnet. Använd default_channel_id eller namnet general i ny kod.
• Kanallänkar: #channel-name länkar en kanal, precis som ~channel-name. Egenskapen channel_mentions i inlägget listar kanalerna som är länkade på något av sätten; ett #word som inte nämner någon kanal förblir en hashtag. Antimatters webbgränssnitt och mobilapp skriver #name.
• Arkiverade kanaler kan fortfarande få nya medlemmar (POST /channels/{channel_id}/members), som kan läsa deras historik. Ingen kan posta, reagera, fästa, lägga ett meddelande överst, byta namn på kanalen eller ändra dess medlemmars roller där.
• Inline-svar: ett inlägg med "props": {"reply_to": "<post id>"} citerar det meddelandet från samma kanal. Lägg till "reply_to_mention": false för att inte avisera meddelandets författare. Servern fyller i metadata.reply_to med en kort beskrivning av det citerade meddelandet.
• Spoilers: "props": {"spoiler": true} döljer ett inläggs text och filer tills läsaren väljer att se dem.
• Ignorera och blockera är inställningar: kategori user_block, namngiven efter den andres ID, med värdet ignore eller block. Om ett direktmeddelande väntar som en begäran anges i din kanalmedlems notify_props.dm_request (pending, accepted eller dismissed).
• Meddelandebilagor kan bära stages och ett chart: se Kort.

Flytta en tråd

POST /posts/{post_id}/move_to_channel flyttar en tråd, dess första meddelande och alla dess svar, till en annan kanal i samma community. post_id kan vara det första meddelandet eller vilket som helst svar.

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 (obligatorisk): kanalen som tråden flyttas till.
• flatten (standard false): true gör svaren till meddelanden i målkanalet i stället för en tråd. Fusion använder Gör det till en kanal för detta.

Meddelandena behåller sina författare, tidsstämplar, reaktioner och filer. Deras kopior har silent_notification-egenskapen, så de avisera ingen. De ursprungliga meddelandena tas bort. Svarskoden är det flyttade första meddelandet, med dess nya ID.

Vem som kan flytta en tråd

• Du måste kunna läsa tråden och posta i målkanalet.
• Kanalens administratörer, communityns administratörer, personer med Hantera meddelanden (delete_others_posts) i kanalen samt systemadministratörer kan flytta vilken tråd som helst.
• Trådens författare kan flytta den när båda kanalerna är publika, eller när alla meddelanden i tråden är deras. I andra fall är svaret 403 med ID:t api.post.move_thread.private_needs_moderator.app_error.
• Båda kanaler måste tillhöra samma community (inga direkt- eller gruppmeddelanden), vara olika och inte arkiverade. Systemmeddelanden och meddelanden som bränns vid läsning kan inte flyttas.
• En tråd som är längre än WranglerSettings.MoveThreadMaxCount meddelanden (100 som standard; 0 för ingen gräns) avvisas.

Peckaren och anteckningen

Flytten lämnar efter sig två systemmeddelanden av typen system_wrangler: en peckare i den gamla kanalen ("En tråd med 13 meddelanden har flyttats till #target") och en anteckning i målet ("Denna tråd flyttades från #source"), under den flyttade tråden eller, med flatten, efter dess meddelanden. Förutom meddelandetexten gör deras egenskaper att en klient kan rita kanalnamnet som en länk:

• Peckaren: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId och, för ett publikt mål, MovedThreadChannelName och MovedThreadChannelDisplayName.
• Anteckningen: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (peckaren), MovedFromPermalink och, för en publik källa, MovedFromChannelName och MovedFromChannelDisplayName.

Båda har också ett TranslationID. Ett privat kanals namn utelämnas: läsare ser "en annan kanal". Mattermosts egen POST /posts/{post_id}/move är avstängd i Antimatter; använd denna endpoint.

Modellanslutningar

En modellanslutning är en AI-leverantörs adress och nyckel, som ställs in av en administratör. Serverns AI-funktioner och apparna som anropar AI-tjänsten använder dem. Systemadministratörer hanterar serveromfattande anslutningar (manage_ai_connections); en communitys administratörer hanterar deras communitys egna (manage_team_ai_connections). Nycklar är skrivskyddade: inget svar innehåller en, bara api_key_set och api_key_last4.

Innehållet i en ny anslutning:

{
  "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 är openai_compatible eller anthropic. scope är som standard server; ett samfällighets-ID gör det till samfällighetens anslutning. I limits betyder 0 ingen gräns; förfrågningar per minut räknas på varje server, tokenbudgeter per kalendermånad (UTC) för hela klustret. sharing anger vilka samfälligheter som kan använda en serveromfattande anslutning (direktmeddelanden och gruppmeddelanden kräver all_teams), och audience vem som kan använda den; gäster endast med allow_guests. Ändringar skrivs till revisionsloggen. Administratörsguiden förklarar inställningarna: se AI.