Dos modos, un endpoint
- Desechable: efímero, TTL de 5 min a 1 hora, se autodestruye y se factura por los minutos que funcionó. Ideal para trabajos de scraping, automatizaciones puntuales y ejecuciones de CI.
- Persistente: duradero, con un perfil sincronizado con el vault (cookies, localStorage, huella digital), facturación mensual y sesiones bajo demanda. Ideal para agentes de larga duración que mantienen la sesión iniciada entre ejecuciones.
Todos los endpoints están bajo https://browsa.io. Autentícate con X-API-Key: agt_live_…. Consigue una con un registro gratis (100 créditos al verificar tu correo, sin tarjeta) y luego crea claves en el panel.
Inicio rápido
Dos formas de empezar. La mayoría quiere la primera.
1. Extrae una página (sin agente, sin LLM)
Un POST devuelve la página como Markdown limpio y enlaces, renderizada en un navegador real. 1 crédito, sin clave de LLM, y la respuesta HTTP son los datos.
# 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. Controla tú el navegador: Playwright por CDP
Tres líneas hasta un navegador en la nube que controla tu código. Crea un navegador desechable y conecta Playwright/Puppeteer a la URL cdp_http que devuelve, con tu clave en un encabezado X-API-Key. Sin infraestructura ni ajustes de huella digital.
# 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());Eso es todo. El agente se destruye cuando el TTL llega a cero (o cuando lo eliminas con DELETE). Pagas el tiempo que funcionó: 1 crédito por cada bloque de 12 minutos iniciado, 5 créditos por una hora completa. Al iniciarlo se retiene el precio del TTL que pediste (1 crédito hasta 5 minutos, 5 créditos por encima); los bloques que no usa vuelven cuando termina.
Autenticación
Cada solicitud necesita una clave de API en el encabezado X-API-Key. Las claves se crean en el panel y tienen la forma agt_live_ seguido de 24 caracteres hexadecimales.
X-API-Key: agt_live_aabbccddeeff001122334455También se admite la autenticación Bearer (con la misma clave) para clientes que siempre envían el encabezado Authorization.
Mantén tus claves en secreto. El secreto completo se muestra una sola vez al crear la clave. Solo guardamos sha256(secret). Si se filtra una clave, revócala desde el panel y crea una nueva.
Idempotencia
Todos los endpoints POST /v1/quick/*, POST /v1/tasks, POST /v1/auto y POST /v1/sessions/{id}/messages aceptan un encabezado Idempotency-Key (compatible con Stripe). POST /v1/agents no: cada llamada inicia, y factura, un navegador nuevo. Pasa un UUID por cada solicitud lógica y la plataforma guarda en caché la respuesta completa durante 24 h. Un reintento con la misma clave devuelve el cuerpo en caché byte a byte con Idempotent-Replay: true: no se crea un segundo navegador desechable ni hay un segundo cargo.
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"}'Úsalo en cualquier reintento automático de tu librería cliente (p. ej., requests.Session con backoff). Sin él, un fallo de red pasajero puede volver a ejecutar el scraping y cobrarse dos veces.
IDs de solicitud
Cada respuesta (de éxito o de error) lleva un encabezado X-Request-Id. Los errores también incluyen request_id en el cuerpo JSON. Indícalo al escribir a support@browsa.io por cualquier incidencia, para que encontremos tu solicitud en nuestros logs.
SDKs
Wrappers sin dependencias de la API REST, con respuestas tipadas, long-poll con waitForJob, verificación de firmas HMAC de webhooks y el formato de error completo {code, error, request_id} convertido en errores tipados. La misma interfaz en Python y 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)Paquete: browsa en PyPI (Python 3.9+, sin dependencias, 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);Paquete: browsa en npm (Node 18+, sin dependencias, ESM + CJS, .d.ts completo, MIT).
Servidor MCP: Claude Desktop, Cursor, Cline
Controla la plataforma desde cualquier cliente compatible con MCP con un solo bloque de configuración. El agente obtiene 13 herramientas: 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.
La configuración no necesita ningún secreto de LLM. Guarda una clave de LLM en tu espacio de trabajo y el servidor probará primero tu clave guardada por defecto. BROWSA_LLM_API_KEY es opcional. Sin clave guardada y sin llm definido, las tareas pasan al nivel alojado por defecto de Browsa ("llm": "browsa", que suma los créditos por tarea de ese nivel), y el servidor lo indica. Un llm explícito sin clave devuelve LLM_KEY_REQUIRED. Define BROWSA_LLM_KEY_ID para elegir una clave guardada concreta.
{
"mcpServers": {
"browsa": {
"command": "npx",
"args": ["-y", "@browsa/mcp"],
"env": {
"BROWSA_API_KEY": "agt_live_..."
}
}
}
}Pon esto en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) y reinicia Claude Desktop. Pregunta: "Ve a news.ycombinator.com y dime el título de la noticia principal."
Paquete: @browsa/mcp en npm (funciona en Claude Desktop, Cursor, Cline, Continue y Zed; MIT). Configuración para Claude Code, Cursor y VS Code: guía del servidor MCP.
Ejemplos
Las páginas de los paquetes incluyen un inicio rápido y un receptor de webhooks: Python en PyPI, TypeScript en npm. Para scripts completos, consulta las recetas y las guías de frameworks.
Especificación OpenAPI
Impórtala en Postman, Insomnia, Swagger UI o cualquier cliente OpenAPI 3.1. La especificación completa está publicada en 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