REST API

Antimatter uygulamalarının yaptığı her şey aynı HTTP API’si üzerinden geçer; bu nedenle senin betiklerin de bunu yapabilir. Bu sayfa, kimlik doğrulamanın nasıl yapıldığını, en sık kullanacağın kaynakları, yanıtların ve hataların nasıl göründüğünü ve WebSocket üzerinden olayları canlı olarak nasıl takip edebileceğini açıklar.

Temeller

• Temel URL: https://chat.example.com/api/v4. Aşağıdaki tüm uç noktalar buna görelidir.
• Biçim: Girdi ve çıktı JSON’dur (dosya yüklemeleri multipart’tır). Content-Type: application/json gönderin.
• Kimlikler: her nesnenin 26 karakterlik bir id’si vardır. Zamanlar Unix epoch’undan bu yana geçen milisaniyelerdir (create_at, update_at, delete_at; 0 “silinmemiş” anlamına gelir).
• Topluluklar takımlardır: API bunlara teams der ve team_id kullanır.
• Kendiniz: bir yol user_id alıyorsa, me oturum açmış kullanıcıyı ifade eder; örneğin GET /users/me.

Uç noktaların tam listesi sunucunun kodundadır: rotalar server/channels/api4/*.go içinde, tipler ise server/public/model içinde tanımlanmıştır. Depodaki api/v4/source klasöründeki OpenAPI betiği, Mattermost'tan devralınan uç noktaları ve Antimatter'ın bazı eklerini (konu taşıma, model bağlantıları ve ileti işlemleri) kapsar. Diğerleri yalnızca kodda mevcuttur.

Kimlik doğrulama

Oturum açma ve birkaç herkese açık uç nokta dışında her isteğin Authorization başlığında bir jetonu olmalıdır:

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

Burada üç tür jeton kabul edilir: kişisel erişim jetonları, oturum jetonları ve OAuth erişim jetonları. Authorization: Token … biçimi de kabul edilir. Sorgu dizisindeki jetonlar (?access_token=) yalnızca OAuth erişim jetonları için kabul edilir.

Kişisel erişim jetonları (betikler için önerilir)

Bir kişisel erişim jetonu sizin adınıza hareket eder, son kullanma tarihi vermediğiniz sürece zaman aşımına uğramaz ve istediğiniz zaman iptal edilebilir. Kişisel erişim jetonları varsayılan olarak kapalıdır:

1. Sistem yöneticisi, Sistem Konsolu › Bütünleştirmeler › Bütünleştirme yönetimi bölümünde Kişisel erişim kodları kullanılsın seçeneğini etkinleştirir (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Kod oluşturabilecek her kullanıcı için sistem yöneticisi, Sistem Konsolu › Kullanıcı yönetimi › Kullanıcılar bölümüne gider, kullanıcının menüsünden Rolleri yönet seçeneğini seçer ve Bu hesabın kişisel erişim kodları oluşturmasına izin ver onay kutusunu işaretler. Sistem yöneticileri her zaman kod oluşturabilir.
3. Kullanıcı, sağ üst köşedeki avatarına tıklayıp ardından Profil & ayarlar › Güvenlik bölümüne gider. Kişisel erişim kodları altında kodun ne için kullanılacağını açıklar ve Kod oluştur seçeneğini seçer. Kod yalnızca bir kez görüntülenir: kopyalayın.

API ile: POST /users/{user_id}/tokens ve {"description": "backup script", "expires_at": 0} (expires_at milisaniye cinsindendir; 0 için yok). Yanıtın token alanı gizli anahtardır; id alanı ise onu iptal etmek için kullanılır (POST /users/tokens/revoke ve {"token_id": "…"}). Komut satırından: amctl token generate <user> <description>.

Sistem yöneticisi, aynı Sistem Konsolu sayfasındaki Maksimum Kişisel Erişim Jetonu Geçerlilik Süresi (gün) ayarıyla kod geçerlilik sürelerini sınırlayabilir.

Oturum token'ları

Parola ile oturum açma, Token yanıt başlığında bir oturum token'ı döndürür; bu, uygulamaların kullandığı türden bir oturumdur:

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

Çok faktörlü kimlik doğrulama bulunan bir hesap için "token": "123456" ekleyin. Oturumlar, sunucunun oturum ayarlarına göre sona erer ve oturum açma uç noktası hız sınırlıdır (saniyede 5 istek). POST /users/logout oturumu sonlandırır.

OAuth 2.0 uygulamaları

Kişilerin Antimatter hesaplarıyla uygulamanıza oturum açmasına izin vermek için bir OAuth 2.0 uygulaması kaydedin. Antimatter bu durumda OAuth sağlayıcısı olur:

1. OAuth 2.0 hizmet sağlayıcısı kullanılsın seçeneği etkin olmalıdır (Sistem Konsolu › Bütünleştirmeler › Bütünleştirme yönetimi, ServiceSettings.EnableOAuthServiceProvider, varsayılan olarak etkindir).
2. OAuth uygulamalarını yönetme yetkisine sahip olan biri (varsayılan olarak sistem yöneticileri), avatarına tıklayıp Bütünleştirmeler › OAuth 2.0 uygulamaları bölümüne gider ve geri çağırma (callback) URL'leriyle birlikte uygulamayı ekler. Bir istemci kimliği (client ID) ve istemci gizli anahtarı (client secret) alır.
3. Uygulamanız, https://chat.example.com/oauth/authorize adresine response_type=code, client_id, redirect_uri ve state parametreleriyle yönlendirir. code_challenge_method=S256 ile PKCE desteklenir.
4. Kodu, POST https://chat.example.com/oauth/access_token adresinde (grant_type=authorization_code ile, ardından yenilemek için refresh_token ile) takas eder ve API'yi Authorization: Bearer <access token> ile çağırır.

Kişiler, yetkilendirdikleri uygulamaları Profil ve ayarlar › Güvenlik › Yetkilendirdiğiniz uygulamalar bölümünde görür.

Ana kaynaklar

İleti gönder

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

İletiler Markdown biçimindedir. Bir konuya yanıt vermek için "root_id" (konunun ilk gönderisi) ekleyin, dosyalar için "file_ids" ve ek dosyalar ile diğer ekler için "props" kullanın (bkz. Ek dosyalar).

Bir kanalın kimliğini bulun

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

İsimler, kanal bağlantısındaki isimlerdir: /lumen-labs/channels/ops-alerts.

Sayfalama

Liste uç noktaları page (0'dan başlar) ve per_page (varsayılan 60, en fazla 200) parametrelerini alır. Bir sayfa per_page değerinden kısa döndürülene kadar sonraki sayfayı istemeye devam edin.

Bir kanalın iletileri (GET /channels/{channel_id}/posts) ayrıca since (bir zaman: o andan beri değişen her şey) veya before ve after (bir ileti kimliği) parametrelerini de alır. Yanıt, bir ileti listesi olarak döner: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Hatalar

Hatalar, standart HTTP durum kodlarını (400 hatalı girdi, 401 oturum açılmamış, 403 izin yok, 404 bulunamadı, 501 özellik devre dışı) ve bir JSON gövdesini kullanır:

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

Kodunuzda id alanını kullanın: message kullanıcının diline çevrilir. detailed_error, sunucu geliştirici modunda çalışmıyorsa (ServiceSettings.EnableDeveloper) boş kalır. request_id değerini sunucunun yöneticisine iletin: bu değer günlüklerde bulunur.

Hız sınırları

Hız sınırlaması varsayılan olarak devre dışıdır. Sistem yöneticisi bunu etkinleştirdiğinde (Sistem Konsolu › Ortam › Hız sınırlaması), her istemci için varsayılan olarak saniyede 10 istek ve 100'lük patlamalar (bursts) uygulanır; sayım IP adresine veya kullanıcıya göre yapılır. Yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır; sınır aşıldığında sunucu 429 yanıtı verir ve saniye cinsinden Retry-After başlığı ekler. Giriş yapma gibi bazı uç noktalar, ayar ne olursa olsun kendi sınırlarına sahiptir.

429 durumunda bekleyip yeniden denemek için betikler yazın ve yoklama (polling) yapmaktan kaçının: bunun yerine WebSocket'i izleyin.

WebSocket olay akışı

wss://chat.example.com/api/v4/websocket adresine bağlanın. Kimlik doğrulama, bağlantı isteğinde Authorization: Bearer başlığıyla veya ilk mesaj olarak şunu göndererek yapılır:

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

Sunucu bir hello olayı gönderir, ardından görüntülemeye yetkili olduğunuz her şey için bir olay gönderir:

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

data.post'un bir JSON dizgesi olarak iletinin kendisi olduğunu unutmayın. Yaygın olaylar: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Uygulamalar, custom_<app id>_<event> adlı kendi olaylarını gönderir.

Artan seq değerleriyle eylemler de gönderebilirsiniz: {"channel_id", "parent_id"} içeren user_typing veya get_statuses. Bağlantı koptuğunda yeniden bağlanın ve since ile kaçırdıklarınızı alın (bkz. Sayfalama).

Antimatter şu olayları ekler: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated ve category_overrides_updated.

İstemci kütüphaneleri

• Go: server/public/model içindeki model.Client4 (içe aktarım: github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url) çağrıldıktan sonra client.SetToken(token) kullanılır; model.NewWebSocketClient4(wsURL, token) olayları izler. Antimatter'in kopyası, UpdateMessageRequest, PutPostOnTop ve ExportChannel gibi kendi uç noktaları için yöntemler ekler.
• TypeScript: webapp/platform/client içindeki @mattermost/client paketinin Client4 sınıfı, tipleri ise webapp/platform/types içindedir. Antimatter deposundaki kopya, Antimatter'in uç noktalarını içerir; Mattermost tarafından npm'de yayınlanan paket ise içermez.

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

Antimatter'in API'ye ekledikleri

Bu uç noktalar ve alanlar bir Mattermost sunucusunda mevcut değildir. Hepsinin bir oturum gerektirir.

Yeni alanlar

• Topluluklar (Team ve PUT /teams/{team_id}/patch): all_channels_membership (herkes, görebildiği her kanala üyedir), default_channel_id (yeni gelenlerin düştüğü yer; boşsa Genel), kind (community veya workplace: bir çalışma alanında, kanal yöneticileri kendi kanallarını da arşivleyebilir; yeni topluluklar sunucunun TeamSettings.DefaultCommunityKind değerini alır, varsayılan olarak community), member_list_view (üye listesinin üyeleri nasıl grupladığı: varsayılan olan choice, her üyenin seçim yapmasına olanak tanır; roles veya teams bunu sabitler), hide_role_colors, require_team_badges, onboarding ve autolinks (ikisi de JSON dizeleri).
• Yeni bir topluluğun varsayılan kanalı general (Genel), town-square değil. 0.9.0 yükseltmesi, topluluğun town-square kanalını general olarak yeniden adlandırır, kimliğini korur; toplulukta zaten bir general kanalı varsa bu işlem yapılmaz. Eski adlar çalışmaya devam eder: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square ve gelen webhook'ların channel alanı, bu adla eşleşen bir kanal yoksa topluluğun varsayılan kanalını döndürür. Yeni kodlarda default_channel_id veya general adını kullanın.
• Kanal bağlantıları: #channel-name bir kanalı bağlar, tıpkı ~channel-name gibi. Gönderinin channel_mentions özelliği, her iki şekilde de bağlanan kanalları listeler; kanal adı belirtmeyen bir #word etiket olarak kalır. Antimatter'ın web arayüzü ve mobil uygulaması #name yazar.
• Arşivlenmiş kanallar hâlâ yeni üyeler kabul eder (POST /channels/{channel_id}/members); bu üyeler geçmişteki iletileri okuyabilir. Kimse bu kanallarda ileti gönderemez, tepki veremez, sabitleyemez, bir iletiyi en üste taşıyamaz, kanalın adını değiştiremez veya üyelerin rollerini değiştiremez.
• Satır içi yanıtlar: "props": {"reply_to": "<post id>"} alanı, aynı kanaldaki ilgili iletinin alıntısını yapar. Yazarı bilgilendirmemek için "reply_to_mention": false ekleyin. Sunucu, alıntılanan iletinin kısa bir açıklamasını metadata.reply_to alanına doldurur.
• Spoiler: "props": {"spoiler": true} alanı, okuyucu görmeyi seçene kadar iletinin metnini ve eklerini gizler.
• Yoksayma ve engelleme tercihlerdir: kategori user_block, diğer kişinin kimliğiyle adlandırılır ve değeri ignore veya block olur. Bir doğrudan iletinin istek olarak bekleyip beklemeyeceği, kanal üyenizin notify_props.dm_request alanında belirtilir (pending, accepted veya dismissed).
• İleti ekleri stages ve chart taşıyabilir: bkz. Kartlar.

Bir konuyu taşıma

POST /posts/{post_id}/move_to_channel, bir konuyu, ilk iletisini ve tüm yanıtlarını, aynı toplulukta başka bir kanala taşır. post_id, ilk ileti veya herhangi bir yanıt olabilir.

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 (zorunlu): Konunun taşınacağı kanal.
• flatten (varsayılan false): true değeri, yanıtları bir konu olarak değil, hedef kanaldaki normal iletiler olarak oluşturur. Fusion'ın Kanal yap özelliği bunu kullanır.

İletiler yazarlarını, zaman damgalarını, tepkilerini ve dosyalarını korur. Kopyaları silent_notification özelliğini taşır, bu nedenle kimseye bildirim göndermez. Orijinal iletiler silinir. Yanıt, yeni kimliğiyle taşınmış ilk iletidir.

Bir konuyu kim taşıyabilir

• Konuyu okuyabilmeli ve hedef kanala ileti gönderebilmelisiniz.
• Kanal yöneticileri, topluluk yöneticileri, kanalda İletileri yönet (delete_others_posts) yetkisine sahip kişiler ve sistem yöneticileri herhangi bir konuyu taşıyabilir.
• Konunun yazarı, her iki kanal herkese açıksa veya konudaki tüm iletiler kendisine aittiyse konuyu taşıyabilir. Aksi halde yanıt, api.post.move_thread.private_needs_moderator.app_error kimliğiyle 403 olur.
• Her iki kanal da aynı toplulukta olmalı (doğrudan veya grup iletisi olamaz), birbirinden farklı olmalı ve arşivlenmemiş olmalıdır. Sistem iletileri ve okunduğunda silinen iletiler taşınamaz.
• WranglerSettings.MoveThreadMaxCount (varsayılan olarak 100; sınırsız için 0) iletiden uzun bir konu reddedilir.

İşaretçi ve not

Taşıma işlemi, system_wrangler türünde iki sistem iletisi bırakır: eski kanalda bir işaretçi ("13 iletiden oluşan bir konu #hedef kanalına taşındı") ve hedef kanalda bir not ("Bu konu #kaynak kanalından taşındı"); taşınan konunun altında veya flatten kullanılırsa iletilerinin ardından. İletinin metninin yanı sıra, bu iletilerin özellikleri (props) bir istemcinin kanal adını bağlantı olarak çizmesine olanak tanır:

• İşaretçi: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId ve herkese açık bir hedef için MovedThreadChannelName ile MovedThreadChannelDisplayName.
• Not: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (işaretçi), MovedFromPermalink ve herkese açık bir kaynak için MovedFromChannelName ile MovedFromChannelDisplayName.

Her ikisinde de bir TranslationID bulunur. Özel bir kanalın adı yer almaz: okuyucular "başka bir kanal" görür. Mattermost'un kendi POST /posts/{post_id}/move uç noktası Antimatter'da devre dışıdır; bu uç noktası kullanın.

Model bağlantıları

Bir model bağlantısı, bir yapay zeka sağlayıcısının adresi ve anahtarıdır ve bir yönetici tarafından yapılandırılır. Sunucunun yapay zeka özellikleri ve yapay zeka hizmetini çağıran uygulamalar bunları kullanır. Sistem yöneticileri sunucu genelindeki bağlantıları (manage_ai_connections), bir topluluğun yöneticileri ise kendi topluluklarının bağlantılarını (manage_team_ai_connections) yönetir. Anahtarlar yalnızca yazılabilir: hiçbir yanıt bir anahtar taşımaz, yalnızca api_key_set ve api_key_last4 alanları vardır.

Yeni bir bağlantının gövdesi:

{
  "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 değeri openai_compatible veya anthropic olmalıdır. scope değeri varsayılan olarak server'dır; bir topluluğun kimliği, bağlantıyı o topluluğun bağlantısı yapar. limits içinde 0, sınırsız anlamına gelir; dakikadaki istekler her sunucuda sayılır, jeton bütçeleri ise tüm küme için takvim ayına (UTC) göre hesaplanır. sharing, sunucu genelindeki bir bağlantıyı hangi toplulukların kullanabileceğini belirtir (doğrudan ve grup iletileri için all_teams gerekir) ve audience, onu kimlerin kullanabileceğini belirtir; konuklar yalnızca allow_guests ile. Değişiklikler denetim kaydına yazılır. Ayarlar hakkında yönetici kılavuzuna bakın: Yapay Zekâ.