Create a response

POST /api/v1/responses starts a browser-agent run. Default routing: "smart" is production — the router uses the brain to pick and fall back. routing: "learning" and "learning-all" exist to teach the router the best path: they calibrate the brain on a domain/task so later smart runs pick the winning runner (paid calibration; not the production default). The response is OpenAI-compatible, with Banana Peel details under banana_peel — runner used (the runnerfield), ranking chain, timing, cost, session links, and artifacts. The same keys appear for every runner (null when a field doesn't apply). For OpenAI SDK baseURL / streaming notes see OpenAI Responses compatibility.

export BANANA_PEEL_BASE=https://bananapeel.com
export BANANA_PEEL_API_KEY=bp_live_…

curl -s "$BANANA_PEEL_BASE/api/v1/responses" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "banana-peel",
    "input": "Extract the title from https://example.com",
    "routing": "smart"
  }'

SLA profile

On routing: "smart", sla_profile shifts how the router weighs cost, speed, and block-avoidance against success probability. It does not pin a runner and has no effect on named-runner, chain, category, or Learning routing.

• balanced (default) — mix of success rate, cost, and speed.
• cheapest — prefer lower expected cost; a proven-but-pricey runner can lose the primary slot.
• fastest — prefer lower expected latency.
• most_reliable — prefer success probability and block-avoidance; a pricey winner can keep the primary slot.

Field table below is generated from OpenAPI. More on scoring: Smart routing.

Fallback count (max_fallbacks)

On routing: "smart", max_fallbacks is how many additional runners may run after the first pick (1 + N). The default is 5 — up to six attempts unless spend, time, or a repeating-error breaker stops earlier. Pass 0 to pin to the first choice only. Values must be integers from 0 to 12; a malformed value fails free with 400 invalid_max_fallbacks. Staggered race still starts the primary first; this knob is the re-route depth, not an all-at-once launch.

Spend ceiling (max_cost_usd)

The spend rules in one place: every executed attempt bills — including failed attempts and parallel or staggered fallbacks. On routing: "smart" the router launches up to max_fallbacks additional runners after the primary (default 5, so up to six billable attempts), and when the planned set exhausts with spend headroom left, budget-governed widening can dispatch further attempts one at a time — widened attempts bill like any other and respect the same max_cost_usd ceiling (a widened dispatch is only chosen while its expected cost fits the remaining headroom, and the widening steps are disclosed in the routing summary). Real cost can therefore climb well past a single attempt's price; max_cost_usd is the hard bound on all of it.

max_cost_usd caps what a single run may spend, in every routing mode. Once the attempts that already executed reach the ceiling, no new attempts, waves, batches, or widening dispatches are launched; attempts still in flight finish and bill. The run then ends honestly with error code budget_exhausted and partial results under banana_peel.routing_attempts. Learning runs (paid calibration to teach the best path) default to a $20 ceiling (learning-all defaults to $20) when max_cost_usdis omitted (an explicit value overrides the default in either direction); smart runs are additionally bounded by the routing plan's own pre-flight budget. The ceiling that governed dispatch is echoed under banana_peel.budget (max_cost_usd, source, exhausted), and POST /api/v1/estimate reflects it before you run. A malformed value fails free with 400 invalid_max_cost_usd.

Time budget (time_budget_ms) — uncapped by default

time_budget_ms is an optional run time ceiling for routing: "smart", "category", "learning" and "learning-all". When set, it governs the whole run: smart attempts share the window (a doomed primary cannot burn all of it), learning sweeps stop dispatching new batches once it elapses (in-flight attempts finish and bill, same contract as the spend ceiling), and the run is expired at budget + a 10-minute grace if the worker never persists a terminal state. Minimum 30000 (30 s); there is no upper bound. A malformed value fails free with 400 invalid_time_budget_ms; pinned runner/chain routing rejects the parameter with 400 time_budget_unsupported. timeout_ms is accepted as an alias.

When omitted, the run is uncapped: no run-level deadline exists and orchestration never cuts a working attempt to satisfy a global clock — attempts defer to each runner's own leash (e.g. Skyvern's ~6.5-minute poll budget) and the per-attempt watchdog, so the fallback chain still advances past a stuck runner. Uncapped does not mean unprotected: the no-progress watchdog, repeating-error detection, and runner probation stay fully active, and the lifecycle reaper still expires runs whose executor died (no progress heartbeat for the whole mode-aware window) plus an absolute 24-hour safety ceiling. Spend ceilings (max_cost_usd) are independent and unchanged.

Use background mode for uncapped runs.A synchronous or streaming request is still bounded by the platform's HTTP request timeout — an uncapped run should be created with background: true (or Prefer: respond-async) and polled / webhooked to terminal. The active contract is echoed on every response as banana_peel.time_budget_ms (the number when set; null plus uncapped: true when uncapped).

Background execution

Browser jobs often take several minutes. Pass background: true (or Prefer: respond-async) to get HTTP 202 with status: "in_progress" and an id. Polling GET /api/v1/responses/:id until terminal is fine for v0. At production scale, register outbound webhooks and let Banana Peel POST response.completed / .failed / .cancelled / response.requires_action (HMAC-signed) so you are not sitting on GET. Polling remains valid.

Idempotency

Send an Idempotency-Key HTTP header (Stripe / IETF style; header names are case-insensitive) or idempotency_key on the JSON body — they are equivalent. If both are present they must match; different values fail free with 400 idempotency_key_mismatch. Keys are up to 255 characters, scoped to your workspace, shared across every run-creating endpoint (/v1/responses, /v1/messages, and the provider-compatible wrapper creates), honored on every create mode (default sync, background: true / Prefer: respond-async, and stream: true), and expire 24 hours after first use.

• Replay (same key, same request). The key is reserved before dispatch and bound to the run it creates, together with a fingerprint of the request body (the key itself and the delivery-mode fields stream / background are excluded — a request keyed via header or via body fingerprints identically). Reusing the key with an identical body returns the original run — original created_at, current state (200 when terminal, 202 while still running, failures included) — and never starts a duplicate. Replays carry Idempotent-Replayed: true and echo Idempotency-Key in the response headers.
• Conflict (same key, different request). Reusing a key with a different body within its 24h window is refused with 422 idempotency_conflict — it almost always means a retry loop is mutating its payload. Use a fresh key for the new request, or resend the exact original body to replay. Nothing is created or billed.
• Concurrent duplicates. Once the run exists, duplicates replay it (202 while in flight). A duplicate that lands during the brief admission window — after the key is reserved, before the run row is persisted — is refused with 409 idempotency_in_flight plus Retry-After: 1; resend the identical request to receive the original run.
• Failed creates don't consume keys. A create refused before its run exists (validation, insufficient credits, custody, capacity 429s) releases the key, so an honest retry with the same key succeeds.

Scope notes: the Browserbase-compatible Sessions proxy (/api/v1/sessions) is a pass-through to the upstream Sessions API — it creates browser sessions, not runs, so run idempotency does not apply there. Keys attached to runs created before this feature shipped replay without fingerprint verification (there is nothing stored to verify against).

Canonical banana_peel fields

Every response includes a banana_peelenvelope (nulls OK when a field doesn't apply). The generated tables above are the field contract; this list is the conceptual map.

• banana_peel.answer / answer_present / evidence — the guaranteed read path. Runners name output keys differently run to run; answer is the stable distilled answer string (null only when no answer was delivered), answer_present says whether the requested answer was actually delivered, and evidencecarries the verdict reason, final URL, and artifact names. A legitimate empty result ("0 orders", "No Order History Found") IS a delivered answer: status: succeeded with answer_present: true. A hollow completion (output that only narrates login/click steps without the requested value) is status: failed with answer_present: false— terminal status follows the delivery verdict, never the runner's mechanical exit code, and routing learns from the same verdict-based labels
• banana_peel.session — id / live_url / replay_url / connect_url (nulls OK). Metadata about the browser the run used — not a standalone session you manage
• banana_peel.artifacts, steps, cost, fallback_from
• banana_peel.ranked_runners — runners considered for smart/category
• confidence / banana_peel.confidence — quality score when graded (null otherwise)
• banana_peel.ran_in — compliance pool when routing was SOC2 / HIPAA / EU
• banana_peel.routing_summary— compact "why was it routed there" echo on brain-routed runs (see below)

Routing summary (why this runner)

Every brain-routed response carries a compact banana_peel.routing_summary: the executed runner, the explore/exploit strategy, the machine reason code, one redacted plain-words sentence (the same headline the console decision card shows), the routing policy version, per-attempt fault attribution, a budget-widening echo when the run widened past the planned set, and the path to the full decision card. In-flight polls carry the honest base (planned primary + decision reason); the terminal object adds attribution, policy version, and widening. Pinned single-runner routing has no decision to explain, so the field is absent — same rule as the explanation endpoint.

"banana_peel": {
  "routing_summary": {
    "runner": "stagehand",
    "strategy": "exploit",
    "reason": "exploit_expected_utility",
    "summary": "Router picked stagehand on expected utility for this request…",
    "policy_version": "bandit-v1",
    "attempts": [
      { "runner": "browserbase", "status": "failed", "attribution": "runner" },
      { "runner": "stagehand", "status": "succeeded", "attribution": "runner" }
    ],
    "widening": { "dispatches": 1, "stop_reason": null },
    "explanation": "/api/v1/responses/resp_…/explanation"
  }
}

The summary sentence and every text-bearing field pass through the platform redaction pass before they leave the API. For the full card — candidate table with expected-utility decomposition, site-defense profile, widening steps and stop reasons, per-attempt rewards — fetch GET /api/v1/responses/{id}/explanation or read Routing explanations. The same object is embedded in response.completed / response.failed webhook payloads.

Output normalization (+$0.10)

Pass normalize: true with an output_schema (JSON Schema or property map) to reshape the runner result after the run. Also accepts OpenAI text.format / response_format schemas. Build the schema visually in Console → Normalize. Adds a flat $0.10 on top of runner cost + platform fee for that run (every executed run is billed — not success-only). Preview cost without running via POST /api/v1/estimate (same body; returns likely_runner + catalog total).

curl -s "$BANANA_PEEL_BASE/api/v1/responses" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "banana-peel",
    "input": {
      "url": "https://example.com/orders",
      "goal": "Extract the latest order",
      "success_criteria": "an order_id is present"
    },
    "routing": "smart",
    "normalize": true,
    "output_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "total": { "type": "string" }
      },
      "required": ["order_id", "total"]
    }
  }'

Whenever normalization was requested, the response confirms what actually happened under banana_peel.normalization (also on GET /api/v1/responses/{id} when polling):

"banana_peel": {
  "normalization": {
    "requested": true,
    "applied": true,
    "reason": null,
    "addon_usd": 0.1
  }
}

• applied: true — the Output normalization pass ran and the +$0.10 add-on was billed (banana_peel.billing.normalization_usd matches).
• applied: false — the pass did not run; reason says why (e.g. the run failed before normalization, or the pass errored) and addon_usd is 0 — you are not charged for a pass that never executed.
• The field is absent when normalization was not requested.

output_schema is a hard contract

When you supply an output_schema (directly, or via text.format / response_format), the terminal output must populate exactly those keys: every required key present and non-empty with the declared type, and no undeclared extra data keys unless your schema sets additionalProperties: true (run metadata like url / final_url is tolerated). A run whose output cannot satisfy the contract terminates status: "failed" with error.code: "schema_violation" and the violations listed in error.message — Banana Peel never bills-and-claims-success on drifted keys. The nonconforming output stays under banana_peel.output for inspection; runner attempts that executed still bill (same as any failed run) but the +$0.10 normalization add-on is dropped. Without a schema, read the stable default envelope instead: banana_peel.answer / answer_present / evidence.

Multi-account portals

Account-scoped value asks ("amount due", "balance", bills, usage) against portals that can hold several accounts (telco/utility dashboards, e.g. Videotron or Hydro-Québec) are automatically instructed to enumerate all accounts/profiles/contracts first and answer with a structured per-account array (accounts: [{"account_label", …}]) instead of a single scalar from whichever account the agent landed on. If you pinned an output_schema, your schema owns the shape and this guidance is not injected — declare an array field yourself when you expect several accounts.

Multi-entity jobs — orchestration disabled

Multi-entity long-task orchestration is disabled: POST /api/v1/long-tasks returns 403 feature_disabled, and every task — including "download the latest bill for ALL properties"-style jobs — runs as a single run right here. For a job that spans several entities, loop client-side and create one response run per entity (an idempotency_key per entity keeps retries from double-running). A task whose text looks multi-entity is never rejected on this endpoint; it runs single-shot and its envelope carries the informational banana_peel.scale_hint: "multi" flag. Previously created lt_… objects stay readable — see Long tasks (disabled).

Live progress while in flight

For background: true runs, each poll of GET /api/v1/responses/{id} exposes live progress under banana_peel.progress while the status is in_progress / requires_action: runner attempts so far, the current Learning batch, and runner spend to date. On the terminal object it is superseded by banana_peel.routing_attempts.

"banana_peel": {
  "progress": {
    "attempts": [
      { "runner": "browserbase", "status": "failed", "started_at": "…", "finished_at": "…", "cost_usd": 0.04 },
      { "runner": "steel", "status": "running", "started_at": "…" }
    ],
    "attempts_started": 2,
    "attempts_finished": 1,
    "batch": { "current": 1, "total": 4, "size": 5 },
    "spend_usd": 0.04,
    "updated_at": "…"
  }
}

Cancel a run

POST /api/v1/responses/{id}/cancel stops an in-flight run (OpenAI-compatible — returns the response object with status: "cancelled"). Especially useful for Learning-mode batch probes, which bill every attempt.

curl -s -X POST "$BANANA_PEEL_BASE/api/v1/responses/$ID/cancel" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY"
# → { "id": "resp_…", "status": "cancelled", … }

• Runner attempts that already executed still bill (every-attempt billing); no new attempts or Learning batches start after the cancel.
• In-flight upstream attempts are aborted best-effort where the adapter supports it (e.g. Skyvern); otherwise they finish server-side without further billing.
• Cancelling an already-finished run is a no-op — the object is returned unchanged.
• Independently of cancel, no run sits at in_progress forever: runs with a time_budget_ms are expired at budget + a 10-minute grace; uncapped smart/learning-family runs (the default — see Time budget) are expired only when their executor provably died (no progress heartbeat for the whole mode-aware window) or at the 24-hour safety ceiling; pinned runner/chain runs keep the legacy hard TTL (default 20 minutes). Expired runs are marked failed with error code run_timeout.

Validation fails free

Structurally unusable requests are rejected with a 400 and a machine-readable error.code before any runner attempt starts, so nothing bills: missing_input (no task text or URL), missing_url (routing: "learning" / "learning-all" without a resolvable target URL — Learning modes need a domain to teach the brain against), invalid_output_schema / missing_output_schema (normalization requested but unusable). Prose-only tasks where the runner finds the site itself remain valid on all other routing modes.

MFA / OTP / human input

Full guide: MFA / OTP. When a target site asks for MFA, 2FA, or an OTP, the run pauses immediately and asks the user for the code. It does not keep trying other runners.

CAPTCHA and other bot-detection gates (reCAPTCHA, hCaptcha, Turnstile, DataDome, Cloudflare challenge, “prove you are human”) are solved, re-routed, or end blocked with reason bot_challenge. They never become a human text prompt.

Poll GET /api/v1/responses/:id until status is requires_action (or handle the response.requires_action webhook). MCP create_response waits until that pause and returns human_action_required plus required_action. Use background: true so you receive the id immediately, then poll and answer:

curl -s "$BANANA_PEEL_BASE/api/v1/responses" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "banana-peel",
    "input": "Log into https://example.com and download the latest invoice",
    "routing": "smart",
    "background": true,
    "credential_id": "cred_…"
  }'
# → { "id": "resp_…", "status": "in_progress", … }

• Outer status requires_action + required_action.type = submit_input (kind: otp | text | confirm, channel: totp | sms | email | unknown, plus submit.method / submit.path).
• Submit the code with POST /api/v1/responses/{id}/input { "code": "123456" } (or { "answer": "…" } for text/confirm). MCP: submit_input({ id, code }). Then keep polling until completed or failed. The secret is not echoed and is cleared after the agent consumes it.
• If the vault credential (or request totp_secret) includes a base32 TOTP seed, OTP asks are answered in-process and the run does not pause. Username/password alone is not enough — the run still pauses for the code.
• allow_interaction has three effective states (the wire format stays a boolean). Omitted: interaction is permitted whenever the executing runner supports the relay — runs on non-relay runners still work and simply never pause. false: never interact — a run that hits an MFA wall ends with a blocked verdict instead of pausing for input. true: interaction capability is REQUIRED — the run declares it will need mid-run input, and runners that cannot relay questions (hosted vendor agents executing on their own infrastructure) are refused up front rather than running to a dead end.
• For login flows end to end (vault credentials, TOTP, what pauses and what doesn't), see Auth flows. At production scale, register outbound webhooks and handle response.requires_action instead of spinning GET — polling still works.

The full request/response contract is in the OpenAPI spec; what each runner can return is in the capability matrix.