Banana Peel
Get API key

Browser Agent API

Banana Peel API

Banana Peel is an OpenAI-compatible API for browser agents backed by 250+ executable runner combinations across 50+ single runners — hosted agents, infrastructure providers, extraction engines and OSS frameworks. Send a task, set routing, and it runs on the runner most likely to succeed. You get back a Responses-shaped result with the executing runner, timing, cost, and any fallbacks.

Base URL

Production host (no trailing slash):

https://bananapeel.com

Set BANANA_PEEL_BASE to that value. There is no separate api.* subdomain — the API lives on the canonical host above under /api/v1 (or your own deploy).

OpenAI SDK drop-in: set baseURL to https://bananapeel.com/api/v1, model banana-peel, and Authorization: Bearer bp_live_…. See OpenAI Responses compatibility. Anthropic Messages / Agent SDK: Anthropic adapter (baseURL → /api).

Long runs (often 60–420s): prefer { "background": true } or header Prefer: respond-async (HTTP 202). Poll GET /api/v1/responses/:id until terminal, or register outbound webhooks and receive signed response.completed / requires_action events (prefer webhooks at production scale). When a target site asks for MFA/OTP the run pauses immediately — poll until requires_action and POST /api/v1/responses/:id/input with { "code": "123456" }. Captcha never becomes a human prompt. OpenAI SDK streaming: stream: true (SSE). Send an Idempotency-Key header (or body idempotency_key) so a retried create after a dropped socket does not double-execute — identical retries replay the original run; a reused key with a different body is refused with 422 idempotency_conflict.

Output normalization (+$0.10 / run): pass normalize: true with an output_schema (or OpenAI text.format / response_format) to reshape the runner result after the run. Build schemas in Console → Normalize. Full example: Create a response → Output normalization.

Core endpoints

  • POST/api/v1/responses — start a browser-agent run (details; OpenAI SDK)
  • GET/api/v1/responses / /api/v1/responses/:id — list / fetch; DELETE:id purges copied artifacts (retention)
  • POST/api/v1/messages — thin Anthropic Messages adapter (docs)
  • POST/api/v1/estimate — dry-run cost (same body as create)
  • GET/api/v1/runs — list runs for your workspace (details)
  • POST/api/v1/credentials — store a vault credential; also GET list, PATCH / DELETE :id (details)
  • POST/api/v1/webhooks — outbound signed events; also GET list, PATCH / DELETE :id (details)
  • GET/api/v1/rankings — live runner benchmark (details)

Full endpoint index

  • POST/api/v1/responses/:id/cancel — cancel an in-flight run (returns the response with status: "cancelled")
  • GETPOST/api/v1/responses/:id/input — read the pending MFA/OTP prompt / submit the code when a run is requires_action
  • GET/api/v1/responses/:id/explanation — routing decision card (details)
  • GET/api/v1/responses/:id/artifacts/:artifactId — download a run artifact (screenshots, files) before it expires
  • GET/api/v1/long-tasks — historical multi-entity long tasks (orchestration is disabled: POST returns 403 feature_disabled — submit tasks individually via /api/v1/responses; details)
  • GET/api/v1/long-tasks/:id — historical long-task detail: per-entity table, counts, honest gap list, budget spend; POST:id/cancel (no-op on terminal tasks)
  • GET/api/v1/me — account identity for this API key (account_id, claim_url for unclaimed agent accounts)
  • GETPATCH/api/v1/workspace — document retention policy; PATCH (24h / 7d / 30d) is Enterprise-only (retention)
  • GET/api/v1/capabilities — capability matrix with per-runner live availability (details)
  • GET/api/v1/webhooks/:id/deliveries — delivery history (cursor paginated); GET :delivery_id, POST:delivery_id/retry, and POST/api/v1/webhooks/:id/rotate (secret rotation)
  • GET/api/v1/agent-signup/challenge + POST/api/v1/agent-signup — HTTP fallback for agent key minting (agent signup)
  • GET/api/status — public health probe (ratios only; powers /status)
  • Wrapper surfaces: /api/v1/sessions (Browserbase-compatible live sessions) and /api/wrappers/… (compatibility wrappers)

Authentication

Authorization: Bearer bp_live_…
# or
x-api-key: bp_live_…

Create keys in the console if you already have an account (optional). Agents should follow /docs/agents — npx -y @banana-peel/cli init --agent --json — and must not ask a human to create an account. Both header styles work on the Browser Agent API and wrappers.

Routing

  • smart — production; the router uses the brain to pick and fall back. Works out of the box on never-seen sites.
  • learning / learning-all — teach the router the best path (paid calibration — every executed attempt bills, $20 default ceiling). Recommended flow: calibrate a new domain/task with learning first, verify banana_peel.learning_ranking, then run production on smart. learning probes the live ~54-single-runner pool; learning-all sweeps the full catalog — do not use it for every production job. See Learning mode and the Quickstart.
  • browserbasesteelbrowser-useskyvernhyperbrowserplaywrightdeck

    Pin any runner by slug. Also anchor and other slugs from capabilities.

  • Fallback chain: ["browserbase", "steel", "skyvern"]
  • Category pools (SOC2, HIPAA, EU) — live today as fixed runner lists only; not full compliance attestation. See Categories.

Already on a provider SDK?

Keep your existing Browserbase, Steel, Browser Use, Skyvern, or Hyperbrowser client — point it at Banana Peel and get routing without rewriting your app. Browserbase uses /api/v1/sessions; the others use /api/wrappers/…. Note the session endpoints create a live browser you drive yourself over CDP, not a routed run — see Runs vs. sessions. For the full picture see compatibility wrappers or the machine-readable OpenAPI / YAML. Coding agents: start at For AI agents or /llms.txt.

Errors

Browser Agent API errors use { error: { message, type, code, param, doc_url, hint? } } — see Errors.

Command Palette

Search for a command to run...