openapi: 3.0.1
info:
  title: Hyperbrowser Agents X402 API
  version: 1.0.0
  description: Start, stop, and monitor agentic browser tasks across HyperAgent, Browser-Use, Claude Computer Use, Gemini Computer Use, and OpenAI CUA.
  contact:
    name: Hyperbrowser
    url: https://hyperbrowser.ai
  license:
    name: Hyperbrowser Terms
    url: https://hyperbrowser.ai/terms
servers:
- url: https://api.hyperbrowser.ai
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: X402
paths:
  /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
  /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
components:
  schemas:
    WebSearchResponseData:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchResultItem'
      required:
      - query
      - results
    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
    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
    FetchOutputScreenshotOptions:
      type: object
      properties:
        fullPage:
          type: boolean
        format:
          $ref: '#/components/schemas/FetchScreenshotFormat'
        cropToContent:
          type: boolean
        cropToContentMaxHeight:
          type: integer
        cropToContentMinHeight:
          type: integer
    FetchSanitizeMode:
      type: string
      enum:
      - none
      - basic
      - advanced
    WebSearchResponse:
      type: object
      properties:
        jobId:
          type: string
        status:
          $ref: '#/components/schemas/WebSearchStatus'
        error:
          type: string
          nullable: true
        data:
          $ref: '#/components/schemas/WebSearchResponseData'
      required:
      - jobId
      - status
    FetchScreenshotFormat:
      type: string
      enum:
      - jpeg
      - png
      - webp
    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
    FetchStealthMode:
      type: string
      enum:
      - none
      - auto
      - ultra
    FetchOutputMarkdown:
      type: object
      properties:
        type:
          type: string
          enum:
          - markdown
      required:
      - type
    FetchBrowserLocationOptions:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
    FetchResponse:
      type: object
      properties:
        jobId:
          type: string
        status:
          $ref: '#/components/schemas/FetchStatus'
        error:
          type: string
          nullable: true
        data:
          $ref: '#/components/schemas/FetchResponseData'
      required:
      - jobId
      - status
    FetchOutputJson:
      allOf:
      - $ref: '#/components/schemas/FetchOutputJsonOptions'
      - type: object
        properties:
          type:
            type: string
            enum:
            - json
        required:
        - type
    WebSearchResultItem:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
        description:
          type: string
      required:
      - title
      - url
      - description
    FetchNavigationOptions:
      type: object
      properties:
        waitUntil:
          $ref: '#/components/schemas/FetchWaitUntil'
        timeoutMs:
          type: integer
        waitFor:
          type: integer
    ScreenConfig:
      type: object
      properties:
        width:
          type: number
          default: 1280
        height:
          type: number
          default: 720
    FetchOutputScreenshot:
      allOf:
      - $ref: '#/components/schemas/FetchOutputScreenshotOptions'
      - type: object
        properties:
          type:
            type: string
            enum:
            - screenshot
        required:
        - type
    FetchStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - running
    WebSearchFiletype:
      type: string
      enum:
      - pdf
      - doc
      - docx
      - xls
      - xlsx
      - ppt
      - pptx
      - html
    FetchOutputBranding:
      type: object
      properties:
        type:
          type: string
          enum:
          - branding
      required:
      - type
    FetchCacheOptions:
      type: object
      properties:
        maxAgeSeconds:
          type: integer
    FetchWaitUntil:
      type: string
      enum:
      - load
      - domcontentloaded
      - networkidle
    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.'
    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'
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    FetchOutputHtml:
      type: object
      properties:
        type:
          type: string
          enum:
          - html
      required:
      - type
    FetchStorageStateOptions:
      type: object
      properties:
        localStorage:
          type: object
          additionalProperties:
            type: string
        sessionStorage:
          type: object
          additionalProperties:
            type: string
    FetchOutputLinks:
      type: object
      properties:
        type:
          type: string
          enum:
          - links
      required:
      - type
    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.
    FetchBrowserOptions:
      type: object
      properties:
        screen:
          $ref: '#/components/schemas/ScreenConfig'
        profileId:
          type: string
        solveCaptchas:
          type: string
        location:
          $ref: '#/components/schemas/FetchBrowserLocationOptions'
    WebSearchStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - running
      - stopped
    WebSearchLocation:
      type: object
      properties:
        country:
          type: string
        state:
          type: string
        city:
          type: string
      required:
      - country
    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'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Account API key from app.hyperbrowser.ai