انتقل إلى المحتوى
Browsa
الأقسام

RESThttps://browsa.io/v1

Browsa API

متصفحات سحابية لوكلاء الذكاء الاصطناعي. شغّل Phantom، متصفحنا الخاص، في السحابة باستدعاء API واحد وتحكّم فيه عبر Playwright أو Puppeteer أو CDP المباشر. أو صِف المهمة بلغة بسيطة ويتولى الوكيل الباقي.

llms.txt مواصفات OpenAPI

أول استدعاء في ثلاث خطوات

  1. احصل على مفتاح

    تسجيل مجاني: 100 رصيد عند تأكيد بريدك الإلكتروني، بلا بطاقة. تبدأ المفاتيح بـ 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 دقائق إلى ساعة، يُدمّر نفسه، ويُحاسَب على الدقائق التي عملها. الأنسب لمهام الاستخراج، والأتمتة لمرة واحدة، وتشغيلات CI.
  • دائم: ملف تعريف ثابت متزامن مع الخزنة (ملفات تعريف الارتباط وlocalStorage والبصمة)، يُحاسَب شهريًا، وتُفتح جلساته عند الطلب. الأنسب للوكلاء طويلي التشغيل الذين يحافظون على حالة تسجيل الدخول بين التشغيلات.

كل نقاط النهاية تحت https://browsa.io. صادِق باستخدام X-API-Key: agt_live_…. احصل على مفتاح عبر تسجيل مجاني (100 رصيد عند تأكيد بريدك الإلكتروني، بلا بطاقة)، ثم أنشئ المفاتيح من لوحة التحكم.

بداية سريعة

طريقتان للبدء. معظم المستخدمين يريدون الأولى.

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 بعنوان 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). من دونه، قد يؤدي انقطاع عابر في الشبكة إلى إعادة تنفيذ الاستخراج والمحاسبة مرتين.

معرّفات الطلبات

تحمل كل استجابة (نجاح أو خطأ) ترويسة X-Request-Id، وتتضمن رسائل الخطأ أيضًا request_id في جسم JSON. اذكره عند مراسلة support@browsa.io بشأن أي مشكلة، لنجد طلبك في سجلاتنا.

حزم SDK

مغلّفات بلا اعتماديات حول REST API، مع استجابات محددة الأنواع، وwaitForJob بالاستطلاع الطويل، والتحقق من توقيع HMAC لـ Webhook، وتحويل غلاف الأخطاء الكامل {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.

أمثلة

تعرض صفحات الحزم بداية سريعة ومستقبِل Webhook: 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