API locale Aurorium v1

#Démarrage rapide

1. Démarrez Aurorium et connectez-vous à votre compte.
2. Ouvrez Automatisation → API et générez une clé API.
3. Enregistrez immédiatement la clé : le backend ne l’affiche qu’une seule fois.
4. Envoyez la clé avec chaque requête via Authorization: Bearer <api_key>.

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

URL de base :

http://127.0.0.1:50325/api/v1

Le serveur écoute uniquement sur 127.0.0.1, pas sur une interface réseau externe. Le port fixe actuel est 50325.

#Format des réponses

Les résultats réussis et les erreurs applicatives utilisent la même enveloppe de réponse :

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

• code = 0 indique une réussite.
• code != 0 indique une erreur applicative ; vérifier uniquement le statut HTTP ne suffit pas.
• Conservez request_id dans les journaux de votre intégration pour le diagnostic.
• Le serveur renvoie généralement HTTP 200, même en cas d’erreur applicative.
• Si le corps JSON dépasse 5 MiB, l’API renvoie code: 1001 et msg: "request body too large".

Exemple d’erreur :

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

#Paramètres communs

Les endpoints de liste acceptent :

Format de data pour une réponse de liste :

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

#Vue d’ensemble des endpoints

#Système

#GET /health

Renvoie la disponibilité de l’application locale, l’état de la connexion cloud et l’identifiant de l’appareil actuel.

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

L’authentification est requise même pour le contrôle de disponibilité.

#GET /version

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

core_version n’est pas encore implémenté et renvoie toujours null.

#Profils

#GET /profile

Paramètres de requête :

Élément de liste :

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

Les profils archivés ne sont pas renvoyés. Le filtre running|idle est appliqué côté client uniquement après le chargement de la page ; total et le nombre d’éléments de la page peuvent donc ne pas correspondre à la liste filtrée.

#POST /profile

Requête minimale :

{
  "name": "Automation profile"
}

Champs pris en charge :

Exemple avec un proxy :

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

La création du profil est asynchrone côté backend. L’API locale attend l’événement de fin et renvoie normalement le modèle complet du profil. Si la lecture suivante échoue, seul profile_id peut être renvoyé.

#GET /profile/:id

Renvoie un élément de liste avec les objets supplémentaires proxy et fingerprint. Le mot de passe du proxy n’est jamais renvoyé en clair ; s’il existe, il est remplacé par ******.

#PATCH /profile/:id

Met à jour partiellement un profil :

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

Un corps vide est une opération réussie sans effet. Les métadonnées sont appliquées immédiatement. Les modifications de l’empreinte sont appliquées immédiatement si le profil est arrêté ; s’il est en cours d’exécution, elles sont reportées au prochain lancement et répertoriées dans deferred_fields.

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

Pour un profil arrêté, deferred_fields est toujours vide.

#DELETE /profile/:id

Le paramètre de requête force=true arrête un profil exécuté sur l’appareil actuel avant sa suppression. Sans force, ce profil renvoie 1203.

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

La suppression est idempotente pour un ObjectId syntaxiquement valide : une réponse « introuvable » du backend est actuellement traitée comme un profil déjà supprimé.

#Empreinte numérique

L’objet fingerprint dans POST et PATCH permet des mises à jour partielles de ces champs :

Utilisez /catalog pour obtenir des valeurs compatibles de système d’exploitation, GPU, CPU, RAM, écran, fuseau horaire et langue.

#Dossiers

#GET /folder

Prend en charge name, page et 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

La suppression d’un dossier ne supprime pas ses profils. Le backend déplace les profils d’équipe vers le dossier système et place les profils personnels dans l’état sans dossier.

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

moved_profiles et moved_to sont calculés avant la suppression avec les informations disponibles et peuvent être inexacts si l’état du cloud ne peut pas être lu.

#Cycle de vie du navigateur

#GET /browser/status?profile_id=:id

Renvoie idle ou running, l’appareil de lancement et les coordonnées du processus disponibles localement.

#GET /browser/active

Le paramètre de requête scope accepte :

• this_device : profils exécutés localement ; valeur par défaut ;
• account : profils exécutés sur tous les appareils du compte selon le registre cloud.

La pagination standard est prise en charge.

#POST /browser/start

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

Réponse réussie :

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

Redémarrer un profil sur l’appareil actuel est idempotent. Un profil exécuté sur un autre appareil renvoie 1204. Si le moteur de navigateur requis est absent ou en cours de téléchargement, l’API locale renvoie 1304 ; cette méthode ne le télécharge pas automatiquement.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

L’arrêt est idempotent et renvoie was_running.

#POST /browser/stop-all

Arrête tous les profils sur l’appareil actuel :

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

#Proxy

Format du proxy intégré :

#POST /proxy/check

Fournissez exactement une source : proxy ou 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

Le corps est l’objet proxy lui-même, sans enveloppe proxy :

{
  "type": "no_proxy"
}

Pour un profil en cours d’exécution, la modification est reportée au prochain lancement et la réponse contient deferred_fields: ["proxy"].

#Cookies

Un cookie utilise un format plat :

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

expires est une date Unix en secondes ; 0 ou null indique un cookie de session. same_site accepte unspecified, no_restriction, lax ou strict.

#GET /profile/:id/cookies

Lit d’abord la base SQLite locale de Chromium, puis utilise les cookies stockés dans le cloud si elle est indisponible.

#POST /profile/:id/cookies/import

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

• clear=true remplace les cookies et constitue la valeur par défaut ;
• clear=false les fusionne avec la copie cloud existante ;
• le profil doit être arrêté sur tous les appareils ;
• chaque cookie accepté doit contenir au moins domain et name.

#Appareils

#GET /device

Renvoie une liste paginée :

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

#Catalogue

#GET /catalog

Renvoie les valeurs d’empreinte autorisées et les dépendances GPU → CPU/RAM/écran. Utilisez os=windows|macos|linux pour limiter le résultat à un système d’exploitation.

Le catalogue dépend du cloud et renvoie 1701 lorsque celui-ci est indisponible.

#Codes d’erreur

#Exemple JavaScript minimal

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);

#Compatibilité

• La version de l’API figure dans l’URL : /api/v1.
• Les codes d’erreur numériques sont stables au sein d’une version majeure de l’API.
• Les clients doivent ignorer les champs inconnus, car des champs de réponse facultatifs peuvent être ajoutés sans rupture de compatibilité.
• Les changements incompatibles exigent une nouvelle URL de version majeure, comme /api/v2, ou une période de migration explicitement convenue.