Haurin
Masuk

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.

  • 400 Body tidak valid: template tidak ditemukan (TEMPLATE_NOT_FOUND), mode tidak valid (INVALID_MODE), snapshot tidak valid (INVALID_SNAPSHOT, disertai daftar errors), format setup key salah (INVALID_SETUP_KEY), atau request lain yang tidak valid (INVALID_REQUEST, INVALID_JSON).
  • 401 Header x-api-key tidak ada atau key tidak valid (INVALID_API_KEY). Route internal yang butuh login menjawab 401 dengan code UNAUTHORIZED.
  • 403 Bukan admin (FORBIDDEN), hanya untuk route admin.
  • 404 Setup key tidak ditemukan (SETUP_NOT_FOUND) atau template tidak ditemukan (TEMPLATE_NOT_FOUND).
  • 413 Body request lebih dari 256 KiB (BODY_TOO_LARGE). Batas ini diperiksa sebelum body dibaca.
  • 429 Rate limit terlampaui (RATE_LIMITED). Selalu disertai header Retry-After: 60 dan X-RateLimit-Remaining.
  • 503 Layanan belum tersedia, dengan code yang membedakan penyebabnya: MIGRATION_MISSING bila migrasi database belum diterapkan, UPSTREAM_UNAVAILABLE bila database tidak terjangkau, dan WRITE_FAILED bila 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/health kini 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>"