Saltar al contenido
Browsa
Secciones

RESThttps://browsa.io/v1

API de Browsa

Navegadores en la nube para agentes de IA. Inicia Phantom, nuestro propio navegador, en la nube con una llamada a la API y contrólalo con Playwright, Puppeteer o CDP directo. O describe la tarea en lenguaje natural y el agente hace el resto.

llms.txt Especificación OpenAPI

Tu primera llamada en tres pasos

  1. Obtén una clave

    Registro gratis: 100 créditos al verificar tu correo, sin tarjeta. Las claves tienen la forma agt_live_….

    Obtén una clave de APIAutenticación

  2. Haz la primera llamada

    Extrae una página con un solo POST. 1 crédito, sin clave de LLM.

  3. Mira el resultado

    La respuesta HTTP son los datos. Siguiente: controla el navegador con Playwright o ejecuta una tarea 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"]}'
Respuesta 200
{
  "markdown": "...",
  "links": [...],
  "http_status": 200
}

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.

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. 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"}'

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.

HTTP
X-API-Key: agt_live_aabbccddeeff001122334455

Tambié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
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

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)

Paquete: browsa en PyPI (Python 3.9+, sin dependencias, 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);

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.

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

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