> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Render a PDF asynchronously

> Generate a PDF from one or more content sources in the background and store it in the specified cloud destination. Content can be provided as URLs to fetch, raw HTML strings, or a combination of both. This endpoint returns immediately with a success status while the rendering happens asynchronously. When rendering completes, the PDF will be uploaded to the specified destination, and an optional callback URL will be called. 



## OpenAPI

````yaml post /api/v1/renderers/pdf/async
openapi: 3.0.0
info:
  title: Vortex PDF
  version: '1.0'
servers:
  - url: https://vortexpdf.com
    variables: {}
security: []
tags: []
paths:
  /api/v1/renderers/pdf/async:
    post:
      tags:
        - Renderers
      summary: Create PDF asynchronously
      description: >-
        Generate a PDF from one or more content sources in the background and
        store it in the specified cloud destination. Content can be provided as
        URLs to fetch, raw HTML strings, or a combination of both. This endpoint
        returns immediately with a success status while the rendering happens
        asynchronously. When rendering completes, the PDF will be uploaded to
        the specified destination, and an optional callback URL will be called. 
      operationId: VortexWeb.API.V1.RenderController.render_async
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/async_render_options'
        description: Render async options
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error_response'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error_response'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
          description: Resource not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
      callbacks:
        onRenderComplete:
          '{$request.body#/callback/url}':
            post:
              callbacks: {}
              deprecated: false
              parameters: []
              requestBody:
                content:
                  application/json:
                    schema:
                      properties:
                        error:
                          description: Error message if the rendering failed
                          type: string
                        result:
                          properties:
                            bucket:
                              description: The storage bucket name
                              type: string
                            etag:
                              description: Entity tag for the stored object
                              type: string
                            id:
                              description: Unique identifier for the stored object
                              type: string
                            md5Hash:
                              description: MD5 hash of the file content
                              type: string
                            mediaLink:
                              description: URL to download the generated PDF
                              type: string
                            name:
                              description: The path to the generated PDF file
                              type: string
                            size:
                              description: Size of the generated PDF file in bytes
                              type: string
                            storageClass:
                              description: Storage class of the object
                              type: string
                            timeCreated:
                              description: When the file was created in storage
                              format: date_time
                              type: string
                          type: object
                        status:
                          description: The final status of the rendering job
                          enum:
                            - success
                            - failed
                          type: string
                        timestamp:
                          description: ISO8601 timestamp of when the job completed
                          format: date_time
                          type: string
                      required:
                        - status
                        - timestamp
                      type: object
                description: Callback payload with rendering job status
                required: true
              responses:
                '200':
                  description: Callback received successfully
              tags: []
      security:
        - authorization: []
components:
  schemas:
    async_render_options:
      additionalProperties: false
      allOf:
        - description: >-
            Common options for configuring PDF rendering behavior, applicable to
            both synchronous and asynchronous rendering.
          properties:
            emulate_media_type:
              default: print
              description: >-
                Emulates the specified media type during rendering. Use 'screen'
                for web display styles or 'print' for print-optimized styles.
                Particularly useful for pages with different CSS for screen and
                print media queries.
              enum:
                - screen
                - print
              title: emulate_media_type
              type: string
            evaluate_js:
              additionalProperties: false
              description: >-
                Evaluates a JavaScript expression in the page context before
                rendering. Useful for manipulating the DOM, triggering actions,
                or waiting for dynamic content to load. If the expression
                returns a Promise, rendering will wait for it to resolve.
              properties:
                expression:
                  description: The JavaScript expression to evaluate in the page context.
                  title: expression
                  type: string
              required:
                - expression
              title: evaluate_js
              type: object
            footer_template:
              description: >-
                HTML template for the page footer. Supports special classes like
                'date', 'title', 'url', 'pageNumber', and 'totalPages' for
                dynamic content.
              title: footer_template
              type: string
            header_template:
              description: >-
                HTML template for the page header. Supports special classes like
                'date', 'title', 'url', 'pageNumber', and 'totalPages' for
                dynamic content.
              title: header_template
              type: string
            include_backgrounds:
              default: true
              description: >-
                Whether to include background images and colors in the rendered
                PDF. Set to false to optimize for printing or reduce file size.
              title: include_backgrounds
              type: boolean
            margin:
              additionalProperties: false
              default:
                bottom: 0
                left: 0
                right: 0
                top: 0
                unit: mm
              description: >-
                Document margins specification with unit. Controls the space
                between the page edges and content.
              example:
                bottom: 10
                left: 10
                right: 10
                top: 10
                unit: mm
              properties:
                bottom:
                  description: Bottom margin in the specified unit
                  minimum: 0
                  type: number
                left:
                  description: Left margin in the specified unit
                  minimum: 0
                  type: number
                right:
                  description: Right margin in the specified unit
                  minimum: 0
                  type: number
                top:
                  description: Top margin in the specified unit
                  minimum: 0
                  type: number
                unit:
                  default: mm
                  description: Measurement unit for margin dimensions
                  enum:
                    - mm
                    - cm
                    - in
                    - px
                  type: string
              required:
                - top
                - right
                - bottom
                - left
              title: margin
              type: object
            orientation:
              default: portrait
              description: >-
                Page orientation for the PDF. 'portrait' is taller than wide,
                'landscape' is wider than tall.
              enum:
                - portrait
                - landscape
              title: orientation
              type: string
            output_format:
              default: pdf/a
              description: >-
                Output file format. 'pdf/a' is PDF/A-2b compliant for archiving,
                while 'pdf' is standard PDF.
              enum:
                - pdf/a
                - pdf
              title: output_format
              type: string
            pages:
              default: ''
              description: >-
                Specifies which pages to include in the output using a
                comma-separated list of page ranges (e.g., '1-5, 8, 11-13').
                Uses one-based indexing. Pages will be included in the
                document's natural order regardless of the specified range, and
                each page will only be included once. An empty string includes
                all pages.
              pattern: ^$|^(\d+(-\d+)?)(,\s*(\d+(-\d+)?))*$
              title: pages
              type: string
            parts:
              description: >-
                An array of content parts to render into a single PDF. Each part
                can be a URL string, HTML content string, or a structured
                content object with type and content.
              example:
                - https://example.com
                - <h1>Hello World</h1>
                - content: <div>Structured HTML content</div>
                  type: html
                - content:
                    context:
                      customer_name: Acme Inc.
                    template_id: invoice_template
                  type: template
              items:
                anyOf:
                  - description: >-
                      A valid URL string that will be fetched and rendered into
                      the PDF. The URL must be publicly accessible and return
                      HTML content.
                    format: uri
                    pattern: ^https?://\S+
                    title: url_string
                    type: string
                  - description: >-
                      Raw HTML content to render directly into the PDF. Must
                      start with a valid HTML tag. Can include CSS styles inline
                      or via <style> tags.
                    pattern: ^\s*<[^>]+>
                    title: html_string
                    type: string
                  - additionalProperties: false
                    description: >-
                      A structured part of content to render in the PDF. Allows
                      explicitly specifying the content type and value.
                    example:
                      content: https://example.com
                      type: url
                    properties:
                      content:
                        description: >-
                          The content to render - either a URL string when type
                          is 'url', HTML markup when type is 'html', or a
                          template specification object when type is 'template'.
                        oneOf:
                          - type: string
                          - additionalProperties: false
                            description: >-
                              Template specification with context data for
                              rendering into HTML
                            example:
                              context:
                                customer_name: Acme Inc.
                                invoice_number: INV-2023-001
                                items:
                                  - description: Product A
                                    price: 100
                                    quantity: 2
                                  - description: Product B
                                    price: 50
                                    quantity: 1
                              template_id: invoice_template
                            properties:
                              context:
                                additionalProperties: true
                                description: >-
                                  JSON object containing data to be inserted
                                  into the template
                                title: context
                                type: object
                              template_id:
                                description: Unique identifier for the template to use
                                title: template_id
                                type: string
                            required:
                              - template_id
                            title: template_content
                            type: object
                        title: content
                      type:
                        description: >-
                          The type of content to render - 'url' for a web page,
                          'html' for raw HTML content, or 'template' for
                          template-based rendering.
                        enum:
                          - url
                          - html
                          - template
                        title: type
                        type: string
                    required:
                      - type
                      - content
                    title: content_part
                    type: object
                description: >-
                  A content part that can be a URL string, HTML string, or a
                  structured content object.
              maxItems: 50
              minItems: 1
              title: content_parts
              type: array
            prefer_css_page_size:
              default: false
              description: >-
                Whether to prioritize page size defined in CSS using @page
                rules. When true, CSS page size takes precedence over the 'size'
                parameter. When false, content will be scaled to fit the
                specified paper size.
              title: prefer_css_page_size
              type: boolean
            render_header_footer:
              default: false
              description: >-
                Whether to render the header and footer templates on each page.
                Must be true for header_template and footer_template to take
                effect.
              title: render_header_footer
              type: boolean
            scale:
              default: 1
              description: >-
                Scale factor for the webpage rendering. Values below 1.0 reduce
                size, above 1.0 enlarge content.
              maximum: 2
              minimum: 0.1
              title: scale
              type: number
            set_cookie:
              additionalProperties: false
              description: >-
                Sets a cookie before rendering, useful for authenticated content
                or personalized views.
              properties:
                domain:
                  description: >-
                    Cookie domain (must match the domain of the URL being
                    rendered)
                  type: string
                name:
                  description: Cookie name
                  type: string
                value:
                  description: Cookie value
                  type: string
              required:
                - name
                - value
                - domain
              title: set_cookie
              type: object
            size:
              default: a4
              example: a4
              oneOf:
                - description: Standard document size preset name.
                  enum:
                    - a0
                    - a1
                    - a2
                    - a3
                    - a4
                    - a5
                    - a6
                    - a7
                    - a8
                    - a9
                    - a10
                    - letter
                    - legal
                    - tabloid
                    - ledger
                  title: size_preset
                  type: string
                - additionalProperties: false
                  description: Custom document size dimensions with unit.
                  properties:
                    height:
                      description: Document height in the specified unit.
                      type: number
                    unit:
                      default: mm
                      description: Measurement unit for dimensions.
                      enum:
                        - mm
                        - cm
                        - in
                        - px
                      type: string
                    width:
                      description: Document width in the specified unit.
                      type: number
                  required:
                    - width
                    - height
                  title: size_custom
                  type: object
            wait_for:
              additionalProperties: false
              description: >-
                Waits for a specific element attribute to be set before
                rendering, useful for ensuring dynamic content is fully loaded.
              properties:
                attribute:
                  description: >-
                    The attribute name to wait for on the selected element.
                    Rendering will proceed once this attribute exists on the
                    element.
                  title: attribute
                  type: string
                selector:
                  description: >-
                    CSS selector for the element to wait for (e.g., '#content'
                    or '.ready').
                  title: selector
                  type: string
              required:
                - selector
                - attribute
              title: wait_for
              type: object
          required:
            - parts
          title: render_options_common
          type: object
        - properties:
            callback:
              additionalProperties: false
              description: >-
                Callback configuration for notification when the asynchronous
                rendering is complete.
              properties:
                headers:
                  additionalProperties:
                    type: string
                  description: >-
                    Custom HTTP headers to include in the callback request,
                    useful for authentication or request identification.
                  title: headers
                  type: object
                url:
                  description: >-
                    URL that will receive a POST request when rendering is
                    complete, including status and file location information.
                  format: uri
                  title: url
                  type: string
              required:
                - url
              title: callback
              type: object
            destination:
              additionalProperties: false
              description: >-
                Configuration specifying where the rendered PDF should be stored
                when using asynchronous rendering.
              example:
                bucket: my-bucket
                path: pdfs/document.pdf
                provider: aws_s3
              properties:
                bucket:
                  description: The storage bucket name where the PDF will be stored.
                  title: bucket
                  type: string
                path:
                  description: >-
                    Storage path within the bucket, including the filename
                    (e.g., 'pdfs/document.pdf').
                  title: path
                  type: string
                provider:
                  description: >-
                    The cloud storage provider to use for storing the generated
                    PDF.
                  enum:
                    - aws_s3
                    - google_cloud_storage
                  title: provider
                  type: string
              required:
                - provider
                - bucket
                - path
              title: cloud_destination
              type: object
          type: object
      description: >-
        Options for asynchronous PDF rendering, where the rendering happens in
        the background and the result is stored in the specified destination.
      title: async_render_options
      type: object
    success_response:
      description: Standard success response
      example:
        status: success
      properties:
        status:
          description: Status of the operation
          enum:
            - success
          type: string
      required:
        - status
      title: success_response
      type: object
    auth_error_response:
      description: Response when authentication or authorization fails
      example:
        error: unauthorized
        message: Authentication required to access this resource
      properties:
        error:
          description: Error message describing the authentication or authorization failure
          enum:
            - unauthorized
            - forbidden
            - invalid_token
            - expired_token
            - insufficient_permissions
          type: string
        message:
          description: A more detailed message explaining the error
          type: string
      required:
        - error
      title: auth_error_response
      type: object
    error_response:
      description: Response when an error occurs
      properties:
        error:
          properties:
            message:
              description: Error message
              type: string
          required:
            - message
          type: object
      required:
        - error
      title: error_response
      type: object
    JsonErrorResponse:
      properties:
        errors:
          items:
            properties:
              detail:
                example: null value where string expected
                type: string
              source:
                properties:
                  pointer:
                    example: /data/attributes/petName
                    type: string
                required:
                  - pointer
                type: object
              title:
                example: Invalid value
                type: string
            required:
              - title
              - source
              - detail
            type: object
          type: array
      required:
        - errors
      title: JsonErrorResponse
      type: object
  securitySchemes:
    authorization:
      description: Manage your API keys at https://vortexpdf.com/api-keys
      scheme: bearer
      type: http

````