Aurorium स्थानीय API v1

स्थानीय API आपके कंप्यूटर पर चल रही स्क्रिप्ट को Aurorium प्रोफ़ाइल, ब्राउज़र सत्र, फ़ोल्डर, प्रॉक्सी और कुकी प्रबंधित करने देता है। सर्वर डेस्कटॉप ऐप के साथ शुरू होता है और केवल उसी कंप्यूटर पर उपलब्ध रहता है।

#त्वरित शुरुआत

  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/cookiesकुकी निर्यात करें
POST/profile/:id/cookies/importकुकी आयात करें
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फ़ोल्डर के अनुसार फ़िल्टर करें
namestringनाम से खोजें
statusall, running, idleडिफ़ॉल्ट all है
page, page_sizeintegerपृष्ठांकन

सूची का आइटम:

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

समर्थित फ़ील्ड:

फ़ील्डप्रकारआवश्यकटिप्पणियाँ
namestringहाँखाली न होने वाला नाम
descriptionstringनहींडिफ़ॉल्ट "" है
folder_idstring या nullनहींMongo ObjectId; null का अर्थ कोई फ़ोल्डर नहीं है
tagsarrayनहींडिफ़ॉल्ट [] है
osstringनहींwindows, macos, linux
os_versionstringनहींफ़िंगरप्रिंट बनाने के लिए OS संस्करण का संकेत, जैसे "11" या "Tahoe"; सुझाए गए मानों के लिए /catalog देखें
is_armbooleanनहींARM का संकेत; न देने पर GPU निर्माता से अनुमान लगाया जाता है
proxyobjectनहींनीचे दिए गए प्रारूप में इनलाइन प्रॉक्सी
proxy_idstringनहींमौजूदा प्रॉक्सी का संदर्भ; proxy को प्राथमिकता मिलती है
launch_argumentsstringनहींएक स्ट्रिंग में लॉन्च आर्ग्युमेंट
start_pagestringनहींशुरुआती पेज
fingerprintobjectनहींफ़िंगरप्रिंट के कुछ मान बदलना

प्रॉक्सी के साथ उदाहरण:

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
timezonestring या null
language_modeauto, manual
languagesstring[]; पहला आइटम उपयोग होता है
languagestring; संक्षिप्त विकल्प
screen_resolutionstring
webrtc_modereal, replace
canvas_noiseboolean
webgl_image_noiseboolean
webgl_vendorstring या null
webgl_rendererstring या null
audio_noiseboolean
client_rects_noiseboolean
hardware_concurrencynumber
device_memorynumber
do_not_trackdefault, true
os_versionstring
dns_modereal, manual
dns_serverstring या null
geolocation{mode, latitude, longitude, accuracy}
media_devices{audio_inputs, audio_outputs, video_inputs}

संगत OS, GPU, CPU, RAM, स्क्रीन, समय क्षेत्र और भाषा के मान पाने के लिए /catalog का उपयोग करें।

#फ़ोल्डर

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

#प्रॉक्सी

इनलाइन प्रॉक्सी का प्रारूप:

फ़ील्डप्रकारटिप्पणियाँ
typestringhttp, socks4, socks5, ssh, no_proxy
hoststringno_proxy को छोड़कर आवश्यक
portinteger/string1..65535, no_proxy को छोड़कर
userstringवैकल्पिक
passwordstringवैकल्पिक
refresh_urlstringवैकल्पिक

#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"] शामिल होता है।

#कुकी

कुकी समतल प्रारूप का उपयोग करती है:

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

json
{
  "clear": true,
  "cookies": [
    {
      "domain": ".example.com",
      "name": "session",
      "value": "value"
    }
  ]
}
  • clear=true कुकी को बदल देता है और डिफ़ॉल्ट है;
  • clear=false उन्हें मौजूदा क्लाउड कॉपी के साथ मर्ज करता है;
  • प्रोफ़ाइल हर डिवाइस पर रुकी होनी चाहिए;
  • स्वीकार की गई हर कुकी में कम से कम 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 का उपयोग करें।

कैटलॉग क्लाउड पर निर्भर है और क्लाउड उपलब्ध न होने पर 1701 लौटाता है।

#त्रुटि कोड

कोडअर्थ
0सफलता
1001अमान्य JSON या अनुरोध बॉडी बहुत बड़ी है
1002अज्ञात एंडपॉइंट या HTTP विधि
1003API कुंजी मौजूद नहीं है या अमान्य है
1101आवश्यक पैरामीटर मौजूद नहीं है
1103पैरामीटर का मान या प्रारूप अमान्य है
1201प्रोफ़ाइल नहीं मिली
1202प्रोफ़ाइल संग्रहित है
1203प्रोफ़ाइल इस डिवाइस पर चल रही है
1204प्रोफ़ाइल दूसरे डिवाइस पर चल रही है
1301ब्राउज़र कोर शुरू नहीं हो सका
1304ब्राउज़र कोर मौजूद नहीं है या डाउनलोड हो रहा है
1401अमान्य प्रॉक्सी कॉन्फ़िगरेशन
1402प्रॉक्सी जाँच विफल हुई
1501फ़ोल्डर नहीं मिला
1503सिस्टम फ़ोल्डर हटाया नहीं जा सकता
1601कुकी का प्रारूप अमान्य है
1602चल रही प्रोफ़ाइल में कुकी आयात नहीं की जा सकतीं
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 या स्पष्ट रूप से सहमत माइग्रेशन अवधि आवश्यक है।