HTTP API¶

Kaynakları okumak ve değiştirmek için HTTP API'yi kullanın. Her yol tek bir temel URL'nin altında bulunur:

https://tebhos.com/api/v1

Bu sayfalardaki yollar bu temele göre yazılmıştır; yani GET /channels/{channel_id}, GET https://tebhos.com/api/v1/channels/{channel_id} anlamına gelir. Temel URL'yi veya dağıtımın başka herhangi bir uç noktasını keşfetmesi gereken bir istemci önce /.well-known/tebhos adresini okur. Oradaki endpoints.api_public değeri API köküdür (/api ile biter) ve istemci /v1 ekini kendisi ekler.

Tek API sürümü v1 sürümüdür. Sürüm anlaşması için bir başlık ve geri dönülecek daha eski bir sürüm yoktur.

Ek sayısı, mesaj uzunluğu ve sunucu ifade sayısı gibi kaynak sınırları, örnek keşfinin sınır yapılandırmasında yayımlanır. Bu değerleri koda sabit yazmak yerine oradan okuyun.

Kurallar¶

Snowflake'ler¶

Her kimlik bir snowflake'tir: API'nin her zaman ondalık dize olarak serileştirdiği 64 bitlik bir tamsayı; örneğin "1501314428688998182". Kimlikleri geri gönderirken de dize olarak gönderin. Bir JavaScript istemcisi bir kimliği number olarak ayrıştırMAMALIDIR (MUST NOT), çünkü snowflake çift duyarlıklı kayan noktalı sayıya sığmaz.

Snowflake'ler oluşturulma zamanlarını içerir ve kronolojik olarak sıralanır; aşağıdaki imleç tabanlı sayfalama buna dayanır.

Zaman damgaları¶

Zaman damgaları UTC'de ISO 8601 / RFC 3339 dizeleridir; örneğin "2026-09-23T00:15:57.000Z". Gerçek zamanlı katmandan veya bir önbellekten gelen birkaç alan bunun yerine Unix zamanı taşır ve bunlar kendi sayfalarında belirtilir (örneğin OAuth2 introspection içindeki exp ve iat).

Alan gösterimi¶

Her kaynak sayfasındaki alan tabloları aynı gösterimi kullanır:

Alanlar zamanla eklendiğinden, bir istemci bilinmeyen bir yanıt alanını hata vermek yerine yokmuş gibi ele almak ZORUNDADIR (MUST).

Sayfalama¶

Sınırsız büyüyebilen liste yolları, snowflake'lerle imleç tabanlı sayfalanır. Bir yol destekliyorsa, bir snowflake kimliğiyle before, after veya around ve bir sayıyla limit gönderin; varsayılan ve en büyük limit değerini yolun sayfası belirtir. Küçük, sınırlı koleksiyonlar (örneğin bağlantılar veya bir kullanıcının sahip olduğu uygulamalar) bütün olarak döndürülür.

İstek biçimi¶

JSON gövdelerini Content-Type: application/json ile gönderin. Bir işlem aksini belirtmedikçe yanıtlar UTF-8 JSON'dur. İstisnalar kendi kaynak sayfalarında belirtilir:

• OAuth2 token, introspection ve iptal uçları application/x-www-form-urlencoded gövde alır.
• Mesaj oluşturma ve webhook çalıştırma, Mesajlar ve Webhook'lar sayfalarında açıklandığı gibi multipart/form-data da kabul eder.
• Dosya yüklemeleri önceden imzalanmış URL'ler kullanır; bkz. Ek yüklemeleri.

Geçerli JSON olmayan ya da biçimi işlemle uyuşmayan (eksik zorunlu alan, yanlış tür) bir gövde, işlem çalışmadan önce 400 ile reddedilir.

Bilinmeyen yollar boş gövdeyle 404 döndürür. Bilinen bir yol desteklemediği bir metotla çağrılırsa da 405 değil, boş gövdeyle 404 döndürür. Sondaki eğik çizgiler önemlidir: /users/@me/, /users/@me yolundan farklı bir yoldur.

Yalnızca genel medya yolları (/files/{key}, /avatars/..., /banners/..., /server-icons/... ve Medya vekili yolları bölümünde açıklanan diğer görsel yolları) HEAD isteğine yanıt verir. Diğer tüm yollarda HEAD, desteklenmeyen herhangi bir metot gibi ele alınır.

Kimlik doğrulama¶

Çoğu yol bir Authorization başlığı gerektirir. TEBHOS, REST API'de iki şema kabul eder:

Kullanıcı oturum token'ı Bearer öneki olmadan, yalın olarak da gönderilebilir. Kimlik doğrulama her iki kimlik bilgisini ayrıntılı olarak açıklar.

Her yol hangi kimlik bilgilerini kabul ettiğini belirtir. Kullanıcıya yönelik pek çok yol yalnızca kullanıcılar içindir: bir oturum token'ı okur ve geçerli bir bot token'ını 403 ACCESS_DENIED ile (geçersiz olanı 401 ile) reddeder. Botların kullandığı yollar (mesajlar, tepkiler, kanallar, sunucu okumaları vb.) ikisini de kabul eder. OAuth2 bearer erişim token'ları yalnızca bunları belgeleyen iki OAuth2 yolu (kullanıcı bilgileri ve geçerli yetkilendirme) ile eşleşen bir kapsam isteyen birkaç okuma yolu tarafından kabul edilir; OAuth2 erişim token'ları bunları listeler. Diğer tüm yollar geçerli bir erişim token'ını 403 ACCESS_DENIED ile yanıtlar.

Hassas hesap işlemleri ek olarak sudo kipi gerektirir: istek gövdesinde verilen ya da oturuma beş dakikalığına tanınan, parolanın, bir doğrulayıcı kodunun veya bir geçiş anahtarının (passkey) taze bir kanıtı.

Standart istek başlıkları¶

Standart yanıt başlıkları¶

X-RateLimit-* başlıkları başarılı yanıtlarda değil, yalnızca bir hız sınırı reddinde gönderilir. Sözleşmenin tamamını Hız sınırları tanımlar.

Hız sınırları¶

Kimliği doğrulanmış her /api/v1 isteği, istemci başına saniyede 50 isteklik genel bir sınıra sayılır. İstemci Authorization başlığıyla, başlık göndermiyorsa IP adresiyle tanımlanır. Kimliği doğrulanmamış GET/HEAD istekleri, genel medya okumaları ve webhook çalıştırma genel sınırdan muaftır.

Çoğu yolun ayrıca her işlemde belgelenen kendi yol kovası vardır. İkisinden birinden gelen ret, RATE_LIMITED koduyla 429 döndürür:

{
  "error": "429 Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "...",
  "global": false,
  "retry_after": 1.25
}

retry_after kesirli kısmı olan saniye cinsindendir; Retry-After aynı değerin tam saniyeye yukarı yuvarlanmış hâlidir. Kovaları ve başlık sözleşmesini Hız sınırları listeler.

Çapraz kaynaklı istekler¶

Tarayıcı isteklerine TEBHOS web kaynaklarından (https://tebhos.com ve onun *.tebhos.com alt alan adları) izin verilir. İzin verilen bir Origin için yanıt, o kaynağa ayarlanmış Access-Control-Allow-Origin ve Access-Control-Allow-Credentials: true taşır. Başka herhangi bir kaynaktan gelen istekler Access-Control-Allow-Origin almaz; bu yüzden tarayıcı onları engeller.

Ön kontrol (preflight); GET, POST, PUT, PATCH, DELETE ve OPTIONS metotlarına ve Content-Type ile Authorization istek başlıklarına izin verir. Hız sınırı başlıkları ve Retry-After, Access-Control-Expose-Headers aracılığıyla betiklere açılır.

Genel medya yolları (avatarlar, simgeler, afişler ve /files/{key}) her kaynağa Access-Control-Allow-Origin: * ile yanıt verir; böylece görseller her yerden yüklenebilir.

Bir bot veya sunucu tarafı istemci tarayıcı değildir ve CORS'tan etkilenmez.

Hata yanıtı nesnesi¶

Başarısız bir istek, kalıcı bir hata kodu ve insanların okuyabileceği bir mesaj içeren JSON gövde döndürür.

Yapı¶

İstemci dallanmayı message değerine göre değil, her zaman code ve HTTP durumuna göre yapmak ZORUNDADIR (MUST). Mesajlar son kullanıcılar için yazılır, şu anda Türkçedir ve her an değişebilir.

Örnek¶

{
  "error": "403 Forbidden",
  "code": "FORBIDDEN",
  "message": "Kendi yetkilerinizi değiştiremezsiniz"
}

Bazı işlemler yapılandırılmış ayrıntı içeren ek üst düzey üyeler ekler ve bunları belgeler. Örneğin giriş, ticket, email ve resend_available_in ile IP_AUTHORIZATION_REQUIRED döndürür; bir hız sınırı reddi de global ve retry_after taşır. İstemci tanımadığı üyeleri yok saymak ZORUNDADIR (MUST).

Doğrulama hatası nesnesi¶

Her kayıt, doğrulamadan geçemeyen bir girdi alanını belirtir.

Yapı¶

Örnek¶

{
  "error": "400 Bad Request",
  "code": "INVALID_FORM_BODY",
  "message": "Kanal sesli kanal olmalı",
  "errors": [
    {"path": "channel_id", "code": "CHANNEL_MUST_BE_VOICE", "message": "CHANNEL_MUST_BE_VOICE"}
  ]
}

Bir errors kaydında message şu anda code değerini tekrarlar. Pek çok doğrulama hatası yalnızca üst düzey bir message ile, errors dizisi olmadan INVALID_FORM_BODY döndürür. Kodları Hatalar listeler.

Kaynak sayfaları¶