PDFEndpoint Convert HTML API

openapi: 3.0.1
info:
  title: PDFEndpoint API
  description: >-
    Lightweight HTML and URL to PDF conversion API. A single POST /convert
    endpoint renders raw HTML or a publicly accessible HTTPS URL into a PDF
    using a headless browser, with options for page size, margins, orientation,
    headers and footers, encryption, and multiple delivery modes. Additional
    endpoints list, remove, and report usage for generated renders.
  termsOfService: https://pdfendpoint.com
  contact:
    name: PDFEndpoint Support
    url: https://pdfendpoint.com
  version: '1.0'
servers:
  - url: https://api.pdfendpoint.com/v1
security:
  - bearerAuth: []
paths:
  /convert:
    post:
      operationId: convert
      tags:
        - Convert
      summary: Convert HTML or a URL to PDF.
      description: >-
        Renders raw HTML (html) or a publicly accessible HTTPS URL (url) into a
        PDF. Exactly one of html or url is required. Returns a JSON envelope by
        default; the delivery_mode parameter selects alternate delivery (base64,
        inline, webhook, s3, gcp, jsonp). Only successful, non-sandbox
        conversions are billed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertRequest'
      responses:
        '200':
          description: Conversion succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limit or monthly conversion limit exceeded.
  /list:
    get:
      operationId: listRenders
      tags:
        - Renders
      summary: List created PDFs.
      description: >-
        Lists previously created PDFs from latest to oldest, with optional
        filters.
      responses:
        '200':
          description: A list of created renders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse'
        '401':
          description: Missing or invalid API key.
  /remove/{task_id}:
    delete:
      operationId: removeRender
      tags:
        - Renders
      summary: Delete a specific PDF.
      description: Deletes a previously created PDF identified by its task identifier.
      parameters:
        - name: task_id
          in: path
          required: true
          description: Identifier of the render to delete.
          schema:
            type: string
      responses:
        '200':
          description: Render deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
        '401':
          description: Missing or invalid API key.
        '404':
          description: Render not found.
  /usage:
    get:
      operationId: getUsage
      tags:
        - Account
      summary: Get current billing-cycle usage.
      description: Returns API usage for the current billing cycle.
      responses:
        '200':
          description: Current usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Missing or invalid API key.
  /health:
    get:
      operationId: getHealth
      tags:
        - Account
      summary: System status check.
      description: Returns the current system status.
      responses:
        '200':
          description: System status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key passed as a Bearer token in the Authorization header. Manage
        keys at https://pdfendpoint.com/app/tokens.
  schemas:
    ConvertRequest:
      type: object
      description: >-
        Conversion request. Provide exactly one of html or url. All other
        properties are optional and control rendering, layout, delivery, and
        security.
      properties:
        html:
          type: string
          description: Raw HTML content to convert. Mutually exclusive with url.
        url:
          type: string
          format: uri
          description: Publicly accessible HTTPS URL to convert. Mutually exclusive with html.
        sandbox:
          type: boolean
          default: false
          description: When true, output is watermarked and the conversion is not billed.
        page_size:
          type: string
          default: A4
          description: Page size such as A4, Letter, Legal, or A0-A9 / B0-B9.
        orientation:
          type: string
          enum: [vertical, horizontal]
          default: vertical
          description: Page orientation.
        viewport:
          type: string
          default: 1440x900
          description: Browser viewport in WIDTHxHEIGHT format.
        zoom:
          type: number
          minimum: 0.1
          maximum: 2
          default: 1
          description: Page zoom factor.
        margin_top:
          type: string
          default: 0px
        margin_bottom:
          type: string
          default: 0px
        margin_left:
          type: string
          default: 0px
        margin_right:
          type: string
          default: 0px
        print_pages:
          type: string
          description: Page ranges to print, e.g. "2-5" or "2,3,5".
        css:
          type: string
          description: CSS injected into the page via a style tag.
        js:
          type: string
          description: JavaScript injected into the page.
        parse_liquid:
          type: boolean
          default: false
          description: When true, the HTML is parsed as a Liquid template.
        liquid_data:
          type: object
          additionalProperties: true
          description: JSON variables used when parse_liquid is true.
        no_images:
          type: boolean
          default: false
        no_links:
          type: boolean
          default: false
        no_backgrounds:
          type: boolean
          default: false
        no_javascript:
          type: boolean
          default: false
        no_blank_pages:
          type: boolean
          default: false
        no_css:
          type: boolean
          default: false
        no_ads:
          type: boolean
          default: false
        no_forms:
          type: boolean
          default: false
        scroll_whole_page:
          type: boolean
          default: false
          description: Scrolls the page to trigger lazy-loaded content before rendering.
        use_print_media:
          type: boolean
          default: false
          description: Emulates @media print CSS styles.
        image_compression_quality:
          type: integer
          minimum: 0
          maximum: 100
          description: Image compression quality.
        image_compression_width:
          type: integer
          description: Target image width in pixels; aspect ratio is preserved.
        header_html:
          type: string
          description: HTML for the page header. Mutually exclusive with header_text.
        header_text:
          type: string
          description: Plain text page header. Mutually exclusive with header_html.
        header_align:
          type: string
          enum: [left, center, right]
        header_margin:
          type: string
          default: 0px
        header_start_at:
          type: string
          default: '1'
        footer_html:
          type: string
          description: HTML for the page footer. Mutually exclusive with footer_text.
        footer_text:
          type: string
          description: Plain text page footer. Mutually exclusive with footer_html.
        footer_align:
          type: string
          enum: [left, center, right]
        footer_margin:
          type: string
          default: 0px
        footer_start_at:
          type: string
          default: '1'
        delivery_mode:
          type: string
          enum: [json, base64, inline, webhook, s3, gcp, jsonp]
          default: json
          description: How the generated PDF is returned or delivered.
        webhook_endpoint:
          type: string
          format: uri
          description: HTTPS URL notified when delivery_mode is webhook.
        callback:
          type: string
          description: Callback function name used when delivery_mode is jsonp.
        s3_bucket_name:
          type: string
        s3_bucket_key:
          type: string
        s3_bucket_secret:
          type: string
        gcp_project_id:
          type: string
        gcp_user_email:
          type: string
        gcp_private_key:
          type: string
        gcp_bucket_name:
          type: string
        wait_for_selector:
          type: string
          description: CSS selector to wait for before rendering (30s timeout).
        wait_for_function:
          type: string
          description: JavaScript function name to wait for before rendering (30s timeout).
        wait_for_timeout:
          type: integer
          description: Time to wait in milliseconds before rendering.
        wait_for_network:
          type: boolean
          default: false
          description: Waits for network activity to settle before rendering.
        auth_user:
          type: string
          description: Username for HTTP basic auth on the target URL.
        auth_password:
          type: string
          description: Password for HTTP basic auth on the target URL.
        http_cookies:
          type: object
          additionalProperties: true
          description: Cookies sent when loading the target URL.
        http_headers:
          type: object
          additionalProperties: true
          description: HTTP headers sent when loading the target URL.
        location_lat:
          type: number
          description: Geolocation latitude.
        location_lng:
          type: number
          description: Geolocation longitude.
        location_accuracy:
          type: integer
          minimum: 0
          maximum: 100
          default: 100
        user_agent:
          type: string
        accept_language:
          type: string
          default: en-US
        accept_encoding:
          type: string
          default: utf-8
        filename:
          type: string
          maxLength: 180
          description: Output filename.
        enable_html_validation:
          type: boolean
          default: true
        secret_key:
          type: string
          description: MD5 hash used to restrict URL access.
        encrypt:
          type: boolean
          default: false
        owner_password:
          type: string
        user_password:
          type: string
        encryption_print_rights:
          type: string
          enum: [full, low, none]
          default: full
        encryption_modify_rights:
          type: string
          enum: [all, annotate, form, assembly, none]
          default: all
        encryption_copy_rights:
          type: string
          enum: [full, none]
          default: full
        title:
          type: string
        author:
          type: string
        creator:
          type: string
        producer:
          type: string
        subject:
          type: string
        keywords:
          type: string
    ConvertResponse:
      type: object
      properties:
        request_id:
          type: string
          description: Unique identifier for the request.
        success:
          type: boolean
        billed:
          type: boolean
          description: Whether the conversion counted toward the monthly limit.
        billed_units:
          type: integer
          description: Number of units billed for the conversion.
        data:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: URL of the generated PDF (json delivery mode).
            filename:
              type: string
            file_size:
              type: integer
              description: Size of the generated PDF in bytes.
            expires_after:
              type: string
              format: date-time
              description: Timestamp after which the stored PDF expires.
    ListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            type: object
            properties:
              request_id:
                type: string
              filename:
                type: string
              file_size:
                type: integer
              url:
                type: string
                format: uri
              created_at:
                type: string
                format: date-time
    UsageResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            monthly_limit:
              type: integer
            monthly_used:
              type: integer
            cycle_ends:
              type: string
              format: date-time
    SimpleResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        errors:
          type: array
          items:
            type: string