openapi: 3.0.3
info:
  title: PDFShift API Documentation account Convert API
  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: []
tags:
- name: Convert
paths:
  /convert/pdf:
    post:
      tags:
      - Convert
      summary: Convert to PDF
      x-mint:
        content: '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>'
      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'
      x-last-modified: 1764751282579
  /convert/png:
    x-last-modified: 1764751294923
    post:
      tags:
      - Convert
      summary: Convert to PNG
      x-mint:
        content: 'This endpoint will convert an HTML document to a PNG image.


          You can specify additional options to customize the output image, such as capturing the full page, selecting specific elements using CSS selectors, or defining a clip region.

          <Note>Only one of `fullpage`, `css_selector`, or `clip` can be set at a time.</Note>


          <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>'
      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/ImageConvertForm'
              - $ref: '#/components/schemas/ConvertForm'
              required:
              - source
      responses:
        '200':
          description: PNG 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:
            image/png:
              schema:
                type: string
                format: binary
              example: <...PNG 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
                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'
        '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'
  /convert/jpeg:
    x-last-modified: 1764751315921
    post:
      tags:
      - Convert
      summary: Convert to JPEG
      x-mint:
        content: 'This endpoint will convert an HTML document to a JPEG image.


          You can specify additional options to customize the output image, such as capturing the full page, selecting specific elements using CSS selectors, or defining a clip region.

          <Note>Only one of `fullpage`, `css_selector`, or `clip` can be set at a time.</Note>


          <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>'
      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/ImageConvertForm'
              - $ref: '#/components/schemas/ConvertForm'
              required:
              - source
      responses:
        '200':
          description: JPEG 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:
            image/jpeg:
              schema:
                type: string
                format: binary
              example: <...JPEG 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
                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'
        '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'
  /convert/webp:
    x-last-modified: 1764751389626
    post:
      tags:
      - Convert
      summary: Convert to WEBP
      x-mint:
        content: 'This endpoint will convert an HTML document to a WEBP image.


          You can specify additional options to customize the output image, such as capturing the full page, selecting specific elements using CSS selectors, or defining a clip region.

          <Note>Only one of `fullpage`, `css_selector`, or `clip` can be set at a time.</Note>


          <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>'
      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/ImageConvertForm'
              - $ref: '#/components/schemas/ConvertForm'
              required:
              - source
      responses:
        '200':
          description: WEBP 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:
            image/webp:
              schema:
                type: string
                format: binary
              example: <...WEBP 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
                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'
        '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:
    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
    Errors:
      type: object
      properties:
        success:
          type: boolean
        errors:
          type: object
        code:
          type: integer
          format: int32
    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
    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.
    CookieForm:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        secure:
          type: boolean
          default: false
        http_only:
          type: boolean
          default: false
      required:
      - name
      - value
    Error:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        code:
          type: integer
          format: int32
    ImageConvertForm:
      type: object
      properties:
        viewport:
          type: string
          default: 1280x1024
          description: Default size of the rendering window. This will define the size of your image when using fullpage. Format in {width}x{height} (in pixels).
        transparent:
          type: boolean
          default: false
          description: 'If set to true, the image will have a transparent background.

            **Note**: This option is only available when outputting PNG images.'
        fullpage:
          type: boolean
          default: false
          description: 'Capture the full scrollable page.

            Only one of `fullpage`, `css_selector`, or `clip` can be set.'
        css_selector:
          type: string
          default: null
          description: 'CSS selector for the element to capture.

            Only one of `fullpage`, `css_selector`, or `clip` can be set.'
        clip:
          type: object
          description: 'Clip region to capture.

            Only one of `fullpage`, `css_selector`, or `clip` can be set.'
          properties:
            width:
              type: integer
              minimum: 1
              description: Width of the region to capture (in pixels).
            height:
              type: integer
              minimum: 1
              description: Height of the region to capture (in pixels).
            x:
              type: integer
              description: X coordinate of the top-left corner (in pixels).
            y:
              type: integer
              description: Y coordinate of the top-left corner (in pixels).
          required:
          - width
          - height
          - x
          - y
        quality:
          type: integer
          minimum: 10
          maximum: 100
          default: 80
          description: Quality of the output image (only for JPEG, 10-100).
        dpi:
          type: integer
          enum:
          - 1
          - 2
          - 4
          default: 1
          description: DPI scaling factor. Must be one of 1, 2, or 4.
    MarginForm:
      type: object
      properties:
        top:
          type: string
          default: '48'
        right:
          type: string
          default: '48'
        bottom:
          type: string
          default: '48'
        left:
          type: string
          default: '48'
    BasicAuthForm:
      type: object
      properties:
        username:
          type: string
          default: null
        password:
          type: string
          default: null
    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).
    CustomHeaderFooter:
      type: object
      properties:
        source:
          description: "Element to add in the header part of the document.\nPDFShift will automatically detect if it's an URL and load it, or an HTML data and charge it.\n\nAccepted variables are:\n  {{date}}  - Formatted print date\n  {{title}} - Title of the HTML document\n  {{url}}   - Page URL\n  {{page}}  - Current page\n  {{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
  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
externalDocs:
  description: You can access our documentation online by visiting https://docs.pdfshift.io
  url: https://docs.pdfshift.io