openapi: 3.0.3
info:
  title: SOAX Proxy Management Ecommerce Data Web Data API
  description: The SOAX Proxy Management API enables programmatic control of proxy packages. Manage IP whitelists, configure proxy endpoints, and retrieve geo-targeting options including cities, regions, carriers, and ISPs across 195+ countries.
  version: '1'
  contact:
    name: SOAX Support
    url: https://helpcenter.soax.com/
  license:
    name: Proprietary
    url: https://soax.com/terms-of-service
servers:
- url: https://partner.api.soax.com
  description: SOAX Partner API endpoint
security:
- APIKeyHeader: []
tags:
- name: Web Data
  description: Extract content from web pages
paths:
  /v2/webdata/fetch-content:
    post:
      operationId: fetchWebContent
      summary: Fetch Web Content
      description: Fetch fully rendered content from any public web page. Handles JavaScript execution, CAPTCHA bypass, anti-bot circumvention, and headless browser management automatically. Returns HTML body, screenshots, XHR calls, or Markdown depending on response configuration.
      tags:
      - Web Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchContentRequest'
            example:
              url: https://www.example.com
              proxy_settings:
                country: us
                type: 1
              response:
                body: true
                screenshot: false
                xhr: false
                markdown: false
      responses:
        '200':
          description: Successfully extracted web content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchContentResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error or target site failure
components:
  schemas:
    FetchContentResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code of the fetched page
          example: 200
        url:
          type: string
          format: uri
          description: Final URL after redirects
        body:
          type: string
          description: Fully rendered HTML content of the page
        screenshot:
          type: string
          format: byte
          description: Base64-encoded PNG screenshot (if requested)
        xhr:
          type: array
          description: XHR/fetch calls captured during page rendering
          items:
            type: object
            properties:
              url:
                type: string
                description: URL of the XHR request
              method:
                type: string
                description: HTTP method
              status:
                type: integer
                description: Response status code
              body:
                type: string
                description: Response body
        markdown:
          type: string
          description: Markdown representation of the page content (if requested)
        metadata:
          type: object
          properties:
            title:
              type: string
              description: Page title
            description:
              type: string
              description: Meta description
            proxy_used:
              type: string
              description: The proxy IP used for the request
    FetchContentRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The target URL to fetch content from
          example: https://www.example.com
        proxy_settings:
          type: object
          description: Proxy configuration for the request
          properties:
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code for geo-targeting
              example: us
            type:
              type: integer
              description: Proxy type identifier (1=residential, 2=mobile, 3=datacenter)
              enum:
              - 1
              - 2
              - 3
              example: 1
            city:
              type: string
              description: Target city for geo-targeting
            region:
              type: string
              description: Target region/state for geo-targeting
            isp:
              type: string
              description: Target ISP for proxy selection
        response:
          type: object
          description: Configure what content to return in the response
          properties:
            body:
              type: boolean
              default: true
              description: Return the fully rendered HTML body
            screenshot:
              type: boolean
              default: false
              description: Return a PNG screenshot of the rendered page
            xhr:
              type: boolean
              default: false
              description: Return XHR/fetch background API responses captured during rendering
            markdown:
              type: boolean
              default: false
              description: Return a lightweight Markdown version of the page content
        session:
          type: object
          description: Session configuration for stateful browsing
          properties:
            sticky:
              type: boolean
              default: false
              description: Maintain the same IP across multiple requests
            session_id:
              type: string
              description: Session identifier for sticky sessions
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
        request_id:
          type: string
          description: Request identifier for support
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: api-key
      description: Your SOAX API key from the Profile tab in your dashboard