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

#คุกกี้

คุกกี้ใช้รูปแบบแบน:

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

expires คือเวลา Unix หน่วยวินาที; 0 หรือ null หมายถึงคุกกี้เซสชัน same_site ยอมรับ unspecified, no_restriction, lax หรือ strict

#GET /profile/:id/cookies

อ่านฐานข้อมูล Chromium SQLite ภายในเครื่องก่อน และใช้คุกกี้ที่เก็บบนคลาวด์แทนหากฐานข้อมูลไม่พร้อมใช้งาน

#POST /profile/:id/cookies/import

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

• clear=true แทนที่คุกกี้ และเป็นค่าเริ่มต้น;
• clear=false รวมเข้ากับสำเนาที่มีอยู่บนคลาวด์;
• ต้องหยุดโปรไฟล์บนอุปกรณ์ทุกเครื่อง;
• คุกกี้แต่ละรายการที่ยอมรับต้องมีอย่างน้อย 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 หรือมีช่วงย้ายระบบที่ตกลงไว้อย่างชัดเจน