Versioning & changelog

The Browser Agent API lives under /api/v1. Within v1, Banana Peel does not ship breaking changes: code written against today's contract keeps working. Evolution happens additively, and anything that would break existing integrations would ship under a new path version instead (none has ever been needed).

What counts as breaking

Removing or renaming a response field, endpoint, or accepted request parameter.
Changing the type or meaning of an existing field (e.g. units, null-ability).
Tightening validation so a previously accepted request starts failing (fail-free validation additions that reject never-worked garbage earlier are not breaking).
Repurposing an existing error code or status mapping.

What is additive (expect it without notice)

New response fields — including new keys under banana_peel. Parse what you know, ignore what you don't.
New enum values: statuses, reason codes, webhook event types, error codes, routing values. Write tolerant clients — treat an unknown status as "not one I handle specially", never as a parse error.
New endpoints, new optional request parameters, new query filters.
New webhook event types (your endpoint already receives only the events it subscribed to).

Deprecation

If a field or behavior is ever deprecated, it keeps working for at least 90 days after the deprecation is announced in this changelog, and its reference entry (OpenAPI + llms.txt) is marked deprecated for the whole window. Removal only happens with a new path version.

The date-based `api_version`

The current public API version is 2026-08-13. It is stamped on every webhook event envelope (api_version), reported as the OpenAPI info.version, and echoed under x-banana-peel.api_version in /openapi.json. The date advances when payload shapes change meaningfully; it is informational — do not hard-fail on an unexpected value, and do not expect a bump for purely additive fields. There is no per-request version pinning header: /v1 itself is the compatibility contract.

How changes are announced

This page's changelog is the canonical record of API changes. The machine-readable surfaces — /openapi.json, /llms.txt, and the agent guide — are generated from the same source as the API and update with every deploy, so agents re-reading them always see the current contract. Operational incidents are separate — see /status.

Changelog

2026-08-27 — Default LLM backend is now Gemini 2.5 Pro (additive). Runs that pin nothing (no combo slug, no llm field) now use gemini-2-5-pro for extraction and the act-observe loop (previously gemini-2-5-flash); token cost is priced at Pro's published rates ($1.25 / $10.00 per 1M). Pinned selections are untouched: combo slugs, explicit model ids, and bare provider names (llm: "gemini" still resolves to gemini-2-5-flash). The provider availability-fallback order for unpinned runs is unchanged. extraction_model / engine labels on shared-extraction runners now always name the model that actually served the run. See Framework + LLM.
2026-08-27 — Multi-entity orchestration disabled — all tasks run as single runs. POST /api/v1/long-tasks now returns 403 with the new documented error code feature_disabled — submit each task individually via POST /api/v1/responses (smart routing treats every task the same; an explicit multi-entity request is never silently converted into a single run). Historical lt_… objects stay fully readable: GET /api/v1/long-tasks, …/:id, …/:id/runs, console rows/detail, and sub-run parent_id / entity_id / role fields keep working, and GET /v1/runs keeps its exclude_children=true default. Any still-moving task is drained to cancelled with its delivered-entity ledger preserved (none were in flight at the switch). long_task.* webhook types remain accepted subscription values but no longer fire. /v1/responses behavior is unchanged — multi-entity-looking text still runs as a normal single run with the informational banana_peel.scale_hint echo (there was never auto-promotion), and single-run time semantics (time_budget_ms / uncapped) are untouched. See Long tasks (disabled).
2026-08-24 — Compare tool removed. The console Compare tool and its console-only dispatcher (POST /api/live/run) were removed; the dispatcher now returns 404. Neither was part of the /v1 contract (both were documented console-only), so no /v1 integration is affected. Routing modes smart / learning / learning-all remain fully available via POST /api/v1/responses and MCP. Runs previously made from Compare stay visible on the console Runs page and in usage history.
2026-08-19 — Long-task enumeration acceptance policy (additive). The evidence bar for accepting an entity list now scales with the claimed count, and verified work is never discarded at retry exhaustion. New enum values: manifest.verification.method gains sampled(a large claimed list — beyond one viewport, >~12 entities — was confirmed by a spot-check sub-task navigating to randomly chosen claimed ids in-session; normal confidence) and exhaustion_union (retries exhausted with verified entities held → the union across attempts was accepted at low_confidence: true and fanned out open-world); sub-run role gains verification; new audit events sampling_dispatched and manifest_accepted_at_exhaustion. Verification evidence is strictly from the present session — historical counts never confirm or reject a current list. See Long tasks.
2026-08-19 — Encryption upgrade (no API changes): vault secrets, run artifact bytes, and stored screenshots moved to Cloud KMS envelope encryption — per-secret/per-object data keys wrapped by dedicated KMS keys with automatic 90-day rotation. Ciphertext is versioned; pre-upgrade data keeps reading and existing vault secrets were rolled forward. Artifact downloads now always stream through the authenticated endpoint (no direct signed URLs for encrypted objects). Response and webhook payload shapes are unchanged. See Encryption.
2026-08-19 — Long-task chunked dispatch (additive). Fan-out sub-tasks may now carry a chunk of ~2–6 pending entities (one login amortized over N fetches; N adapts per domain from learned per-entity pace). Caller-visible: chunk members share one run_id in entities[], a new chunk_dispatched event type appears in the audit log, and partial chunk deliveries bank per entity (a chunk delivering 4/6 banks 4; only the gap is retried). Sub-task instruction/event shapes for single-entity dispatches are unchanged. See Long tasks.
2026-08-19 — Long-task sub-run visibility, one behavior change and three additions. Behavior change: GET /v1/runs now defaults to exclude_children=true — long-task sub-runs are omitted from the top-level list (a single fan-out otherwise makes the flat list unusable). Pass exclude_children=false to restore the interleaved view. Additions: sub-run objects expose banana_peel.parent_id, entity_id, and role (enumeration | entity_fetch); GET /v1/runs?parent_id=lt_…filters to one task's children; new GET /v1/long-tasks/:id/runs lists them oldest-first with manifest entity labels. Long-task objects also gained manifest.verification {method, confidence, low_confidence} on the object itself. See Runs & history and Long tasks.
2026-08-19 — banana_peel.routing_summary: every brain-routed response envelope (and the response.completed / response.failed webhook payloads, which embed the same object) now carries a compact "why was it routed there" summary — runner, strategy, reason code, one redacted plain-words sentence, per-attempt fault attribution, policy version, a budget-widening echo, and the path to the full decision card. In-flight polls carry the base (planned primary + reason); the terminal object is complete. Additive. See Create a response and Routing explanations.
2026-08-19 — Multi-entity long tasks: POST/GET /v1/long-tasks, GET /v1/long-tasks/:id, POST /v1/long-tasks/:id/cancel — Enumerate → Fan-out → Reconcile orchestration with a per-entity ledger and first-class partial_complete. Five new webhook event types (long_task.progress / interaction_required / completed / partial / failed) and three new error codes (long_task_not_found, not_multi_entity, invalid_expected_entities). Plain /v1/responses runs whose text looks multi-entity now carry banana_peel.scale_hint: "multi" (no auto-promotion — single-shot behavior is unchanged). All additive. See Long tasks.
2026-08-19 — GET /v1/runs grew cursor pagination (starting_after, has_more, next_starting_after) and filters (status, runner, routing, created_after / created_before). Additive; the previous limit-only contract still works. See Runs & history.
2026-08-18 — time_budget_ms (alias timeout_ms): caller-controlled run time budget for smart / category / learning routing, echoed under banana_peel.time_budget_ms. In the same change, smart / category / learning runs without a budget became UNCAPPED by default — no fixed run ceiling; a dead-executor watchdog and a 24h safety ceiling still apply. Pinned-runner and chain routing keep the legacy hard TTL (default 20 min) and reject time_budget_ms with a fail-free 400. The run_timeout error copy is now contract-aware — see Errors.
2026-08-13 — current api_version date: webhook event envelopes (banana_peel.event) with signed delivery, per-response sequence, and Retry-After on every 429.