PDFShift Convert API
The Convert API from PDFShift — 4 operation(s) for convert.
OpenAPI Specification
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 excepte
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pdfshift/refs/heads/main/openapi/pdfshift-convert-api-openapi.yml