Dois modos, um endpoint
- Descartável: efêmero, TTL de 5 min a 1 hora, se autodestrói e é cobrado pelos minutos que rodou. Ideal para jobs de scrape, automações pontuais e execuções de CI.
- Persistente: perfil durável e sincronizado com o cofre (cookies, localStorage, fingerprint), cobrado por mês, com sessões abertas sob demanda. Ideal para agentes de longa duração que mantêm o login entre execuções.
Todos os endpoints ficam em https://browsa.io. Autentique com X-API-Key: agt_live_…. Pegue uma chave com um cadastro grátis (100 créditos assim que você confirmar seu e-mail, sem cartão) e depois gere chaves no painel.
Início rápido
Duas formas de começar. A maioria prefere a primeira.
1. Scrape de uma página (sem agente, sem LLM)
Um único POST retorna a página como Markdown limpo e links, renderizada em um navegador real. 1 crédito, sem chave de LLM, e a resposta HTTP são os dados.
# Scrape any URL → clean Markdown + links in one call.
curl -X POST https://browsa.io/v1/quick/scrape \
-H "X-API-Key: agt_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://news.ycombinator.com","formats":["markdown","links"]}'
# → { "markdown": "...", "links": [...], "http_status": 200 }2. Controle o navegador você mesmo: Playwright via CDP
Três linhas até um navegador na nuvem controlado pelo seu código. Crie um navegador descartável e conecte o Playwright/Puppeteer à URL cdp_http retornada, com sua chave no header X-API-Key. Sem infraestrutura, sem ajuste de fingerprint.
# Provision a burner agent - returns CDP URL you can attach to.
curl https://browsa.io/v1/agents \
-H "X-API-Key: agt_live_…" \
-H "Content-Type: application/json" \
-d '{"ttl":"10m","initial_url":"https://example.com"}'# pip install browsa
from browsa import Client
from playwright.sync_api import sync_playwright
API_KEY = "agt_live_…"
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(agent["cdp_http"], headers={"X-API-Key": API_KEY})
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())// npm i browsa playwright
import { Client } from "browsa";
import { chromium } from "playwright";
const apiKey = "agt_live_…";
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });
const browser = await chromium.connectOverCDP(agent.cdp_http, { headers: { "X-API-Key": apiKey } });
const context = browser.contexts()[0];
const page = context.pages()[0] ?? await context.newPage();
await page.goto("https://example.com");
console.log(await page.title());Pronto. O agente é destruído quando o TTL chega a zero (ou quando você faz DELETE). Você paga pelo tempo que ele rodou: 1 crédito a cada 12 minutos iniciados, 5 créditos por uma hora inteira. Ao iniciar, ele reserva o preço do TTL pedido (1 crédito até 5 minutos, 5 créditos acima disso); os blocos não usados voltam quando ele termina.
Autenticação
Toda requisição precisa de uma chave de API no header X-API-Key. As chaves são geradas no painel e têm o formato agt_live_ seguido de 24 caracteres hexadecimais.
X-API-Key: agt_live_aabbccddeeff001122334455Autenticação Bearer também é aceita (mesmo formato de chave) para clientes que sempre enviam o header Authorization.
Mantenha as chaves em segredo. O segredo completo aparece uma única vez, quando a chave é gerada. Guardamos só o sha256(secret). Se uma chave vazar, revogue no painel e gere uma nova.
Idempotência
Todo endpoint POST /v1/quick/*, POST /v1/tasks, POST /v1/auto e POST /v1/sessions/{id}/messages aceita o header Idempotency-Key (compatível com a Stripe). POST /v1/agents não aceita: cada chamada inicia, e cobra, um novo navegador. Envie um UUID por requisição lógica e a plataforma guarda a resposta completa em cache por 24h. Uma nova tentativa com a mesma chave retorna o corpo em cache, byte a byte, com Idempotent-Replay: true: nenhum segundo navegador descartável criado, nenhuma segunda cobrança.
curl -X POST https://browsa.io/v1/quick/scrape \
-H "X-API-Key: agt_live_…" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Use isso em qualquer nova tentativa automática da sua biblioteca cliente (por exemplo, requests.Session com backoff). Sem isso, uma falha momentânea de rede pode executar o scrape de novo e cobrar duas vezes.
IDs de requisição
Toda resposta (sucesso ou erro) traz o header X-Request-Id. Os envelopes de erro também incluem request_id no corpo JSON. Informe esse valor a support@browsa.io em qualquer incidente, para encontrarmos sua requisição nos nossos logs.
SDKs
Wrappers sem dependências sobre a API REST, com respostas tipadas, long-poll waitForJob, verificação de assinatura HMAC de webhooks e o envelope completo {code, error, request_id} mapeado para erros tipados. A mesma interface em Python e TypeScript.
Python
pip install browsafrom browsa import Client
c = Client(api_key="agt_live_...")
job = c.run_task(
task="Go to news.ycombinator.com and return the top story title.",
llm="claude-opus-5-5",
llm_api_key="sk-ant-...",
)
print(job.final_result)
print("watch live:", job.live_url)Pacote: browsa no PyPI (Python 3.9+, sem dependências, MIT).
TypeScript / Node
npm i browsaimport { Client } from "browsa";
const c = new Client({ apiKey: "agt_live_..." });
const job = await c.runTask({
task: "Go to news.ycombinator.com and return the top story title.",
llm: "claude-opus-5-5",
llmApiKey: "sk-ant-...",
});
console.log(job.finalResult);
console.log("watch live:", job.liveUrl);Pacote: browsa no npm (Node 18+, sem dependências, ESM + CJS, .d.ts completo, MIT).
Servidor MCP: Claude Desktop, Cursor, Cline
Controle a plataforma de qualquer cliente compatível com MCP com um único bloco de configuração. O agente recebe 13 ferramentas: run_task, get_job, cancel_job, respond_to_job, list_job_files, create_schedule, list_schedules, list_llm_keys, credits, list_webhooks, create_webhook, delete_webhook, list_identities.
A configuração não precisa de segredo de LLM. Salve uma chave de LLM no seu workspace, e o servidor tenta primeiro sua chave salva padrão. BROWSA_LLM_API_KEY é opcional. Sem chave salva e sem llm definido, as tarefas usam o modelo hospedado padrão da Browsa ("llm": "browsa", que soma os créditos por tarefa desse modelo), e o servidor avisa. Um llm explícito sem chave retorna LLM_KEY_REQUIRED. Defina BROWSA_LLM_KEY_ID para escolher uma chave salva específica.
{
"mcpServers": {
"browsa": {
"command": "npx",
"args": ["-y", "@browsa/mcp"],
"env": {
"BROWSA_API_KEY": "agt_live_..."
}
}
}
}Coloque isto em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) e reinicie o Claude Desktop. Pergunte: "Vá até news.ycombinator.com e me diga o título da principal notícia."
Pacote: @browsa/mcp no npm (funciona no Claude Desktop, Cursor, Cline, Continue e Zed, MIT). Configuração para Claude Code, Cursor e VS Code: guia do servidor MCP.
Exemplos
As páginas dos pacotes mostram um início rápido e um receptor de webhooks: Python no PyPI, TypeScript no npm. Para scripts completos, veja o cookbook e os guias de frameworks.
Especificação OpenAPI
Importe no Postman, Insomnia, Swagger UI ou em qualquer cliente OpenAPI 3.1. A especificação completa está publicada em https://browsa.io/openapi.yaml.
# Generate a typed client in any language with openapi-generator-cli
npx @openapitools/openapi-generator-cli generate \
-i https://browsa.io/openapi.yaml \
-g typescript-axios -o ./browsa-client