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