Локальний API Aurorium v1

#Швидкий старт

1. Запустіть Aurorium і увійдіть до свого облікового запису.
2. Відкрийте Автоматизація → API та згенеруйте ключ API.
3. Одразу збережіть ключ: серверна частина показує його лише один раз.
4. Надсилайте ключ із кожним запитом через Authorization: Bearer <api_key>.

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

Базова URL-адреса:

http://127.0.0.1:50325/api/v1

Сервер слухає лише 127.0.0.1, а не зовнішній мережевий інтерфейс. Поточний фіксований порт — 50325.

#Формат відповіді

Успішні результати й помилки застосунку використовують однакову оболонку відповіді:

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

• code = 0 означає успіх.
• code != 0 означає помилку застосунку; перевірки лише статусу HTTP недостатньо.
• Зберігайте request_id у журналах інтеграції для діагностики.
• Сервер зазвичай повертає HTTP 200 навіть у разі помилки застосунку.
• Якщо тіло JSON перевищує 5 MiB, API повертає code: 1001 і msg: "request body too large".

Приклад помилки:

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

#Спільні параметри

Кінцеві точки списків приймають:

Формат data у відповіді зі списком:

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

#Огляд кінцевих точок

#Система

#GET /health

Повертає готовність локального застосунку, стан з’єднання з хмарою та ID поточного пристрою.

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

Автентифікація потрібна навіть для перевірки працездатності.

#GET /version

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

core_version ще не реалізовано, тому воно завжди повертає null.

#Профілі

#GET /profile

Параметри запиту:

Елемент списку:

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

Архівовані профілі не повертаються. Фільтр running|idle застосовується на клієнті лише після завантаження сторінки, тому total і кількість елементів на сторінці можуть не відповідати відфільтрованому списку.

#POST /profile

Мінімальний запит:

{
  "name": "Automation profile"
}

Підтримувані поля:

Приклад із проксі:

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

Створення профілю на серверній частині асинхронне. Локальний API чекає на подію завершення й зазвичай повертає повну модель профілю. Якщо подальше читання не вдається, може повернутися лише profile_id.

#GET /profile/:id

Повертає елемент списку з додатковими об’єктами proxy і fingerprint. Пароль проксі ніколи не повертається відкритим текстом; за наявності його замінено на ******.

#PATCH /profile/:id

Частково оновлює профіль:

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

Порожнє тіло успішно обробляється без змін. Метадані застосовуються одразу. Зміни відбитка застосовуються одразу, якщо профіль зупинено; для запущеного профілю вони відкладаються до наступного запуску й перелічуються в deferred_fields.

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

Для зупиненого профілю deferred_fields завжди порожній.

#DELETE /profile/:id

Параметр запиту force=true зупиняє профіль, що працює на поточному пристрої, перед видаленням. Без force такий профіль повертає 1203.

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

Видалення ідемпотентне для синтаксично коректного ObjectId: відповідь серверної частини «не знайдено» наразі трактується як уже видалений профіль.

#Відбиток

Об’єкт fingerprint у POST і PATCH підтримує часткове оновлення таких полів:

Використовуйте /catalog, щоб отримати сумісні значення ОС, GPU, CPU, RAM, екрана, часового поясу й мови.

#Папки

#GET /folder

Підтримує name, page і 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

Профілі не видаляються разом із папкою. Серверна частина переміщує командні профілі до системної папки, а особисті переводить у стан без папки.

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

moved_profiles і moved_to обчислюються перед видаленням за можливості й можуть бути неточними, якщо стан хмари неможливо прочитати.

#Життєвий цикл браузера

#GET /browser/status?profile_id=:id

Повертає idle або running, пристрій запуску й локально доступні координати процесу.

#GET /browser/active

Параметр запиту scope приймає:

• this_device — профілі, що працюють локально; значення за замовчуванням;
• account — профілі, що працюють на всіх пристроях облікового запису згідно з хмарним реєстром.

Підтримується стандартний поділ на сторінки.

#POST /browser/start

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

Успішна відповідь:

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

Повторний запуск профілю на поточному пристрої ідемпотентний. Профіль, запущений на іншому пристрої, повертає 1204. Якщо потрібного ядра браузера немає або воно завантажується, локальний API повертає 1304; цей метод не завантажує його автоматично.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

Зупинення ідемпотентне й повертає was_running.

#POST /browser/stop-all

Зупиняє кожен профіль на поточному пристрої:

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

#Проксі

Формат вбудованого об’єкта проксі:

#POST /proxy/check

Укажіть рівно одне джерело: proxy або 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

Тіло — безпосередньо об’єкт проксі, без оболонки proxy:

{
  "type": "no_proxy"
}

Для запущеного профілю зміна відкладається до наступного запуску, а відповідь містить deferred_fields: ["proxy"].

#Файли cookie

Cookie використовує плоский формат:

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

expires — час Unix у секундах; 0 або null означає сеансовий cookie. same_site приймає unspecified, no_restriction, lax або strict.

#GET /profile/:id/cookies

Спочатку читає локальну базу даних Chromium SQLite, а якщо вона недоступна, використовує cookie, збережені в хмарі.

#POST /profile/:id/cookies/import

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

• clear=true замінює cookie та є значенням за замовчуванням;
• clear=false об’єднує їх із наявною хмарною копією;
• профіль має бути зупинений на кожному пристрої;
• кожен прийнятий cookie має містити щонайменше domain і name.

#Пристрої

#GET /device

Повертає список із поділом на сторінки:

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

#Каталог

#GET /catalog

Повертає допустимі значення відбитка та залежності GPU → CPU/RAM/екран. Використовуйте os=windows|macos|linux, щоб обмежити результат однією операційною системою.

Каталог залежить від хмари й повертає 1701, коли хмара недоступна.

#Коди помилок

#Мінімальний приклад 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);

#Сумісність

• Версію API включено до URL-адреси: /api/v1.
• Числові коди помилок стабільні в межах однієї основної версії API.
• Клієнти мають ігнорувати невідомі поля, оскільки необов’язкові поля відповіді можуть додаватися без порушення сумісності.
• Зміни, що порушують сумісність, потребують нової URL-адреси основної версії, наприклад /api/v2, або явно погодженого періоду міграції.