openapi: 3.0.1
info:
  title: Zenscrape API
  description: >-
    Zenscrape is a web scraping API that returns the rendered HTML of a target
    URL. The GET /get endpoint fetches a page through rotating standard or
    premium proxies with optional headless-browser JavaScript rendering,
    geolocation, and device emulation. The GET /status endpoint returns the
    remaining request credits for the authenticated account. Authentication is
    via the `apikey` request header (the key may also be supplied as a query
    parameter or form field). Request cost ranges from 1 to 25 credits
    depending on configuration.
  termsOfService: https://zenscrape.com/terms-and-conditions/
  contact:
    name: Zenscrape Support
    url: https://zenscrape.com/contact/
  version: '1.0'
servers:
  - url: https://app.zenscrape.com/api/v1
paths:
  /get:
    get:
      operationId: getPage
      tags:
        - Scrape
      summary: Scrape a target URL and return its HTML.
      description: >-
        Fetches the target URL through a rotating proxy pool and returns the
        page source. Set `render=true` to execute the page's JavaScript with a
        headless browser, and `premium=true` to route through premium
        residential proxies. Cost: 1 credit (no render, no premium), 5 (render),
        10 (premium), 25 (premium + render).
      parameters:
        - name: url
          in: query
          required: true
          description: The fully qualified URL of the page to scrape.
          schema:
            type: string
            format: uri
        - name: render
          in: query
          required: false
          description: >-
            Render the page with a headless browser, executing client-side
            JavaScript before returning the resulting HTML.
          schema:
            type: boolean
            default: false
        - name: premium
          in: query
          required: false
          description: >-
            Route the request through premium residential proxies to reduce the
            chance of bot detection.
          schema:
            type: boolean
            default: false
        - name: location
          in: query
          required: false
          description: >-
            Two-letter country code identifying the geolocation the request
            should originate from (e.g. `us`, `de`, `au`). Premium locations
            require the premium parameter.
          schema:
            type: string
            example: us
        - name: device
          in: query
          required: false
          description: Device type to emulate for the request.
          schema:
            type: string
            enum:
              - desktop
              - mobile
            default: desktop
        - name: keep_headers
          in: query
          required: false
          description: >-
            Forward the headers sent on the request to the target site. Combine
            with custom request headers to control the scraped response.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: The HTML source of the scraped page.
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: object
                description: JSON error or status payload returned for some conditions.
        '400':
          description: Bad request - missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The requested target URL could not be reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /status:
    get:
      operationId: getStatus
      tags:
        - Account
      summary: Return remaining account credits.
      description: >-
        Returns the number of request credits remaining for the authenticated
        account.
      responses:
        '200':
          description: Remaining account credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: apikey
      description: >-
        API key issued from the Zenscrape dashboard. May also be supplied as the
        `apikey` query parameter or form field.
  schemas:
    Status:
      type: object
      properties:
        remaining_requests:
          type: integer
          description: Number of request credits left on the account.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
security:
  - apikey: []