overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Browser Use Public API v4
  version: 1.0.0
x-provenance:
  generated: '2026-08-29'
  method: generated
  source: openapi/browser-use-api-v4-openapi.json
  note: >-
    Captures API Evangelist's enrichment of the harvested v4 contract without mutating it. Every value
    below is either restated from a Browser Use published document (cited inline) or a classification
    this pipeline made from the contract itself. Apply against
    openapi/browser-use-api-v4-openapi.json.
extends: openapi/browser-use-api-v4-openapi.json
actions:
  - target: $.info
    update:
      contact:
        name: Browser Use
        url: https://browser-use.com/developers
      termsOfService: https://browser-use.com/legal/terms-of-service
      x-status-page: https://status.browser-use.com
      x-changelog: https://browser-use.com/changelog
      x-llms-txt: https://browser-use.com/llms.txt
      x-pricing: https://browser-use.com/pricing.md
  - target: $
    update:
      x-mcp-server: https://api.browser-use.com/mcp
      x-agent-card: https://docs.browser-use.com/.well-known/agent-card.json
      x-webhooks-documented: https://browser-use.com/webhooks
      x-rate-limit-model: concurrency
      x-idempotency-key: none
  - target: $.paths['/runs'].post
    update:
      x-consequence: write
      x-billable: true
      x-reversible:
        operation: cancel_run_runs__run_id__cancel_post
        window: before the run reaches a terminal state
        source: openapi/browser-use-api-v4-openapi.json
      x-retry-safe: false
      x-retry-note: >-
        No idempotency key. A retried POST /runs after a dropped response can start and bill a second
        run.
  - target: $.paths['/browsers'].post
    update:
      x-consequence: write
      x-billable: true
      x-reversible:
        operation: update_browser_session_browsers__session_id__patch
        window: >-
          Stop at any time; unused reserved time is refunded, with a one-minute minimum and partial
          minutes rounded up.
        source: https://browser-use.com/pricing.md
      x-retry-safe: false
  - target: $.paths['/sessions/{session_id}/purge'].post
    update:
      x-consequence: destructive
      x-reversible: false
      x-human-in-the-loop: recommended
  - target: $.paths['/workspaces/{workspace_id}'].delete
    update:
      x-consequence: destructive
      x-idempotent: true
      x-idempotent-source: >-
        Operation description — "Idempotent for missing, archived, and foreign ids."
      x-reversible: unknown
      x-reversible-note: Archives rather than hard-deletes, but no restore operation or retention window is published.
  - target: $.paths['/workspaces/{workspace_id}/files'].delete
    update:
      x-consequence: destructive
      x-reversible: false
  - target: $.paths['/profiles/{profile_id}'].delete
    update:
      x-consequence: destructive
      x-reversible: false
      x-note: Deletes persistent authentication state (cookies, login sessions) that cannot be regenerated by the API.
  - target: $.paths['/runs/{run_id}/cancel'].post
    update:
      x-consequence: mitigating
      x-idempotent: true
      x-idempotent-source: >-
        Operation description — "a run already in a terminal state (completed / failed / cancelled) is
        returned as-is."
  - target: $.components.securitySchemes.APIKeyHeader
    update:
      description: >-
        Project API key issued at https://cloud.browser-use.com/settings?tab=api-keys&new=1. Keys are
        prefixed bu_. Scope is the whole project — Browser Use publishes no finer-grained REST scopes.
      x-key-prefix: bu_
      x-issued-at: https://cloud.browser-use.com/settings?tab=api-keys&new=1