Aurorium ローカル API v1

ローカル API を使うと、コンピューター上で実行するスクリプトから Aurorium のプロファイル、ブラウザーセッション、フォルダー、プロキシ、Cookie を管理できます。サーバーはデスクトップアプリとともに起動し、同じコンピューターからのみ利用できます。

#クイックスタート

  1. Aurorium を起動し、アカウントにログインします。
  2. 「自動化」→「API」を開き、API キーを生成します。
  3. バックエンドでキーが表示されるのは一度だけなので、すぐに保存してください。
  4. すべてのリクエストで Authorization: Bearer <api_key> を使用してキーを送信します。
bash
curl "http://127.0.0.1:50325/api/v1/health" \
  -H "Authorization: Bearer $AURORIUM_API_KEY"

ベース URL:

text
http://127.0.0.1:50325/api/v1

サーバーは 127.0.0.1 のみで待ち受け、外部ネットワークインターフェースでは待ち受けません。現在の固定ポートは 50325 です。

#レスポンス形式

成功結果とアプリケーションエラーは、同じレスポンス構造を使用します。

json
{
  "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" を返します。

エラーの例:

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

#共通パラメーター

一覧取得エンドポイントは次を受け付けます。

パラメーターデフォルト制限
page1最小 1
page_size50最大 200。それより大きな値は 200 に制限されます

一覧レスポンスの data 形式:

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

#エンドポイントの概要

メソッドパス目的
GET/healthアプリケーションとクラウド接続の準備状態
GET/versionアプリケーションと API のバージョン
GET/profileアーカイブされていないプロファイルの一覧を取得
POST/profileプロファイルを作成
GET/profile/:idプロファイルの詳細を取得
PATCH/profile/:idプロファイルを部分更新
DELETE/profile/:idプロファイルを削除
GET/folderフォルダーの一覧を取得
POST/folderフォルダーを作成
PUT/folder/:idフォルダー名を変更
DELETE/folder/:idフォルダーを削除
GET/browser/statusプロファイルの起動状態を取得
GET/browser/active実行中のプロファイルの一覧を取得
POST/browser/startCDP を使用してプロファイルを起動
POST/browser/stopプロファイルを停止
POST/browser/stop-allローカルのプロファイルを停止
POST/proxy/checkプロキシを確認
PUT/profile/:id/proxyプロファイルのプロキシを置換
GET/profile/:id/cookiesCookie をエクスポート
POST/profile/:id/cookies/importCookie をインポート
GET/deviceアカウントのデバイス一覧を取得
GET/catalog使用可能なフィンガープリント値を取得

#システム

#GET /health

ローカルアプリの準備状態、クラウド接続状態、現在のデバイス ID を返します。

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

ヘルスチェックにも認証が必要です。

#GET /version

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

core_version は未実装で、常に null を返します。

#プロファイル

#GET /profile

クエリパラメーター:

パラメーター値説明
folder_idObjectIdフォルダーで絞り込み
name文字列名前で検索
statusall, running, idleデフォルトは all
page, page_size整数ページネーション

一覧の項目:

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

最小限のリクエスト:

json
{
  "name": "Automation profile"
}

対応フィールド:

フィールド型必須備考
name文字列はい空でない名前
description文字列いいえデフォルトは ""
folder_id文字列または nullいいえMongo ObjectId。null はフォルダーなしを意味します
tags配列いいえデフォルトは []
os文字列いいえwindows, macos, linux
os_version文字列いいえフィンガープリント生成用の OS バージョンのヒント（例: "11"、"Tahoe"）。推奨値は /catalog を参照
is_arm真偽値いいえARM のヒント。省略時は GPU ベンダーから推定
proxyオブジェクトいいえ下記形式のインラインプロキシ
proxy_id文字列いいえ既存のプロキシへの参照。proxy が優先されます
launch_arguments文字列いいえ起動引数を 1 つの文字列で指定
start_page文字列いいえスタートページ
fingerprintオブジェクトいいえフィンガープリントの部分的な上書き

プロキシを使用する例:

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

プロファイルを部分更新します。

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

ボディが空の場合、変更せず成功します。メタデータは即座に適用されます。フィンガープリントの変更は停止中のプロファイルには即座に適用され、実行中の場合は次回の起動まで延期されて deferred_fields に記載されます。

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

停止中のプロファイルでは、deferred_fields は常に空です。

#DELETE /profile/:id

force=true クエリは、現在のデバイスで実行中のプロファイルを削除前に停止します。force がない場合、このようなプロファイルは 1203 を返します。

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

構文が正しい ObjectId の削除は冪等です。現在、バックエンドの「見つかりません」という応答は、すでに削除済みのプロファイルとして扱われます。

#フィンガープリント

POST と PATCH の fingerprint オブジェクトでは、次のフィールドを部分更新できます。

フィールド型または値
timezone_modeauto, manual
timezone文字列または null
language_modeauto, manual
languages文字列配列。最初の項目を使用
language文字列。省略記法として使用可能
screen_resolution文字列
webrtc_modereal, replace
canvas_noise真偽値
webgl_image_noise真偽値
webgl_vendor文字列または null
webgl_renderer文字列または null
audio_noise真偽値
client_rects_noise真偽値
hardware_concurrency数値
device_memory数値
do_not_trackdefault, true
os_version文字列
dns_modereal, manual
dns_server文字列または null
geolocation{mode, latitude, longitude, accuracy}
media_devices{audio_inputs, audio_outputs, video_inputs}

/catalog を使用して、互換性のある OS、GPU、CPU、RAM、画面、タイムゾーン、言語の値を取得します。

#フォルダー

#GET /folder

name、page、page_size に対応します。

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

#POST /folder

json
{ "name": "QA" }

#PUT /folder/:id

json
{ "name": "QA automation" }

#DELETE /folder/:id

フォルダーを削除してもプロファイルは削除されません。バックエンドはチームのプロファイルをシステムフォルダーへ移動し、個人のプロファイルをフォルダーなしの状態にします。

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

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

成功時のレスポンス:

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

json
{ "profile_id": "507f1f77bcf86cd799439011" }

停止操作は冪等で、was_running を返します。

#POST /browser/stop-all

現在のデバイスのすべてのプロファイルを停止します。

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

#プロキシ

インラインプロキシの形式:

フィールド型備考
type文字列http, socks4, socks5, ssh, no_proxy
host文字列no_proxy 以外では必須
port整数/文字列1..65535（no_proxy を除く）
user文字列任意
password文字列任意
refresh_url文字列任意

#POST /proxy/check

proxy または profile_id のどちらか一方だけを指定します。

json
{
  "proxy": {
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080
  }
}
json
{
  "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 ラッパーを付けず、プロキシオブジェクト自体を指定します。

json
{
  "type": "no_proxy"
}

実行中のプロファイルでは変更は次回起動まで延期され、レスポンスに deferred_fields: ["proxy"] が含まれます。

#Cookie

Cookie はフラットな形式を使用します。

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

json
{
  "clear": true,
  "cookies": [
    {
      "domain": ".example.com",
      "name": "session",
      "value": "value"
    }
  ]
}
  • clear=true は Cookie を置換し、デフォルトの動作です。
  • clear=false は既存のクラウド上のコピーとマージします。
  • プロファイルはすべてのデバイスで停止している必要があります。
  • 受け付ける各 Cookie には、少なくとも domain と name が必要です。

#デバイス

#GET /device

ページ分割された一覧を返します。

json
{
  "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 を使うと、結果を 1 つの OS に制限できます。

カタログはクラウドに依存し、クラウドが利用できない場合は 1701 を返します。

#エラーコード

コード意味
0成功
1001JSON が無効、またはリクエストボディが大きすぎる
1002不明なエンドポイントまたは HTTP メソッド
1003API キーが未指定または無効
1101必須パラメーターが未指定
1103パラメーターの値または形式が無効
1201プロファイルが見つからない
1202プロファイルがアーカイブ済み
1203このデバイスでプロファイルが実行中
1204別のデバイスでプロファイルが実行中
1301ブラウザーコアの起動に失敗
1304ブラウザーコアが存在しない、またはダウンロード中
1401プロキシ設定が無効
1402プロキシの確認に失敗
1501フォルダーが見つからない
1503システムフォルダーは削除できない
1601Cookie の形式が無効
1602実行中のプロファイルには Cookie をインポートできない
1701クラウドが利用できない
1901内部エラー

#最小限の JavaScript サンプル

js
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 メジャーバージョン内で安定しています。
  • 互換性を維持したまま任意のレスポンスフィールドが追加される可能性があるため、クライアントは不明なフィールドを無視する必要があります。
  • 互換性を損なう変更には、/api/v2 などの新しいメジャーバージョンの URL、または明示的に合意した移行期間が必要です。