API Dökümanları · v1

JubbioBots için geliştirici rehberi

Botunu entegre et, oy webhook'larını işle, istatistiklerini çek. Her şey JSON ve Bearer token ile.

Token oluştur Hızlı başlangıç Geri bildirim

Genel Bakış

JubbioBots API

JubbioBots API, botunun istatistiklerine programatik erişim sağlar ve her oy verildiğinde sunucuna webhook göndermenin yolunu açar. API, RESTful prensiplere göre çalışır; JSON üzerinden iletişim kurar ve Bearer token ile yetkilendirilir.

Base URL

https://jubbiobots.com

Format

JSON

Güncelleme

Hızlı Başla

Developer Panel'den bir API token oluştur.
Token'ı Authorization header'ında gönder.
GET /api/bots/:id/stats ile istatistikleri çek.

Authentication

Kimlik Doğrulama

Tüm geliştirici endpoint'leri, Authorization header'ında geçerli bir API token bekler. Token'ları Developer Panel'den oluşturabilirsin. Bir token kaybolursa veya güvenliği ihlal edilirse yenile — eski token hemen geçersiz olur.

Header Formatı

http

Authorization: YOUR_API_TOKEN
# eşdeğer:
Authorization: Bot YOUR_API_TOKEN

Çok Gizli

API token'ı istemci (browser, mobil) kodunda ASLA kullanma. Sadece sunucu tarafında tut; sızarsa anında Developer Panel'den yeniden oluştur.

Endpoint

Bot Bilgisi (Herkese Açık)

GET/api/bots/:id

Listelenmiş (approved) bir botun herkese açık profil bilgisini döner. Token gerektirmez. Botunu kendi sitene gömmek veya third-party bir bot listesi kurmak için idealdir.

URL Parametreleri

Alan / Key	Tip	Açıklama
id*	string	Botun Jubbio ID'si veya iç cuid'i.

Örnek İstek

bash

curl https://jubbiobots.com/api/bots/10000000000000001

Örnek Yanıt

json

{
  "id": "cmn9xabcdefghk3z",
  "botId": "10000000000000001",
  "name": "ModGuard",
  "avatar": "https://cdn.jubbio.com/avatars/...",
  "shortDesc": "Gelişmiş moderasyon ve otomatik anti-raid botu.",
  "prefix": "!",
  "website": "https://modguard.app",
  "inviteUrl": "https://jubbio.com/oauth2/authorize?...",
  "supportServer": "https://jubbio.gg/modguard",
  "githubUrl": null,
  "verified": true,
  "featured": true,
  "views": 15839,
  "votes": 1248,
  "favorites": 321,
  "comments": 42,
  "ratings": { "count": 86, "average": 4.7 },
  "categories": [{ "slug": "moderation", "name": "Moderasyon" }],
  "tags": [{ "slug": "anti-raid", "name": "Anti-raid" }],
  "owner": {
    "id": "cmo4i...",
    "username": "rendel",
    "displayName": "Rendel",
    "avatar": "https://cdn.jubbio.com/avatars/..."
  },
  "url": "https://jubbiobots.com/bot/10000000000000001"
}

Endpoint

Bot İstatistikleri

GET/api/bots/:id/stats

Sahibi olduğun bir botun güncel sayaçlarını + derecelendirme ortalamasını döner. Token botun sahibine ait olmalıdır; :id hem iç cuid hem de Jubbio botId ile çalışır.

Header

http

Authorization: YOUR_API_TOKEN
# veya
Authorization: Bot YOUR_API_TOKEN

Örnek İstek

bash

curl -H "Authorization: YOUR_API_TOKEN" \
  https://jubbiobots.com/api/bots/10000000000000001/stats

Örnek Yanıt

json

{
  "id": "cmn9xabcdefghk3z",
  "botId": "10000000000000001",
  "name": "ModGuard",
  "status": "approved",
  "featured": true,
  "verified": true,
  "views": 15839,
  "votes": 1248,
  "favorites": 321,
  "comments": 42,
  "ratings": { "count": 86, "average": 4.7 }
}

Yanıt Alanları

Alan / Key	Tip	Açıklama
id	string	Bot'un iç JubbioBots cuid'i.
botId	string	Jubbio bot ID'si.
name	string	Bot ismi.
status	string	pending \| approved \| rejected.
featured	boolean	Editör tarafından öne çıkarılmış mı?
verified	boolean	Doğrulama rozeti.
views	integer	Detay sayfası görüntülenme sayısı.
votes	integer	Toplam oy.
favorites	integer	Favori sayısı.
comments	integer	Yorum sayısı.
ratings.count	integer	Yıldızlı değerlendirme sayısı.
ratings.average	number\|null	Yıldız ortalaması (1-5).

Endpoint

Oy Kontrolü

GET/api/bots/:id/voted?user=<id>

Bir kullanıcının bu bota aktif oy cooldown'u olup olmadığını döner (ör. 12 saatlik oyun hâlâ geçerli). Oy kampanyası yürüten botlar için rol/rozet dağıtımında kullanışlıdır.

Query Parametreleri

Alan / Key	Tip	Açıklama
user*	string	Jubbio kullanıcı ID'si, kullanıcı adı veya iç cuid.

Örnek İstek

bash

curl -H "Authorization: YOUR_API_TOKEN" \
  "https://jubbiobots.com/api/bots/10000000000000001/voted?user=2387192837419823"

Yanıt (Oy Aktif)

json

{
  "voted": true,
  "lastVoteAt": "2026-04-20T08:14:31.000Z",
  "nextVoteAt": "2026-04-20T20:14:31.000Z"
}

Yanıt (Oy Yok / Süresi Geçmiş)

json

{ "voted": false }

Webhook

Oy Webhook'ları

Her oy verildiğinde, botun ayarlarında tanımladığın URL'e POST isteği atılır. İstekte bulunulacak URL'yi ve doğrulama için kullanılacak gizli anahtarı Developer Panel'den yapılandırabilirsin.

Güvenlik & Doğrulama

Gelen istekleri X-JubbioBots-Signature header'ıyla doğrula. İmza = HMAC-SHA256(secret, raw_body) (hex).

Payload

http

POST https://senin-webhooku.com/vote
Content-Type: application/json
X-JubbioBots-Signature: a83fcd...

json

{
  "bot":  "10000000000000001",
  "user": "2387192837419823",
  "type": "upvote",
  "time": "2026-04-18T15:54:00.000Z"
}

Payload Alanları

Alan / Key	Tip	Açıklama
bot	string	Oy verilen botun Jubbio ID'si.
user	string	Oyu veren kullanıcının Jubbio ID'si.
type	string	Şu an yalnızca "upvote".
time	string (ISO 8601)	Oyun verildiği zaman.

İmza Doğrulama Örneği

javascript

import crypto from "crypto";

app.post("/vote", express.json({ verify: (req, _, buf) => req.rawBody = buf }), (req, res) => {
  const signature = req.header("X-JubbioBots-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest("hex");

  if (signature !== expected) return res.status(401).send("invalid signature");

  const { bot, user, type } = req.body;
  console.log(`${user} voted for ${bot}`);
  res.sendStatus(200);
});

Kritik Timeout Süresi

Webhook'unun 10 saniye içinde 2xx statü dönmesi beklenir. Aksi halde teslimat başarısız sayılır (şu an otomatik yeniden deneme yok).

Jubbio API Referansı

Jubbio Guild Webhook'ları

Botun, Jubbio sunucularındaki kanallara otomatik mesaj göndermek için Jubbio Webhook API'sini kullanabilir. GitHub, Slack, özel uygulamalar gibi harici servislerden kanallara mesaj iletmek için idealdir. Bu bölüm, Jubbio platformunun sunduğu endpoint'lerin hızlı referansıdır — JubbioBots'a değil, doğrudan Jubbio gateway'e gider.

Gateway & Base URL

Tüm istekler https://gateway.jubbio.com/api/v1 tabanı üzerinden yapılır. Bearer token için kullanıcı OAuth2 access token'ı, Bot endpoint'leri için Authorization: Bot <bot_token> kullanılır.

Genel Sınırlar

Guild limiti

15 webhook

Bir guild'de en fazla 15 webhook oluşturulabilir.

Kanal tipleri

text · announcement · forum

Yalnızca bu üç kanal tipinde webhook açılabilir.

Rate limit

60 istek / webhook

Her webhook token'ı için dakikada 60 istek (otomatik düşer).

Avatar boyutu

max 5 MB

jpg, jpeg, png, webp desteklenir.

Token yapısı

256-bit base64

Webhook oluşturulduğunda üretilir; kaybedersen sıfırlanamaz.

İsimlendirme

Otomatik atanır

Oluşturma sırasında gönderilmezse rastgele eğlenceli bir isim verilir.

1. Webhook Oluştur

POST/guilds/{guildId}/channels/{channelId}/webhooks

MANAGE_WEBHOOKS veya ADMINISTRATOR iznine sahip kullanıcılar webhook oluşturabilir. Body göndermek zorunlu değildir — isim otomatik atanır.

Örnek Yanıt (201 Created)

json

{
  "id": "554114951992586240",
  "guild_id": "540528238699487232",
  "channel_id": "545980009056055296",
  "name": "Captain Hook",
  "avatar_url": null,
  "token": "WBTUYkSzHiKQNzXm_cBkNf95DlPYzpXnstvWM50mIx4",
  "created_by": 2,
  "is_active": true,
  "last_used_at": null,
  "rate_limit_remaining": 60
}

Olası Hatalar

Alan / Key	Tip	Açıklama
201	Created	Webhook başarıyla oluşturuldu.
400	Bad Request	Geçersiz kanal tipi (sadece text, announcement, forum).
403	Forbidden	Yetersiz izin veya guild webhook limiti (15) aşıldı.

2. Webhook'ları Listele

İki farklı endpoint aynı formatta webhook array'i döner:

GET/guilds/{guildId}/channels/{channelId}/webhooks

Belirtilen kanaldaki tüm webhook'ları listeler.

GET/guilds/{guildId}/webhooks

Guild'deki tüm webhook'ları listeler.

3. Webhook Güncelle

PATCH/guild-webhooks/{webhookId}

Webhook adını, avatarını veya kanalını günceller. Hem application/json hem multipart/form-data desteklenir. Tüm alanlar opsiyoneldir.

JSON Body

json

{
  "name": "Yeni İsim",
  "avatar_url": "https://cdn.example.com/avatar.png",
  "channel_id": "545980009056055297"
}

Avatar Temizliği

avatar_url boş string ("") gönderilirse avatar silinir ve CDN'deki dosya temizlenir.

Form-Data Alanları

Alan / Key	Tip	Açıklama
name	string	Yeni webhook adı (1–80 karakter).
avatar	file	Avatar dosyası — max 5 MB (jpg, jpeg, png, webp).
avatar_url	string	Boş string ("") gönderilirse avatar silinir.
channel_id	string	Webhook'u taşımak istediğin kanal ID'si.

4. Webhook Sil

DELETE/guild-webhooks/{webhookId}

Webhook'u kalıcı olarak siler ve işlevsiz bırakır.

Özel Bot Endpoint'leri

Botlar Authorization: Bot <bot_token> header'ı ile aşağıdaki endpoint'leri kullanır. Body formatları standart kullanıcı endpoint'leri ile tamamen aynıdır.

POST/bot/guilds/{guildId}/channels/{channelId}/webhooks

Bot olarak yeni webhook oluşturur. name opsiyoneldir.

GET/bot/guilds/{guildId}/channels/{channelId}/webhooks

Kanaldaki webhook'ları listeler.

GET/bot/guilds/{guildId}/webhooks

Guild'deki tüm webhook'ları listeler.

PATCH/bot/guilds/{guildId}/webhooks/{webhookId}

Webhook günceller (body aynı PATCH formatı).

DELETE/bot/guilds/{guildId}/webhooks/{webhookId}

Webhook'u kalıcı olarak siler.

Bu API JubbioBots'a ait değildir

Bu bölüm Jubbio platformunun resmi webhook API'sini referans olarak özetler. Resmi ve güncel doküman için Jubbio developer portalını takip et — endpoint'ler veya limitler zamanla değişebilir.

Kullanıcı Girişi

Jubbio OAuth2

Sitemizdeki kullanıcı girişi tamamen Jubbio OAuth2 + PKCE üzerinden yapılır. Kendi uygulamanda da aynı akışı kullanmak istersen:

Authorize: https://jubbio.com/oauth2/authorize
Token: https://gateway.jubbio.com/api/v1/oauth2/token
Userinfo: https://gateway.jubbio.com/api/v1/oauth2/users/@me

Hızlı SDK Çözümü

Jubbio resmi SDK'sını kullanabilirsin: npm i @jubbio/auth (browser) veya @jubbio/auth-react (React).

javascript

import { JubbioAuth } from "@jubbio/auth";

const auth = new JubbioAuth({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: window.location.origin + "/callback",
  scopes: ["identify", "guilds"],
});

await auth.login();

Rate Limits

Limitler & Kurallar

Oy Bekleme Süresi

12 Saat

Aynı kullanıcı aynı bota 12 saatte bir oy verebilir.

API İstekleri

60 / DK

API token başına dakikada 60 istek hakkı.

Webhook Timeout

10 Saniye

Yanıt bu sürede 2xx dönmeli, aksi taktirde yanar.

Kötüye Kullanım / Ban

Oy sistemini manipüle etmeye çalışan botlar / hesaplar kalıcı olarak yasaklanır. Yapay oylama, self-bot veya proxy döngüleri tespit edildiğinde hem bot sistemden tamamen kaldırılır hem de hesap kapatılır.

Errors

Hata Kodları

API, standart HTTP statü kodları döner. Hatalı yanıtlarda body şöyle görünür:

json

{ "error": "Invalid token" }

Kod Açıklamaları

Alan / Key	Tip	Açıklama
400	Bad Request	Eksik veya geçersiz parametre gönderdin.
401	Unauthorized	Token eksik veya geçersiz.
403	Forbidden	Bu kaynağa erişim yetkin yok.
404	Not Found	Kaynak bulunamadı.
429	Too Many Requests	Rate limit veya oy bekleme süresi aktif.
500	Server Error	Sunucu hatası. Bizi Discord'dan darlayın.

Changelog

Değişiklikler

2026-06-15v1.1
Public bot info endpoint eklendi, /voted üzerinden oy kontrolü sağlandı, stats response'a ratings ortalaması dahil edildi. Ayrıca tüm endpoint'ler artık botId veya iç cuid ile hibrit çalışabiliyor.
2026-04-18v1.0
Sistem canlıya alındı. İlk sürüm: stats endpoint, oy webhook'ları ve HMAC imzalı payload onayı.

Yükleniyor...

Alan / Key

Tip

Açıklama

id*

string

Botun Jubbio ID'si veya iç cuid'i.

{ "id": "cmn9xabcdefghk3z", "botId": "10000000000000001", "name": "ModGuard", "avatar": "https://cdn.jubbio.com/avatars/...", "shortDesc": "Gelişmiş moderasyon ve otomatik anti-raid botu.", "prefix": "!", "website": "https://modguard.app", "inviteUrl": "https://jubbio.com/oauth2/authorize?...", "supportServer": "https://jubbio.gg/modguard", "githubUrl": null, "verified": true, "featured": true, "views": 15839, "votes": 1248, "favorites": 321, "comments": 42, "ratings": { "count": 86, "average": 4.7 }, "categories": [{ "slug": "moderation", "name": "Moderasyon" }], "tags": [{ "slug": "anti-raid", "name": "Anti-raid" }], "owner": { "id": "cmo4i...", "username": "rendel", "displayName": "Rendel", "avatar": "https://cdn.jubbio.com/avatars/..." }, "url": "https://jubbiobots.com/bot/10000000000000001" }

{ "id": "cmn9xabcdefghk3z", "botId": "10000000000000001", "name": "ModGuard", "status": "approved", "featured": true, "verified": true, "views": 15839, "votes": 1248, "favorites": 321, "comments": 42, "ratings": { "count": 86, "average": 4.7 } }

Alan / Key

Tip

Açıklama

string

Bot'un iç JubbioBots cuid'i.

botId

string

Jubbio bot ID'si.

name

string

Bot ismi.

status

string

pending | approved | rejected.

featured

boolean

Editör tarafından öne çıkarılmış mı?

verified

boolean

Doğrulama rozeti.

views

integer

Detay sayfası görüntülenme sayısı.

votes

integer

Toplam oy.

favorites

integer

Favori sayısı.

comments

integer

Yorum sayısı.

ratings.count

integer

Yıldızlı değerlendirme sayısı.

ratings.average

number|null

Yıldız ortalaması (1-5).

Alan / Key

Tip

Açıklama

user*

string

Jubbio kullanıcı ID'si, kullanıcı adı veya iç cuid.

Alan / Key

Tip

Açıklama

bot

string

Oy verilen botun Jubbio ID'si.

user

string

Oyu veren kullanıcının Jubbio ID'si.

type

string

Şu an yalnızca "upvote".

time

string (ISO 8601)

Oyun verildiği zaman.

import crypto from "crypto"; app.post("/vote", express.json({ verify: (req, _, buf) => req.rawBody = buf }), (req, res) => { const signature = req.header("X-JubbioBots-Signature"); const expected = crypto .createHmac("sha256", process.env.WEBHOOK_SECRET) .update(req.rawBody) .digest("hex"); if (signature !== expected) return res.status(401).send("invalid signature"); const { bot, user, type } = req.body; console.log(`${user} voted for ${bot}`); res.sendStatus(200); });

{ "id": "554114951992586240", "guild_id": "540528238699487232", "channel_id": "545980009056055296", "name": "Captain Hook", "avatar_url": null, "token": "WBTUYkSzHiKQNzXm_cBkNf95DlPYzpXnstvWM50mIx4", "created_by": 2, "is_active": true, "last_used_at": null, "rate_limit_remaining": 60 }

Alan / Key

Tip

Açıklama

201

Created

Webhook başarıyla oluşturuldu.

400

Bad Request

Geçersiz kanal tipi (sadece text, announcement, forum).

403

Forbidden

Yetersiz izin veya guild webhook limiti (15) aşıldı.

Alan / Key

Tip

Açıklama

name

string

Yeni webhook adı (1–80 karakter).

avatar

file

Avatar dosyası — max 5 MB (jpg, jpeg, png, webp).

avatar_url

string

Boş string ("") gönderilirse avatar silinir.

channel_id

string

Webhook'u taşımak istediğin kanal ID'si.

import { JubbioAuth } from "@jubbio/auth"; const auth = new JubbioAuth({ clientId: "YOUR_CLIENT_ID", redirectUri: window.location.origin + "/callback", scopes: ["identify", "guilds"], }); await auth.login();

Alan / Key

Tip

Açıklama

400

Bad Request

Eksik veya geçersiz parametre gönderdin.

401

Unauthorized

Token eksik veya geçersiz.

403

Forbidden

Bu kaynağa erişim yetkin yok.

404

Not Found

Kaynak bulunamadı.

429

Too Many Requests

Rate limit veya oy bekleme süresi aktif.

500

Server Error

Sunucu hatası. Bizi Discord'dan darlayın.