API local de Aurorium v1

#Inicio rápido

1. Inicia Aurorium e inicia sesión en tu cuenta.
2. Abre Automatización → API y genera una clave de API.
3. Guarda la clave de inmediato: el backend solo la muestra una vez.
4. Envía la clave en cada solicitud usando Authorization: Bearer <api_key>.

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

URL base:

http://127.0.0.1:50325/api/v1

El servidor escucha únicamente en 127.0.0.1, no en una interfaz de red externa. El puerto fijo actual es 50325.

#Formato de respuesta

Los resultados correctos y los errores de la aplicación usan la misma estructura de respuesta:

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

• code = 0 indica éxito.
• code != 0 indica un error de la aplicación; no basta con comprobar el estado HTTP.
• Guarda request_id en los registros de tu integración para el diagnóstico.
• El servidor suele devolver HTTP 200 incluso cuando hay un error de la aplicación.
• Si el cuerpo JSON supera los 5 MiB, la API devuelve code: 1001 y msg: "request body too large".

Ejemplo de error:

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

#Parámetros comunes

Los endpoints de listas aceptan:

Formato de data en la respuesta de una lista:

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

#Resumen de endpoints

#Sistema

#GET /health

Devuelve la disponibilidad de la aplicación local, el estado de la conexión a la nube y el ID del dispositivo actual.

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

Se requiere autenticación incluso para comprobar el estado del servicio.

#GET /version

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

core_version aún no está implementado y siempre devuelve null.

#Perfiles

#GET /profile

Parámetros de consulta:

Elemento de la lista:

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

No se devuelven perfiles archivados. El filtro running|idle se aplica en el cliente solo después de cargar la página, por lo que total y el número de elementos de la página pueden no coincidir con la lista filtrada.

#POST /profile

Solicitud mínima:

{
  "name": "Automation profile"
}

Campos admitidos:

Ejemplo con un proxy:

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

La creación de perfiles es asíncrona en el backend. La API local espera el evento de finalización y normalmente devuelve el modelo completo del perfil. Si la lectura posterior falla, puede devolver únicamente profile_id.

#GET /profile/:id

Devuelve un elemento de la lista con los objetos adicionales proxy y fingerprint. La contraseña del proxy nunca se devuelve como texto sin formato; si existe, se sustituye por ******.

#PATCH /profile/:id

Actualiza parcialmente un perfil:

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

Un cuerpo vacío es una operación correcta sin cambios. Los metadatos se aplican de inmediato. Los cambios de huella digital se aplican inmediatamente si el perfil está detenido; si está en ejecución, se aplazan hasta el siguiente inicio y se enumeran en deferred_fields.

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

Para un perfil detenido, deferred_fields siempre está vacío.

#DELETE /profile/:id

La consulta force=true detiene un perfil en ejecución en el dispositivo actual antes de eliminarlo. Sin force, ese perfil devuelve 1203.

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

La eliminación es idempotente para un ObjectId sintácticamente válido: actualmente, una respuesta «no encontrado» del backend se interpreta como un perfil ya eliminado.

#Huella digital

El objeto fingerprint en POST y PATCH admite actualizaciones parciales de estos campos:

Usa /catalog para obtener valores compatibles de SO, GPU, CPU, RAM, pantalla, zona horaria e idioma.

#Carpetas

#GET /folder

Admite name, page y 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

Los perfiles no se eliminan junto con una carpeta. El backend mueve los perfiles de equipo a la carpeta del sistema y deja los perfiles personales sin carpeta.

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

moved_profiles y moved_to se calculan antes de la eliminación con la información disponible y pueden ser inexactos si no se puede leer el estado de la nube.

#Ciclo de vida del navegador

#GET /browser/status?profile_id=:id

Devuelve idle o running, el dispositivo de inicio y las coordenadas del proceso disponibles localmente.

#GET /browser/active

La consulta scope acepta:

• this_device: perfiles ejecutados localmente; es el valor predeterminado;
• account: perfiles ejecutados en todos los dispositivos de la cuenta según el registro de la nube.

Se admite la paginación estándar.

#POST /browser/start

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

Respuesta correcta:

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

Volver a iniciar un perfil en el dispositivo actual es idempotente. Un perfil ejecutado en otro dispositivo devuelve 1204. Si el núcleo del navegador necesario no está instalado o se está descargando, la API local devuelve 1304; este método no lo descarga automáticamente.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

La detención es idempotente y devuelve was_running.

#POST /browser/stop-all

Detiene todos los perfiles del dispositivo actual:

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

#Proxy

Formato del proxy incluido:

#POST /proxy/check

Proporciona exactamente un origen: proxy o 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

El cuerpo es el propio objeto del proxy, sin un contenedor proxy:

{
  "type": "no_proxy"
}

Si el perfil está en ejecución, el cambio se aplaza hasta el siguiente inicio y la respuesta contiene deferred_fields: ["proxy"].

#Cookies

Una cookie usa un formato plano:

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

expires es la hora Unix en segundos; 0 o null indica una cookie de sesión. same_site acepta unspecified, no_restriction, lax o strict.

#GET /profile/:id/cookies

Primero lee la base de datos SQLite local de Chromium y, si no está disponible, recurre a las cookies almacenadas en la nube.

#POST /profile/:id/cookies/import

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

• clear=true sustituye las cookies y es el valor predeterminado;
• clear=false las combina con la copia existente en la nube;
• el perfil debe estar detenido en todos los dispositivos;
• cada cookie aceptada debe incluir al menos domain y name.

#Dispositivos

#GET /device

Devuelve una lista paginada:

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

#Catálogo

#GET /catalog

Devuelve los valores permitidos de la huella digital y las dependencias GPU → CPU/RAM/pantalla. Usa os=windows|macos|linux para limitar el resultado a un sistema operativo.

El catálogo depende de la nube y devuelve 1701 cuando esta no está disponible.

#Códigos de error

#Ejemplo mínimo en 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);

#Compatibilidad

• La versión de la API se incluye en la URL: /api/v1.
• Los códigos de error numéricos son estables dentro de una versión principal de la API.
• Los clientes deben ignorar los campos desconocidos, ya que pueden añadirse campos opcionales a las respuestas sin romper la compatibilidad.
• Los cambios incompatibles requieren una nueva URL de versión principal, como /api/v2, o un período de migración acordado explícitamente.