rendex-dev Batch API

openapi: 3.2.0
info:
  title: Rendex Rendering Batch API
  version: 1.8.0
  description: 'Render any webpage, raw HTML, or Markdown to a pixel-perfect image or PDF.

    A rendering API for automation builders and AI agents — HTML-to-image, URL

    screenshots, hosted OG links, and URL-to-Markdown extraction from one endpoint.


    Deployed on Cloudflare''s global edge (300+ locations, zero cold starts).

    MCP-compatible for AI agent workflows. Free tier included.


    **Features**: PNG/JPEG/WebP/PDF output, HTML/URL/Markdown input, batch capture (up to 500 URLs),

    geo-targeted rendering (50+ countries), async pipeline with webhook

    delivery, CSS/JS injection, custom cookies and headers, full-page capture,

    dark mode emulation, ad blocking, element selectors, custom viewports

    (320–3840px), device scale factor (1–3x), progressive navigation with

    automatic fallback.'
  contact:
    name: Copperline Labs
    url: https://rendex.dev
    email: support@rendex.dev
    x-twitter: rendexdev
  license:
    name: Proprietary
    url: https://rendex.dev/terms
  x-logo:
    url: https://rendex.dev/brand/icon-400.png
  x-providerName: rendex.dev
  x-apisguru-categories:
  - application_development
servers:
- url: https://api.rendex.dev
  description: Production
security:
- BearerAuth: []
tags:
- name: Batch
  description: Multi-URL batch capture
paths:
  /v1/screenshot/batch:
    post:
      operationId: postScreenshotBatch
      summary: Batch capture multiple URLs
      description: 'Submit up to 500 URLs for capture in a single request. Each URL is processed

        asynchronously. Returns a `batchId` that can be polled via `GET /v1/batches/{batchId}`.

        Shared defaults apply to all URLs unless overridden per-item.'
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            examples:
              basic:
                summary: Batch of three URLs
                value:
                  urls:
                  - url: https://example.com
                  - url: https://github.com
                  - url: https://stripe.com
                  defaults:
                    format: webp
                    width: 1280
                    fullPage: true
      responses:
        '202':
          description: Batch accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                success: true
                data:
                  batchId: batch_abc123
                  totalUrls: 3
                  status: processing
                  createdAt: '2026-04-05T12:00:00.000Z'
                meta:
                  requestId: req_abc123
                  timestamp: '2026-04-05T12:00:00.000Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Please try again later.
            meta:
              requestId: req_abc123
              timestamp: '2026-04-02T12:00:00.000Z'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key.
            meta:
              requestId: req_abc123
              timestamp: '2026-04-02T12:00:00.000Z'
    ValidationError:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: Invalid request parameters.
              details:
              - path: url
                message: Must be a valid URL
            meta:
              requestId: req_abc123
              timestamp: '2026-04-02T12:00:00.000Z'
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error description
            details:
              description: Additional error context (validation errors, etc.)
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ScreenshotRequest:
      type: object
      description: 'Provide exactly one of `url`, `html`, or `markdown` (mutually exclusive). If none is

        provided, the request will fail with a validation error.

        '
      properties:
        url:
          type: string
          format: uri
          description: Webpage URL to capture (mutually exclusive with `html` and `markdown`)
        html:
          type: string
          maxLength: 5242880
          description: Raw HTML to render (up to 5 MB, mutually exclusive with `url` and `markdown`)
        markdown:
          type: string
          maxLength: 5242880
          description: Markdown to render as styled HTML, then capture (up to 5 MB, mutually exclusive with `url` and `html`)
        data:
          type: object
          additionalProperties: true
          description: 'Mustache template data object. When present, the `html` or `markdown` string is

            treated as a logic-less Mustache template and rendered against `data` before capture.

            Valid only with `html` or `markdown` — returns 400 if combined with `url`.

            Serialized size must not exceed 256 KB.

            Syntax: `{{var}}` (HTML-escaped), `{{{var}}}` (raw), `{{#items}}…{{/items}}` (loop),

            `{{^x}}…{{/x}}` (inverted section), `{{a.b}}` (nested access).

            '
        format:
          type: string
          enum:
          - png
          - jpeg
          - webp
          - pdf
          default: png
          description: Output format
        width:
          type: integer
          minimum: 320
          maximum: 3840
          default: 1280
          description: Viewport width in pixels
        height:
          type: integer
          minimum: 240
          maximum: 2160
          default: 800
          description: Viewport height in pixels
        fullPage:
          type: boolean
          default: false
          description: Capture full scrollable page (capped at 16384px height)
        quality:
          type: integer
          minimum: 1
          maximum: 100
          description: Image quality (JPEG and WebP only)
        delay:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
          description: Wait milliseconds after page load before capture
        darkMode:
          type: boolean
          default: false
          description: Emulate dark color scheme
        deviceScaleFactor:
          type: number
          minimum: 1
          maximum: 3
          default: 2
          description: Device pixel ratio (2 for Retina)
        blockAds:
          type: boolean
          default: true
          description: Block ads, trackers, and chat widgets
        blockResourceTypes:
          type: array
          items:
            type: string
            enum:
            - font
            - image
            - media
            - stylesheet
            - other
          description: Resource types to block during page load
        css:
          type: string
          maxLength: 51200
          description: CSS to inject into the page before capture
        js:
          type: string
          maxLength: 51200
          description: JavaScript to execute on the page before capture
        cookies:
          type: array
          description: Cookies to set before navigating to the page
          items:
            type: object
            required:
            - name
            - value
            properties:
              name:
                type: string
              value:
                type: string
              domain:
                type: string
              path:
                type: string
              httpOnly:
                type: boolean
              secure:
                type: boolean
              sameSite:
                type: string
                enum:
                - Strict
                - Lax
                - None
              expires:
                type: number
                description: Unix timestamp (seconds) for cookie expiration
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom HTTP headers to send with the page request
        userAgent:
          type: string
          maxLength: 512
          description: Custom User-Agent string
        timeout:
          type: integer
          minimum: 5
          maximum: 60
          default: 30
          description: Navigation timeout in seconds
        waitUntil:
          type: string
          enum:
          - load
          - domcontentloaded
          - networkidle0
          - networkidle2
          default: networkidle2
          description: Page readiness condition before capture
        waitForSelector:
          type: string
          maxLength: 500
          description: CSS selector to wait for before capture
        bestAttempt:
          type: boolean
          default: true
          description: Return partial screenshot on timeout instead of failing
        selector:
          type: string
          maxLength: 500
          description: CSS selector of element to capture instead of full page
        pdfFormat:
          type: string
          enum:
          - A4
          - Letter
          - Legal
          - Tabloid
          - A3
          description: Paper size for PDF output (only applies when `format` is `pdf`)
        pdfLandscape:
          type: boolean
          description: Use landscape orientation for PDF output
        pdfPrintBackground:
          type: boolean
          description: Include background colors and images in PDF output
        pdfScale:
          type: number
          minimum: 0.1
          maximum: 2
          description: Scale factor for PDF rendering (0.1 to 2)
        pdfMargin:
          type: object
          description: Page margins for PDF output (CSS units, e.g. "1cm", "0.5in")
          properties:
            top:
              type: string
            right:
              type: string
            bottom:
              type: string
            left:
              type: string
        geo:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code for geo-targeted rendering (Pro/Enterprise)
        geoCity:
          type: string
          maxLength: 100
          description: City for geo-targeted rendering (Pro/Enterprise)
        geoState:
          type: string
          maxLength: 100
          description: State or region for geo-targeted rendering (Pro/Enterprise)
        async:
          type: boolean
          description: Process the capture asynchronously (returns a `jobId` to poll)
        webhookUrl:
          type: string
          format: uri
          description: URL to receive a webhook notification when the capture completes (Starter+ channel; Free/Basic poll GET /v1/jobs/{jobId} instead).
        cacheTtl:
          type: integer
          minimum: 3600
          maximum: 2592000
          description: Cache time-to-live in seconds (1 hour to 30 days)
        device:
          type: string
          enum:
          - desktop
          - iphone_15
          - iphone_se
          - pixel_8
          - ipad
          - ipad_pro
          description: Device preset — sets viewport, device scale, and user agent in one parameter. Explicit width/height/userAgent still win.
        hideSelectors:
          type: array
          items:
            type: string
            maxLength: 500
          maxItems: 50
          description: CSS selectors to hide before capture (popups, sticky nav, chat bubbles). Never errors on a miss.
        blockCookieBanners:
          type: boolean
          default: false
          description: Hide common cookie/consent walls (OneTrust, Cookiebot, Quantcast, …) via a curated CSS list.
        hosted:
          type: boolean
          default: false
          description: Store the result in R2 and return `{url, expiresAt}` (a signed CDN-backed URL) instead of the image bytes. Drop the URL into an `<img>`/`og:image`.
        extract:
          type: boolean
          default: false
          description: Also return clean reader-mode content from the same render pass (use on `/v1/screenshot/json`; the binary endpoint rejects it). Shape set by `extractFormat`.
        extractFormat:
          type: string
          enum:
          - markdown
          - json
          - html
          - text
          default: markdown
          description: Shape of the extracted content when `extract` is true.
        resizeWidth:
          type: integer
          minimum: 16
          maximum: 3840
          description: Downscale the output to this width (image formats only). Aspect ratio preserved when only one dimension is set. Never upscales.
        resizeHeight:
          type: integer
          minimum: 16
          maximum: 2160
          description: Downscale the output to this height (image formats only).
    ResponseMeta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request identifier
        timestamp:
          type: string
          format: date-time
    BatchResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            batchId:
              type: string
              description: Unique batch identifier for polling
            totalUrls:
              type: integer
              description: Number of URLs in the batch
            status:
              type: string
              enum:
              - processing
              - completed
              - failed
            createdAt:
              type: string
              format: date-time
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    BatchRequest:
      type: object
      required:
      - urls
      properties:
        urls:
          type: array
          minItems: 1
          maxItems: 500
          description: List of URLs to capture (each item can override defaults)
          items:
            type: object
            required:
            - url
            properties:
              url:
                type: string
                format: uri
                description: Webpage URL to capture
        defaults:
          $ref: '#/components/schemas/ScreenshotRequest'
        webhookUrl:
          type: string
          format: uri
          description: URL to receive a webhook notification when the batch completes (Starter+ channel; Free/Basic poll GET /v1/batches/{batchId} instead).
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer rdx_...`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key in custom header: `x-api-key: rdx_...`'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: 'API key as query parameter (GET endpoint only): `?key=rdx_...`'
externalDocs:
  description: Rendex API Documentation
  url: https://rendex.dev/docs