API e automação · Rocket Browser

Visão geral

API	Endereço	Para quê	Login
Local	`http://127.0.0.1:58888/api`	Abrir, fechar e listar perfis neste computador; ligar Puppeteer, Playwright e Selenium.	O app precisa estar aberto e com a conta conectada.
Nuvem	`https://api.rocketbrowser.online/api/v2/automation`	Criar, editar e apagar perfis, proxies, tags, pastas, extensões e equipe.	Token da API no cabeçalho.

Todos os pedidos e respostas usam JSON (Content-Type: application/json). Os exemplos abaixo foram gerados com o próprio código do Rocket Browser; os identificadores e IPs são de exemplo.

API local

Fica no ar sempre que o app está aberto, na porta 58888 (dá para trocar em Configurações). Por segurança, ela só aceita conexões do próprio computador (127.0.0.1).

GET

/api/profiles/active

Lista os perfis abertos neste computador.

Terminal

curl http://127.0.0.1:58888/api/profiles/active

Resposta 200

[
  {
    "uuid": "ac25c70306b844859cdaf95434937c15",
    "state": "STARTED",
    "headless": false,
    "start_time": 1762184362,
    "ws_endpoint": "ws://127.0.0.1:52344/devtools/browser/8f0c6e1d-4b8a-4d1e-9a51-2f7f0b3c9d10",
    "debug_port": "52344",
    "one_time": false,
    "browser_pid": 48211,
    "connection_data": {
      "ip": "203.0.113.10",
      "ipv4": "203.0.113.10",
      "ipv6": null,
      "country": "Brazil",
      "city": "São Paulo"
    }
  }
]

POST

/api/profiles/start

Abre um perfil salvo. A resposta traz o ws_endpoint, o endereço que o Puppeteer e o Playwright usam para controlar o navegador, e a debug_port, usada pelo Selenium.

Campo	Tipo	Padrão	O que faz
`uuid`	texto	obrigatório	Identificador do perfil.
`headless`	sim/não	`false`	Abre sem janela.
`debug_port`	número	porta livre	Porta fixa para o controle do navegador.
`only_local`	sim/não	`true`	Com `false`, o controle fica acessível na rede, não só neste computador.
`flags`	lista de textos	`[]`	Argumentos extras para o navegador.
`timeout`	número	`60`	Segundos de espera para o perfil abrir.
`password`	texto	–	Senha do perfil, se ele tiver uma.

Terminal

curl -X POST http://127.0.0.1:58888/api/profiles/start \
  -H 'Content-Type: application/json' \
  -d '{"uuid": "ac25c70306b844859cdaf95434937c15", "headless": false}'

A resposta tem o mesmo formato de cada item de /api/profiles/active. connection_data mostra o IP e o país de saída do proxy (ou null se não houver checagem).

POST

/api/profiles/stop

Fecha o perfil e salva os dados (cookies, abas, armazenamento) para a próxima vez.

Terminal

curl -X POST http://127.0.0.1:58888/api/profiles/stop \
  -H 'Content-Type: application/json' \
  -d '{"uuid": "ac25c70306b844859cdaf95434937c15"}'

Resposta 200

{ "msg": "Profile stopped" }

POST

/api/profiles/force_stop

Fecha à força, para quando o navegador do perfil não responde. Mesmo corpo do stop; responde { "msg": "Profile stopped successfully" }.

POST

/api/profiles/one_time/start

Abre um perfil descartável: ele não é salvo na conta e some quando é fechado. Bom para coleta de dados em grande volume. Aqui headless começa ligado.

Terminal

curl -X POST http://127.0.0.1:58888/api/profiles/one_time/start \
  -H 'Content-Type: application/json' \
  -d '{
    "profile_data": {
      "fingerprint": { "os": "mac" },
      "proxy": { "type": "socks5", "host": "203.0.113.20", "port": 1080, "login": "user", "password": "pass" },
      "start_pages": ["https://example.com"]
    },
    "headless": true
  }'

Também aceita cookies, extensions (no formato id@versão, já instaladas no app), launch_args e local_cache dentro de profile_data. A resposta é igual à do start, com "one_time": true e um uuid novo.

POST

/api/profiles/password

Define a senha de um perfil. Corpo: {"uuid": "…", "password": "…"}. Resposta: { "msg": "Profile password has been set" }.

DELETE

/api/profiles/password

Remove a senha (é preciso informar a senha atual). Resposta: { "msg": "Profile password has been cleared" }. Senha errada:

Resposta 400

{ "code": "profiles.invalid_password", "error": "Profile password incorrect", "error_code": 1 }

Conta e versão

Rota	Corpo	Resposta
POST `/api/auth/login`	`{"email", "password", "totp_code"}` ou `{"api_token"}`	`{"msg": "Logged in successfully"}`
POST `/api/auth/logout`	–	`{"msg": "Logged out successfully"}`
GET `/api/username`	–	`{"username": "voce@empresa.com"}`
GET `/api/update`	–	`{"current": "1.0.0", "latest": "1.0.0", "update_required": false}`

O login por script mexe na tela do app também: ao entrar ou sair pela API, o app acompanha.

Erros da API local

Situação	HTTP	Corpo
Faltou um campo	422	`{"detail": [{"type": "missing", "loc": ["body", "uuid"], "msg": "Field required", "input": {}}]}`
Perfil não existe	400	`{"code": "profiles.not_found", "error": "Profile not found", "error_code": 6}`
App sem conta conectada	401	`{"code": "auth.not_logged_in", "error": "Not logged in", "error_code": 0}`
JSON inválido	422	`{"detail": [{"loc": ["body"], "msg": "Invalid JSON", "type": "json_invalid"}]}`
Rota que não existe	404	`{"detail": "Not Found"}`

Conectar o automatizador

O fluxo é sempre o mesmo: abrir o perfil pela API local, conectar o automatizador ao endereço devolvido e, no fim, fechar o perfil pela API para os dados serem salvos.

puppeteer.mjs

import puppeteer from 'puppeteer-core';

const API = 'http://127.0.0.1:58888/api';
const UUID = 'ac25c70306b844859cdaf95434937c15';
const post = (rota, corpo) => fetch(API + rota, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(corpo),
}).then((r) => r.json());

const perfil = await post('/profiles/start', { uuid: UUID });
const browser = await puppeteer.connect({ browserWSEndpoint: perfil.ws_endpoint, defaultViewport: null });

const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());

await browser.disconnect();
await post('/profiles/stop', { uuid: UUID });

playwright.mjs

import { chromium } from 'playwright';

const API = 'http://127.0.0.1:58888/api';
const UUID = 'ac25c70306b844859cdaf95434937c15';
const post = (rota, corpo) => fetch(API + rota, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(corpo),
}).then((r) => r.json());

const perfil = await post('/profiles/start', { uuid: UUID });
const browser = await chromium.connectOverCDP(perfil.ws_endpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? await context.newPage();

await page.goto('https://example.com');
console.log(await page.title());

await browser.close();
await post('/profiles/stop', { uuid: UUID });

selenium_exemplo.py

import requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

API = "http://127.0.0.1:58888/api"
UUID = "ac25c70306b844859cdaf95434937c15"

perfil = requests.post(f"{API}/profiles/start", json={"uuid": UUID}).json()

options = Options()
options.add_experimental_option("debuggerAddress", f"127.0.0.1:{perfil['debug_port']}")
# o chromedriver precisa ser da mesma versão principal do navegador do perfil
driver = webdriver.Chrome(options=options)

driver.get("https://example.com")
print(driver.title)

driver.quit()
requests.post(f"{API}/profiles/stop", json={"uuid": UUID})

Ao terminar, feche sempre pelo /api/profiles/stop. É nessa hora que o Rocket salva cookies e dados do perfil e libera a trava para o resto da equipe.

API na nuvem

Endereço e token

O endereço oficial é https://api.rocketbrowser.online/api/v2/automation. Equipes com servidor Rocket próprio usam o endereço do próprio servidor, com o mesmo caminho /api/v2/automation. O token fica no app, em Configurações → Token da API (nuvem), onde também dá para gerar um novo. Mande-o em um destes cabeçalhos:

Terminal

curl https://api.rocketbrowser.online/api/v2/automation/profiles \
  -H 'X-Octo-Api-Token: SEU_TOKEN'
# ou, com o mesmo efeito:
#  -H 'X-Rocket-Api-Token: SEU_TOKEN'

Sem token, ou com token errado:

Resposta 401

{ "success": false, "msg": "Invalid or missing API token.", "data": "", "code": "api_token" }

Limites de requisições

Cada equipe pode fazer, por padrão, 1.000 pedidos por minuto e 50.000 por hora. Toda resposta informa quanto falta:

Cabeçalho	O que diz
`X-Ratelimit-Limit`	Limite por minuto.
`X-Ratelimit-Remaining`	Quantos pedidos ainda cabem neste minuto.
`X-Ratelimit-Reset`	Horário (Unix, em segundos) em que o minuto vira.
`X-Ratelimit-Limit-Hour` / `X-Ratelimit-Remaining-Hour`	O mesmo, por hora.
`Retry-After`	Segundos para tentar de novo quando o limite estoura.

Resposta 429

{ "success": false, "msg": "Rate limit exceeded", "code": "rate_limit_exceeded", "data": "" }

Formato das respostas e erros

Respostas de sucesso vêm sempre no mesmo envelope: success, msg, data e code. Listas trazem também total_count e page. Erros de validação dizem exatamente qual campo está errado:

Resposta 400 (validação)

{
  "validation_error": {
    "body_params": [
      { "type": "missing", "loc": ["title"], "msg": "Field required", "input": "" },
      { "type": "missing", "loc": ["fingerprint"], "msg": "Field required" }
    ]
  }
}

Outros erros usam o envelope com "success": false, por exemplo {"success": false, "msg": "Cannot find profile by uuid", "code": "not_found", "data": ""} (404).

Perfis

GET

/profiles

Lista perfis, 10 por página. Sem fields, cada item traz só o uuid; peça os campos que quiser, ou * para todos.

Parâmetro	O que faz
`page`	Página, começando em 0.
`page_len`	Itens por página: 10, 25, 50 ou 100.
`fields`	Campos separados por vírgula (`title,tags,proxy,status`…) ou `*`.
`ordering`	`created`, `-created`, `active`, `-active`, `title` ou `-title`.
`search`	Começo do nome (sem diferenciar maiúsculas e acentos) ou o uuid exato.
`search_tags`	Nomes de tags separados por vírgula (o perfil precisa ter todas).
`status`, `password`	Filtra por status e por perfis com senha (`true`/`false`).
`proxies`	Uuids de proxies separados por vírgula, ou `@no-proxies-filter` para perfis sem proxy.
`folder`	Nome ou uuid da pasta, ou `@none` para perfis fora de pastas.

Terminal

curl 'https://api.rocketbrowser.online/api/v2/automation/profiles?page=0&page_len=10&fields=title,tags,proxy,status' \
  -H 'X-Octo-Api-Token: SEU_TOKEN'

Resposta 200

{
  "success": true,
  "msg": "",
  "data": [
    {
      "uuid": "7118b397a6e94312b4a71cc3fd5bd93b",
      "title": "Loja 01",
      "tags": ["loja"],
      "proxy": {
        "uuid": "",
        "type": "socks5",
        "host": "203.0.113.10",
        "port": 1080,
        "login": "user",
        "password": "pass",
        "change_ip_url": null,
        "external_id": null
      },
      "status": 0
    }
  ],
  "code": null,
  "total_count": 1,
  "page": 0
}

POST

/profiles

Cria um perfil. Só title (até 90 letras) e fingerprint com o sistema são obrigatórios; o resto da impressão digital é montado de forma coerente.

Terminal

curl -X POST https://api.rocketbrowser.online/api/v2/automation/profiles \
  -H 'X-Octo-Api-Token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Loja 01",
    "tags": ["loja"],
    "fingerprint": { "os": "win" },
    "proxy": { "type": "socks5", "host": "203.0.113.10", "port": 1080, "login": "user", "password": "pass" },
    "start_pages": ["https://example.com"]
  }'

Resposta 201

{ "success": true, "msg": "", "data": { "uuid": "7118b397a6e94312b4a71cc3fd5bd93b" }, "code": null }

Campo	O que é
`title`	Nome do perfil (obrigatório).
`fingerprint`	Impressão digital; no mínimo `{"os": "win" \| "mac" \| "android"}`. Veja as opções.
`proxy`	Uuid de um proxy salvo ou um objeto com `type`, `host`, `port`, `login`, `password`.
`tags`	Nomes de tags que já existem.
`folder`	Nome ou uuid da pasta.
`description`	Anotação livre (até 1.024 letras).
`start_pages`, `bookmarks`	Até 20 páginas iniciais; até 100 favoritos `{name, url}`.
`cookies`	Cookies para importar na primeira abertura.
`extensions`, `launch_args`	Extensões do perfil e argumentos extras do navegador.
`password`	Senha do perfil (4 a 255 letras).
`storage_options`	O que salvar: `cookies`, `passwords`, `extensions`, `localstorage`, `history`, `bookmarks`, `serviceworkers`.

GET

/profiles/{uuid}

Devolve o perfil completo. Trecho da resposta:

Resposta 200 (trecho)

{
  "success": true,
  "msg": "",
  "data": {
    "uuid": "7118b397a6e94312b4a71cc3fd5bd93b",
    "title": "Loja 01",
    "start_pages": ["https://example.com"],
    "tags": ["loja"],
    "folder": null,
    "status": 0,
    "version": "0",
    "storage_options": {
      "cookies": true, "passwords": true, "extensions": true, "localstorage": false,
      "history": false, "bookmarks": true, "serviceworkers": false
    },
    "fingerprint": {
      "os": "win",
      "os_arch": "x86",
      "os_version": "10",
      "screen": "1280x1024",
      "renderer": "AMD Radeon RX 580 Series",
      "cpu": 4,
      "ram": 8,
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36",
      "languages": { "type": "ip", "data": null },
      "timezone": { "type": "ip", "data": null },
      "geolocation": { "type": "ip", "data": null },
      "webrtc": { "type": "ip", "data": null },
      "noise": { "webgl": true, "canvas": true, "audio": true, "client_rects": false },
      "media_devices": { "video_in": 1, "audio_in": 1, "audio_out": 1 },
      "dnt": false,
      "dns": null
    },
    "has_user_password": false,
    "created_at": "2026-11-03T15:39:22",
    "updated_at": "2026-11-03T15:39:22"
  },
  "code": null
}

PATCH

/profiles/{uuid}

Muda só o que você mandar. O sistema do perfil não pode ser trocado depois de criado. Para senha, use /profiles/set_password.

Corpo

{
  "title": "Loja 01 (BR)",
  "fingerprint": { "languages": { "type": "ip" }, "timezone": { "type": "ip" } }
}

Resposta 200

{ "success": true, "msg": "", "data": { "uuid": "7118b397a6e94312b4a71cc3fd5bd93b" }, "code": null }

DELETE

/profiles

Apaga vários perfis. Como na API do Octo, por padrão apaga de vez; mande "skip_trash_bin": false para mandar para a lixeira (72 horas).

Corpo e resposta 200

{ "uuids": ["7118b397a6e94312b4a71cc3fd5bd93b"], "skip_trash_bin": false }

{
  "success": true,
  "msg": "Profiles deleted",
  "data": { "deleted_uuids": ["7118b397a6e94312b4a71cc3fd5bd93b"], "active_uuids": [] },
  "code": null
}

Também em perfis:

Rota	Corpo	O que faz
POST `/profiles/{uuid}/force_stop`	`{"version"}`	Libera um perfil travado como “em uso”.
POST `/profiles/force_stop`	`{"uuids"}`	O mesmo, para vários (responde 207 se parte falhar).
POST `/profiles/transfer`	`{"uuids", "receiver_email", "transfer_proxy"}`	Transfere perfis para outra conta.
POST `/profiles/export`	`{"uuids", "export_proxy"}`	Exporta perfis (acompanhe em `GET /profiles/export`).
POST `/profiles/import`	`{"data", "folder"}`	Importa perfis exportados.
POST `/profiles/set_password`	`{"profiles", "password", "old_password"}`	Define ou troca a senha de vários perfis.
POST `/profiles/{uuid}/clear_password`	`{"password"}`	Remove a senha do perfil.

Impressão digital

Dentro de fingerprint, tudo é opcional menos os. O que não for informado é escolhido de forma coerente com o sistema.

Campo	Valores
`os`	`win`, `mac` ou `android`
`os_arch`	`x86` ou `arm` (Mac Intel ou Apple Silicon)
`device_type`, `device_model`	Android: `phone` ou `tablet` e o modelo (lista em `/fingerprint/device_models`)
`screen`, `renderer`	Resolução e placa de vídeo (listas em `/fingerprint/screens` e `/fingerprint/renderers`)
`cpu`, `ram`	Núcleos e memória em GB
`languages`, `timezone`, `geolocation`	`{"type": "ip" \| "real" \| "manual", "data": …}`
`webrtc`	`{"type": "ip" \| "real" \| "disable_non_proxied_udp" \| "manual" \| "disabled", "data": …}`
`noise`	`{"webgl", "canvas", "audio", "client_rects"}`, cada um `true` ou `false`
`media_devices`	`{"video_in", "audio_in", "audio_out"}` (quantidades)
`fonts`, `user_agent`, `dns`, `dnt`	Lista de fontes, user agent, DNS próprio e “não rastrear”

GET /fingerprint/screens?os=win (trecho)

{
  "success": true,
  "msg": "",
  "data": [
    { "value": "1366x768", "platform": "win", "archs": ["x86"] },
    { "value": "1920x1080", "platform": "win", "archs": ["x86"] },
    { "value": "2560x1440", "platform": "win", "archs": ["x86"] }
  ],
  "code": null
}

Proxies

POST

/proxies

Salva um proxy para usar em vários perfis. type: http, https, socks (SOCKS4), socks5 ou ssh. O change_ip_url é o link de troca de IP do seu provedor.

Corpo

{
  "title": "SOCKS São Paulo",
  "type": "socks5",
  "host": "203.0.113.20",
  "port": 1080,
  "login": "user",
  "password": "pass",
  "change_ip_url": "https://provedor.example/troca?key=abc"
}

Resposta 201

{
  "success": true,
  "msg": "",
  "data": {
    "uuid": "72bc84fb5d504307abae374fcfaf4b33",
    "type": "socks5",
    "host": "203.0.113.20",
    "port": 1080,
    "login": "user",
    "password": "pass",
    "change_ip_url": "https://provedor.example/troca?key=abc",
    "external_id": null,
    "title": "SOCKS São Paulo",
    "profiles_count": 0,
    "last_check": null
  },
  "code": null
}

Também: GET /proxies (com search), PATCH /proxies/{uuid} e DELETE /proxies/{uuid}.

Cookies

POST

/profiles/{uuid}/import_cookies

Importa cookies num perfil. Aceita a lista em JSON (como abaixo) ou o texto nos formatos Netscape e Mozilla.

Corpo

{
  "cookies": [
    {
      "domain": ".example.com",
      "name": "sessao",
      "value": "abc123",
      "path": "/",
      "expirationDate": 1893456000,
      "secure": true,
      "httpOnly": true
    }
  ]
}

Resposta 200

{ "success": true, "msg": "Cookies imported", "data": "", "code": null }

Tags, pastas, extensões e equipe

POST /tags · corpo e resposta 201

{ "name": "loja", "color": "orange" }

{ "success": true, "msg": "", "data": { "uuid": "5e3dd1ae6e7649f2a3acdfb5dccc46c7", "name": "loja", "color": "orange" }, "code": null }

Cores das tags: grey, blue, cyan, orange, green, purple, red e yellow.

Rota	O que faz
`GET` · `POST` `/tags`, `PATCH` · `DELETE` `/tags/{uuid}`	Tags
`GET` · `POST` `/folders`, `PATCH` · `DELETE` `/folders/{pasta}`	Pastas (`POST` recebe `{"folders": [...]}`, até 100)
`GET` · `DELETE` `/teams/extensions`	Extensões da equipe
`GET` · `POST` · `PATCH` · `DELETE` `/teams/subaccounts`	Membros da equipe e permissões (`POST` envia o convite)
`GET` · `DELETE` `/teams/invites`	Convites pendentes

Histórico de ações em tempo real

/api/v2/automation/ws/action_log

Conexão WebSocket que manda o histórico de ações da equipe (perfis criados, abertos, editados…) assim que elas acontecem. Autentique com o cabeçalho do token ou com ?token=SEU_TOKEN. Use after_uuid ou from_timestamp para continuar de onde parou (até 24 horas para trás). Precisa da permissão de ver o histórico.

Todas as rotas da API na nuvem

Prefixo: /api/v2/automation.

Método	Rota
GET POST DELETE	`/profiles`
GET PATCH	`/profiles/{uuid}`
POST	`/profiles/force_stop`, `/profiles/transfer`, `/profiles/import`, `/profiles/set_password`
GET POST	`/profiles/export`
GET	`/profiles/export/{uuid}`
POST	`/profiles/{uuid}/import_cookies`, `/profiles/{uuid}/force_stop`, `/profiles/{uuid}/clear_password`
GET POST	`/tags`, `/folders`, `/proxies`
PATCH DELETE	`/tags/{uuid}`, `/folders/{pasta}`, `/proxies/{uuid}`
GET DELETE	`/teams/extensions`, `/teams/invites`
GET POST PATCH DELETE	`/teams/subaccounts`
GET	`/fingerprint/renderers`, `/fingerprint/screens`, `/fingerprint/device_models`
WS	`/ws/action_log`

Dúvidas ou algo que não bate com o seu script? Escreva para contato@rocketbrowser.online.