API REST

Semua yang bisa dilakukan di panel adalah panggilan API publik. Panel web, MCP, dan skrip Anda memakai API yang sama.

Dasar

export SAKA_TOKEN="saka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Format galat

Setiap galat memakai bentuk yang sama, sehingga bisa dibaca manusia maupun agent AI:

{
  "galat": {
    "kode": "server-terputus",
    "arti": "Server sedang tidak tersambung ke sakapanel.",
    "langkah": "Pastikan server hidup dan agent berjalan: `systemctl status saka-agent`. Aplikasi di server tetap jalan walau terputus."
  }
}

• kode: tetap, untuk dicocokkan program.
• arti: penjelasan singkat.
• langkah: apa yang sebaiknya dilakukan (boleh kosong).
• detail: pesan teknis mentah dari server, bila ada.

Contoh kode yang sering muncul: belum-masuk (401), server-tidak-ada (404), server-terputus (409), perlu-konfirmasi (400), batas-server (403), isian-rusak (400), agent-sedang-diperbarui.

Bahasa jawaban

Panel tersedia dalam bahasa Inggris (bawaan) dan Indonesia, dan API mengikuti header Accept-Language. Dengan Accept-Language: en, teks untuk manusia (arti, langkah, langkah kemajuan tugas, dan catatan) dikirim dalam bahasa Inggris. Tanpa header, atau dengan id, jawabannya berbahasa Indonesia. Yang tidak pernah berubah: kode galat, nama kolom JSON, dan nilai seperti keadaan, jadi program Anda cukup mencocokkan kode. MCP dan pesan Telegram tetap berbahasa Indonesia.

curl -s https://app.saka.work/api/v1/server/<id-server> \
  -H "Authorization: Bearer $SAKA_TOKEN" \
  -H "Accept-Language: en"

Tugas yang berjalan lama

Aksi di server dikirim sebagai tugas. Bila selesai cepat, jawabannya langsung berisi hasil. Bila belum, jawabannya 202 berisi tugas dan catatan cara memantaunya. Pantau dengan GET /tugas/{id} sampai keadaan menjadi selesai atau gagal. Pembuatan klaster database, load balancer, dan situs dipantau lewat GET /database/{id}, GET /lb/{id}, dan GET /situs/{id} (keadaan: dibuat, siap, atau gagal).

Endpoint utama

Semua jalur di bawah relatif terhadap /api/v1.

Aksi yang menghapus atau mengganti isi (aplikasi, klaster, load balancer, situs, pulihkan situs, memindahkan situs sekarang, Lepas server) menolak permintaan dengan kode perlu-konfirmasi sampai isian konfirmasi berisi nama sumber daya. Tunjukkan dulu ke pengguna apa yang akan dihapus.

Contoh curl

Daftar server

curl -s https://app.saka.work/api/v1/server \
  -H "Authorization: Bearer $SAKA_TOKEN"

Jawaban berisi server: tiap server punya id (misalnya srv_…), nama, ip, os, terhubung, dan status (CPU, RAM, disk, aplikasi, kesiapan).

Buat klaster database

curl -s -X POST https://app.saka.work/api/v1/database \
  -H "Authorization: Bearer $SAKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mesin": "postgresql",
    "nama": "toko-produksi",
    "mode": "sinkron",
    "data": ["srv_aaaaaaaaaaaaaaaa", "srv_bbbbbbbbbbbbbbbb"],
    "saksi": "srv_cccccccccccccccc"
  }'

mesin: postgresql (bawaan) atau mariadb. mode: asinkron (bawaan) atau sinkron; MariaDB selalu sinkron. Jawaban 202 berisi klaster dengan keadaan: "dibuat". Pantau:

curl -s https://app.saka.work/api/v1/database/<id-klaster> \
  -H "Authorization: Bearer $SAKA_TOKEN"

Buat load balancer

curl -s -X POST https://app.saka.work/api/v1/lb \
  -H "Authorization: Bearer $SAKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nama": "toko-lb",
    "mode": "proxy",
    "domain": ["toko.contoh.id"],
    "penyeimbang": ["srv_1111111111111111", "srv_2222222222222222"],
    "tujuan": ["srv_3333333333333333", "srv_4444444444444444"],
    "cadangan": [],
    "port_tujuan": 8080,
    "kebijakan": "bergiliran",
    "sticky": false,
    "path_sehat": "/"
  }'

mode: proxy (bawaan) atau dns (tanpa domain). kebijakan: bergiliran atau koneksi_tersedikit. port_tujuan bawaan 80. Penyeimbang 1 atau 2 server. Opsional untuk mode proxy: izinkan dan tolak, daftar IP/CIDR untuk firewall.

Jalankan perbaikan lalu pantau tugas

curl -s -X POST https://app.saka.work/api/v1/server/<id-server>/perbaiki \
  -H "Authorization: Bearer $SAKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jenis": "swap"}'

curl -s https://app.saka.work/api/v1/tugas/<id-tugas> \
  -H "Authorization: Bearer $SAKA_TOKEN"

Jawaban berisi tugas (id, perintah, keadaan: antre, berjalan, selesai, atau gagal, lewat: panel, api, atau mcp), kemajuan (langkah yang sedang dikerjakan), dan hasil bila sudah selesai.