Hyperbrowser X402 API

openapi: 3.2.0
info:
  title: Hyperbrowser X402 API
  version: 1.0.0
servers:
- url: https://api.hyperbrowser.ai
  description: Production server
tags:
- name: X402
paths:
  /x402/session:
    post:
      summary: Create a session with X402 payment
      description: Purchase one browser session at 0.10 USDC per hour, paid upfront for timeoutMinutes (5–60, default 30). No Hyperbrowser account or API key is required. A valid unpaid request returns 402 with payment requirements. Retry with a signed PAYMENT-SIGNATURE authorization. Payment is settled before connection credentials and a managementToken are returned. One authorization can create only one session. Invalid options are rejected before payment verification. See /integrations/x402/sessions for connection examples and lifetime behavior.
      security: []
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: Base64-encoded payment authorization generated by an X402 client from the advertised PAYMENT-REQUIRED requirements. Omit on the initial request to obtain a quote.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/X402SessionParams'
            examples:
              defaults:
                summary: Default 30-minute browser session
                value: {}
              customized:
                summary: Five-minute session with browser preferences
                value:
                  screen:
                    width: 1920
                    height: 1080
                  viewOnlyLiveView: true
                  timeoutMinutes: 5
      responses:
        '200':
          description: Browser created and payment settled. Use the returned connection details to control it without further X402 payments.
          headers:
            PAYMENT-RESPONSE:
              description: Base64-encoded JSON with settlement information.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402SessionResponse'
        '400':
          description: Invalid or unsupported request parameters or malformed payment proof. Invalid options are rejected before payment verification or reservation of the proof.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment is missing or invalid, or settlement failed. Connection credentials are not returned. On settlement failure, the server attempts to stop the browser.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded JSON with payment requirements, including accepted networks, assets, amounts, and recipients. Returned with the initial payment challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        '409':
          description: This payment authorization is already reserved or used, including by a request still in progress. No additional session is launched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Session capacity is currently unavailable. A request rejected before settlement can be retried with the same unexpired authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Session creation or payment processing failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service or payment facilitator is temporarily unavailable. If settlement was attempted, the authorization stays reserved; an error response alone does not establish that payment was not settled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - X402
      operationId: postX402Session
      x-operation-id-source: derived
  /x402/web/fetch:
    post:
      summary: Fetch a web page with X402 payment
      description: X402 payment endpoint. First request returns 402 with payment requirements. Retry with PAYMENT-SIGNATURE header containing cryptographic proof to get the actual data. See https://x402.gitbook.io/x402 for protocol details.
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: Base64-encoded JSON containing payment proof (x402Version, resource, accepted payment method, and cryptographic payload with signature and payer address)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchParams'
      responses:
        '200':
          description: Page fetched successfully (after valid payment)
          headers:
            PAYMENT-RESPONSE:
              description: Base64-encoded JSON with settlement information
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - returned on first request without PAYMENT-SIGNATURE header
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded JSON containing X402 payment requirements (x402Version, resource info, and array of accepted payment methods with network, asset, amount, payTo address, and timeout)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - X402
      operationId: postX402WebFetch
      x-operation-id-source: derived
  /x402/web/search:
    post:
      summary: Search the web with X402 payment
      description: X402 payment endpoint. First request returns 402 with payment requirements. Retry with PAYMENT-SIGNATURE header containing cryptographic proof to get search results. See https://x402.gitbook.io/x402 for protocol details.
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: Base64-encoded JSON containing payment proof (x402Version, resource, accepted payment method, and cryptographic payload with signature and payer address)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSearchParams'
      responses:
        '200':
          description: Search completed successfully (after valid payment)
          headers:
            PAYMENT-RESPONSE:
              description: Base64-encoded JSON with settlement information
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchResponse'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required - returned on first request without PAYMENT-SIGNATURE header
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded JSON containing X402 payment requirements (x402Version, resource info, and array of accepted payment methods with network, asset, amount, payTo address, and timeout)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - X402
      operationId: postX402WebSearch
      x-operation-id-source: derived
  /x402/session/{id}:
    get:
      summary: Get an X402 session
      description: Get the purchased session's status and original expiry without another payment. Authenticate with managementToken, not the browser token. Connection credentials are not reissued.
      security:
      - X402SessionManagement: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Purchased session ID.
      responses:
        '200':
          description: Success. No payment is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402SessionStatus'
        '400':
          description: Invalid session ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or incorrectly scoped management token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token authorizes a different session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found for the token's session and team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Session lookup or stop failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - X402
      operationId: getX402SessionById
      x-operation-id-source: derived
  /x402/session/{id}/stop:
    put:
      summary: Stop an X402 session
      description: Stop the purchased browser without another payment. Authenticate with managementToken, not the browser token. An already closed or errored session also succeeds.
      security:
      - X402SessionManagement: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Purchased session ID.
      responses:
        '200':
          description: Success. No payment is required.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
        '400':
          description: Invalid session ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or incorrectly scoped management token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token authorizes a different session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found for the token's session and team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Session lookup or stop failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - X402
      operationId: putX402SessionByIdStop
      x-operation-id-source: derived
components:
  schemas:
    BrandingProfile:
      type: object
      description: Visual brand profile extracted via DOM analysis + LLM enhancement. All fields optional; the server may return a partial profile when the LLM refuses or fails.
      properties:
        colorScheme:
          type: string
          description: 'Page color scheme. Common values: light, dark.'
        colors:
          type: object
          description: 'Color role assignments. Common keys: primary, secondary, accent, background, textPrimary, textSecondary, link.'
        fonts:
          type: array
          description: Cleaned brand fonts with roles.
          items:
            type: object
            properties:
              family:
                type: string
              role:
                type: string
        typography:
          type: object
          description: 'Font families, stacks, and sizes. Keys: fontFamilies, fontStacks, fontSizes, lineHeights, fontWeights.'
        spacing:
          type: object
          description: 'Spacing scale. Common keys: baseUnit, borderRadius, padding, margins, gridGutter.'
        components:
          type: object
          description: 'Per-component style dictionaries. Common keys: buttonPrimary, buttonSecondary, input. Each value has background, textColor, borderColor, borderRadius, borderRadiusCorners, shadow.'
        images:
          type: object
          description: 'Brand images. Common keys: logo, logoHref, logoAlt, favicon, ogImage.'
        personality:
          type: object
          description: 'Brand personality. Common keys: tone, energy, targetAudience.'
        designSystem:
          type: object
          description: 'Detected design system. Common keys: framework, componentLibrary.'
        confidence:
          type: object
          description: 'Confidence scores (0-1). Common keys: buttons, colors, overall.'
    FetchOutputMarkdown:
      type: object
      properties:
        type:
          type: string
          enum:
          - markdown
      required:
      - type
    FetchOutputLinks:
      type: object
      properties:
        type:
          type: string
          enum:
          - links
      required:
      - type
    WebSearchLocation:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
      required:
      - country
    FetchOutputOptions:
      type: object
      properties:
        formats:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FetchOutputMarkdown'
            - $ref: '#/components/schemas/FetchOutputHtml'
            - $ref: '#/components/schemas/FetchOutputLinks'
            - $ref: '#/components/schemas/FetchOutputScreenshot'
            - $ref: '#/components/schemas/FetchOutputJson'
            - $ref: '#/components/schemas/FetchOutputBranding'
            - type: string
              enum:
              - markdown
              - html
              - links
              - screenshot
              - branding
        sanitize:
          $ref: '#/components/schemas/FetchSanitizeMode'
        includeSelectors:
          type: array
          items:
            type: string
        excludeSelectors:
          type: array
          items:
            type: string
        storageState:
          $ref: '#/components/schemas/FetchStorageStateOptions'
    WebSearchResponseData:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchResultItem'
      required:
      - query
      - results
    FetchOutputJsonOptions:
      type: object
      properties:
        schema:
          type: object
        prompt:
          type: string
          description: Natural language prompt describing what data to extract. If only prompt is provided, a schema is auto-generated from it. If both prompt and schema are provided, the schema defines the output structure while the prompt provides additional guidance for the extraction.
    FetchCacheOptions:
      type: object
      properties:
        maxAgeSeconds:
          type: integer
    X402SessionStatus:
      type: object
      additionalProperties: false
      required:
      - id
      - status
      - startTime
      - endTime
      - timeoutMinutes
      - expiresAt
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - active
          - closed
          - error
          - close-error
        startTime:
          type:
          - integer
          - 'null'
          format: int64
          description: Session start timestamp in Unix milliseconds, when available.
        endTime:
          type:
          - integer
          - 'null'
          format: int64
          description: Session end timestamp in Unix milliseconds, when available.
        timeoutMinutes:
          type: integer
          minimum: 5
          maximum: 60
          description: Prepaid duration chosen at creation.
        expiresAt:
          type: string
          format: date-time
          description: Original purchased expiry, unchanged by status checks or an early stop.
    WebSearchResponse:
      type: object
      properties:
        jobId:
          type: string
        status:
          $ref: '#/components/schemas/WebSearchStatus'
        error:
          type:
          - string
          - 'null'
        data:
          $ref: '#/components/schemas/WebSearchResponseData'
      required:
      - jobId
      - status
    WebSearchStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - running
      - stopped
    FetchOutputBranding:
      type: object
      properties:
        type:
          type: string
          enum:
          - branding
      required:
      - type
    WebSearchParams:
      type: object
      properties:
        query:
          type: string
        page:
          type: integer
        maxAgeSeconds:
          type: integer
        location:
          $ref: '#/components/schemas/WebSearchLocation'
        filters:
          $ref: '#/components/schemas/WebSearchFilters'
      required:
      - query
    FetchSanitizeMode:
      type: string
      enum:
      - none
      - basic
      - advanced
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    X402SessionResponse:
      type: object
      additionalProperties: false
      description: Connection credentials and a management token for the purchased browser. Save this response; get does not reissue connection credentials. These tokens cannot authenticate regular account APIs.
      required:
      - id
      - wsEndpoint
      - webdriverEndpoint
      - liveUrl
      - computerActionEndpoint
      - token
      - expiresAt
      - managementToken
      properties:
        id:
          type: string
          format: uuid
          description: Purchased session ID.
        wsEndpoint:
          type: string
          format: uri
          description: CDP WebSocket URL for Playwright, Puppeteer, or another CDP client. Includes its authentication token.
        webdriverEndpoint:
          type: string
          format: uri
          description: Selenium/WebDriver endpoint. Send token in the x-hyperbrowser-token header.
        liveUrl:
          type: string
          format: uri
          description: Authenticated live-view URL. Interaction is disabled when viewOnlyLiveView is true.
        computerActionEndpoint:
          type: string
          format: uri
          description: Endpoint for mouse, keyboard, and screenshot actions. Includes its authentication token.
        token:
          type: string
          description: Credential scoped to this browser session. Use it for WebDriver authentication, not the regular get/list/stop/update/extend session APIs.
        expiresAt:
          type: string
          format: date-time
          description: Returned session expiry timestamp based on timeoutMinutes. The browser can stop earlier if closed or disconnected.
        managementToken:
          type: string
          description: Bearer token for GET /x402/session/{id} and PUT /x402/session/{id}/stop only. Valid for 24 hours from purchase, including after browser expiry. Does not authenticate browser connections or regular account APIs.
    FetchBrowserOptions:
      type: object
      properties:
        screen:
          $ref: '#/components/schemas/ScreenConfig'
        profileId:
          type: string
        solveCaptchas:
          type: string
        location:
          $ref: '#/components/schemas/FetchBrowserLocationOptions'
    WebSearchFilters:
      type: object
      properties:
        exactPhrase:
          type: boolean
        semanticPhrase:
          type: boolean
        excludeTerms:
          type: array
          items:
            type: string
        boostTerms:
          type: array
          items:
            type: string
        filetype:
          $ref: '#/components/schemas/WebSearchFiletype'
        site:
          type: string
        excludeSite:
          type: string
        intitle:
          type: string
        inurl:
          type: string
    WebSearchFiletype:
      type: string
      enum:
      - pdf
      - doc
      - docx
      - xls
      - xlsx
      - ppt
      - pptx
      - html
    FetchStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - running
    WebSearchResultItem:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
        description:
          type: string
      required:
      - title
      - url
      - description
    FetchStorageStateOptions:
      type: object
      properties:
        localStorage:
          type: object
          additionalProperties:
            type: string
        sessionStorage:
          type: object
          additionalProperties:
            type: string
    FetchOutputJson:
      allOf:
      - $ref: '#/components/schemas/FetchOutputJsonOptions'
      - type: object
        properties:
          type:
            type: string
            enum:
            - json
        required:
        - type
    FetchOutputScreenshotOptions:
      type: object
      properties:
        fullPage:
          type: boolean
        format:
          $ref: '#/components/schemas/FetchScreenshotFormat'
        cropToContent:
          type: boolean
        cropToContentMaxHeight:
          type: integer
        cropToContentMinHeight:
          type: integer
    FetchParams:
      type: object
      properties:
        url:
          type: string
        stealth:
          $ref: '#/components/schemas/FetchStealthMode'
        outputs:
          $ref: '#/components/schemas/FetchOutputOptions'
        browser:
          $ref: '#/components/schemas/FetchBrowserOptions'
        navigation:
          $ref: '#/components/schemas/FetchNavigationOptions'
        cache:
          $ref: '#/components/schemas/FetchCacheOptions'
      required:
      - url
    FetchResponse:
      type: object
      properties:
        jobId:
          type: string
        status:
          $ref: '#/components/schemas/FetchStatus'
        error:
          type:
          - string
          - 'null'
        data:
          $ref: '#/components/schemas/FetchResponseData'
      required:
      - jobId
      - status
    FetchWaitUntil:
      type: string
      enum:
      - load
      - domcontentloaded
      - networkidle
    FetchStealthMode:
      type: string
      enum:
      - none
      - auto
      - ultra
    FetchScreenshotFormat:
      type: string
      enum:
      - jpeg
      - png
      - webp
    FetchResponseData:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: array
              items:
                type: string
        html:
          type: string
        markdown:
          type: string
        links:
          type: array
          items:
            type: string
        screenshot:
          type: string
        json:
          type: object
        branding:
          $ref: '#/components/schemas/BrandingProfile'
    X402SessionParams:
      type: object
      additionalProperties: false
      description: Optional preferences for a browser session priced at 0.10 USDC per hour, paid upfront for timeoutMinutes. Unknown fields are rejected before payment verification. Web recording is disabled. Other regular session creation options are not supported.
      default: {}
      properties:
        screen:
          type: object
          additionalProperties: false
          description: Browser screen dimensions. An omitted dimension uses its default.
          default:
            width: 1280
            height: 720
          properties:
            width:
              type: number
              minimum: 500
              maximum: 3840
              default: 1280
            height:
              type: number
              minimum: 360
              maximum: 2160
              default: 720
        viewOnlyLiveView:
          type: boolean
          default: false
          description: Make the live-view link read-only. CDP, WebDriver, and the computer action endpoint still allow browser control.
        timeoutMinutes:
          type: integer
          minimum: 5
          maximum: 60
          default: 30
          description: Maximum session lifetime in minutes, from 5 through 60. Defaults to 30. Determines the session duration and upfront price at 0.10 USDC per hour. Connection token lifetimes and expiresAt follow this value.
    FetchBrowserLocationOptions:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
    ScreenConfig:
      type: object
      properties:
        width:
          type: number
          default: 1280
        height:
          type: number
          default: 720
    FetchNavigationOptions:
      type: object
      properties:
        waitUntil:
          $ref: '#/components/schemas/FetchWaitUntil'
        timeoutMs:
          type: integer
        waitFor:
          type: integer
    FetchOutputHtml:
      type: object
      properties:
        type:
          type: string
          enum:
          - html
      required:
      - type
    FetchOutputScreenshot:
      allOf:
      - $ref: '#/components/schemas/FetchOutputScreenshotOptions'
      - type: object
        properties:
          type:
            type: string
            enum:
            - screenshot
        required:
        - type
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    X402SessionManagement:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The managementToken from the X402 session purchase response. Valid for 24 hours and scoped to that session; no API key or further payment is required.
x-provenance:
  method: harvested
  publisher: Hyperbrowser
  source: https://www.hyperbrowser.ai/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)