Два режима, один эндпоинт
- Одноразовый: временный, TTL от 5 мин до 1 часа, самоуничтожается, оплачиваются минуты работы. Подходит для скрейпинга, разовых автоматизаций и CI.
- Постоянный: долговечный профиль, синхронизируемый с хранилищем (cookies, localStorage, отпечаток), помесячная оплата, сессии открываются по запросу. Подходит для долгоживущих агентов, которые должны оставаться залогиненными между запусками.
Все эндпоинты находятся под https://browsa.io. Аутентификация: X-API-Key: agt_live_…. Ключ доступен после бесплатной регистрации (100 кредитов после подтверждения email, без карты), а новые ключи создаются в дашборде.
Быстрый старт
Два способа начать. Большинству нужен первый.
1. Скрейпинг страницы (без агента и LLM)
Один POST возвращает страницу в виде чистого Markdown и ссылок, отрисованную в настоящем браузере. 1 кредит, без ключа LLM, HTTP-ответ и есть данные.
# 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. Управляйте браузером сами: Playwright по CDP
Три строки до облачного браузера под управлением вашего кода. Создайте одноразовый браузер, затем подключите Playwright/Puppeteer к полученному URL cdp_http с ключом в заголовке X-API-Key. Без инфраструктуры и настройки отпечатков.
# 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());Вот и всё. Агент уничтожается, когда TTL доходит до нуля (или когда вы удаляете его через DELETE). Вы платите за время работы: 1 кредит за каждые начатые 12 минут, 5 кредитов за целый час. При запуске резервируется цена запрошенного TTL (1 кредит до 5 минут, 5 кредитов свыше); неиспользованные блоки возвращаются по завершении.
Аутентификация
Каждому запросу нужен API-ключ в заголовке X-API-Key. Ключи создаются в дашборде и выглядят как agt_live_ и 24 шестнадцатеричных символа.
X-API-Key: agt_live_aabbccddeeff001122334455Поддерживается и Bearer-аутентификация (тот же формат ключа) для клиентов, которые всегда передают заголовок Authorization.
Храните ключи в секрете. Секрет показывается один раз при создании. Мы храним только sha256(secret). Если ключ утёк, отзовите его в дашборде и создайте новый.
Идемпотентность
Все эндпоинты POST /v1/quick/*, а также POST /v1/tasks, POST /v1/auto и POST /v1/sessions/{id}/messages принимают заголовок Idempotency-Key (совместим со Stripe). POST /v1/agents его не принимает: каждый вызов запускает и оплачивает новый браузер. Передавайте UUID на каждый логический запрос, и платформа кэширует полный ответ на 24 часа. Повтор с тем же ключом возвращает кэшированное тело байт в байт с Idempotent-Replay: true: второй браузер не создаётся, второго списания нет.
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"}'Используйте его для всех автоматических повторов в вашей клиентской библиотеке (например, requests.Session с backoff). Без него кратковременный сбой сети может повторно запустить скрейпинг и списать кредиты дважды.
ID запросов
Каждый ответ (успешный или с ошибкой) содержит заголовок X-Request-Id. В JSON ошибки также есть request_id. Указывайте его в письмах на support@browsa.io по любому инциденту, чтобы мы нашли ваш запрос в логах.
SDKs
Обёртки над REST API без зависимостей: типизированные ответы, long-poll waitForJob, проверка HMAC-подписи вебхуков и полный конверт {code, error, request_id}, преобразованный в типизированные ошибки. Одинаковый интерфейс в Python и 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)Пакет: browsa на PyPI (Python 3.9+, без зависимостей, 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);Пакет: browsa на npm (Node 18+, без зависимостей, ESM + CJS, полные .d.ts, MIT).
MCP-сервер: Claude Desktop, Cursor, Cline
Управляйте платформой из любого MCP-клиента одним блоком конфигурации. Агент получает 13 инструментов: 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.
В конфигурации не нужен секрет LLM. Сохраните ключ LLM в рабочем пространстве, и сервер сначала попробует ваш сохранённый ключ по умолчанию. BROWSA_LLM_API_KEY необязателен. Если сохранённого ключа нет и llm не задан, задачи выполняются на модели Browsa по умолчанию ("llm": "browsa", она добавляет свои кредиты за задачу), и сервер об этом сообщает. Явный llm без ключа возвращает LLM_KEY_REQUIRED. Задайте BROWSA_LLM_KEY_ID, чтобы выбрать конкретный сохранённый ключ.
{
"mcpServers": {
"browsa": {
"command": "npx",
"args": ["-y", "@browsa/mcp"],
"env": {
"BROWSA_API_KEY": "agt_live_..."
}
}
}
}Добавьте это в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows) и перезапустите Claude Desktop. Спросите: «Зайди на news.ycombinator.com и назови заголовок главной новости.»
Пакет: @browsa/mcp на npm (работает в Claude Desktop, Cursor, Cline, Continue, Zed, MIT). Настройка для Claude Code, Cursor и VS Code: руководство по MCP-серверу.
Примеры
На страницах пакетов есть быстрый старт и приёмник вебхуков: Python на PyPI, TypeScript на npm. Готовые скрипты: рецепты и руководства по фреймворкам.
Спецификация OpenAPI
Импортируйте в Postman, Insomnia, Swagger UI или любой клиент OpenAPI 3.1. Полная спецификация опубликована по адресу 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