Urlbox Render API

openapi: 3.2.0
info:
  title: Urlbox Render API
  description: Urlbox is a website screenshot and rendering API for capturing screenshots, PDFs, and video (MP4/WebM) of any URL or raw HTML. Renders can be requested synchronously (POST /render/sync), asynchronously with polling or webhooks (POST /render/async + GET /render/{renderId}), or via signed, cacheable HMAC render links (GET /{api_key}/{token}/{format}).
  termsOfService: https://urlbox.com/terms
  contact:
    name: Urlbox Support
    url: https://urlbox.com/contact
    email: support@urlbox.com
  version: '1.0'
servers:
- url: https://api.urlbox.com/v1
  description: Urlbox v1 API
security:
- BearerAuth: []
tags:
- name: Render
  description: Create screenshot, PDF, and video renders.
paths:
  /render/sync:
    post:
      operationId: createSyncRender
      tags:
      - Render
      summary: Create a synchronous render
      description: Renders a screenshot, PDF, or video of a URL or HTML and blocks until the asset is ready. Responds 200 OK with a temporary renderUrl and timing metrics. Long-running requests may return 307 Temporary Redirect with a Location header after ~95 seconds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderOptions'
      responses:
        '200':
          description: Render completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncRenderResult'
        '307':
          description: Render still in progress after the sync timeout; follow the Location header to retrieve the result when ready.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
  /render/async:
    post:
      operationId: createAsyncRender
      tags:
      - Render
      summary: Create an asynchronous render
      description: Accepts the same render options as the sync endpoint and returns immediately with a renderId and statusUrl. The render is processed in the background; results are retrieved by polling the status URL or via a configured webhook_url callback.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderOptions'
      responses:
        '201':
          description: Render accepted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncRenderResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
        requestId:
          type: string
    SyncRenderResult:
      type: object
      properties:
        renderUrl:
          type: string
          format: uri
          description: Temporary URL pointing to the generated render.
        size:
          type: integer
          description: Size of the render in bytes.
        renderTime:
          type: integer
          description: Time spent rendering in milliseconds.
        queueTime:
          type: integer
          description: Time spent queued in milliseconds.
        bandwidth:
          type: integer
          description: Bandwidth consumed in bytes.
    RenderFormat:
      type: string
      description: Output format of the render.
      enum:
      - png
      - jpeg
      - webp
      - avif
      - svg
      - pdf
      - html
      - mp4
      - webm
      - md
    AsyncRenderResponse:
      type: object
      properties:
        status:
          type: string
          example: created
        renderId:
          type: string
          format: uuid
        statusUrl:
          type: string
          format: uri
          description: URL to poll for the render status.
    RenderOptions:
      type: object
      description: Render request options. Either url or html is required. This schema covers commonly used options; see https://urlbox.com/docs/options for the full catalog.
      properties:
        url:
          type: string
          description: The website URL to render. HTTP is prepended if missing.
        html:
          type: string
          description: Raw HTML to render instead of a URL.
        format:
          $ref: '#/components/schemas/RenderFormat'
        width:
          type: integer
          default: 1280
          description: Viewport width in pixels.
        height:
          type: integer
          default: 1024
          description: Viewport height in pixels.
        full_page:
          type: boolean
          default: false
          description: Capture the entire scrollable area of the page.
        full_width:
          type: boolean
          default: false
          description: Capture horizontally scrollable content as well.
        selector:
          type: string
          description: CSS selector to capture a specific element only.
        clip:
          type: string
          description: Bounding box to capture as x,y,width,height.
        retina:
          type: boolean
          default: false
          description: Render at 2x device pixel ratio for high-DPI output.
        thumb_width:
          type: integer
          description: Resize the output to this thumbnail width in pixels.
        thumb_height:
          type: integer
          description: Resize the output to this thumbnail height in pixels.
        quality:
          type: integer
          default: 80
          description: JPEG/WebP quality (1-100).
        transparent:
          type: boolean
          default: false
          description: Render PNG/WebP with a transparent background.
        dark_mode:
          type: boolean
          default: false
          description: Emulate prefers-color-scheme dark.
        block_ads:
          type: boolean
          description: Block advertising network requests.
        hide_cookie_banners:
          type: boolean
          description: Hide cookie consent notices via injected CSS.
        click_accept:
          type: boolean
          description: Click accept buttons on cookie banners.
        hide_selector:
          type: string
          description: Comma-delimited CSS selectors to hide before capture.
        click:
          type: string
          description: CSS selector to click before capture.
        hover:
          type: string
          description: CSS selector to hover over before capture.
        scroll_to:
          type: string
          description: CSS selector or pixel offset to scroll to before capture.
        css:
          type: string
          description: Custom CSS to inject into the page.
        js:
          type: string
          description: Custom JavaScript to execute in the page (Ultra+).
        delay:
          type: integer
          default: 0
          description: Milliseconds to wait before capture.
        timeout:
          type: integer
          default: 30000
          description: URL load timeout in milliseconds (5000-100000).
        wait_until:
          type: string
          default: loaded
          enum:
          - domloaded
          - mostrequestsfinished
          - requestsfinished
          - loaded
          description: Page-load event to wait for before capture.
        wait_for:
          type: string
          description: CSS selector to wait for before capture.
        wait_to_leave:
          type: string
          description: CSS selector to wait to disappear before capture.
        fail_on_4xx:
          type: boolean
          default: false
          description: Fail the render on 4xx responses from the target URL.
        fail_on_5xx:
          type: boolean
          default: false
          description: Fail the render on 5xx responses from the target URL.
        pdf_page_size:
          type: string
          default: A4
          enum:
          - A0
          - A1
          - A2
          - A3
          - A4
          - A5
          - A6
          - Legal
          - Letter
          - Ledger
          - Tabloid
          description: PDF page size.
        pdf_orientation:
          type: string
          default: portrait
          enum:
          - portrait
          - landscape
          description: PDF page orientation.
        pdf_margin:
          type: string
          default: none
          enum:
          - none
          - default
          - minimum
          description: PDF margin preset.
        pdf_scale:
          type: number
          default: 1
          description: PDF scale factor (0.1-2.0).
        pdf_background:
          type: boolean
          default: true
          description: Include background images/colors in the PDF.
        media:
          type: string
          enum:
          - print
          - screen
          description: CSS media type to emulate for PDF rendering.
        cookie:
          type: string
          description: Cookie to set as name=value (supports multiple).
        header:
          type: string
          description: Custom request header as name=value (HiFi+).
        user_agent:
          type: string
          description: Custom user agent string or a preset (random, mobile, desktop).
        accept_lang:
          type: string
          default: en-US
          description: Accept-Language header value.
        tz:
          type: string
          default: UTC
          description: IANA timezone ID to emulate.
        proxy:
          type: string
          description: Proxy as [user:pass@]address:port (Ultra+).
        force:
          type: boolean
          default: false
          description: Bypass the cache and generate a fresh render.
        unique:
          type: string
          description: Cache-busting token (UUID, hash, or timestamp).
        ttl:
          type: integer
          default: 2592000
          description: Cache duration in seconds.
        use_s3:
          type: boolean
          description: Save the render to the configured S3 bucket (HiFi+).
        s3_path:
          type: string
          description: Destination path/filename within the S3 bucket (HiFi+).
        webhook_url:
          type: string
          format: uri
          description: URL to receive a POST callback when an async render completes (render.succeeded / render.failed).
        response_type:
          type: string
          enum:
          - json
          - binary
          description: Whether to return JSON metadata or the binary asset.
      oneOf:
      - required:
        - url
      - required:
        - html
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Project secret key supplied as a Bearer token in the Authorization header.