Dokumentasi / API REST

API REST

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

Dasar

HalNilai
Basis URLhttps://app.saka.work/api/v1
AutentikasiAuthorization: Bearer saka_… (buat di Pengaturan, lihat Buat token)
FormatJSON. Kirim Content-Type: application/json untuk permintaan yang mengubah.
IsianKolom yang tidak dikenal ditolak, agar salah ketik tidak diam-diam diabaikan.
BahasaAccept-Language: id (bawaan) atau en untuk teks galat, langkah kemajuan, dan catatan. Lihat Bahasa jawaban.
Terminal
export SAKA_TOKEN="saka_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Format galat

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

JSON
{
  "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."
  }
}

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
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.

KelompokMetodeJalurKeterangan
AkunGET/akunProfil akun dan status Telegram.
GET/tokenDaftar token API.
POST/tokenBuat token. Isian {"nama", "hak": "penuh" | "baca", "izin": ["situs", "server", "database", "kubernetes", "jaringan", "pantau", "hapus"]}; izin membuat token berizin (menggantikan hak). Rahasia hanya ditampilkan sekali.
DELETE/token/{id}Cabut token.
GET/tim/peranPeran bawaan, peran khusus, dan daftar izin (pemilik dan admin tim).
POST/tim/peranBuat peran khusus. Isian {"nama", "izin": [..]}; maksimal 10 per akun, izin tim tidak ada.
PUT/tim/peran/{kode}Ubah nama dan izin; berlaku langsung bagi anggotanya.
DELETE/tim/peran/{kode}Hapus. Ditolak (409) selama masih dipakai anggota atau undangan. Pakai kode peran khusus di isian peran pada POST /tim/undang.
POST/telegram/tautanTautan untuk menghubungkan Telegram (30 menit).
DELETE/telegramPutuskan Telegram.
ServerGET/serverDaftar server beserta status terakhir.
POST/serverBuat perintah pasang. Isian {"nama"}.
GET/server/{id}Detail satu server.
PATCH/server/{id}Ganti nama. Isian {"nama"}.
GET/server/{id}/metrik?jam=24Riwayat metrik dari server (maks. 720 jam).
GET/server/{id}/tugas50 tugas terakhir di server ini.
POST/server/{id}/perbaikiIsian {"jenis": "swap" | "firewall-cek" | "firewall", "port": ["80/tcp"]}.
GET/server/{id}/lepasRencana Lepas server: apa saja yang akan dihapus.
DELETE/server/{id}Lepas server. Isian {"konfirmasi": "<nama server>", "simpan_cadangan": true}.
AplikasiGET/resepKatalog aplikasi siap pasang (tanpa login).
POST/server/{id}/aplikasiPasang aplikasi. Isian {"resep", "nama", "variabel"}.
POST/server/{id}/aplikasi/{nama}/mulai-ulangMulai ulang aplikasi.
GET/server/{id}/aplikasi/{nama}/log?baris=100Log terakhir aplikasi.
POST/server/{id}/aplikasi/{nama}/aksiAksi kelola, misalnya {"aksi": "akses.daftar"}.
DELETE/server/{id}/aplikasi/{nama}Hapus aplikasi. Isian {"konfirmasi": "<nama aplikasi>"}.
DatabaseGET/databaseDaftar klaster.
POST/databaseBuat klaster. Isian {"mesin", "nama", "mode", "data": [id, id], "saksi": id}.
GET/database/{id}Detail, status anggota, dan alamat sambungan.
POST/database/{id}/sandiBaca sandi langsung dari server data.
POST/database/{id}/proxySambungkan server aplikasi. Isian {"server_id"}.
DELETE/database/{id}/proxy/{server}Lepas proxy dari satu server aplikasi.
DELETE/database/{id}Hapus klaster. Isian {"konfirmasi": "<nama klaster>"}.
Load balancerGET/lbDaftar load balancer.
POST/lbBuat load balancer.
GET/lb/{id}Detail dan kesehatan tujuan dari tiap penyeimbang.
PATCH/lb/{id}Ubah firewall (mode proxy). Isian {"izinkan": ["IP/CIDR"], "tolak": ["IP/CIDR"]}. Lihat Firewall.
DELETE/lb/{id}Hapus. Isian {"konfirmasi": "<nama lb>"}.
SitusGET/situsDaftar situs (bisa disaring ?server_id=).
POST/situsBuat situs. Isian {"nama", "server_id", "jenis", "domain", "php", "bahasa", "db", "klaster_id", "sumber", "cpanel"}; cpanel berisi {"host", "pengguna", "sandi" atau "token", "abaikan_tls"} untuk masuk ke cPanel lama. Lihat Situs.
GET/situs/{id}Detail dan status: DNS, HTTPS, cadangan, SFTP tanpa sandi.
PATCH/situs/{id}Ubah nama, domain, versi PHP, atau pengaturan PHP. Isian {"nama", "domain", "php", "php_ini"}; php_ini: {"unggah_mb", "memori_mb", "waktu_detik", "input_vars", "zona_waktu", "tampil_galat"}.
DELETE/situs/{id}Hapus. Isian {"konfirmasi": "<nama situs>", "simpan_cadangan": true}.
POST/situs/{id}/rahasiaBaca sandi database, SFTP, dan admin WordPress langsung dari server.
POST/situs/{id}/cadanganCadangkan sekarang.
POST/situs/{id}/pulihkanPulihkan. Isian {"berkas": "<nama cadangan>", "konfirmasi": "<nama situs>"}.
POST/situs/{id}/phpmyadminNyalakan phpMyAdmin situs. Jawaban {"url"}, tautan masuk sekali pakai (60 detik).
POST/situs/{id}/pindahPindah ke server lain, langkah salin. Isian {"server_id", "php", "perbarui_wp"}. Pantau pindah.keadaan di GET /situs/{id}: menyalin, disalin, memindah, dipindah.
POST/situs/{id}/pindah/sekarangPindahkan sekarang (situs lama pemeliharaan sebentar). Isian {"konfirmasi": "<nama situs>"}.
POST/situs/{id}/pindah/selesaiSelesaikan: hapus situs di server lama (cadangan terakhir disimpan di /root).
POST/situs/{id}/pindah/batalBatalkan pemindahan; situs tetap atau kembali di server lama.
Permintaan fiturGET/fiturDaftar usulan fitur beserta status, balasan, jumlah suara, dan apakah Anda sudah mendukungnya.
POST/fiturUsulkan fitur. Isian {"judul", "isi", "kategori"}; judul 5 sampai 120 karakter, paling banyak 10 usulan per 24 jam.
POST/fitur/{id}/suaraDukung usulan, atau batalkan dukungan bila sudah.
EnterprisePOST/enterpriseMinta bantuan migrasi (tanpa token). Isian {"nama", "kontak", "asal", "skala", "kebutuhan"}; kontak wajib, asal: aws, gcp, azure, cpanel, vps, atau lain.
Tugas & peringatanGET/tugas/{id}Keadaan tugas, kemajuan, dan hasilnya.
GET/peringatan?aktif=1Peringatan (aktif saja bila aktif=1).
AkunPOST/akun/verifikasi/kirimKirim ulang kode verifikasi email (3 kali per jam).
POST/akun/verifikasi/kodeIsi {"kode"} 6 angka. Sesi panel dengan email belum terverifikasi hanya bisa memakai jalur akun.
POST/akun/lupaKirim tautan atur ulang sandi ke {"email"}.
POST/akun/reset{"token", "sandi"}; semua sesi lama keluar.
TunnelGET/tunnelDaftar alamat <nama>-app.hack.id.
POST/tunnel{"nama", "server_id", "situs_id" atau "port", "utama"}.
DELETE/tunnel/{id}Dengan {"konfirmasi": "<nama>"}.
Aplikasi luarPOST/server/{id}/ambil-alihAmbil alih Hermes yang dipasang di luar Saka: {"resep", "cara", "nama"} dari status.luar server. Berjalan sebagai tugas.
Aplikasi GitPOST/situs/{id}/deployDeploy commit terbaru dari cabangnya (tugas berjalan). Situs dibuat dengan jenis: "git" dan git: {"repo", "cabang", "subfolder", "port", "path_sehat", "perintah_build", "perintah_start"}.
POST/situs/{id}/rollback{"commit"}: tag rilis atau awalan hash commit.
POST/situs/{id}/env{"env": {"NAMA": "nilai"}}; nilai kosong menghapus.
GET/situs/{id}/webhookPayload URL dan secret untuk deploy saat push.
KatalogGET/katalogDaftar aplikasi siap pakai. Pasang dengan POST /situs {"jenis": "katalog", "katalog": "n8n", ...}.
POST/situs/{id}/perbarui-aplikasiPerbarui ke versi terbaru (cadangan dulu, kembali otomatis bila gagal). Variabel lewat /situs/{id}/env.
KesiapanGET/kesiapanRingkasan siap-bila-satu-server-mati: replika, cadangan, uji pulih, TTL DNS, standby, peringatan.
POST/jaringan/periksaPra-periksa server dan UDP/TCP antar server. Isian {"server_ids": [..]}; hasilnya {id}.
GET/jaringan/periksa/{id}Baca hasil pra-periksa jaringan sampai selesai bernilai true.
GET/persetujuanKeadaan persetujuan Telegram untuk tindakan berisiko.
PUT/persetujuanIsian {"aktif": true}. Butuh Telegram yang tertaut.
Database (lanjutan)POST/database/{id}/nodeTambah server data sebagai replika. Isian {"server_id"}.
DELETE/database/{id}/node/{sid}Lepas replika. ?paksa=1 untuk server yang sudah mati.
POST/database/{id}/utamaJadikan utama. Isian {"node"}.
POST/database/{id}/modeGanti mode replikasi sinkron atau asinkron.
POST/database/{id}/aksesIzinkan atau cabut alamat IP ke port database.
POST/database/{id}/cadangan/verifikasiUji pulih sekarang (di latar belakang).
POST/database/{id}/imporSalin database lama. Tambahkan layanan dan cek_url untuk pindah terpandu dengan rollback.
Pengalihan DNSPOST/dns-failover/{id}/alihkanIsian {"ke": "cadangan" | "utama"}.
POST/dns-failover/{id}/gladiGladi pengalihan. Isian {"tahan_detik", "cek_jalur"}; hasilnya dikirim ke Telegram.

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

Buat load balancer

curl
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
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
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.