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

# Convert to PDF

Convert a given HTML document to a PDF file.

You can provide the HTML source directly, or a URL to fetch it from.

Numerous options are available to customize the generated PDF document.

<Warning>
  Please note that the response from this endpoint will vary depending on some parameters.

  You can read more at [Varying responses](/docs/varying-responses).
</Warning>


## OpenAPI

````yaml https://api.pdfshift.io/openapi.json post /convert/pdf
openapi: 3.0.3
info:
  title: PDFShift API Documentation
  version: '3.0'
  description: >-
    This is the documentation for the PDFShift API.


    Our aim here is to provide you with a clear, concise and complete set of
    tool to generate the PDF you want.


    Don't forget to add the `sandbox` parameter to `True` while testing the API,
    this won't use your credits and generate free PDF (with a watermark).

    But if you forgot to set it, don't worry ; Send us a message and we'll reset
    your credits usage.
  termsOfService: https://pdfshift.io/terms
  contact:
    name: PDFShift
    url: https://pdfshift.io
    email: support@pdfshift.io
  x-logo:
    url: https://pdfshift.io/images/favicons/android-chrome-512x512.png
servers:
  - url: https://api.pdfshift.io/v3
    description: ''
    x-last-modified: 1764750693905
security:
  - apiKeyHeader: []
externalDocs:
  description: You can access our documentation online by visiting https://docs.pdfshift.io
  url: https://docs.pdfshift.io
paths:
  /convert/pdf:
    post:
      tags: []
      summary: Convert to PDF
      parameters:
        - name: X-Processor-Version
          in: header
          description: >-
            Specifies the Chromium version that will be used for the conversion.
            Right now, only "116" and "142" are accepted.

            All new users are automatically using the latest version.
          required: false
          schema:
            type: string
            enum:
              - '116'
              - '142'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ConvertForm'
                - type: object
                  properties:
                    landscape:
                      type: boolean
                      default: false
                      description: Will set the view in landscape mode instead of portrait.
                    format:
                      type: string
                      default: A4
                      description: >-
                        Format of the document.

                        You can either use the standard values (Letter, Legal,
                        Tabloid, Ledger, A0, A1, A2, A3, A4, A5) or a custom
                        `{width}x{height}` value.

                        For `{width}` and `{height}`, you can indicate the
                        following units: in, cm, mm.

                        . The `{height}` value can be replaced by `auto` to
                        automatically adjust the height to the content. For
                        instance, pasing the format `1024xauto` will set the
                        page width to 1024px and the height to the content
                        height.
                    disable_backgrounds:
                      type: boolean
                      default: false
                      description: The final document will not have the background images.
                    remove_blank:
                      type: boolean
                      default: false
                      description: >-
                        Will analyze the last page of the document. If no
                        content is present in it, the page will be removed. But
                        note that if there are remaining hidden data, header or
                        footer that have been pushed to that page, the page will
                        be kept.
                    pages:
                      type: string
                      default: null
                      description: >-
                        Pages to print. Can be one number (`3`), a range
                        (`1-5`), a list (`4,5,6`) or a combination of both
                        (`1-3,6,7`).

                        If the number is higher than the real number of pages,
                        that number will be ignored.
                    zoom:
                      type: number
                      minimum: 0.1
                      maximum: 2
                      default: 1
                      description: >-
                        A value between 0.1 and 2.

                        Allows you to increase the zoom in the document for
                        specific purposes.

                        1 is the default zoom, lower is smaller, higher is
                        bigger.
                    margin:
                      oneOf:
                        - $ref: '#/components/schemas/MarginForm'
                        - type: string
                        - type: integer
                      default: null
                      description: >-
                        Empty spaces between the outer and the beginning of the
                        content. See the [Margin](/docs/margin) section for more
                        details.
                    header:
                      $ref: '#/components/schemas/CustomHeaderFooter'
                      description: >-
                        Defines a custom header.


                        **Note**: The footer and header are Independent from the
                        rest of the document.


                        As such, the CSS style defined in your body won't apply
                        on your header/footer. To style your header/footer, you
                        need to set a specific style either using <style> tag
                        first, or adding style="" on your DOM elements.


                        See the [Header/Footer section](/docs/header-footer) for
                        more details.
                      type: object
                      default: null
                      example:
                        source: <div style="font-size:12px;">Header Example</div>
                        height: '48'
                        start_at: 1
                    footer:
                      $ref: '#/components/schemas/CustomHeaderFooter'
                      description: >-
                        Defines a custom header.


                        **Note**: The footer and header are Independent from the
                        rest of the document.


                        As such, the CSS style defined in your body won't apply
                        on your header/footer. To style your header/footer, you
                        need to set a specific style either using <style> tag
                        first, or adding style="" on your DOM elements.


                        See the [Header/Footer section](/docs/header-footer) for
                        more details.
                      type: object
                      default: null
                      example:
                        source: <div style="font-size:12px;">Footer Example</div>
                        height: '48'
                        start_at: 1
                    metadata:
                      type: object
                      additionalProperties:
                        type: string
                      default: null
                      description: >-
                        Allows you to add custom metadata to the generated PDF
                        document.

                        The following metadata are reserved and thus not
                        accepted: 'author_raw', 'creator_raw', 'producer',
                        'producer_raw', 'subject_raw', 'title_raw'.
                      example:
                        author: John Doe
                        title: Sample PDF Document
                        subject: Demonstration of PDFShift Capabilities
                        keywords: PDF, API, PDFShift, Example
                    protection:
                      $ref: '#/components/schemas/ProtectionForm'
                      description: >-
                        Will add restrictions on the PDF document.


                        **Note**: Some PDF Reader don't make the distinction
                        between **user** and **owner** in a PDF Document.

                        This means that when the user password has been entered,
                        some PDF reader ignore the restrictions (no print, no
                        copy, etc).


                        So, setting a blank password for the user is similar to
                        no security.


                        See the [Protection](/docs/protection) section for more
                        details.
                      type: object
                      default: null
                    watermark:
                      $ref: '#/components/schemas/WatermarkForm'
                      description: >-
                        Add a watermark to the generated document.

                        The watermark will always be placed at the center of the
                        document.

                        See the [Watermark](/docs/watermark) section for more
                        details.
                      type: object
                      default: null
              required:
                - source
      responses:
        '200':
          description: PDF file generated successfully
          headers:
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests allowed in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets (Unix
                timestamp).
              schema:
                type: integer
                format: int64
            X-Response-Status-Code:
              description: >-
                Provides the status code PDFShift got when loading your source
                when it is an HTTP request.
              schema:
                type: integer
            X-PDFShift-Processor:
              description: >-
                Returns the name of the PDFShift’s server that ran the
                conversion.
              schema:
                type: string
            X-Credits-Cost:
              description: Indicates the number of credits that this generation requires.
              schema:
                type: integer
            X-Credits-Used:
              description: >-
                Contrary to X-Credits-Cost, this header indicates the number of
                credits that were decreased from your account. It is identical
                to X-Credits-Cost excepted if you passed the sandbox parameter,
                in which case the value will be at 0.
              schema:
                type: integer
            X-Response-Duration:
              description: >-
                The number of miliseconds it took to load the HTML source
                provided in the request.
              schema:
                type: integer
            X-PDFShift-Duration:
              description: >-
                The number of miliseconds it took to load the source and then
                generate the PDF document. This value should be closer to the
                Time To First Byte duration you can have on your end.
              schema:
                type: integer
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: <...PDF binary data...>
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  url:
                    type: string
                    format: uri
                  filesize:
                    type: integer
                  duration:
                    type: integer
                  response:
                    type: object
                  executed:
                    type: string
                    format: date-time
                  pdf_pages:
                    type: integer
                required:
                  - success
                  - url
                  - filesize
                  - duration
                  - response
                  - executed
              example:
                success: true
                url: >-
                  https://s3.amazonaws.com/pdfshift/d/2/2019-05/99c456250a01448686d81752a3fb5beb/15466098-8368-49e1-ac33-ff4c3941a0df.pdf
                filesize: 259972
                duration: 1500
                response:
                  duration: 2562
                  status-code: 200
                executed: '2025-12-02T12:34:56.789Z'
                pdf_pages: 5
        '202':
          description: >-
            Conversion request accepted and queued for processing. Returned when
            the `webhook` parameter is used.
          headers:
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests allowed in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets (Unix
                timestamp).
              schema:
                type: integer
                format: int64
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  queued:
                    type: boolean
              example:
                success: true
                queued: true
        '400':
          description: >-
            Bad request. Data passed to the request were invalid or wrongly
            formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized. Invalid auth key, missing, or disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden. No remaining credits left.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: Request Timeout. The requested page took too long to load.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests. You have been rate limited.
          headers:
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: >-
                The maximum number of requests allowed in the current rate limit
                window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets (Unix
                timestamp).
              schema:
                type: integer
                format: int64
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ConvertForm:
      type: object
      properties:
        source:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Original document to convert to PDF. PDFShift will automatically
            detect if it's an URL and load it, or an HTML document and charge
            it.

            You can also send an array of documents to convert if parallel
            conversions is enabled on your account. In that case, you will also
            need to provide the webhook parameters as this operation is
            asynchronous.
        sandbox:
          type: boolean
          default: false
          description: >-
            Will generates documents that doesn't count in the credits. The
            generated document will come with a watermark and you are limited to
            10 documents per minutes.
        encode:
          type: boolean
          default: false
          description: >-
            Will return the generated PDF in Base64 encoded format, instead of
            raw.
        filename:
          type: string
          description: >-
            Name of the destination file.

            Only an alphanumerical value with "-" or "_", of at least 7 chars
            accepted.


            If given, the response **will not be the PDF**, but a JSON response
            containing an url parameter to an Amazon S3 bucket, to download the
            file.

            The file will be **kept for 2 days**, then automatically deleted.


            See [Saving the document to Amazon S3](/docs/saving-to-s3) for an
            example.
        s3_destination:
          type: string
          description: >-
            Path to your S3 bucket, in order to save the converted PDF directly
            into your AWS S3 account.

            Use a full path value like

            `s3://doc-example-bucket/pdfshift/upload/86aa3ede7d05.pdf`.


            See [Saving to your Amazon S3](/docs/saving/to-s3) for more details.


            Note that you can also save to [Google Cloud
            Storage](/docs/saving/to-gs) and reach out to us if you want to
            store to other services as well
        use_print:
          type: boolean
          default: false
          description: Use the print stylesheet instead of the general one.
        css:
          type: string
          description: >-
            Will append this CSS styles to the document before saving it. Can be
            an URL or a String of CSS rules.
        javascript:
          type: string
          description: >-
            Will execute the given Javascript before saving the document. Can be
            an URL or a String of JS code.
        delay:
          type: integer
          default: 0
          minimum: 0
          maximum: 10000
          description: >-
            In milliseconds. Will wait for this duration before capturing the
            document. Up to 10 seconds max.
        timeout:
          type: integer
          minimum: 0
          maximum: 900
          description: >-
            If provided, will kill the page loading at a specified time without
            stopping with a TimeoutError. Value in seconds.
        wait_for:
          type: string
          description: >-
            Name of a function available globally.

            When present, PDFShift will wait for this function to return a
            truthy value (true, 1, a string, etc) or up to 30 seconds, then
            proceed to the conversion.

            If the function never returns a truthy value in the allocated time,
            the conversion will fail with an error.
        wait_for_network:
          type: boolean
          default: true
          description: >-
            If set to true, will wait that there was no network requests in the
            last 500ms.
        ignore_long_polling:
          type: boolean
          default: false
          description: >-
            Will not wait for long-polling request to end before generating the
            document.

            This can be helpful when loading a page that have websockets or long
            running queries that have no impact on the generated document.

            Requires `wait_for_network` to be set to true, otherwise the
            conversion never waits for network requests at all.
        disable_javascript:
          type: boolean
          default: false
          description: Will not execute the javascript at all in the document.
        lazy_load_images:
          type: boolean
          default: false
          description: >-
            When set to true, will scroll the page to the bottom to trigger
            loading the images with lazy loading before saving the document.
        raise_for_status:
          type: boolean
          default: false
          description: >-
            Won't convert the document if the loaded source (when HTTP) returns
            a non 2XX response.
        webhook:
          oneOf:
            - $ref: '#/components/schemas/WebhookForm'
            - type: string
              format: uri
          description: >-
            An URL where we will send a POST request containing a JSON body
            similar to when you use the filename parameter.

            The JSON response will contain a URL key that points to your file,
            stored on Amazon S3.


            **Note**: When the conversion fail, we also do a `POST` request to
            your endpoint, but with an `error` key instead.


            We recommend you to first check if the body contains the `error`
            before processing the document, and act accordingly.
        auth:
          $ref: '#/components/schemas/BasicAuthForm'
          description: >-
            Basic authentication that will be sent along the request to load the
            source when it's an URL.
        http_headers:
          type: object
          additionalProperties:
            type: string
          description: >-
            List of HTTP headers that you can pass to the request when loading
            the source URL.
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/CookieForm'
          description: >-
            List of cookies you want to send along with the requests when
            loading the source.

            They must be provided as an array of objects.
        is_hipaa:
          type: boolean
          default: false
          description: >-
            When set to True, ensure the conversion's parameters are compliant
            to HIPAA regulations.

            This will disable features such as `filename` or `webhook` when the
            `s3_destination` is managed by PDFShift, to avoid storing any
            sensitive documents on PDFShift's servers. See [Handling sensitive
            documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents)
            for more details.
        is_gdpr:
          type: boolean
          default: false
          description: >-
            When set to True, ensure the conversion's parameters are compliant
            to GDPR regulations.

            This will disable features such as `filename` or `webhook` when the
            `s3_destination` is managed by PDFShift, to avoid storing any
            sensitive documents on PDFShift's servers. See [Handling sensitive
            documents](https://help.pdfshift.io/how-do-you-handle-sensitive-documents)
            for more details.
        log_request:
          type: boolean
          default: false
          description: >-
            Log the request parameters. Useful for debugging purposes with
            PDFShift support.
      required:
        - source
    MarginForm:
      type: object
      properties:
        top:
          type: string
          default: '48'
        right:
          type: string
          default: '48'
        bottom:
          type: string
          default: '48'
        left:
          type: string
          default: '48'
    CustomHeaderFooter:
      type: object
      properties:
        source:
          description: >-
            Element to add in the header part of the document.

            PDFShift will automatically detect if it's an URL and load it, or an
            HTML data and charge it.


            Accepted variables are:
              {{date}}  - Formatted print date
              {{title}} - Title of the HTML document
              {{url}}   - Page URL
              {{page}}  - Current page
              {{total}} - Total number of pages
          type: string
        height:
          type: string
          default: null
          description: >-
            A spacing between the header or footer and the content.

            For header, it's the space between the header and the beginning of
            the document.

            For the footer, it's the space between the end of the document and
            the bottom of the page.
        start_at:
          type: integer
          minimum: 1
          default: 1
          description: >-
            Start to display the header/footer at that given page.

            **Important**: If you send header AND footer, and set a start_at
            higher than 1, it must be the same for header and footer.


            For instance, header.start_at = 1 and footer.start_at = 5 is
            possible.

            But header.start_at = 2 and footer.start_at = 3 is NOT possible.
      required:
        - source
    ProtectionForm:
      type: object
      properties:
        author:
          type: string
          default: null
          description: Author metadata for the PDF.
        user_password:
          type: string
          default: ''
          description: Password required to open the PDF.
        owner_password:
          type: string
          default: ''
          description: Password required to change permissions.
        no_print:
          type: boolean
          default: false
          description: Disallow printing of the PDF.
        no_copy:
          type: boolean
          default: false
          description: Disallow copying content from the PDF.
        no_modify:
          type: boolean
          default: false
          description: Disallow modifying the PDF.
    WatermarkForm:
      type: object
      properties:
        source:
          type: string
          description: PDF source. Must be a valid URL or a base64 encoded PDF document.
        image:
          type: string
          description: Image source for watermark.
        text:
          type: string
          description: Text to use as watermark.
        font_size:
          type: integer
          minimum: 5
          maximum: 300
          default: 16
          description: Font size for text watermark (5-300).
        font_family:
          type: string
          enum:
            - Helvetica
            - Times
            - Courier
          default: Helvetica
          description: Font family for text watermark.
        font_color:
          type: string
          pattern: ^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$
          default: '000000'
          description: 'Font color in hexadecimal (e.g. #000000 or 000000).'
        font_opacity:
          type: integer
          minimum: 0
          maximum: 100
          default: 100
          description: Font opacity percentage (0-100).
        font_bold:
          type: boolean
          default: false
          description: Bold font for text watermark.
        font_italic:
          type: boolean
          default: false
          description: Italic font for text watermark.
        offset_x:
          type: string
          default: center
          description: >-
            Horizontal offset: 'left', 'right', 'center', or value ending with
            px/in/cm/mm/pt.
        offset_y:
          type: string
          default: middle
          description: >-
            Vertical offset: 'top', 'bottom', 'middle', or value ending with
            px/in/cm/mm/pt.
        rotate:
          type: integer
          minimum: -359
          maximum: 359
          default: -45
          description: Rotation angle for watermark (-359 to 359).
    Errors:
      type: object
      properties:
        success:
          type: boolean
        errors:
          type: object
        code:
          type: integer
          format: int32
    Error:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        code:
          type: integer
          format: int32
    WebhookForm:
      type: object
      properties:
        url:
          type: string
          format: uri
        method:
          type: string
          default: POST
        auth:
          $ref: '#/components/schemas/BasicAuthForm'
        headers:
          type: object
          additionalProperties:
            type: string
      required:
        - url
    BasicAuthForm:
      type: object
      properties:
        username:
          type: string
          default: null
        password:
          type: string
          default: null
    CookieForm:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        secure:
          type: boolean
          default: false
        http_only:
          type: boolean
          default: false
      required:
        - name
        - value
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      description: >-
        Authenticate your account by including your secret key in API requests.

        You can manage your API keys in the
        [Dashboard](https://app.pdfshift.io/dashboard/).


        Authentication to the API is performed by using the HTTP Header
        X-API-Key.
      name: X-API-Key
      in: header
      x-last-modified: 1764750344730

````