API local do Aurorium v1

#Início rápido

1. Inicie o Aurorium e entre na sua conta.
2. Abra Automação → API e gere uma chave de API.
3. Salve a chave imediatamente: o backend a exibe apenas uma vez.
4. Envie a chave em cada requisição 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

O servidor escuta apenas em 127.0.0.1, e não em uma interface de rede externa. A porta fixa atual é 50325.

#Formato de resposta

Resultados bem-sucedidos e erros da aplicação usam a mesma estrutura de resposta:

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

• code = 0 significa sucesso.
• code != 0 significa um erro da aplicação; verificar apenas o status HTTP não é suficiente.
• Armazene request_id nos logs da sua integração para diagnóstico.
• O servidor normalmente retorna HTTP 200 mesmo em caso de erro da aplicação.
• Se o corpo JSON exceder 5 MiB, a API retornará code: 1001 e msg: "request body too large".

Exemplo de erro:

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

#Parâmetros comuns

Os endpoints de listagem aceitam:

Formato de data na resposta de listagem:

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

#Visão geral dos endpoints

#Sistema

#GET /health

Retorna a disponibilidade da aplicação local, o estado da conexão com a nuvem e o ID do dispositivo atual.

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

A autenticação é obrigatória mesmo na verificação de integridade.

#GET /version

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

core_version ainda não está implementado e sempre retorna null.

#Perfis

#GET /profile

Parâmetros de consulta:

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

Perfis arquivados não são retornados. O filtro running|idle é aplicado no cliente somente após o carregamento da página, portanto total e a quantidade de itens na página podem não corresponder à lista filtrada.

#POST /profile

Requisição mínima:

{
  "name": "Automation profile"
}

Campos compatíveis:

Exemplo com proxy:

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

A criação de perfis é assíncrona no backend. A API local aguarda o evento de conclusão e normalmente retorna o modelo completo do perfil. Se a leitura seguinte falhar, poderá retornar apenas profile_id.

#GET /profile/:id

Retorna um item de lista com os objetos adicionais proxy e fingerprint. A senha do proxy nunca é retornada em texto puro; quando presente, é substituída por ******.

#PATCH /profile/:id

Atualiza parcialmente um perfil:

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

Um corpo vazio é uma operação bem-sucedida sem efeito. Os metadados são aplicados imediatamente. As alterações de impressão digital são aplicadas imediatamente quando o perfil está parado; em um perfil em execução, são adiadas até a próxima inicialização e listadas em deferred_fields.

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

Para um perfil parado, deferred_fields está sempre vazio.

#DELETE /profile/:id

A consulta force=true para um perfil em execução no dispositivo atual antes de excluí-lo. Sem force, esse perfil retorna 1203.

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

A exclusão é idempotente para um ObjectId sintaticamente válido: uma resposta “não encontrado” do backend é atualmente tratada como um perfil já excluído.

#Impressão digital

O objeto fingerprint em POST e PATCH aceita atualizações parciais destes campos:

Use /catalog para obter valores compatíveis de sistema operacional, GPU, CPU, RAM, tela, fuso horário e idioma.

#Pastas

#GET /folder

Aceita name, page e 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

Os perfis não são excluídos com a pasta. O backend move perfis de equipe para a pasta do sistema e deixa os perfis pessoais sem pasta.

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

moved_profiles e moved_to são calculados antes da exclusão com as informações disponíveis e podem ser imprecisos quando não é possível ler o estado da nuvem.

#Ciclo de vida do navegador

#GET /browser/status?profile_id=:id

Retorna idle ou running, o dispositivo de inicialização e as coordenadas do processo disponíveis localmente.

#GET /browser/active

A consulta scope aceita:

• this_device: perfis em execução localmente; é o padrão;
• account: perfis em execução em todos os dispositivos da conta, conforme o registro na nuvem.

A paginação padrão é compatível.

#POST /browser/start

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

Resposta bem-sucedida:

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

Iniciar novamente um perfil no dispositivo atual é idempotente. Um perfil em execução em outro dispositivo retorna 1204. Se o núcleo do navegador necessário estiver ausente ou sendo baixado, a API local retornará 1304; este método não o baixa automaticamente.

#POST /browser/stop

{ "profile_id": "507f1f77bcf86cd799439011" }

A parada é idempotente e retorna was_running.

#POST /browser/stop-all

Para todos os perfis no dispositivo atual:

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

#Proxy

Formato do proxy incluído:

#POST /proxy/check

Forneça exatamente uma origem: 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

O corpo é o próprio objeto do proxy, sem um invólucro proxy:

{
  "type": "no_proxy"
}

Para um perfil em execução, a alteração é adiada até a próxima inicialização e a resposta contém deferred_fields: ["proxy"].

#Cookies

Um cookie usa um formato plano:

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

expires é o horário Unix em segundos; 0 ou null significa um cookie de sessão. same_site aceita unspecified, no_restriction, lax ou strict.

#GET /profile/:id/cookies

Primeiro lê o banco SQLite local do Chromium e, se ele não estiver disponível, usa os cookies armazenados na nuvem.

#POST /profile/:id/cookies/import

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

• clear=true substitui os cookies e é o padrão;
• clear=false mescla os cookies com a cópia existente na nuvem;
• o perfil deve estar parado em todos os dispositivos;
• cada cookie aceito deve incluir pelo menos domain e name.

#Dispositivos

#GET /device

Retorna uma 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

Retorna os valores de impressão digital permitidos e as dependências GPU → CPU/RAM/tela. Use os=windows|macos|linux para limitar o resultado a um sistema operacional.

O catálogo depende da nuvem e retorna 1701 quando ela está indisponível.

#Códigos de erro

#Exemplo mínimo em 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);

#Compatibilidade

• A versão da API faz parte da URL: /api/v1.
• Os códigos numéricos de erro são estáveis dentro de uma versão principal da API.
• Os clientes devem ignorar campos desconhecidos, pois campos opcionais podem ser adicionados à resposta sem quebrar a compatibilidade.
• Mudanças incompatíveis exigem uma nova URL de versão principal, como /api/v2, ou um período de migração explicitamente acordado.