API Lokal Aurorium v1

#Mulai cepat

1. Jalankan Aurorium dan masuk ke akun Anda.
2. Buka Otomatisasi → API dan buat kunci API.
3. Segera simpan kunci: backend hanya menampilkannya sekali.
4. Kirim kunci bersama setiap permintaan menggunakan Authorization: Bearer <api_key>.

curl "http://127.0.0.1:50325/api/v1/health" \
  -H "Authorization: Bearer $AURORIUM_API_KEY"

URL dasar:

http://127.0.0.1:50325/api/v1

Server hanya mendengarkan pada 127.0.0.1, bukan pada antarmuka jaringan eksternal. Port tetap yang digunakan saat ini adalah 50325.

#Format respons

Hasil yang berhasil dan kesalahan aplikasi menggunakan pembungkus respons yang sama:

{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "req_0d30b83f3fbb43e6a2e1b255e21d24b8"
}

• code = 0 berarti berhasil.
• code != 0 berarti kesalahan aplikasi; memeriksa status HTTP saja tidak cukup.
• Simpan request_id di log integrasi Anda untuk diagnostik.
• Server biasanya mengembalikan HTTP 200 bahkan saat terjadi kesalahan aplikasi.
• Jika badan JSON melebihi 5 MiB, API mengembalikan code: 1001 dan msg: "request body too large".

Contoh kesalahan:

{
  "code": 1201,
  "msg": "profile not found",
  "data": null,
  "request_id": "req_7f3ab37ea65048f99ebd0fdbe6f4da63"
}

#Parameter umum

Endpoint daftar menerima:

Format data respons daftar:

{
  "list": [],
  "page": 1,
  "page_size": 50,
  "total": 0
}

#Ringkasan endpoint

#Sistem

#GET /health

Mengembalikan kesiapan aplikasi lokal, status koneksi cloud, dan ID perangkat saat ini.

{
  "ready": true,
  "cloud_connected": true,
  "device_id": "device-id-or-null"
}

Autentikasi diperlukan bahkan untuk pemeriksaan kesehatan.

#GET /version

{
  "app_version": "0.3.1",
  "core_version": null,
  "api_version": "v1"
}

core_version belum diimplementasikan dan selalu mengembalikan null.

#Profil

#GET /profile

Parameter kueri:

Item daftar:

{
  "profile_id": "507f1f77bcf86cd799439011",
  "name": "Automation profile",
  "folder_id": null,
  "status": "idle",
  "location": null,
  "os": "windows",
  "os_version": "Windows 11",
  "core": "chrome",
  "core_version": "134",
  "description": "",
  "created_at": "2026-07-24T10:00:00Z",
  "updated_at": "2026-07-24T10:00:00Z"
}

Profil yang diarsipkan tidak dikembalikan. Filter running|idle diterapkan pada klien hanya setelah halaman dimuat, sehingga total dan jumlah item pada halaman mungkin tidak sesuai dengan daftar yang difilter.

#POST /profile

Permintaan minimal:

{
  "name": "Automation profile"
}

Kolom yang didukung:

Contoh dengan proxy:

{
  "name": "Profile with proxy",
  "os": "windows",
  "proxy": {
    "type": "socks5",
    "host": "127.0.0.1",
    "port": 1080,
    "user": "login",
    "password": "secret"
  }
}

Pembuatan profil berlangsung secara asinkron di backend. API Lokal menunggu peristiwa penyelesaian dan biasanya mengembalikan model profil lengkap. Jika pembacaan lanjutan gagal, hanya profile_id yang mungkin dikembalikan.

#GET /profile/:id

Mengembalikan item daftar dengan objek proxy dan fingerprint tambahan. Kata sandi proxy tidak pernah dikembalikan sebagai teks biasa; jika ada, kata sandi diganti dengan ******.

#PATCH /profile/:id

Memperbarui sebagian profil:

{
  "name": "New name",
  "description": "Updated through API",
  "folder_id": null,
  "fingerprint": {
    "timezone_mode": "manual",
    "timezone": "Europe/Moscow"
  }
}

Badan kosong berhasil tanpa melakukan perubahan. Metadata langsung diterapkan. Perubahan sidik jari langsung diterapkan saat profil dihentikan; untuk profil yang berjalan, perubahan ditunda hingga peluncuran berikutnya dan dicantumkan dalam deferred_fields.

{
  "profile_id": "507f1f77bcf86cd799439011",
  "deferred_fields": ["fingerprint.timezone_mode", "fingerprint.timezone"]
}

Untuk profil yang dihentikan, deferred_fields selalu kosong.

#DELETE /profile/:id

Kueri force=true menghentikan profil yang berjalan di perangkat saat ini sebelum penghapusan. Tanpa force, profil seperti itu mengembalikan 1203.

{
  "profile_id": "507f1f77bcf86cd799439011",
  "deleted": true
}

Penghapusan bersifat idempoten untuk ObjectId yang valid secara sintaksis: respons “tidak ditemukan” dari backend saat ini dianggap sebagai profil yang sudah dihapus.

#Sidik jari

Objek fingerprint dalam POST dan PATCH mendukung pembaruan sebagian pada kolom berikut:

Gunakan /catalog untuk mendapatkan nilai OS, GPU, CPU, RAM, layar, zona waktu, dan bahasa yang kompatibel.

#Folder

#GET /folder

Mendukung name, page, dan page_size.

{
  "folder_id": "507f1f77bcf86cd799439012",
  "name": "QA",
  "profile_count": 3,
  "system": false
}

#POST /folder

{ "name": "QA" }

#PUT /folder/:id

{ "name": "QA automation" }

#DELETE /folder/:id

Profil tidak dihapus bersama folder. Backend memindahkan profil tim ke folder sistem dan profil pribadi ke status tanpa folder.

{
  "folder_id": "507f1f77bcf86cd799439012",
  "deleted": true,
  "moved_profiles": 3,
  "moved_to": null
}

moved_profiles dan moved_to dihitung sebelum penghapusan sejauh memungkinkan dan mungkin tidak akurat jika status cloud tidak dapat dibaca.

#Siklus hidup browser

#GET /browser/status?profile_id=:id

Mengembalikan idle atau running, perangkat peluncuran, dan koordinat proses yang tersedia secara lokal.

#GET /browser/active

Kueri scope menerima:

• this_device — profil yang berjalan secara lokal; nilai default;
• account — profil yang berjalan di semua perangkat akun menurut registri cloud.

Paginasi standar didukung.

#POST /browser/start

{
  "profile_id": "507f1f77bcf86cd799439011",
  "headless": false,
  "open_urls": ["https://example.com"],
  "launch_args": ["--window-size=1280,800"],
  "load_extensions": true
}

Respons berhasil:

{
  "profile_id": "507f1f77bcf86cd799439011",
  "already_running": false,
  "debug_port": 51432,
  "ws": "ws://127.0.0.1:51432/devtools/browser/...",
  "webdriver": null,
  "pid": 12345,
  "lease": {
    "device_id": "device-id",
    "device_name": "Workstation",
    "is_current_device": true
  }
}

Menjalankan kembali profil di perangkat saat ini bersifat idempoten. Profil yang berjalan di perangkat lain mengembalikan 1204. Jika inti browser yang diperlukan tidak ada atau sedang diunduh, API Lokal mengembalikan 1304; metode ini tidak mengunduhnya secara otomatis.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

Penghentian bersifat idempoten dan mengembalikan was_running.

#POST /browser/stop-all

Menghentikan setiap profil di perangkat saat ini:

{
  "stopped": ["507f1f77bcf86cd799439011"],
  "count": 1
}

#Proxy

Format proxy langsung:

#POST /proxy/check

Berikan tepat satu sumber: proxy atau profile_id.

{
  "proxy": {
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080
  }
}

{
  "ok": true,
  "exit_ip": "203.0.113.10",
  "country": "DE",
  "city": "Frankfurt",
  "latitude": 50.11,
  "longitude": 8.68,
  "timezone": null,
  "latency_ms": null
}

#PUT /profile/:id/proxy

Badan permintaan adalah objek proxy itu sendiri, tanpa pembungkus proxy:

{
  "type": "no_proxy"
}

Untuk profil yang berjalan, perubahan ditunda hingga peluncuran berikutnya dan respons memuat deferred_fields: ["proxy"].

#Cookie

Cookie menggunakan format datar:

{
  "domain": ".example.com",
  "name": "session",
  "value": "value",
  "path": "/",
  "expires": 1790000000,
  "http_only": true,
  "secure": true,
  "same_site": "lax"
}

expires adalah waktu Unix dalam detik; 0 atau null berarti cookie sesi. same_site menerima unspecified, no_restriction, lax, atau strict.

#GET /profile/:id/cookies

Membaca database SQLite Chromium lokal terlebih dahulu dan menggunakan cookie yang disimpan di cloud jika database tidak tersedia.

#POST /profile/:id/cookies/import

{
  "clear": true,
  "cookies": [
    {
      "domain": ".example.com",
      "name": "session",
      "value": "value"
    }
  ]
}

• clear=true menggantikan cookie dan merupakan default;
• clear=false menggabungkannya dengan salinan cloud yang ada;
• profil harus dihentikan di setiap perangkat;
• setiap cookie yang diterima harus memuat setidaknya domain dan name.

#Perangkat

#GET /device

Mengembalikan daftar dengan paginasi:

{
  "device_id": "device-id",
  "device_name": "Workstation",
  "platform": "windows",
  "is_current_device": true,
  "online": true,
  "last_seen": "2026-07-24T10:00:00Z",
  "running_profiles": 1,
  "running_profile_ids": ["507f1f77bcf86cd799439011"]
}

#Katalog

#GET /catalog

Mengembalikan nilai sidik jari yang diizinkan dan dependensi GPU → CPU/RAM/layar. Gunakan os=windows|macos|linux untuk membatasi hasil ke satu sistem operasi.

Katalog bergantung pada cloud dan mengembalikan 1701 ketika cloud tidak tersedia.

#Kode kesalahan

#Contoh JavaScript minimal

const baseUrl = "http://127.0.0.1:50325/api/v1";
const token = process.env.AURORIUM_API_KEY;

async function aurorium(path, options = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  const result = await response.json();
  if (result.code !== 0) {
    throw new Error(`[${result.code}] ${result.msg}; ${result.request_id}`);
  }
  return result.data;
}

const profiles = await aurorium("/profile?page_size=10");
console.log(profiles.list);

#Kompatibilitas

• Versi API tercantum dalam URL: /api/v1.
• Kode kesalahan numerik stabil dalam satu versi mayor API.
• Klien sebaiknya mengabaikan kolom yang tidak dikenal karena kolom respons opsional dapat ditambahkan tanpa merusak kompatibilitas.
• Perubahan yang merusak kompatibilitas memerlukan URL mayor baru seperti /api/v2, atau masa migrasi yang disepakati secara eksplisit.