Lokal na API ng Aurorium v1

#Mabilis na pagsisimula

1. Simulan ang Aurorium at mag-sign in sa iyong account.
2. Buksan ang Automation → API at bumuo ng API key.
3. I-save agad ang key: isang beses lamang ito ipinapakita ng backend.
4. Ipadala ang key sa bawat request gamit ang Authorization: Bearer <api_key>.

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

Base URL:

http://127.0.0.1:50325/api/v1

Nakikinig lamang ang server sa 127.0.0.1, hindi sa panlabas na network interface. Ang kasalukuyang nakapirming port ay 50325.

#Format ng tugon

Pareho ang balangkas ng tugon para sa mga matagumpay na resulta at mga error ng application:

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

• Ang code = 0 ay nangangahulugang tagumpay.
• Ang code != 0 ay nangangahulugang error ng application; hindi sapat na suriin lamang ang HTTP status.
• Itago ang request_id sa mga log ng iyong integration para sa pag-diagnose.
• Karaniwang nagbabalik ang server ng HTTP 200 kahit may error ang application.
• Kung lumampas sa 5 MiB ang JSON body, ibabalik ng API ang code: 1001 at msg: "request body too large".

Halimbawa ng error:

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

#Mga karaniwang parameter

Tinatanggap ng mga endpoint ng listahan ang:

Format ng data sa tugon ng listahan:

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

#Pangkalahatang-ideya ng mga endpoint

#System

#GET /health

Ibinabalik ang kahandaan ng lokal na application, estado ng koneksyon sa cloud, at ID ng kasalukuyang device.

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

Kailangan ang authentication kahit para sa pagsusuri ng kalagayan ng serbisyo.

#GET /version

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

Hindi pa ipinapatupad ang core_version at palaging null ang ibinabalik nito.

#Mga profile

#GET /profile

Mga parameter ng query:

Item sa listahan:

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

Hindi ibinabalik ang mga naka-archive na profile. Inilalapat ang filter na running|idle sa client pagkatapos lamang ma-load ang pahina, kaya maaaring hindi tumugma ang total at ang bilang ng mga item sa pahina sa na-filter na listahan.

#POST /profile

Pinakapayak na request:

{
  "name": "Automation profile"
}

Mga suportadong field:

Halimbawang may proxy:

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

Asynchronous ang paggawa ng profile sa backend. Hinihintay ng lokal na API ang completion event at karaniwang ibinabalik ang buong modelo ng profile. Kung mabigo ang kasunod na pagbasa, maaaring profile_id lamang ang maibalik.

#GET /profile/:id

Nagbabalik ng item sa listahan na may dagdag na mga object na proxy at fingerprint. Hindi kailanman ibinabalik bilang plain text ang password ng proxy; kapag mayroon, pinapalitan ito ng ******.

#PATCH /profile/:id

Bahagyang ina-update ang profile:

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

Ang walang lamang body ay matagumpay na operasyong walang epekto. Agad na inilalapat ang metadata. Agad ding inilalapat ang mga pagbabago sa fingerprint kapag nakahinto ang profile; para sa tumatakbong profile, ipinagpapaliban ang mga ito hanggang sa susunod na paglulunsad at inililista sa deferred_fields.

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

Para sa nakahintong profile, palaging walang laman ang deferred_fields.

#DELETE /profile/:id

Inihihinto ng query na force=true ang profile na tumatakbo sa kasalukuyang device bago ito i-delete. Kung walang force, ibinabalik ng ganitong profile ang 1203.

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

Idempotent ang pag-delete para sa ObjectId na may wastong syntax: kasalukuyang itinuturing ang tugong “hindi nahanap” ng backend bilang profile na na-delete na.

#Fingerprint

Sinusuportahan ng object na fingerprint sa POST at PATCH ang bahagyang pag-update sa mga field na ito:

Gamitin ang /catalog para kunin ang mga tugmang halaga ng OS, GPU, CPU, RAM, screen, time zone, at wika.

#Mga folder

#GET /folder

Sinusuportahan ang name, page, at 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

Hindi kasamang nade-delete ang mga profile kapag nag-delete ng folder. Inililipat ng backend ang mga profile ng koponan sa system folder at inaalis sa anumang folder ang mga personal na profile.

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

Kinakalkula ang moved_profiles at moved_to bago mag-delete gamit ang impormasyong available at maaaring hindi tumpak kapag hindi mabasa ang estado ng cloud.

#Siklo ng buhay ng browser

#GET /browser/status?profile_id=:id

Ibinabalik ang idle o running, ang device ng paglulunsad, at ang mga coordinate ng proseso na lokal na available.

#GET /browser/active

Tinatanggap ng query na scope ang:

• this_device: mga profile na lokal na tumatakbo; ito ang default;
• account: mga profile na tumatakbo sa lahat ng device ng account ayon sa registry ng cloud.

Sinusuportahan ang karaniwang paghahati sa mga pahina.

#POST /browser/start

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

Matagumpay na tugon:

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

Idempotent ang muling pagsisimula ng profile sa kasalukuyang device. Ang profile na tumatakbo sa ibang device ay nagbabalik ng 1204. Kung wala ang kinakailangang browser core o dina-download pa ito, ibinabalik ng lokal na API ang 1304; hindi ito awtomatikong dina-download ng method na ito.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

Idempotent ang paghinto at ibinabalik nito ang was_running.

#POST /browser/stop-all

Inihihinto ang lahat ng profile sa kasalukuyang device:

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

#Proxy

Format ng inline na proxy:

#POST /proxy/check

Magbigay ng eksaktong isang pinagmulan: proxy o 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

Ang body ay ang mismong proxy object, nang walang pambalot na proxy:

{
  "type": "no_proxy"
}

Para sa tumatakbong profile, ipinagpapaliban ang pagbabago hanggang sa susunod na paglulunsad at kasama sa tugon ang deferred_fields: ["proxy"].

#Cookies

Gumagamit ang cookie ng flat na format:

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

Ang expires ay Unix time sa segundo; ang 0 o null ay nangangahulugang session cookie. Tinatanggap ng same_site ang unspecified, no_restriction, lax, o strict.

#GET /profile/:id/cookies

Unang binabasa ang lokal na Chromium SQLite database at ginagamit ang cookies sa cloud kung hindi ito available.

#POST /profile/:id/cookies/import

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

• Pinapalitan ng clear=true ang cookies at ito ang default;
• Pinagsasama ng clear=false ang mga ito sa umiiral na kopya sa cloud;
• dapat nakahinto ang profile sa bawat device;
• dapat kasama sa bawat tinatanggap na cookie ang hindi bababa sa domain at name.

#Mga device

#GET /device

Nagbabalik ng listahang hinati sa mga pahina:

{
  "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"]
}

#Katalogo

#GET /catalog

Ibinabalik ang mga pinapayagang halaga ng fingerprint at ang mga dependency na GPU → CPU/RAM/screen. Gamitin ang os=windows|macos|linux para limitahan ang resulta sa isang operating system.

Nakadepende sa cloud ang katalogo at nagbabalik ng 1701 kapag hindi available ang cloud.

#Mga code ng error

#Pinakapayak na halimbawa sa JavaScript

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);

#Compatibility

• Kasama ang bersyon ng API sa URL: /api/v1.
• Hindi nagbabago ang mga numerikong code ng error sa loob ng isang pangunahing bersyon ng API.
• Dapat balewalain ng mga client ang mga hindi kilalang field dahil maaaring magdagdag ng opsyonal na field sa tugon nang hindi sinisira ang compatibility.
• Ang mga pagbabagong sumisira sa compatibility ay nangangailangan ng bagong URL ng pangunahing bersyon, gaya ng /api/v2, o ng panahon ng paglipat na tahasang pinagkasunduan.