Aurorium Local API v1

#Быстрый старт

1. Запустите Aurorium и войдите в аккаунт.
2. Откройте раздел Automation → API и сгенерируйте API key.
3. Сохраните ключ сразу: backend показывает его только один раз.
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.

#Формат ответа

Успех и прикладные ошибки возвращаются в едином envelope:

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

• code = 0 означает успех.
• code != 0 означает прикладную ошибку; проверять только HTTP status недостаточно.
• request_id следует сохранять в логах интеграции для диагностики.
• Обычно сервер возвращает HTTP 200 даже при прикладной ошибке.
• Если JSON body превышает 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
}

#Обзор методов

#System

#GET /health

Возвращает локальную готовность приложения, состояние cloud-соединения и ID текущего устройства.

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

Авторизация обязательна даже для health-check.

#GET /version

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

core_version пока не реализован и всегда возвращает null.

#Profiles

#GET /profile

Query-параметры:

Элемент списка:

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

Создание асинхронно на backend. Local 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"
  }
}

Пустой body является успешной no-op операцией.

Метаданные (name, description, folder_id) применяются сразу. Изменения fingerprint применяются сразу, если профиль остановлен; если профиль запущён — они откладываются до следующего запуска и перечисляются в deferred_fields. Каждый ключ соответствует переданному полю в форме fingerprint.<имя_поля>. Метаданные в deferred_fields не попадают никогда.

Пример для запущенного профиля, которому передали timezone_mode и timezone:

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

Для остановленного профиля deferred_fields всегда пустой:

{
  "profile_id": "507f1f77bcf86cd799439011",
  "deferred_fields": []
}

#DELETE /profile/:id

Query force=true останавливает профиль, запущенный на текущем устройстве, перед удалением. Без force такой профиль возвращает 1203.

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

Удаление идемпотентно для синтаксически корректного ObjectId: backend-ошибка «не найдено» сейчас трактуется как уже удалённый профиль.

#Fingerprint

Объект fingerprint в POST/PATCH поддерживает частичное обновление следующих полей:

Допустимые взаимосвязанные значения OS, GPU, CPU, RAM, экрана, timezone и language следует получать через /catalog.

#Folders

#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

Профили не удаляются вместе с папкой: backend переносит их в системную папку (командные профили) или в состояние без папки (личные профили).

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

moved_profiles и moved_to вычисляются до удаления в best-effort режиме и могут быть неточными при проблемах чтения cloud-состояния.

#Browser lifecycle

#GET /browser/status?profile_id=:id

Возвращает idle или running, устройство запуска и доступные локальные координаты процесса.

#GET /browser/active

Query scope:

• this_device — локально запущенные профили, значение по умолчанию;
• account — профили на всех устройствах аккаунта по cloud registry.

Поддерживает стандартную пагинацию.

#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. Если нужное ядро отсутствует или требует загрузки, Local API возвращает 1304; автоматического скачивания через этот метод сейчас нет.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

Остановка идемпотентна и возвращает was_running.

#POST /browser/stop-all

Останавливает все профили на текущем устройстве:

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

#Proxy

Формат inline proxy:

#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

Body — непосредственно proxy object без обёртки proxy:

{
  "type": "no_proxy"
}

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

#Cookies

Cookie имеет плоский формат:

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

expires — Unix time в секундах; 0 или null означает session cookie. same_site: unspecified, no_restriction, lax, strict.

#GET /profile/:id/cookies

Сначала читает локальную Chromium SQLite, при её отсутствии пытается получить cookies из cloud.

#POST /profile/:id/cookies/import

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

• clear=true по умолчанию заменяет cookies;
• clear=false объединяет их с существующей cloud-копией;
• профиль должен быть остановлен на всех устройствах;
• каждая принимаемая cookie должна иметь как минимум domain и name.

#Devices

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

#Catalog

#GET /catalog

Возвращает разрешённые fingerprint-значения и зависимости GPU → CPU/RAM/screen. Query os=windows|macos|linux ограничивает ответ одной ОС.

Catalog зависит от cloud; при недоступности возвращается 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.
• Числовые коды ошибок заявлены стабильными в пределах major API version.
• Добавление необязательных полей в ответ не должно ломать интеграции; клиентам следует игнорировать неизвестные поля.
• Ломающие изменения требуют нового major URL (/api/v2) либо явно согласованного периода миграции.