Pular para o conteúdo
Browsa
Seções

RESThttps://browsa.io/v1

API da Browsa

Navegadores na nuvem para agentes de IA. Inicie o Phantom, nosso próprio navegador, na nuvem com uma chamada de API e controle com Playwright, Puppeteer ou CDP puro. Ou descreva a tarefa em linguagem natural e o agente faz o resto.

llms.txt Especificação OpenAPI

Sua primeira chamada em três passos

  1. Pegue uma chave

    Cadastro grátis: 100 créditos assim que você confirmar seu e-mail, sem cartão. As chaves têm o formato agt_live_….

    Obter chave de APIAutenticação

  2. Faça a primeira chamada

    Faça scrape de uma página com um único POST. 1 crédito, sem chave de LLM.

  3. Veja o resultado

    A resposta HTTP são os dados. Próximo passo: controlar o navegador com Playwright ou rodar uma tarefa de IA.

# One POST: the page as Markdown and links, rendered in a real browser.
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"]}'
Resposta 200
{
  "markdown": "...",
  "links": [...],
  "http_status": 200
}

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.

curl
# 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"}'

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.

HTTP
X-API-Key: agt_live_aabbccddeeff001122334455

Autenticaçã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
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

Terminal
pip install browsa
Python
from 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

Terminal
npm i browsa
TypeScript
import { 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.

JSON
{
  "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.

Terminal
# 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