Перейти к содержимому
Browsa
Разделы

RESThttps://browsa.io/v1

Browsa API

Облачные браузеры для ИИ-агентов. Запустите Phantom, наш собственный браузер, в облаке одним вызовом API и управляйте им через Playwright, Puppeteer или чистый CDP. Или опишите задачу обычными словами, а остальное сделает агент.

llms.txt Спецификация OpenAPI

Первый вызов за три шага

  1. Получите ключ

    Бесплатная регистрация: 100 кредитов после подтверждения email, без карты. Ключи выглядят так: agt_live_….

    Получить API-ключАутентификация

  2. Сделайте первый вызов

    Скрейпинг страницы одним POST. 1 кредит, без ключа LLM.

  3. Посмотрите результат

    HTTP-ответ и есть данные. Дальше: управляйте браузером через Playwright или запустите ИИ-задачу.

# 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"]}'
Ответ 200
{
  "markdown": "...",
  "links": [...],
  "http_status": 200
}

Два режима, один эндпоинт

  • Одноразовый: временный, TTL от 5 мин до 1 часа, самоуничтожается, оплачиваются минуты работы. Подходит для скрейпинга, разовых автоматизаций и CI.
  • Постоянный: долговечный профиль, синхронизируемый с хранилищем (cookies, localStorage, отпечаток), помесячная оплата, сессии открываются по запросу. Подходит для долгоживущих агентов, которые должны оставаться залогиненными между запусками.

Все эндпоинты находятся под https://browsa.io. Аутентификация: X-API-Key: agt_live_…. Ключ доступен после бесплатной регистрации (100 кредитов после подтверждения email, без карты), а новые ключи создаются в дашборде.

Быстрый старт

Два способа начать. Большинству нужен первый.

1. Скрейпинг страницы (без агента и LLM)

Один POST возвращает страницу в виде чистого Markdown и ссылок, отрисованную в настоящем браузере. 1 кредит, без ключа LLM, HTTP-ответ и есть данные.

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. Управляйте браузером сами: 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"}'

Вот и всё. Агент уничтожается, когда TTL доходит до нуля (или когда вы удаляете его через DELETE). Вы платите за время работы: 1 кредит за каждые начатые 12 минут, 5 кредитов за целый час. При запуске резервируется цена запрошенного TTL (1 кредит до 5 минут, 5 кредитов свыше); неиспользованные блоки возвращаются по завершении.

Аутентификация

Каждому запросу нужен API-ключ в заголовке X-API-Key. Ключи создаются в дашборде и выглядят как agt_live_ и 24 шестнадцатеричных символа.

HTTP
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
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 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)

Пакет: browsa на PyPI (Python 3.9+, без зависимостей, MIT).

TypeScript / Node

Терминал
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);

Пакет: 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, чтобы выбрать конкретный сохранённый ключ.

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