Hyperbrowser Web API

openapi: 3.0.1
info:
  title: Hyperbrowser Agents Web 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: Web
paths:
  /api/web/fetch:
    post:
      summary: Fetch a web page
      description: Fetches a web page and returns the content in various formats (HTML, Markdown, JSON, screenshot, etc.)
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: javascript
        label: Fetch a page
        source: "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.fetch({\n  url: 'https://example.com',\n  outputs: {\n    formats: ['markdown', 'screenshot']\n  }\n});"
      - lang: python
        label: Fetch a page
        source: "from hyperbrowser import Hyperbrowser\nfrom hyperbrowser.models import FetchParams, FetchOutputOptions\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.fetch(FetchParams(\n  url='https://example.com',\n  outputs=FetchOutputOptions(\n    formats=['markdown', 'screenshot']\n  )\n))"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchParams'
      responses:
        '200':
          description: Page fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Web
  /api/web/search:
    post:
      summary: Search the web
      description: Performs a web search and returns search results with titles, URLs, and descriptions
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: javascript
        label: Search the web
        source: "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.search({\n  query: 'hyperbrowser api',\n  filters: {\n    site: 'hyperbrowser.ai'\n  }\n});"
      - lang: python
        label: Search the web
        source: "from hyperbrowser import Hyperbrowser\nfrom hyperbrowser.models import WebSearchParams, WebSearchFilters\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.search(WebSearchParams(\n  query='hyperbrowser api',\n  filters=WebSearchFilters(\n    site='hyperbrowser.ai'\n  )\n))"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSearchParams'
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchResponse'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Web
  /api/web/crawl:
    post:
      summary: Start a web crawl job
      description: Starts an asynchronous crawl job that follows links from a starting URL and returns content from each page in the specified formats.
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: javascript
        label: Start a web crawl
        source: "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.crawl.start({\n  url: 'https://example.com',\n  outputs: {\n    formats: ['markdown']\n  },\n  crawlOptions: {\n    maxPages: 10,\n    followLinks: true\n  }\n});"
      - lang: python
        label: Start a web crawl
        source: "from hyperbrowser import Hyperbrowser\nfrom hyperbrowser.models import StartWebCrawlJobParams, WebCrawlOptions, FetchOutputOptions\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.crawl.start(StartWebCrawlJobParams(\n  url='https://example.com',\n  outputs=FetchOutputOptions(\n    formats=['markdown']\n  ),\n  crawl_options=WebCrawlOptions(\n    max_pages=10,\n    follow_links=True\n  )\n))"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartWebCrawlJobParams'
      responses:
        '200':
          description: Crawl job started successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - jobId
                properties:
                  jobId:
                    type: string
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Web
  /api/web/crawl/{id}:
    get:
      summary: Get web crawl job results
      description: Retrieves the status and results of a web crawl job. Results are paginated.
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: javascript
        label: Get web crawl job
        source: "import { Hyperbrowser } from '@hyperbrowser/sdk';\n\nconst client = new Hyperbrowser({ apiKey: 'your-api-key' });\n\nconst response = await client.web.crawl.get('job-id', {\n  page: 0,\n  batchSize: 10\n});"
      - lang: python
        label: Get web crawl job
        source: "from hyperbrowser import Hyperbrowser\nfrom hyperbrowser.models import GetWebCrawlJobParams\n\nclient = Hyperbrowser(api_key='your-api-key')\n\nresponse = client.web.crawl.get('job-id', GetWebCrawlJobParams(\n  page=0,\n  batch_size=10\n))"
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: batchSize
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Web crawl job details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCrawlJobResponse'
        '404':
          description: Crawl job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Web
  /api/web/crawl/{id}/status:
    get:
      summary: Get web crawl job status
      description: Retrieves just the status of a web crawl job without the full results.
      security:
      - ApiKeyAuth: []
      x-codeSamples:
      - lang: javascript
        label: Get web crawl job status
        source: 'import { Hyperbrowser } from ''@hyperbrowser/sdk'';


          const client = new Hyperbrowser({ apiKey: ''your-api-key'' });


          const response = await client.web.crawl.getStatus(''job-id'');'
      - lang: python
        label: Get web crawl job status
        source: 'from hyperbrowser import Hyperbrowser


          client = Hyperbrowser(api_key=''your-api-key'')


          response = client.web.crawl.get_status(''job-id'')'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Web crawl job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
        '404':
          description: Crawl job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Web
  /x402/web/fetch:
    post:
      operationId: post-x402-web-fetch
      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:
      - Web
  /x402/web/search:
    post:
      operationId: post-x402-web-search
      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:
      - Web
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
    WebCrawlPageData:
      type: object
      properties:
        url:
          type: string
        status:
          $ref: '#/components/schemas/PageStatus'
        error:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: array
              items:
                type: string
        markdown:
          type: string
        html:
          type: string
        links:
          type: array
          items:
            type: string
        screenshot:
          type: string
        json:
          type: object
        branding:
          $ref: '#/components/schemas/BrandingProfile'
      required:
      - url
      - status
    FetchScreenshotFormat:
      type: string
      enum:
      - jpeg
      - png
      - webp
    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
    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
    JobStatus:
      type: string
      enum:
      - pending
      - running
      - completed
      - failed
      - stopped
    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
    WebCrawlJobResponse:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatus'
        error:
          type: string
          nullable: true
        totalPages:
          type: integer
          minimum: 0
        totalPageBatches:
          type: integer
          minimum: 0
        currentPageBatch:
          type: integer
          minimum: 0
        batchSize:
          type: integer
          minimum: 1
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebCrawlPageData'
      required:
      - status
      - jobId
    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
    StartWebCrawlJobParams:
      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'
        crawlOptions:
          $ref: '#/components/schemas/WebCrawlOptions'
      required:
      - url
    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
    JobStatusResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/JobStatus'
      required:
      - status
    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'
    PageStatus:
      type: string
      enum:
      - completed
      - failed
      - pending
      - running
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    FetchOutputHtml:
      type: object
      properties:
        type:
          type: string
          enum:
          - html
      required:
      - type
    FetchOutputLinks:
      type: object
      properties:
        type:
          type: string
          enum:
          - links
      required:
      - type
    FetchStorageStateOptions:
      type: object
      properties:
        localStorage:
          type: object
          additionalProperties:
            type: string
        sessionStorage:
          type: object
          additionalProperties:
            type: string
    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
    WebCrawlOptions:
      type: object
      properties:
        maxPages:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        followLinks:
          type: boolean
          default: true
        ignoreSitemap:
          type: boolean
          default: false
        excludePatterns:
          type: array
          items:
            type: string
        includePatterns:
          type: array
          items:
            type: string
    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