Dokumentasi API
API publik v1 untuk memakai Haurin dari aplikasi sendiri: ambil daftar template, buat setup key, dan cek status setup key. Semua response API v1 memakai format yang sama. Spesifikasi lengkap tersedia sebagai OpenAPI (openapi.json). Handler internal yang dipakai web sendiri didokumentasikan terpisah di dokumentasi API internal.
Autentikasi
Setiap request wajib membawa header x-api-key berisi API key kamu. Buat key di halaman API key. Key berbentuk dsk_ diikuti 32 karakter hex, dan hanya tampil sekali sesudah dibuat. Simpan di tempat yang aman. Kalau key bocor atau hilang, cabut dan buat yang baru. Satu akun maksimal 5 API key.
curl https://api.serverkit.atlys.ai.id/api/v1/templates \ -H "x-api-key: dsk_0123456789abcdef0123456789abcdef"
Ganti nilai key di atas dengan API key kamu.
Rate limit
Setiap API key dibatasi 100 request per jam. Selain itu ada batas per alamat IP yang berlaku untuk semua pemakai dari IP yang sama, jadi 429 bisa muncul dari bucket IP walau key kamu masih punya jatah. Buat setup key dibatasi 20 request per 10 menit per IP. Verifikasi key dibatasi 100 percobaan per 10 menit per IP, bersama untuk semua route v1, supaya satu IP tidak bisa memutar tiga route untuk tiga kali jatah. Daftar template dan cek setup key dibatasi 100 request per 10 menit per IP. Kalau batas terlampaui, server menjawab 429 dengan bentuk yang selalu sama di semua route, lengkap dengan header Retry-After: 60 dan X-RateLimit-Remaining. Tunggu 60 detik lalu coba lagi. Pemakaian terakhir tiap key tercatat dan terlihat di halaman API key.
Format response
Semua endpoint API v1 mengembalikan JSON dengan amplop yang sama. Berhasil berarti ok: true dan data di data. Gagal berarti ok: false, pesan di error, dan kode mesin di code. Amplop error ini berlaku untuk SEMUA error di semua route, termasuk route internal. Yang tidak seragam adalah bentuk sukses route internal: 8 kelompok pengecualian mempertahankan bentuk sukses mentahnya karena konsumen di aplikasi membaca field langsung, dan /api/health sengaja tanpa field ok supaya monitor eksternal tetap jalan. Daftar lengkap pengecualian itu ada di dokumentasi API internal. Setiap response, sukses maupun gagal, membawa header x-request-id berisi ID unik per request. Sertakan ID itu saat melapor masalah supaya jejaknya bisa dilacak di log.
{ "ok": true, "data": { "...": "..." } }
{ "ok": false, "error": "API key tidak valid.", "code": "INVALID_API_KEY" }Daftar template
GET /api/v1/templates mengembalikan ringkasan template: jumlah role, kategori, dan channel, bukan snapshot penuh. Parameter ?q= mencari di nama, tagline, dan tag. Parameter ?tag= menyaring satu tag.
curl "https://api.serverkit.atlys.ai.id/api/v1/templates?q=komunitas" \ -H "x-api-key: dsk_0123456789abcdef0123456789abcdef"
{
"ok": true,
"data": [
{
"id": "komunitas-umum",
"name": "Komunitas Umum",
"tagline": "Struktur aman dan rapi untuk komunitas apa pun, lengkap dengan verifikasi dan tiket.",
"tags": ["community", "umum", "starter"],
"roles": 4,
"categories": 5,
"channels": 15,
"features": {
"welcome": true,
"goodbye": true,
"verify": true,
"ticket": true,
"modlog": true
}
}
]
}Buat setup key
POST /api/v1/setups membuat setup key dari template yang sudah ada atau dari snapshot custom. Isi body dengan template_id atau snapshot. Snapshot divalidasi seperti di editor: nama wajib ada, nama channel text wajib lowercase tanpa spasi, nama channel tidak boleh duplikat, izin role hanya admin, moderator, atau member (nilai lain, termasuk angka bitfield Discord seperti "8", ditolak), dan maksimal 500 channel sesuai batas Discord. Setup key dicatat atas nama pemilik API key. Response selalu menyertakan mode yang dipakai setup itu dan publish_status. Body request maksimal 256 KiB; lebih dari itu dijawab 413.
curl -X POST https://api.serverkit.atlys.ai.id/api/v1/setups \
-H "x-api-key: dsk_0123456789abcdef0123456789abcdef" \
-H "Content-Type: application/json" \
-d '{ "template_id": "komunitas-umum" }'{
"ok": true,
"data": {
"key": "0123456789abcdef0123456789abcdef",
"command": "!setup 0123456789abcdef0123456789abcdef",
"mode": "title",
"publish_status": "not-published"
}
}Jalankan perintah itu di server Discord sebagai pemilik server, sama seperti setup key dari editor. Nilai publish_status bisa queued (masuk antrean persetujuan admin), listed-local (tulis lokal karena antrean database belum live), atau not-published.
Cek setup key
GET /api/v1/setups/:key mengembalikan isi setup key: key, template yang tersimpan, dan waktu pembuatan. Pemilik key tidak dikembalikan. Key yang bukan milikmu menjawab 404 yang sama seperti key yang tidak ada, supaya keberadaan key orang lain tidak bocor.
curl https://api.serverkit.atlys.ai.id/api/v1/setups/0123456789abcdef0123456789abcdef \ -H "x-api-key: dsk_0123456789abcdef0123456789abcdef"
{
"ok": true,
"data": {
"key": "0123456789abcdef0123456789abcdef",
"template": {
"id": "custom-0123456789abcdef0123456789abcdef",
"name": "Server Kecil",
"tagline": "Contoh template custom.",
"tags": [],
"author": "",
"public": false,
"roles": [{ "name": "Admin", "permissions": "admin" }],
"categories": [
{
"name": "Umum",
"visibility": "public",
"channels": [{ "name": "obrolan", "type": "text" }]
}
],
"features": {
"welcome": false,
"goodbye": false,
"verify": false,
"ticket": false,
"modlog": false
}
},
"created_at": "2026-11-06T10:00:00.000Z"
}
}Kode error
Pesan error berbahasa Indonesia dan kata-katanya bisa berubah; yang stabil adalah code. Program kamu sebaiknya bercabang dari code, bukan dari pesan.
400Body tidak valid: template tidak ditemukan (TEMPLATE_NOT_FOUND), mode tidak valid (INVALID_MODE), snapshot tidak valid (INVALID_SNAPSHOT, disertai daftarerrors), format setup key salah (INVALID_SETUP_KEY), atau request lain yang tidak valid (INVALID_REQUEST,INVALID_JSON).401Header x-api-key tidak ada atau key tidak valid (INVALID_API_KEY). Route internal yang butuh login menjawab 401 dengan codeUNAUTHORIZED.403Bukan admin (FORBIDDEN), hanya untuk route admin.404Setup key tidak ditemukan (SETUP_NOT_FOUND) atau template tidak ditemukan (TEMPLATE_NOT_FOUND).413Body request lebih dari 256 KiB (BODY_TOO_LARGE). Batas ini diperiksa sebelum body dibaca.429Rate limit terlampaui (RATE_LIMITED). Selalu disertai headerRetry-After: 60danX-RateLimit-Remaining.503Layanan belum tersedia, dengan code yang membedakan penyebabnya:MIGRATION_MISSINGbila migrasi database belum diterapkan,UPSTREAM_UNAVAILABLEbila database tidak terjangkau, danWRITE_FAILEDbila tulis terverifikasi gagal. Gagal tulis di produksi tidak pernah dijawab sebagai sukses.
Dua catatan soal cache. Hasil pemeriksaan "apakah RPC verifikasi key ada" di-cache 60 detik, jadi sesudah migrasi diterapkan, klasifikasi 401 vs 503 yang baru benar paling lambat 60 detik kemudian. Agregat rating marketplace juga di-cache 60 detik, jadi ulasan baru bisa telat tampil sampai 60 detik.
Changelog API
Perubahan yang memengaruhi pemakai API, terbaru dulu.
v0.34.0
Semua error memakai amplop yang sama (
ok: false, error, code) dengan pesan Indonesia dan kode mesin stabil. 429 seragam di semua route, lengkap dengan header Retry-After 60 dan X-RateLimit-Remaining. 503 dibedakan menjadi MIGRATION_MISSING, UPSTREAM_UNAVAILABLE, dan WRITE_FAILED. Body request dibatasi 256 KiB (413 BODY_TOO_LARGE). Semua response membawa header x-request-id. Validasi setup key diperketat: format salah dijawab 400 INVALID_SETUP_KEY, dan key milik orang lain dijawab 404 tanpa membocorkan keberadaan. Rate limit tulis kini global, bukan per instance, dengan bucket per user untuk yang login./api/healthkini menyertakan version dari package.json. Publish template lewat v1 memakai antrean database (RPC queue_template_publish_by_key), bukan tulis file lokal. Dokumentasi ini diperbaiki: batas channel 500 (sebelumnya tertulis 400), contoh response buat setup key kini menyertakan mode, contoh izin role memakai nilai yang valid, dan klaim amplop seragam diluruskan. Spesifikasi OpenAPI ditambahkan di /openapi.json dan handler internal didokumentasikan di /docs/api-internal.v0.33.0 dan sebelumnya
API v1 diperkenalkan dengan autentikasi x-api-key, daftar template, buat setup key, dan cek setup key. Sebelum v0.34.0, bentuk error belum seragam, 429 belum membawa header yang sama di semua route, dan 503 belum membedakan penyebabnya.
Playground
Coba endpoint di atas tanpa keluar dari halaman ini. Pilih endpoint, isi parameter, tempel API key, lalu kirim.
Playground
Coba API v1 langsung dari browser. Request dikirim nyata ke server dan response ditampilkan apa adanya.
Masuk untuk memakai API key tersimpan. Tanpa masuk, kamu tetap bisa menempel API key secara manual di bawah.
Nilai key tidak tersimpan di server, jadi tempel key yang pernah disalin saat pembuatan.
Perintah curl
curl https://api.serverkit.atlys.ai.id/api/v1/templates -H "x-api-key: <API_KEY>"