API REST
Semua yang bisa dilakukan di panel adalah panggilan API publik. Panel web, MCP, dan skrip Anda memakai API yang sama.
Dasar
| Hal | Nilai |
|---|---|
| Basis URL | https://app.saka.work/api/v1 |
| Autentikasi | Authorization: Bearer saka_… (buat di Pengaturan, lihat Buat token) |
| Format | JSON. Kirim Content-Type: application/json untuk permintaan yang mengubah. |
| Isian | Kolom yang tidak dikenal ditolak, agar salah ketik tidak diam-diam diabaikan. |
| Bahasa | Accept-Language: id (bawaan) atau en untuk teks galat, langkah kemajuan, dan catatan. Lihat Bahasa jawaban. |
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.
| Kelompok | Metode | Jalur | Keterangan |
|---|---|---|---|
| Akun | GET | /akun | Profil akun dan status Telegram. |
GET | /token | Daftar token API. | |
POST | /token | Buat 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/peran | Peran bawaan, peran khusus, dan daftar izin (pemilik dan admin tim). | |
POST | /tim/peran | Buat 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/tautan | Tautan untuk menghubungkan Telegram (30 menit). | |
DELETE | /telegram | Putuskan Telegram. | |
| Server | GET | /server | Daftar server beserta status terakhir. |
POST | /server | Buat perintah pasang. Isian {"nama"}. | |
GET | /server/{id} | Detail satu server. | |
PATCH | /server/{id} | Ganti nama. Isian {"nama"}. | |
GET | /server/{id}/metrik?jam=24 | Riwayat metrik dari server (maks. 720 jam). | |
GET | /server/{id}/tugas | 50 tugas terakhir di server ini. | |
POST | /server/{id}/perbaiki | Isian {"jenis": "swap" | "firewall-cek" | "firewall", "port": ["80/tcp"]}. | |
GET | /server/{id}/lepas | Rencana Lepas server: apa saja yang akan dihapus. | |
DELETE | /server/{id} | Lepas server. Isian {"konfirmasi": "<nama server>", "simpan_cadangan": true}. | |
| Aplikasi | GET | /resep | Katalog aplikasi siap pasang (tanpa login). |
POST | /server/{id}/aplikasi | Pasang aplikasi. Isian {"resep", "nama", "variabel"}. | |
POST | /server/{id}/aplikasi/{nama}/mulai-ulang | Mulai ulang aplikasi. | |
GET | /server/{id}/aplikasi/{nama}/log?baris=100 | Log terakhir aplikasi. | |
POST | /server/{id}/aplikasi/{nama}/aksi | Aksi kelola, misalnya {"aksi": "akses.daftar"}. | |
DELETE | /server/{id}/aplikasi/{nama} | Hapus aplikasi. Isian {"konfirmasi": "<nama aplikasi>"}. | |
| Database | GET | /database | Daftar klaster. |
POST | /database | Buat klaster. Isian {"mesin", "nama", "mode", "data": [id, id], "saksi": id}. | |
GET | /database/{id} | Detail, status anggota, dan alamat sambungan. | |
POST | /database/{id}/sandi | Baca sandi langsung dari server data. | |
POST | /database/{id}/proxy | Sambungkan 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 balancer | GET | /lb | Daftar load balancer. |
POST | /lb | Buat 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>"}. | |
| Situs | GET | /situs | Daftar situs (bisa disaring ?server_id=). |
POST | /situs | Buat 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}/rahasia | Baca sandi database, SFTP, dan admin WordPress langsung dari server. | |
POST | /situs/{id}/cadangan | Cadangkan sekarang. | |
POST | /situs/{id}/pulihkan | Pulihkan. Isian {"berkas": "<nama cadangan>", "konfirmasi": "<nama situs>"}. | |
POST | /situs/{id}/phpmyadmin | Nyalakan phpMyAdmin situs. Jawaban {"url"}, tautan masuk sekali pakai (60 detik). | |
POST | /situs/{id}/pindah | Pindah 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/sekarang | Pindahkan sekarang (situs lama pemeliharaan sebentar). Isian {"konfirmasi": "<nama situs>"}. | |
POST | /situs/{id}/pindah/selesai | Selesaikan: hapus situs di server lama (cadangan terakhir disimpan di /root). | |
POST | /situs/{id}/pindah/batal | Batalkan pemindahan; situs tetap atau kembali di server lama. | |
| Permintaan fitur | GET | /fitur | Daftar usulan fitur beserta status, balasan, jumlah suara, dan apakah Anda sudah mendukungnya. |
POST | /fitur | Usulkan fitur. Isian {"judul", "isi", "kategori"}; judul 5 sampai 120 karakter, paling banyak 10 usulan per 24 jam. | |
POST | /fitur/{id}/suara | Dukung usulan, atau batalkan dukungan bila sudah. | |
| Enterprise | POST | /enterprise | Minta bantuan migrasi (tanpa token). Isian {"nama", "kontak", "asal", "skala", "kebutuhan"}; kontak wajib, asal: aws, gcp, azure, cpanel, vps, atau lain. |
| Tugas & peringatan | GET | /tugas/{id} | Keadaan tugas, kemajuan, dan hasilnya. |
GET | /peringatan?aktif=1 | Peringatan (aktif saja bila aktif=1). | |
| Akun | POST | /akun/verifikasi/kirim | Kirim ulang kode verifikasi email (3 kali per jam). |
POST | /akun/verifikasi/kode | Isi {"kode"} 6 angka. Sesi panel dengan email belum terverifikasi hanya bisa memakai jalur akun. | |
POST | /akun/lupa | Kirim tautan atur ulang sandi ke {"email"}. | |
POST | /akun/reset | {"token", "sandi"}; semua sesi lama keluar. | |
| Tunnel | GET | /tunnel | Daftar alamat <nama>-app.hack.id. |
POST | /tunnel | {"nama", "server_id", "situs_id" atau "port", "utama"}. | |
DELETE | /tunnel/{id} | Dengan {"konfirmasi": "<nama>"}. | |
| Aplikasi luar | POST | /server/{id}/ambil-alih | Ambil alih Hermes yang dipasang di luar Saka: {"resep", "cara", "nama"} dari status.luar server. Berjalan sebagai tugas. |
| Aplikasi Git | POST | /situs/{id}/deploy | Deploy 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}/webhook | Payload URL dan secret untuk deploy saat push. | |
| Katalog | GET | /katalog | Daftar aplikasi siap pakai. Pasang dengan POST /situs {"jenis": "katalog", "katalog": "n8n", ...}. |
POST | /situs/{id}/perbarui-aplikasi | Perbarui ke versi terbaru (cadangan dulu, kembali otomatis bila gagal). Variabel lewat /situs/{id}/env. | |
| Kesiapan | GET | /kesiapan | Ringkasan siap-bila-satu-server-mati: replika, cadangan, uji pulih, TTL DNS, standby, peringatan. |
POST | /jaringan/periksa | Pra-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 | /persetujuan | Keadaan persetujuan Telegram untuk tindakan berisiko. | |
PUT | /persetujuan | Isian {"aktif": true}. Butuh Telegram yang tertaut. | |
| Database (lanjutan) | POST | /database/{id}/node | Tambah server data sebagai replika. Isian {"server_id"}. |
DELETE | /database/{id}/node/{sid} | Lepas replika. ?paksa=1 untuk server yang sudah mati. | |
POST | /database/{id}/utama | Jadikan utama. Isian {"node"}. | |
POST | /database/{id}/mode | Ganti mode replikasi sinkron atau asinkron. | |
POST | /database/{id}/akses | Izinkan atau cabut alamat IP ke port database. | |
POST | /database/{id}/cadangan/verifikasi | Uji pulih sekarang (di latar belakang). | |
POST | /database/{id}/impor | Salin database lama. Tambahkan layanan dan cek_url untuk pindah terpandu dengan rollback. | |
| Pengalihan DNS | POST | /dns-failover/{id}/alihkan | Isian {"ke": "cadangan" | "utama"}. |
POST | /dns-failover/{id}/gladi | Gladi 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 -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.