openapi: 3.1.0 info: title: PDFBolt API version: 1.0.0 summary: PDF generation and reusable template management API description: > PDFBolt provides REST APIs for generating PDFs from Base64-encoded HTML, HTTPS URLs, and published templates with JSON data, and for managing reusable templates. The Conversion API has three modes: Direct returns the generated PDF in the HTTP response, Sync returns a temporary download URL, and Async accepts a background job and delivers the final result to your webhook. The Template API lets you create and manage reusable templates programmatically using a Personal Access Token. Outbound URL fetching, webhook delivery, and custom S3 uploads use PDFBolt's static outbound IP addresses. See [IP Addresses](https://pdfbolt.com/docs/ip-addresses). Open the raw OpenAPI YAML: [openapi.yaml](/openapi.yaml). contact: name: PDFBolt email: contact@pdfbolt.com url: https://pdfbolt.com/contact license: name: Proprietary url: https://pdfbolt.com/terms servers: - url: https://api.pdfbolt.com description: PDFBolt API security: - apiKeyAuth: [] tags: - name: Conversion API description: Generate PDFs from HTML, URLs, or templates. - name: Webhooks description: Callbacks sent by PDFBolt to your application after an async conversion succeeds or permanently fails. - name: Usage description: View your current plan and remaining conversions. - name: Template API description: Create and manage reusable PDF templates using a Personal Access Token. paths: /v1/direct: post: tags: - Conversion API operationId: convertDirect summary: Generate a PDF and return it in the response body description: > Generates a PDF from a URL, Base64-encoded HTML, or a published template ID with template data, then returns the generated document directly in the HTTP response body. Use this endpoint when your application needs the PDF immediately. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DirectConversionRequest" examples: url: summary: Convert a URL to PDF value: url: https://example.com html: summary: Convert Base64 HTML to PDF value: html: PGh0bWw+PGJvZHk+PGgxPkludm9pY2UgIzEwNDI8L2gxPjxwPkFtb3VudDogJDI1MC4wMDwvcD48L2JvZHk+PC9odG1sPg== template: summary: Convert a template to PDF value: templateId: 00000000-0000-0000-0000-000000000000 templateData: invoice_number: INV-2026-0112 total: $250.00 encoded: summary: Return the PDF as Base64 text value: url: https://example.com isEncoded: true responses: "200": description: Generated PDF returned as binary PDF or Base64-encoded text. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" Content-Disposition: $ref: "#/components/headers/ContentDisposition" content: application/pdf: schema: $ref: "#/components/schemas/PdfBinaryResponse" text/plain: schema: $ref: "#/components/schemas/PdfBase64Response" examples: Base64 PDF: summary: Base64-encoded PDF response value: JVBERi0xLjQKJcfs... "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "408": $ref: "#/components/responses/ConversionTimeout" "413": $ref: "#/components/responses/PayloadTooLarge" "422": $ref: "#/components/responses/UnprocessableEntity" "429": $ref: "#/components/responses/TooManyRequests" "499": $ref: "#/components/responses/ClientDisconnected" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/sync: post: tags: - Conversion API operationId: convertSync summary: Generate a PDF and return a temporary download URL description: | Generates a PDF from a URL, Base64-encoded HTML, or a published template ID with template data, then returns a JSON response with a downloadable document URL. By default, files stored in PDFBolt's temporary storage expire after 24 hours. You can provide `customS3PresignedUrl` to upload the PDF directly to your own S3-compatible bucket. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SyncConversionRequest" examples: url: summary: Convert a URL to PDF and receive a download URL value: url: https://example.com html: summary: Convert Base64 HTML to PDF and receive a download URL value: html: PGh0bWw+PGJvZHk+PGgxPkludm9pY2UgIzEwNDI8L2gxPjxwPkFtb3VudDogJDI1MC4wMDwvcD48L2JvZHk+PC9odG1sPg== template: summary: Convert a template to PDF and receive a download URL value: templateId: 00000000-0000-0000-0000-000000000000 templateData: invoice_number: INV-2026-0112 total: $250.00 customS3: summary: Upload the generated PDF to a custom S3-compatible bucket value: url: https://example.com customS3PresignedUrl: https://your-bucket.s3.amazonaws.com/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=example responses: "200": description: PDF generated successfully. The response contains the conversion result. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/SyncResponse" examples: Default storage: $ref: "#/components/examples/SyncSuccess" Custom S3 upload: $ref: "#/components/examples/SyncCustomS3Success" "400": $ref: "#/components/responses/SyncBadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "408": $ref: "#/components/responses/ConversionTimeout" "413": $ref: "#/components/responses/PayloadTooLarge" "422": $ref: "#/components/responses/UnprocessableEntity" "429": $ref: "#/components/responses/TooManyRequests" "499": $ref: "#/components/responses/ClientDisconnected" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/async: post: tags: - Conversion API operationId: createAsyncConversion summary: Generate a PDF and deliver the result by webhook description: > Generates a PDF in the background, immediately returns a `requestId`, and delivers the final result to your HTTPS webhook URL once the job succeeds or permanently fails. The `webhook` parameter is required. You can provide `customS3PresignedUrl` to upload the PDF directly to your own S3-compatible bucket. This endpoint is available on paid plans. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AsyncConversionRequest" examples: url: summary: Generate a PDF from a URL and receive the result by webhook value: url: https://example.com webhook: https://your-app.com/webhook html: summary: Generate a PDF from Base64 HTML and receive the result by webhook value: html: PGh0bWw+PGJvZHk+PGgxPkludm9pY2UgIzEwNDI8L2gxPjxwPkFtb3VudDogJDI1MC4wMDwvcD48L2JvZHk+PC9odG1sPg== webhook: https://your-app.com/webhook template: summary: Generate a PDF from a template and receive the result by webhook value: templateId: 00000000-0000-0000-0000-000000000000 templateData: invoice_number: INV-2026-0112 total: $250.00 webhook: https://your-app.com/webhook customS3: summary: Generate a PDF from a URL and upload it to a custom S3-compatible bucket value: url: https://example.com webhook: https://your-app.com/webhook customS3PresignedUrl: https://your-bucket.s3.amazonaws.com/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=example responses: "200": description: Async request accepted for background processing. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/AsyncResponse" examples: Accepted: $ref: "#/components/examples/AsyncAccepted" "400": $ref: "#/components/responses/AsyncBadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "413": $ref: "#/components/responses/RequestPayloadTooLarge" "422": $ref: "#/components/responses/UnprocessableEntity" "429": $ref: "#/components/responses/TooManyRequests" "499": $ref: "#/components/responses/ClientDisconnected" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/usage: get: tags: - Usage operationId: getUsage summary: Get current plan and remaining conversions description: | Returns the authenticated account's current plan, recurring conversion details, one-time conversion packages, remaining conversions, overage, and expiration dates. Use the same `API-KEY` header as the Conversion API endpoints. Use it to track conversion usage, not API request limits. responses: "200": description: Usage details returned successfully. content: application/json: schema: $ref: "#/components/schemas/UsageResponse" examples: Usage: $ref: "#/components/examples/UsageSuccess" "401": $ref: "#/components/responses/Unauthorized" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/templates/contract: get: tags: - Template API security: [] operationId: getTemplateContract summary: Get the public Template Contract description: > Returns the current version of the Template Contract. It covers supported fields, defaults, rendering guidance, limits, errors, and the recommended workflow for building and publishing templates. Use the Template Contract for PDFBolt-specific template rules and this OpenAPI document for exact request and response schemas. No authentication is required. responses: "200": description: Template Contract returned successfully. content: application/json: schema: $ref: "#/components/schemas/TemplateContract" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/templates: get: tags: - Template API security: - personalAccessTokenAuth: [] operationId: listTemplates summary: List templates description: Returns the current team's templates with details about their published and draft versions. responses: "200": description: Templates returned successfully. content: application/json: schema: $ref: "#/components/schemas/TemplateApiListResponse" example: templates: - id: 123e4567-e89b-12d3-a456-426614174000 name: Invoice description: Monthly invoice template templateEngine: HANDLEBARS hasDraft: true publishedVersion: id: 381 status: PUBLISHED versionNumber: 1 createdTime: "2026-07-20T10:00:00Z" modifiedTime: "2026-07-20T10:05:00Z" draftVersion: id: 382 status: DRAFT versionNumber: 2 createdTime: "2026-07-21T09:00:00Z" modifiedTime: "2026-07-21T09:30:00Z" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "429": $ref: "#/components/responses/TemplateApiTooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/templates/{templateId}: get: tags: - Template API security: - personalAccessTokenAuth: [] operationId: getTemplate summary: Get template details description: > Returns the template details, including its content, sample data, PDF parameters, active draft, and latest published version. If a draft exists, the content, sample data, and PDF parameters come from it. Otherwise, they come from the published version. parameters: - $ref: "#/components/parameters/TemplateId" responses: "200": description: Template details returned successfully. content: application/json: schema: $ref: "#/components/schemas/TemplateApiTemplate" example: id: 2b1124e7-7f8d-4fd9-9d0a-4f8cf0c58f98 name: Invoice description: Monthly invoice template templateEngine: HANDLEBARS hasDraft: true content: PCFET0NUWVBFIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjxwPnt7Y3VzdG9tZXJOYW1lfX08L3A+PC9ib2R5PjwvaHRtbD4= sampleData: invoiceNumber: INV-1001 customerName: Acme Inc. parameters: format: A4 landscape: false waitUntil: load footerTemplate: PGRpdj48c3BhbiBjbGFzcz0icGFnZU51bWJlciI+PC9zcGFuPjwvZGl2Pg== headerTemplate: PGRpdj48L2Rpdj4= printBackground: true waitForFunction: "() => document.readyState === 'complete'" displayHeaderFooter: true publishedVersion: id: 381 status: PUBLISHED versionNumber: 3 createdTime: "2026-06-20T10:12:34Z" modifiedTime: "2026-06-20T10:12:34Z" draftVersion: id: 382 status: DRAFT versionNumber: 4 createdTime: "2026-06-20T11:03:12Z" modifiedTime: "2026-06-20T11:08:41Z" "400": $ref: "#/components/responses/TemplateApiInvalidIdBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "404": $ref: "#/components/responses/TemplateApiNotFound" "429": $ref: "#/components/responses/TemplateApiTooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/templates/validate: post: tags: - Template API security: - personalAccessTokenAuth: [] operationId: validateTemplatePayload summary: Validate a template payload description: > Validates a template payload without saving it or rendering a PDF. It checks required fields, Base64 content, payload size limits, the template engine, Handlebars syntax and evaluation, and supported PDF parameters. Use it before previewing or saving a draft. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TemplateApiTemplatePayload" example: templateEngine: HANDLEBARS content: PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+ sampleData: invoiceNumber: INV-1001 parameters: format: A4 waitUntil: networkidle printBackground: true responses: "200": description: Template payload is valid. "400": $ref: "#/components/responses/TemplateApiValidateBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "413": $ref: "#/components/responses/TemplateApiValidatePayloadTooLarge" "429": $ref: "#/components/responses/TemplateApiTooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/templates/preview: post: tags: - Template API security: - personalAccessTokenAuth: [] operationId: previewTemplatePayload summary: Preview a template payload description: Renders a candidate template payload as a PDF without saving it. Successful previews consume conversion credits. parameters: - name: responseFormat in: query required: false description: Response format. Defaults to `pdf`, which returns raw PDF bytes. Use `json` to return `pdfBase64` and `documentSizeMb`. Both formats return the conversion cost in the `x-pdfbolt-conversion-cost` response header. schema: type: string enum: - pdf - json default: pdf requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TemplateApiTemplatePayload" example: templateEngine: HANDLEBARS content: PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+ sampleData: invoiceNumber: INV-1001 parameters: format: A4 waitUntil: networkidle printBackground: true responses: "200": description: Preview rendered successfully. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/pdf: schema: $ref: "#/components/schemas/TemplateApiPreviewPdfResponse" application/json: schema: $ref: "#/components/schemas/TemplateApiPreviewJsonResponse" example: documentSizeMb: 0.01 pdfBase64: JVBERi0xLjQKJSVFT0YK "400": $ref: "#/components/responses/TemplateApiPreviewBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "403": $ref: "#/components/responses/TemplateApiConversionForbidden" "408": $ref: "#/components/responses/TemplateApiConversionTimeout" "413": $ref: "#/components/responses/TemplateApiPreviewPayloadTooLarge" "422": $ref: "#/components/responses/TemplateApiUnprocessableEntity" "429": $ref: "#/components/responses/TooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/templates/{templateId}/diff: post: tags: - Template API security: - personalAccessTokenAuth: [] operationId: diffTemplatePayload summary: Compare a candidate with the published version description: > Requires the template to have a published version. Renders the published version as `before` and the candidate payload as `after` for visual comparison. Conversion credits are charged separately for each PDF that renders successfully. parameters: - $ref: "#/components/parameters/TemplateId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TemplateApiDiffRequest" example: templateEngine: HANDLEBARS content: PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+ sampleData: invoiceNumber: INV-1001 parameters: format: A4 waitUntil: networkidle printBackground: true responses: "200": description: Comparison completed. Rendering failures are returned in `before.error` or `after.error` while the response remains HTTP 200. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/TemplateApiDiffResponse" example: before: documentSizeMb: 0.00 pdfBase64: JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAyMDAgMjAwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAzOCA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjQwIDEwMCBUZAooQmVmb3JlKSBUagpFVAplbmRzdHJlYW0KZW5kb2JqCjUgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTUgMDAwMDAgbiAKMDAwMDAwMDA2NCAwMDAwMCBuIAowMDAwMDAwMTIxIDAwMDAwIG4gCjAwMDAwMDAyNDcgMDAwMDAgbiAKMDAwMDAwMDMzNCAwMDAwMCBuIAp0cmFpbGVyCjw8IC9TaXplIDYgL1Jvb3QgMSAwIFIgPj4Kc3RhcnR4cmVmCjQwNAolJUVPRgo= error: null after: documentSizeMb: 0.00 pdfBase64: JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCAyMDAgMjAwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCAzNyA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjQwIDEwMCBUZAooQWZ0ZXIpIFRqCkVUCmVuZHN0cmVhbQplbmRvYmoKNSAwIG9iago8PCAvVHlwZSAvRm9udCAvU3VidHlwZSAvVHlwZTEgL0Jhc2VGb250IC9IZWx2ZXRpY2EgPj4KZW5kb2JqCnhyZWYKMCA2CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMDY0IDAwMDAwIG4gCjAwMDAwMDAxMjEgMDAwMDAgbiAKMDAwMDAwMDI0NyAwMDAwMCBuIAowMDAwMDAwMzMzIDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgNiAvUm9vdCAxIDAgUiA+PgpzdGFydHhyZWYKNDAzCiUlRU9GCg== error: null "400": $ref: "#/components/responses/TemplateApiDiffBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "404": $ref: "#/components/responses/TemplateApiDiffNotFound" "413": $ref: "#/components/responses/TemplateApiDiffPayloadTooLarge" "429": $ref: "#/components/responses/TooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /v1/templates/drafts: post: tags: - Template API security: - personalAccessTokenAuth: [] operationId: saveTemplateDraft summary: Create or update a template draft description: > Creates a new template and its first draft when `templateId` is omitted. When `templateId` is provided, the endpoint updates only the supplied fields, using the active draft as the base or the published version when no draft exists. Supplied `content` and `sampleData` replace their complete stored values; `parameters` is applied as a shallow patch. The resulting payload is validated without rendering a PDF or consuming conversion credits. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TemplateApiSaveDraftRequest" responses: "200": description: Draft saved successfully. content: application/json: schema: $ref: "#/components/schemas/TemplateApiSaveDraftResponse" examples: TemplateCreated: summary: New template and first draft created value: templateId: 93fee603-cb2a-40db-8deb-b2e3cb1eed0f draftVersionId: 2038 versionNumber: 1 createdTemplate: true DraftUpdated: summary: Existing template draft updated value: templateId: 93fee603-cb2a-40db-8deb-b2e3cb1eed0f draftVersionId: 2038 versionNumber: 1 createdTemplate: false "400": $ref: "#/components/responses/TemplateApiSaveDraftBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "403": $ref: "#/components/responses/TemplateApiTemplateLimitForbidden" "404": $ref: "#/components/responses/TemplateApiNotFound" "413": $ref: "#/components/responses/TemplateApiPayloadTooLarge" "429": $ref: "#/components/responses/TemplateApiTooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" /v1/templates/{templateId}/publish: post: tags: - Template API security: - personalAccessTokenAuth: [] operationId: publishTemplateDraft summary: Publish a template draft description: > Publishes the active draft as the template's latest published version. Use the published template for PDF conversions by sending its `templateId` and `templateData` to a Conversion API endpoint. parameters: - $ref: "#/components/parameters/TemplateId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TemplateApiPublishRequest" responses: "200": description: Template draft published successfully. content: application/json: schema: $ref: "#/components/schemas/TemplateApiPublishResponse" example: templateId: 93fee603-cb2a-40db-8deb-b2e3cb1eed0f publishedVersionId: 2038 versionNumber: 1 "400": $ref: "#/components/responses/TemplateApiPublishBadRequest" "401": $ref: "#/components/responses/TemplateApiUnauthorized" "404": $ref: "#/components/responses/TemplateApiNotFound" "413": $ref: "#/components/responses/TemplateApiPublishPayloadTooLarge" "429": $ref: "#/components/responses/TemplateApiTooManyRequests" "503": $ref: "#/components/responses/ServiceUnavailable" webhooks: asyncConversionResult: post: tags: - Webhooks security: [] operationId: receiveAsyncConversionResult summary: Receive async result description: | PDFBolt sends this webhook to the URL provided in the `webhook` parameter of an async conversion request. PDFBolt attempts one callback for each accepted async conversion: after the conversion succeeds or after all configured conversion retries fail. Verify the `x-pdfbolt-signature` header with your webhook signature key before trusting the payload. parameters: - name: x-pdfbolt-signature in: header required: true description: HMAC-SHA256 signature of the raw webhook request body, prefixed with `sha256=` and encoded as lowercase hex. Verify the exact bytes received in the HTTP body before parsing or re-serializing JSON. schema: type: string pattern: ^sha256=[a-f0-9]{64}$ examples: - sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef - name: x-pdfbolt-conversion-cost in: header required: true description: Number of document credits charged for the conversion. For failed conversions, PDFBolt sends `0`. schema: type: integer minimum: 0 examples: - 1 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AsyncWebhookRequest" examples: Success: $ref: "#/components/examples/AsyncWebhookSuccess" Failure: $ref: "#/components/examples/AsyncWebhookFailure" responses: 2XX: description: Your webhook endpoint should return a successful 2xx response after accepting the callback. components: parameters: TemplateId: name: templateId in: path required: true description: UUID of a PDFBolt template. schema: type: string format: uuid securitySchemes: apiKeyAuth: type: apiKey in: header name: API-KEY description: API key from the API Credentials page in the PDFBolt Dashboard personalAccessTokenAuth: type: apiKey in: header name: PERSONAL-ACCESS-TOKEN description: Personal Access Token from the API Credentials page in the PDFBolt Dashboard. Used by Template API endpoints. headers: ConversionCost: description: Document credits charged for the request. schema: type: integer minimum: 0 examples: - 1 ContentDisposition: description: Controls inline vs attachment delivery and includes a filename when provided. schema: type: string examples: - inline - attachment; filename="custom_file_name.pdf" RateLimitMinute: description: Request limit for the current rolling minute. schema: type: integer minimum: 0 RateLimitRemainingMinute: description: Requests remaining in the current rolling minute. schema: type: integer minimum: 0 RateLimitHour: description: Request limit for the current rolling hour. schema: type: integer minimum: 0 RateLimitRemainingHour: description: Requests remaining in the current rolling hour. schema: type: integer minimum: 0 RateLimitDay: description: Request limit for the current rolling 24-hour window. schema: type: integer minimum: 0 RateLimitRemainingDay: description: Requests remaining in the current rolling 24-hour window. schema: type: integer minimum: 0 RetryAfter: description: Number of seconds to wait before retrying the Template API management request. schema: type: integer enum: - 60 - 3600 responses: BadRequest: description: Invalid JSON, invalid parameter values, or a problem with the conversion source. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/DirectBadRequestApiError" examples: Bad request: $ref: "#/components/examples/BadRequestError" Target closed: $ref: "#/components/examples/TargetClosedError" No browser context: $ref: "#/components/examples/NoBrowserContextError" URL not resolved: $ref: "#/components/examples/UrlNotResolvedError" PDF printing failed: $ref: "#/components/examples/PdfPrintingFailedError" Template evaluation error: $ref: "#/components/examples/TemplateEvalError" Invalid credentials: $ref: "#/components/examples/InvalidCredentialsError" HTTP response failure: $ref: "#/components/examples/HttpResponseFailureError" Unexpected error: $ref: "#/components/examples/UnexpectedError" SyncBadRequest: description: Invalid JSON, invalid parameter values, a problem with the conversion source, or a custom S3 upload error. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/SyncBadRequestApiError" examples: Bad request: $ref: "#/components/examples/BadRequestError" Target closed: $ref: "#/components/examples/TargetClosedError" No browser context: $ref: "#/components/examples/NoBrowserContextError" URL not resolved: $ref: "#/components/examples/UrlNotResolvedError" PDF printing failed: $ref: "#/components/examples/PdfPrintingFailedError" Template evaluation error: $ref: "#/components/examples/TemplateEvalError" Invalid credentials: $ref: "#/components/examples/InvalidCredentialsError" HTTP response failure: $ref: "#/components/examples/HttpResponseFailureError" Custom S3 upload error: $ref: "#/components/examples/CustomS3UploadError" Unexpected error: $ref: "#/components/examples/UnexpectedError" AsyncBadRequest: description: Invalid JSON, invalid field types, or invalid parameter values. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/AsyncBadRequestApiError" examples: Bad request: $ref: "#/components/examples/BadRequestError" Unauthorized: description: Authentication failed because the API key is missing, invalid, or blocked. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedApiError" examples: Unauthorized: $ref: "#/components/examples/UnauthorizedError" Forbidden: description: The API key is valid, but the account cannot perform this action. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/ForbiddenApiError" examples: Forbidden: $ref: "#/components/examples/ForbiddenError" NotFound: description: The requested API endpoint could not be found. content: application/json: schema: $ref: "#/components/schemas/NotFoundApiError" examples: Not found: $ref: "#/components/examples/NotFoundError" ConversionTimeout: description: Conversion process timed out. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/ConversionTimeoutApiError" examples: Conversion timeout: $ref: "#/components/examples/ConversionTimeoutError" PayloadTooLarge: description: The request payload or generated PDF exceeds the allowed size. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/PayloadTooLargeApiError" examples: Payload too large: $ref: "#/components/examples/PayloadTooLargeError" PDF size too large: $ref: "#/components/examples/PdfSizeTooLargeError" RequestPayloadTooLarge: description: The request payload exceeds the allowed size. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/RequestPayloadTooLargeApiError" examples: Payload too large: $ref: "#/components/examples/PayloadTooLargeError" UnprocessableEntity: description: The request could not be processed correctly. headers: x-pdfbolt-conversion-cost: $ref: "#/components/headers/ConversionCost" x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/UnprocessableEntityApiError" examples: Unprocessable entity: $ref: "#/components/examples/UnprocessableEntityError" TooManyRequests: description: The account exceeded minute, hour, day, or concurrent request limits. content: application/json: schema: $ref: "#/components/schemas/TooManyRequestsApiError" examples: Too many requests: $ref: "#/components/examples/TooManyRequestsError" TemplateApiPublishBadRequest: description: The request is invalid or the template has no active draft to publish. content: application/json: schema: $ref: "#/components/schemas/BadRequestApiError" examples: No active draft: $ref: "#/components/examples/TemplateApiNoActiveDraftError" TemplateApiSaveDraftBadRequest: description: The request body is malformed or the draft payload failed validation. content: application/json: schema: $ref: "#/components/schemas/BadRequestApiError" examples: Missing template name: $ref: "#/components/examples/TemplateApiSaveDraftMissingNameError" TemplateApiValidateBadRequest: description: The request body is malformed or the template payload failed validation. Check the required fields, Base64 content, `sampleData`, the template engine, Handlebars syntax and evaluation, and PDF parameters. content: application/json: schema: $ref: "#/components/schemas/BadRequestApiError" examples: Missing parameters: $ref: "#/components/examples/TemplateApiMissingParametersError" TemplateApiInvalidIdBadRequest: description: The `templateId` path parameter is not a valid UUID. content: application/json: schema: $ref: "#/components/schemas/BadRequestApiError" examples: Invalid template id: $ref: "#/components/examples/TemplateApiInvalidIdError" TemplateApiPreviewBadRequest: description: The request body is malformed, `responseFormat` is unsupported, the template payload failed validation, or PDF rendering failed before the preview could be returned. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/TemplateApiPreviewBadRequestApiError" examples: Missing parameters: $ref: "#/components/examples/TemplateApiMissingParametersError" TemplateApiDiffBadRequest: description: The `templateId` path parameter is invalid, the request body is malformed, or template validation failed before rendering. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/BadRequestApiError" examples: Missing parameters: $ref: "#/components/examples/TemplateApiMissingParametersError" TemplateApiUnauthorized: description: Authentication failed because the Personal Access Token is missing, invalid, inactive, or blocked. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedApiError" examples: Unauthorized: $ref: "#/components/examples/TemplateApiUnauthorizedError" TemplateApiTemplateLimitForbidden: description: A new template could not be created because the authenticated team has reached its current plan's template limit. content: application/json: schema: $ref: "#/components/schemas/ForbiddenApiError" examples: Template limit reached: $ref: "#/components/examples/TemplateApiTemplateLimitError" TemplateApiConversionForbidden: description: The preview could not be rendered because PDF conversion is unavailable. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/ForbiddenApiError" examples: Conversion credits unavailable: $ref: "#/components/examples/TemplateApiConversionCreditsError" PDF conversions disabled: $ref: "#/components/examples/TemplateApiConversionDisabledError" TemplateApiNotFound: description: The template does not exist or does not belong to the authenticated team. content: application/json: schema: $ref: "#/components/schemas/NotFoundApiError" examples: Template not found: $ref: "#/components/examples/TemplateApiNotFoundError" TemplateApiDiffNotFound: description: The template does not exist, does not belong to the authenticated team, or has no published version. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/NotFoundApiError" examples: Template not found: $ref: "#/components/examples/TemplateApiNotFoundError" TemplateApiPayloadTooLarge: description: One of `content`, `sampleData`, or `parameters` exceeds its size limit. content: application/json: schema: $ref: "#/components/schemas/RequestPayloadTooLargeApiError" examples: Template payload too large: $ref: "#/components/examples/TemplateApiPayloadTooLargeError" TemplateApiPublishPayloadTooLarge: description: One of the active draft fields (`content`, `sampleData`, or `parameters`) exceeds its size limit. content: application/json: schema: $ref: "#/components/schemas/RequestPayloadTooLargeApiError" examples: Active draft too large: $ref: "#/components/examples/TemplateApiPayloadTooLargeError" TemplateApiValidatePayloadTooLarge: description: The decoded HTML content, `sampleData`, or `parameters` exceeds the applicable size limit. content: application/json: schema: $ref: "#/components/schemas/RequestPayloadTooLargeApiError" examples: Template content too large: $ref: "#/components/examples/TemplateApiValidatePayloadTooLargeError" TemplateApiDiffPayloadTooLarge: description: One of `content`, `sampleData`, or `parameters` exceeds its size limit before rendering. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/RequestPayloadTooLargeApiError" examples: Template payload too large: $ref: "#/components/examples/TemplateApiPayloadTooLargeError" TemplateApiPreviewPayloadTooLarge: description: The template payload or generated preview PDF exceeds the applicable size limit. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/PayloadTooLargeApiError" examples: Template payload too large: $ref: "#/components/examples/TemplateApiPayloadTooLargeError" PDF size too large: $ref: "#/components/examples/TemplateApiPdfSizeTooLargeError" TemplateApiConversionTimeout: description: Preview rendering timed out. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/ConversionTimeoutApiError" examples: Conversion timeout: $ref: "#/components/examples/TemplateApiConversionTimeoutError" TemplateApiUnprocessableEntity: description: The request could not be processed correctly. headers: x-pdfbolt-limit-minute: $ref: "#/components/headers/RateLimitMinute" x-pdfbolt-remaining-minute: $ref: "#/components/headers/RateLimitRemainingMinute" x-pdfbolt-limit-hour: $ref: "#/components/headers/RateLimitHour" x-pdfbolt-remaining-hour: $ref: "#/components/headers/RateLimitRemainingHour" x-pdfbolt-limit-day: $ref: "#/components/headers/RateLimitDay" x-pdfbolt-remaining-day: $ref: "#/components/headers/RateLimitRemainingDay" content: application/json: schema: $ref: "#/components/schemas/UnprocessableEntityApiError" examples: Unprocessable entity: $ref: "#/components/examples/TemplateApiUnprocessableEntityError" TemplateApiTooManyRequests: description: The authenticated user exceeded a Template API management rate limit. See [Rate Limits](https://pdfbolt.com/docs/rate-limits) for current limits. headers: Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/TooManyRequestsApiError" examples: Too many requests: $ref: "#/components/examples/TemplateApiTooManyRequestsError" ClientDisconnected: description: PDFBolt detected that the client disconnected before the response could be fully delivered. The standard JSON body is documented for consistency, but the client will not receive it if the connection is already closed. content: application/json: schema: $ref: "#/components/schemas/ClientDisconnectedApiError" examples: Client disconnected: $ref: "#/components/examples/ClientDisconnectedError" ServiceUnavailable: description: Service temporarily unavailable. Infrastructure-generated responses may not follow PDFBolt's standard JSON error format. GatewayTimeout: description: Gateway timeout. Infrastructure-generated responses may not follow PDFBolt's standard JSON error format. x-apiErrorShared: required: - timestamp - httpErrorCode - errorCode - errorMessage timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. errorMessage: type: string description: Descriptive message explaining the error. schemas: DirectConversionRequest: oneOf: - title: URL type: object additionalProperties: false required: - url properties: url: $ref: "#/components/schemas/HttpsUrl" html: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. isEncoded: type: - boolean - "null" default: false description: When `true`, returns the generated PDF as Base64 text instead of binary PDF. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: HTML type: object additionalProperties: false required: - html properties: html: type: string contentEncoding: base64 description: Base64-encoded HTML content to convert into a PDF. url: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. isEncoded: type: - boolean - "null" default: false description: When `true`, returns the generated PDF as Base64 text instead of binary PDF. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: Template type: object additionalProperties: false required: - templateId - templateData properties: templateId: type: string format: uuid description: UUID of a published template. templateData: type: object additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. html: type: "null" url: type: "null" isEncoded: type: - boolean - "null" default: false description: When `true`, returns the generated PDF as Base64 text instead of binary PDF. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" SyncConversionRequest: oneOf: - title: URL type: object additionalProperties: false required: - url properties: url: $ref: "#/components/schemas/HttpsUrl" html: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: HTML type: object additionalProperties: false required: - html properties: html: type: string contentEncoding: base64 description: Base64-encoded HTML content to convert into a PDF. url: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: Template type: object additionalProperties: false required: - templateId - templateData properties: templateId: type: string format: uuid description: UUID of a published template. templateData: type: object additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. html: type: "null" url: type: "null" customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" AsyncConversionRequest: oneOf: - title: URL type: object additionalProperties: false required: - url - webhook properties: url: $ref: "#/components/schemas/HttpsUrl" html: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. webhook: $ref: "#/components/schemas/HttpsUrl" description: HTTPS webhook endpoint where PDFBolt delivers the conversion result. customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. additionalWebhookHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent with the webhook callback. Use them for tenant, environment, or request correlation context. Maximum 10 headers. retryDelays: type: - array - "null" minItems: 1 maxItems: 5 uniqueItems: true items: type: integer minimum: 1 maximum: 1440 description: Retry delays for failed conversion attempts, in minutes. Values must be positive integers from 1 to 1440 in strictly ascending order. Webhook delivery is not retried. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: HTML type: object additionalProperties: false required: - html - webhook properties: html: type: string contentEncoding: base64 description: Base64-encoded HTML content to convert into a PDF. url: type: "null" templateId: type: "null" templateData: type: - object - "null" additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. webhook: $ref: "#/components/schemas/HttpsUrl" description: HTTPS webhook endpoint where PDFBolt delivers the conversion result. customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. additionalWebhookHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent with the webhook callback. Use them for tenant, environment, or request correlation context. Maximum 10 headers. retryDelays: type: - array - "null" minItems: 1 maxItems: 5 uniqueItems: true items: type: integer minimum: 1 maximum: 1440 description: Retry delays for failed conversion attempts, in minutes. Values must be positive integers from 1 to 1440 in strictly ascending order. Webhook delivery is not retried. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" - title: Template type: object additionalProperties: false required: - templateId - templateData - webhook properties: templateId: type: string format: uuid description: UUID of a published template. templateData: type: object additionalProperties: true description: Only used with `templateId`. JSON data used to fill variables in the published template. html: type: "null" url: type: "null" webhook: $ref: "#/components/schemas/HttpsUrl" description: HTTPS webhook endpoint where PDFBolt delivers the conversion result. customS3PresignedUrl: anyOf: - $ref: "#/components/schemas/HttpsUrl" - type: "null" description: HTTPS pre-signed PUT URL for uploading the generated PDF to your S3-compatible bucket. Available on paid plans. additionalWebhookHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent with the webhook callback. Use them for tenant, environment, or request correlation context. Maximum 10 headers. retryDelays: type: - array - "null" minItems: 1 maxItems: 5 uniqueItems: true items: type: integer minimum: 1 maximum: 1440 description: Retry delays for failed conversion attempts, in minutes. Values must be positive integers from 1 to 1440 in strictly ascending order. Webhook delivery is not retried. emulateMediaType: $ref: "#/components/schemas/EmulateMediaType" javaScriptEnabled: type: - boolean - "null" default: true description: Whether JavaScript execution is enabled while rendering the source content. httpCredentials: $ref: "#/components/schemas/HttpCredentials" viewportSize: $ref: "#/components/schemas/ViewportSize" isMobile: type: - boolean - "null" default: false description: Enables mobile device emulation, including mobile viewport behavior and touch events. deviceScaleFactor: type: - number - "null" minimum: 1 maximum: 4 default: 1 description: Pixel density used when rendering the page. Higher values can produce sharper output. extraHTTPHeaders: $ref: "#/components/schemas/HeaderMap" description: Custom HTTP headers sent while PDFBolt loads the source content and page resources. Maximum 10 headers. applyExtraHTTPHeadersToAllResources: type: - boolean - "null" default: true description: Whether `extraHTTPHeaders` are sent with all resource requests or only with the main page request. cookies: type: - array - "null" maxItems: 10 items: $ref: "#/components/schemas/Cookie" description: Cookies sent while rendering the source content. Each cookie must include name, value, and either url or both domain and path. Optional fields are expires, httpOnly, and secure. Maximum 10 cookies. waitUntil: $ref: "#/components/schemas/WaitUntil" waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated in the page context. PDF generation continues when it returns true. waitForSelector: $ref: "#/components/schemas/WaitForSelector" timeout: type: - integer - "null" minimum: 1 default: 30000 description: Maximum render wait time in milliseconds. The allowed maximum depends on your plan. format: $ref: "#/components/schemas/Format" landscape: type: - boolean - "null" default: false description: Page orientation for the generated PDF. width: $ref: "#/components/schemas/PageDimension" description: Custom page width for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. height: $ref: "#/components/schemas/PageDimension" description: Custom page height for the generated PDF. Used when format is not provided. Accepts a number of pixels or a string with px, in, cm, or mm units. margin: $ref: "#/components/schemas/Margin" pageRanges: type: - string - "null" pattern: ^\s*[1-9]\d*(?:-[1-9]\d*)?(?:\s*,\s*[1-9]\d*(?:-[1-9]\d*)?)*\s*$ description: Comma-separated page ranges such as `1-3,5,8-11`. Omit to include all pages. preferCssPageSize: type: - boolean - "null" default: false description: Whether to use the CSS `@page` size when generating the PDF. printBackground: type: - boolean - "null" default: false description: Whether to include CSS background colors, gradients, and images. scale: type: - number - "null" minimum: 0.1 maximum: 2 default: 1 description: Scaling factor for rendering the content in the generated PDF. displayHeaderFooter: type: - boolean - "null" default: false description: Whether to render the `headerTemplate` and `footerTemplate` content in the generated PDF. headerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page header. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." footerTemplate: type: - string - "null" contentEncoding: base64 description: "Base64-encoded HTML for the page footer. Used when `displayHeaderFooter` is `true`. Available classes: `pageNumber`, `totalPages`, `title`, `url`, `date`." tagged: type: - boolean - "null" default: false description: Whether to generate a tagged PDF with structural information for accessibility tools. printProduction: $ref: "#/components/schemas/PrintProduction" contentDisposition: $ref: "#/components/schemas/ContentDisposition" filename: type: - string - "null" minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ description: > Filename embedded in the `Content-Disposition` header. Allowed characters are letters, numbers, dots, underscores, and hyphens. If `.pdf` is omitted, PDFBolt adds it automatically. compression: $ref: "#/components/schemas/CompressionLevel" HttpsUrl: type: string format: uri maxLength: 2048 pattern: ^https://.+ description: HTTPS URL up to 2048 characters. Non-HTTPS URLs and test domains are rejected. PdfBinaryResponse: type: string format: binary description: Raw PDF binary returned by `/v1/direct` when `isEncoded` is omitted or `false`. PdfBase64Response: type: string contentEncoding: base64 description: Base64-encoded PDF text returned by `/v1/direct` when `isEncoded` is `true`. PageDimension: type: - number - string - "null" minimum: 1 maximum: 20000 maxLength: 100 pattern: ^\+?0*[1-9]\d*(?:\.\d+)?(px|in|cm|mm)?$ description: Page width or height as a number of pixels or a string with px, in, cm, or mm units. MarginDimension: type: - number - string - "null" minimum: 0 maximum: 20000 maxLength: 100 pattern: ^\+?\d*\.?\d+(px|in|cm|mm)?$ description: Page margin as a number of pixels or a string with px, in, cm, or mm units. HeaderMap: type: - object - "null" additionalProperties: type: string maxProperties: 10 description: HTTP header map with string keys and string values. Maximum 10 headers. ContentDisposition: type: - string - "null" enum: - inline - attachment - null default: inline description: Controls whether browsers display the generated PDF inline or download it as an attachment. EmulateMediaType: type: - string - "null" enum: - screen - print - null default: print description: CSS media type used when rendering the page for PDF generation. WaitUntil: type: - string - "null" enum: - load - domcontentloaded - networkidle - commit - null default: load description: Event used to decide when the page is ready for PDF generation. Format: type: - string - "null" enum: - Letter - Legal - Tabloid - Ledger - A0 - A1 - A2 - A3 - A4 - A5 - A6 - null default: Letter description: Paper format for the generated PDF. Takes priority over custom width or height. CompressionLevel: type: - string - "null" enum: - lossless - low - medium - high - null description: Applies compression to reduce the final PDF file size. This is most useful for image-heavy PDFs. The compression level controls the tradeoff between file size and image quality. HttpCredentials: type: - object - "null" additionalProperties: false required: - username - password properties: username: type: string description: Username for HTTP Basic Authentication. password: type: string description: Password for HTTP Basic Authentication. description: HTTP Basic Authentication credentials for protected pages. ViewportSize: type: - object - "null" additionalProperties: false required: - width - height properties: width: type: integer minimum: 1 maximum: 10000 description: Browser viewport width in pixels. height: type: integer minimum: 1 maximum: 10000 description: Browser viewport height in pixels. description: Browser viewport dimensions used when rendering the source content. Cookie: type: object additionalProperties: false required: - name - value anyOf: - title: Cookie with URL scope description: Requires name, value, and url. required: - name - value - url properties: name: type: string minLength: 1 description: Cookie name. value: type: string minLength: 1 description: Cookie value. url: type: string format: uri minLength: 1 description: URL for which the cookie is valid. - title: Cookie with domain/path scope description: Requires name, value, domain, and path. required: - name - value - domain - path properties: name: type: string minLength: 1 description: Cookie name. value: type: string minLength: 1 description: Cookie value. domain: type: string minLength: 1 description: Domain for which the cookie is valid. path: type: string minLength: 1 description: URL path for which the cookie is valid. properties: name: type: string minLength: 1 description: Cookie name. value: type: string minLength: 1 description: Cookie value. url: type: - string - "null" format: uri minLength: 1 description: URL for which the cookie is valid. Required if domain and path are not used. domain: type: - string - "null" minLength: 1 description: Domain for which the cookie is valid. Required with path if url is not used. path: type: - string - "null" minLength: 1 description: URL path for which the cookie is valid. Required with domain if url is not used. expires: type: - integer - "null" minimum: 0 description: Cookie expiration as a UNIX timestamp. httpOnly: type: - boolean - "null" description: Whether the cookie is HTTP-only. secure: type: - boolean - "null" description: Whether the cookie is secure. WaitForSelector: type: - object - "null" additionalProperties: false required: - selector - state properties: selector: type: string maxLength: 1024 description: CSS selector to wait for. state: type: string enum: - attached - detached - visible - hidden description: State the selector must reach before PDF generation continues. description: Waits for a CSS selector to reach the specified state before generating the PDF. Margin: type: - object - "null" additionalProperties: false properties: top: $ref: "#/components/schemas/MarginDimension" description: Top page margin. right: $ref: "#/components/schemas/MarginDimension" description: Right page margin. bottom: $ref: "#/components/schemas/MarginDimension" description: Bottom page margin. left: $ref: "#/components/schemas/MarginDimension" description: Left page margin. description: Page margins. Accepts a number of pixels or a string with px, in, cm, or mm units. PrintProduction: type: - object - "null" additionalProperties: false properties: pdfStandard: type: - string - "null" enum: - pdf-x-4 - pdf-x-1a - null description: PDF/X standard for print compliance. Requires `colorSpace` set to `cmyk` or left unset. colorSpace: type: - string - "null" enum: - rgb - cmyk - null default: rgb description: Target output color space. Use `cmyk` for commercial printing. iccProfile: type: - string - "null" enum: - fogra39 - fogra51 - swop - gracol - null default: fogra39 description: ICC color profile for RGB-to-CMYK conversion. Requires `colorSpace` set to `cmyk`. preserveBlack: type: - boolean - "null" default: true description: Preserve pure black as 100% K ink during CMYK conversion. Requires `colorSpace` set to `cmyk` or `pdfStandard` to be specified. description: Professional print production options. Available on Growth plan and above. SyncResponse: type: object description: Successful JSON response returned by the Sync conversion endpoint. additionalProperties: false required: - requestId - status - errorCode - errorMessage - documentUrl - expiresAt - isAsync - duration - documentSizeMb - isCustomS3Bucket properties: requestId: type: string format: uuid description: Unique identifier for the request. status: type: string const: SUCCESS description: Always `SUCCESS` for successful Sync responses. errorCode: type: "null" description: Always `null` for successful Sync responses. errorMessage: type: "null" description: Always `null` for successful Sync responses. documentUrl: type: - string - "null" format: uri description: URL to the generated PDF, or `null` when custom S3 upload is used. expiresAt: type: - string - "null" format: date-time description: Expiration timestamp for PDFs in PDFBolt's temporary storage, or `null` when custom S3 upload is used. isAsync: type: boolean const: false description: Always `false` for the Sync endpoint. duration: type: integer minimum: 0 description: PDF conversion time in milliseconds. documentSizeMb: type: number minimum: 0 description: Generated document size in megabytes. isCustomS3Bucket: type: boolean description: Whether the generated PDF was uploaded to a user-provided S3-compatible bucket. AsyncResponse: type: object description: Immediate acknowledgment returned after an Async conversion request is accepted. additionalProperties: false required: - requestId properties: requestId: type: string format: uuid description: Unique identifier for the accepted async conversion request. AsyncWebhookRequest: type: object description: Webhook payload sent by PDFBolt when an async conversion succeeds or permanently fails. additionalProperties: false required: - requestId - status - errorCode - errorMessage - documentUrl - expiresAt - isAsync - duration - documentSizeMb - isCustomS3Bucket properties: requestId: type: string format: uuid description: Unique identifier for the async conversion request. status: $ref: "#/components/schemas/ConversionStatus" errorCode: $ref: "#/components/schemas/AsyncWebhookErrorCodeNullable" description: Final async conversion error code, or `null` on success. errorMessage: type: - string - "null" description: Error message if the conversion failed, otherwise `null`. documentUrl: type: - string - "null" format: uri description: URL to the generated PDF, or `null` for failed conversions or custom S3 uploads. expiresAt: type: - string - "null" format: date-time description: Expiration timestamp for PDFs in PDFBolt's temporary storage, or `null` for failed conversions or custom S3 uploads. isAsync: type: boolean const: true description: Always `true` for async webhook callbacks. duration: type: integer minimum: 0 description: PDF conversion time for the final attempt, in milliseconds. documentSizeMb: type: - number - "null" minimum: 0 description: Generated document size in megabytes, or `null` for failed conversions. isCustomS3Bucket: type: boolean description: Whether the async conversion request used a user-provided S3-compatible bucket. UsageResponse: type: object description: Current plan, conversion packages, remaining conversions, overage, and expiration dates. additionalProperties: false required: - plan - recurring - oneTime properties: plan: type: string description: Current subscription plan name. recurring: type: array items: $ref: "#/components/schemas/RecurringCreditsPackage" description: Recurring conversion details for the current billing period. oneTime: type: array items: $ref: "#/components/schemas/OneTimeCreditsPackage" description: Active one-time conversion packages with remaining conversions. RecurringCreditsPackage: type: object additionalProperties: false required: - total - left - expires - overage properties: total: type: integer minimum: 0 description: Total recurring conversions for the current billing period. left: type: integer minimum: 0 description: Remaining recurring conversions for the current billing period. expires: type: string format: date-time description: Expiration timestamp for the current billing period. overage: type: integer minimum: 0 description: Conversions used beyond the plan allowance and tracked as overage. OneTimeCreditsPackage: type: object additionalProperties: false required: - total - left - expires properties: total: type: integer minimum: 0 description: Total one-time conversions in the package. left: type: integer minimum: 0 description: Remaining one-time conversions. expires: type: string format: date-time description: Expiration timestamp for the one-time conversion package. TemplateContract: type: object description: Versioned rules and guidance for clients that create and manage PDF templates programmatically. additionalProperties: false required: - contractVersion - language - endpointBase - resources - dashboardLinks - authentication - templatePayload - htmlCss - handlebars - templateDefaultOptions - conversionOverrides - recommendedWorkflow - previewQualityGate - authoring - limits - technicalErrors - hints properties: contractVersion: type: string description: Version identifier for the returned Template Contract. example: "2026-07-28" language: type: string description: Language code used for the contract's human-readable guidance. example: en endpointBase: type: string description: Base path for the Template API endpoints described by the contract. example: /v1/templates resources: type: object additionalProperties: false description: Public reference URLs that clients should use together with the contract. required: - openApiUrl - apiReferenceUrl - templateApiDocsUrl - templateGuideUrl - conversionParametersDocsUrl - rateLimitsDocsUrl properties: openApiUrl: type: string format: uri example: https://pdfbolt.com/openapi.yaml apiReferenceUrl: type: string format: uri example: https://pdfbolt.com/docs/api-reference templateApiDocsUrl: type: string format: uri example: https://pdfbolt.com/docs/api-endpoints/template-api templateGuideUrl: type: string format: uri example: https://pdfbolt.com/docs/pdf-templates conversionParametersDocsUrl: type: string format: uri example: https://pdfbolt.com/docs/parameters rateLimitsDocsUrl: type: string format: uri example: https://pdfbolt.com/docs/rate-limits dashboardLinks: $ref: "#/components/schemas/TemplateContractDashboardLinks" authentication: $ref: "#/components/schemas/TemplateContractAuthentication" templatePayload: $ref: "#/components/schemas/TemplateContractPayload" htmlCss: $ref: "#/components/schemas/TemplateContractRuleSection" handlebars: $ref: "#/components/schemas/TemplateContractHandlebars" templateDefaultOptions: description: PDF parameters that can be saved with a template version as defaults. allOf: - $ref: "#/components/schemas/TemplateContractOptions" example: fieldName: parameters description: >- Default PDF options saved on template versions. When creating a new template with POST /v1/templates/drafts, PDFBolt starts from the same defaults as the Dashboard designer: format=Letter, landscape=false, waitUntil=load, printBackground=true, displayHeaderFooter=false, headerTemplate omitted, footerTemplate omitted and a standard readiness waitForFunction. Any provided parameter field overrides that default for the created draft. When updating an existing template, parameters is a shallow patch against the active draft, or the published version when no draft exists. Omitting parameters or sending {} preserves every option. A null value removes headerTemplate, footerTemplate or waitForFunction; all other fields require a concrete value. fields: - name: format type: string required: false allowedValues: - Letter - Legal - Tabloid - Ledger - A0 - A1 - A2 - A3 - A4 - A5 - A6 description: Default standard PDF page format. - name: landscape type: boolean required: false allowedValues: [] description: Default page orientation. - name: waitUntil type: string required: false allowedValues: - load - domcontentloaded - networkidle - commit description: Default navigation lifecycle event used before PDF rendering. - name: printBackground type: boolean required: false allowedValues: [] description: Default CSS background printing setting. - name: displayHeaderFooter type: boolean required: false allowedValues: [] description: Default header and footer rendering setting. - name: headerTemplate type: string required: false allowedValues: [] description: Base64-encoded default Chromium header template HTML. - name: footerTemplate type: string required: false allowedValues: [] description: Base64-encoded default Chromium footer template HTML. - name: waitForFunction type: string required: false allowedValues: [] description: Default JavaScript function that must return true before rendering. conversionOverrides: description: Guidance for overriding saved template parameters in individual Conversion API requests. allOf: - $ref: "#/components/schemas/TemplateContractOptions" example: fieldName: string description: string fields: [] recommendedWorkflow: type: array description: Recommended programmatic workflow for creating or editing templates. items: type: string previewQualityGate: $ref: "#/components/schemas/TemplateContractPreviewQualityGate" authoring: $ref: "#/components/schemas/TemplateContractAuthoring" limits: $ref: "#/components/schemas/TemplateContractLimits" technicalErrors: type: array description: Error meanings that clients can use to decide whether to retry or correct a request. items: $ref: "#/components/schemas/TemplateContractTechnicalError" hints: type: array description: Additional implementation guidance for Template API clients. items: type: string TemplateContractDashboardLinks: type: object description: Dashboard links and guidance for reviewing saved templates in PDFBolt Designer. additionalProperties: false required: - templateDesignerUrlPattern - usage properties: templateDesignerUrlPattern: type: string example: https://app.pdfbolt.com/templates/edit/{templateId} description: Dashboard Designer URL pattern. Replace `{templateId}` with the template UUID returned by the API. usage: type: string description: Guidance for presenting the Designer link after a draft is saved or published. TemplateContractAuthentication: type: object additionalProperties: false description: Public endpoints and authentication schemes used by the Template API and Conversion API. required: - publicEndpoints - templateApi - conversionApi properties: publicEndpoints: type: array description: Template endpoints that do not require authentication. example: - /v1/templates/contract items: type: string templateApi: description: Personal Access Token authentication for protected Template API endpoints. allOf: - $ref: "#/components/schemas/TemplateContractAuthenticationScheme" example: purpose: Create, validate, preview, diff, save and publish templates through the Template API. protectedEndpoints: - "/v1/templates/** except GET /contract" header: "PERSONAL-ACCESS-TOKEN: " tokenFormat: UUID conversionApi: description: API key authentication for Conversion API endpoints that generate PDFs. allOf: - $ref: "#/components/schemas/TemplateContractAuthenticationScheme" example: purpose: Generate production PDFs from HTML, URLs or published templates through the Conversion API. protectedEndpoints: - /v1/direct - /v1/sync - /v1/async header: "API-KEY: " tokenFormat: UUID TemplateContractAuthenticationScheme: type: object description: Authentication details for one PDFBolt API area. additionalProperties: false required: - purpose - protectedEndpoints - header - tokenFormat properties: purpose: type: string description: What the authenticated API is used for. protectedEndpoints: type: array description: Endpoints that require this authentication scheme. items: type: string header: type: string description: Authentication header and value format. tokenFormat: type: string description: Expected credential format. TemplateContractPayload: type: object additionalProperties: false description: Field reference shared by validation, preview, diff, and draft requests. Use endpoint schemas for exact required fields. required: - contentEncoding - fields properties: contentEncoding: type: string description: Encoding required for template content. fields: type: array description: Template payload fields and their general constraints. example: - name: name type: string required: false allowedValues: [] description: Human-readable template name. Required only when creating a new template with POST /v1/templates/drafts. - name: description type: string required: false allowedValues: [] description: Short internal description for the template. - name: templateEngine type: string required: false allowedValues: - HANDLEBARS description: Template engine used to evaluate content with sample data. Required for validate, preview and new draft creation; optional for diff or existing draft update when the current template engine should be reused. - name: content type: string required: false allowedValues: [] description: Base64-encoded complete HTML document with CSS. Required for validate, preview, diff and new draft creation. For an existing draft update, an omitted value is preserved and a provided value replaces the complete document. - name: sampleData type: object required: false allowedValues: [] description: JSON object used to evaluate the Handlebars template. Required for validate, preview, diff and new draft creation. For an existing draft update, an omitted value is preserved and a provided value replaces the complete object. - name: parameters type: object required: false allowedValues: [] description: Template default options. Required for validate, preview and diff. Optional when creating a new template; missing fields are filled with template creation defaults. For an existing draft update, this is a shallow patch; omitted fields are preserved. items: $ref: "#/components/schemas/TemplateContractField" TemplateContractField: type: object description: Details for one template field, including its type, required status, allowed values, and usage guidance. additionalProperties: false required: - name - type - required - allowedValues - description properties: name: type: string description: Field name used in the JSON payload. type: type: string description: JSON type expected for the field. required: type: boolean description: Indicates whether the described payload field is generally required. Use endpoint schemas for endpoint-specific requirements. allowedValues: type: array description: Accepted values when the field has a fixed set. An empty array means no fixed set is defined here. items: type: string description: type: string description: Additional usage guidance for the field. TemplateContractRuleSection: type: object additionalProperties: false description: Supported and avoided HTML/CSS patterns for Chromium PDF rendering. required: - supported - avoid properties: supported: type: array description: Supported and recommended HTML/CSS patterns. items: type: string avoid: type: array description: Patterns that can make PDF rendering unreliable or unsafe. items: type: string TemplateContractHandlebars: type: object additionalProperties: false description: Supported Handlebars syntax, helper guidance, and sampleData rules. required: - supportedSyntax - allowedHelpers - sampleDataRules properties: supportedSyntax: type: array description: Handlebars expressions and block syntax supported by PDFBolt. items: type: string allowedHelpers: type: array description: Handlebars helpers registered by PDFBolt. items: type: string sampleDataRules: type: array description: Rules for data used to evaluate a Handlebars template. items: type: string TemplateContractOptions: type: object additionalProperties: false description: Structure used by contract sections that describe supported PDF parameter fields. required: - fieldName - description - fields properties: fieldName: type: string description: Request field or location where these options are supplied. description: type: string description: Guidance for how these fields are applied. fields: type: array description: PDF parameter fields listed by this section. The array may be empty when another source defines the supported fields. items: $ref: "#/components/schemas/TemplateContractField" TemplateContractAuthoring: type: object additionalProperties: false description: Guidance for Handlebars data, PDF parameters, headers and footers, assets, print CSS, editing, and visual review. required: - handlebarsRules - sampleDataRules - parameterGuidance - headerFooterRules - waitForFunctionRecipes - printCssRules - chartAndAssetRules - specialFeatureRules - editRules - qualityChecklist - commonMistakes properties: handlebarsRules: type: array description: Rules for writing Handlebars expressions and template logic. items: type: string sampleDataRules: type: array description: Rules for preparing representative sample data. items: type: string parameterGuidance: type: array description: Guidance for selecting PDF parameters. items: type: string headerFooterRules: type: array description: Requirements for Chromium header and footer templates. items: type: string waitForFunctionRecipes: type: array description: Ready-to-use `waitUntil` and `waitForFunction` combinations for common rendering scenarios. items: $ref: "#/components/schemas/TemplateContractRecipe" printCssRules: type: array description: CSS guidance for print layout and pagination. items: type: string chartAndAssetRules: type: array description: Guidance for charts, images, fonts, and other external assets. items: type: string specialFeatureRules: type: array description: Guidance for QR codes, barcodes, Paged.js, and page counters. items: type: string editRules: type: array description: Rules for safely updating an existing template. items: type: string qualityChecklist: type: array description: Visual checks to complete before accepting a template. items: type: string commonMistakes: type: array description: Frequent template implementation errors to avoid. items: type: string TemplateContractRecipe: type: object description: One rendering scenario and its recommended readiness settings. additionalProperties: false required: - name - useWhen - waitUntil - waitForFunction properties: name: type: string description: Recipe identifier. useWhen: type: string description: Rendering scenario for which the recipe is intended. waitUntil: type: string description: Recommended navigation lifecycle event. waitForFunction: type: - string - "null" description: Recommended JavaScript readiness function, or null when no function is needed. example: "() => document.readyState === 'complete'" TemplateContractLimits: type: object additionalProperties: false description: Template API payload and metadata limits. required: - templateNameMaxChars - templateDescriptionMaxChars - contentMaxBytes - sampleDataMaxBytes - parametersMaxBytes properties: templateNameMaxChars: type: integer description: Maximum template name length in characters. minimum: 0 example: 100 templateDescriptionMaxChars: type: integer description: Maximum template description length in characters. minimum: 0 example: 500 contentMaxBytes: type: integer description: Maximum decoded template content size in bytes. minimum: 0 example: 2097152 sampleDataMaxBytes: type: integer description: Maximum serialized sample data size in UTF-8 bytes. minimum: 0 example: 2097152 parametersMaxBytes: type: integer description: Maximum serialized parameters size in UTF-8 bytes. minimum: 0 example: 2097152 TemplateContractPreviewQualityGate: type: object description: Visual review criteria for deciding whether a rendered preview or diff is acceptable. additionalProperties: false required: - purpose - appliesTo - agentRules - visualChecks - iterationRules - nonGoals properties: purpose: type: string description: Why visual review is required before accepting a template. appliesTo: type: array description: Workflows that should use this quality gate. items: type: string agentRules: type: array description: Review rules for automated and AI-assisted clients. items: type: string visualChecks: type: array description: Conditions to verify in the rendered PDF. items: type: string iterationRules: type: array description: Guidance for correcting layout and pagination problems. items: type: string nonGoals: type: array description: Quality guarantees that validation, preview, and diff do not provide. items: type: string TemplateContractTechnicalError: type: object additionalProperties: false required: - code - httpStatus - meaning properties: code: type: string description: Stable PDFBolt error code. httpStatus: type: integer description: HTTP status normally associated with the error code. minimum: 400 maximum: 599 meaning: type: string description: Client guidance for handling or correcting the error. TemplateEngine: type: string enum: - HANDLEBARS description: Template engine used to evaluate template content. TemplateApiTemplatePayload: type: object additionalProperties: false required: - templateEngine - content - sampleData - parameters properties: templateEngine: $ref: "#/components/schemas/TemplateEngine" content: type: string contentEncoding: base64 maxLength: 2796204 description: Base64-encoded complete UTF-8 HTML document. It may contain Handlebars placeholders. sampleData: type: object additionalProperties: true description: JSON object used to evaluate the template during validation and preview. parameters: description: PDF parameters supplied with the template payload. Send `{}` when no parameters are needed. $ref: "#/components/schemas/TemplateApiParameters" TemplateApiSaveDraftRequest: description: Use this request to create a new template and its first draft, or to partially update the active draft of an existing template. If the existing template has no draft, omitted values are copied from its published version into a new draft. oneOf: - $ref: "#/components/schemas/TemplateApiCreateDraftRequest" - $ref: "#/components/schemas/TemplateApiUpdateDraftRequest" TemplateApiCreateDraftRequest: type: object title: Create a new template description: Creates the template and its first draft. Do not include `templateId`. additionalProperties: false required: - name - templateEngine - content - sampleData examples: - name: Invoice description: Monthly invoice template templateEngine: HANDLEBARS content: PCFkb2N0eXBlIGh0bWw+PGh0bWw+PGJvZHk+PGgxPkludm9pY2Uge3tpbnZvaWNlTnVtYmVyfX08L2gxPjwvYm9keT48L2h0bWw+ sampleData: invoiceNumber: INV-1001 parameters: format: A4 waitUntil: networkidle printBackground: true properties: name: type: string minLength: 1 maxLength: 100 pattern: ".*\\S.*" description: Human-readable, non-blank template name. description: type: - string - "null" maxLength: 500 description: Optional template description. templateEngine: $ref: "#/components/schemas/TemplateEngine" content: type: string contentEncoding: base64 maxLength: 2796204 description: Base64-encoded complete UTF-8 HTML document. It may contain Handlebars placeholders. sampleData: type: object additionalProperties: true description: JSON object saved with the draft and used to evaluate the template. parameters: description: > PDF parameters saved with the draft. If omitted or only some fields are provided, PDFBolt fills in the remaining values using Dashboard Designer defaults. See [Template parameters](https://pdfbolt.com/docs/api-endpoints/template-api#template-parameters) for the current default values. $ref: "#/components/schemas/TemplateApiParameters" TemplateApiUpdateDraftRequest: type: object title: Save a draft for an existing template description: Partially updates the active draft or, if the template has only a published version, creates the next draft from that version. Include `templateId` and at least one field to change. Omitted fields are preserved. additionalProperties: false required: - templateId anyOf: - required: - name - required: - description - required: - templateEngine - required: - content - required: - sampleData - required: - parameters examples: - templateId: 93fee603-cb2a-40db-8deb-b2e3cb1eed0f parameters: format: A4 properties: templateId: type: string format: uuid description: UUID of the existing template. name: type: string minLength: 1 maxLength: 100 pattern: ".*\\S.*" description: New non-blank template name. Omit it to preserve the current name. description: type: string maxLength: 500 description: New template description. Omit it to preserve the current description; send an empty string to clear it. templateEngine: description: New template engine. Omit it to preserve the current engine. $ref: "#/components/schemas/TemplateEngine" content: type: string contentEncoding: base64 maxLength: 2796204 description: Base64-encoded complete UTF-8 HTML document. Omit it to preserve the current content; when supplied, it replaces the complete document. sampleData: type: object additionalProperties: true description: Complete JSON object saved with the draft. Omit it to preserve the current sample data; when supplied, it replaces the complete object. parameters: description: > Shallow patch of PDF parameters saved with the draft. Omitted fields are preserved and `{}` makes no parameter changes. Send `null` only for `headerTemplate`, `footerTemplate`, or `waitForFunction` to remove that saved option. $ref: "#/components/schemas/TemplateApiParametersPatch" TemplateApiDiffRequest: type: object additionalProperties: false required: - content - sampleData - parameters properties: templateEngine: anyOf: - $ref: "#/components/schemas/TemplateEngine" - type: "null" description: Optional. If omitted, the template's current engine is used. content: type: string contentEncoding: base64 maxLength: 2796204 description: Base64-encoded complete UTF-8 HTML document for the candidate. It may contain Handlebars placeholders. sampleData: type: object additionalProperties: true description: JSON object used to populate the candidate template. parameters: description: PDF parameters used to render the candidate template. Send `{}` when no parameters are needed. $ref: "#/components/schemas/TemplateApiParameters" TemplateApiParameters: type: object additionalProperties: false description: PDF parameters that can be saved with a template version. properties: format: type: - string - "null" enum: - Letter - Legal - Tabloid - Ledger - A0 - A1 - A2 - A3 - A4 - A5 - A6 - null description: Paper format used when rendering the template. landscape: type: - boolean - "null" description: Whether to render the template in landscape orientation. waitUntil: type: - string - "null" enum: - load - domcontentloaded - networkidle - commit - null description: Event used to decide when the template is ready for rendering. printBackground: type: - boolean - "null" description: Whether to include CSS backgrounds when rendering the template. displayHeaderFooter: type: - boolean - "null" description: Whether to display headers and footers when rendering the template. headerTemplate: type: - string - "null" contentEncoding: base64 description: Base64-encoded Chromium header template HTML. footerTemplate: type: - string - "null" contentEncoding: base64 description: Base64-encoded Chromium footer template HTML. waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated before rendering the template. TemplateApiParametersPatch: type: object additionalProperties: false description: Shallow patch of PDF parameters saved with a template version. Omitted fields are preserved. Null removes only headerTemplate, footerTemplate, or waitForFunction. properties: format: type: string enum: - Letter - Legal - Tabloid - Ledger - A0 - A1 - A2 - A3 - A4 - A5 - A6 description: Paper format used when rendering the template. landscape: type: boolean description: Whether to render the template in landscape orientation. waitUntil: type: string enum: - load - domcontentloaded - networkidle - commit description: Event used to decide when the template is ready for rendering. printBackground: type: boolean description: Whether to include CSS backgrounds when rendering the template. displayHeaderFooter: type: boolean description: Whether to display headers and footers when rendering the template. headerTemplate: type: - string - "null" contentEncoding: base64 description: Base64-encoded Chromium header template HTML. Send null to remove the saved option. footerTemplate: type: - string - "null" contentEncoding: base64 description: Base64-encoded Chromium footer template HTML. Send null to remove the saved option. waitForFunction: type: - string - "null" maxLength: 4096 description: JavaScript function evaluated before rendering the template. Send null to remove the saved option. TemplateApiListResponse: type: object description: Templates available to the authenticated team. additionalProperties: false required: - templates properties: templates: type: array description: Templates ordered by the latest version update, newest first. items: $ref: "#/components/schemas/TemplateApiListItem" TemplateApiListItem: type: object additionalProperties: false required: - id - name - description - templateEngine - hasDraft - publishedVersion - draftVersion properties: id: type: string format: uuid description: Unique template identifier. name: type: string maxLength: 100 description: Human-readable template name. description: type: string maxLength: 500 description: Template description. An empty string means no description was provided. templateEngine: $ref: "#/components/schemas/TemplateEngine" hasDraft: type: boolean description: Whether the template currently has an active draft. publishedVersion: description: Metadata for the latest published version, or null if the template has not been published. anyOf: - $ref: "#/components/schemas/TemplateApiPublishedVersionInfo" - type: "null" draftVersion: description: Metadata for the active draft version, or null if no active draft exists. anyOf: - $ref: "#/components/schemas/TemplateApiDraftVersionInfo" - type: "null" TemplateApiTemplate: type: object description: Template metadata, versioned content, and current version information. additionalProperties: false required: - id - name - description - templateEngine - hasDraft - content - sampleData - parameters - publishedVersion - draftVersion properties: id: type: string format: uuid description: Unique template identifier. name: type: string maxLength: 100 description: Human-readable template name. description: type: string maxLength: 500 description: Template description. An empty string means no description was provided. templateEngine: $ref: "#/components/schemas/TemplateEngine" hasDraft: type: boolean description: Whether the template currently has an active draft. content: type: string contentEncoding: base64 description: Base64-encoded UTF-8 template content. sampleData: type: object additionalProperties: true description: Sample data saved with the same version as `content`. parameters: description: PDF parameters saved with the same template version as `content` and `sampleData`. $ref: "#/components/schemas/TemplateApiParameters" publishedVersion: description: Metadata for the latest published version, or null if the template has not been published. anyOf: - $ref: "#/components/schemas/TemplateApiPublishedVersionInfo" - type: "null" draftVersion: description: Metadata for the active draft version, or null if no active draft exists. anyOf: - $ref: "#/components/schemas/TemplateApiDraftVersionInfo" - type: "null" TemplateApiPublishedVersionInfo: type: object description: Metadata for the latest published template version. additionalProperties: false required: - id - status - versionNumber - createdTime - modifiedTime properties: id: type: integer format: int64 minimum: 1 description: Unique template version identifier. status: type: string const: PUBLISHED description: Published version status. versionNumber: type: integer minimum: 1 description: Sequential version number within the template. createdTime: type: string format: date-time description: Date and time when the version was created. modifiedTime: type: string format: date-time description: Date and time when the version was last modified. TemplateApiDraftVersionInfo: type: object description: Metadata for the active draft template version. additionalProperties: false required: - id - status - versionNumber - createdTime - modifiedTime properties: id: type: integer format: int64 minimum: 1 description: Unique template version identifier. status: type: string const: DRAFT description: Draft version status. versionNumber: type: integer minimum: 1 description: Sequential version number within the template. createdTime: type: string format: date-time description: Date and time when the version was created. modifiedTime: type: string format: date-time description: Date and time when the version was last modified. TemplateApiPreviewPdfResponse: type: string format: binary description: Raw PDF binary returned when `responseFormat` is omitted or set to `pdf`. TemplateApiPreviewJsonResponse: type: object description: Rendered preview returned as a Base64-encoded PDF with its size. additionalProperties: false required: - documentSizeMb - pdfBase64 properties: documentSizeMb: type: number minimum: 0 description: Size of the rendered PDF in megabytes. pdfBase64: type: string contentEncoding: base64 description: Base64-encoded rendered PDF. TemplateApiConversionSide: type: object additionalProperties: false required: - documentSizeMb - pdfBase64 - error properties: documentSizeMb: type: - number - "null" minimum: 0 description: Size of the rendered PDF in megabytes, or `null` when rendering this side fails. pdfBase64: type: - string - "null" contentEncoding: base64 description: Base64-encoded rendered PDF, or `null` when rendering this side fails. error: type: - string - "null" description: Rendering error for this side, or `null` when rendering succeeds. TemplateApiDiffResponse: type: object additionalProperties: false required: - before - after properties: before: $ref: "#/components/schemas/TemplateApiConversionSide" description: Render result for the published template version. after: $ref: "#/components/schemas/TemplateApiConversionSide" description: Render result for the candidate template. TemplateApiSaveDraftResponse: type: object description: Result of saving a template draft. additionalProperties: false required: - templateId - draftVersionId - versionNumber - createdTemplate properties: templateId: type: string format: uuid description: UUID of the template whose draft was saved. draftVersionId: type: integer format: int64 minimum: 1 description: Unique identifier of the saved draft version. versionNumber: type: integer minimum: 1 description: Sequential version number within the template. createdTemplate: type: boolean description: Whether the request created a new template. It is `true` for the create variant and `false` for the update variant. TemplateApiPublishRequest: type: object description: Request body for publishing the active draft. Send `{}` when no comment is needed. additionalProperties: false examples: - comment: Ready for production properties: comment: type: - string - "null" maxLength: 500 description: Optional comment saved with the published version. TemplateApiPublishResponse: type: object description: Result of publishing a template draft. additionalProperties: false required: - templateId - publishedVersionId - versionNumber properties: templateId: type: string format: uuid description: UUID of the template whose draft was published. publishedVersionId: type: integer format: int64 minimum: 1 description: Unique identifier of the published version. versionNumber: type: integer minimum: 1 description: Sequential version number within the template. BadRequestApiError: type: object description: Standard JSON error response for 400 Bad Request. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 400 errorCode: type: string enum: - BAD_REQUEST description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. TemplateApiPreviewBadRequestApiError: type: object additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 400 errorCode: type: string enum: - BAD_REQUEST - PDF_PRINTING_FAILED - TARGET_CLOSED - NO_BROWSER_CONTEXT - UNEXPECTED_ERROR description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the validation or rendering error. DirectBadRequestApiError: type: object description: Standard JSON error response for 400 Bad Request on Direct conversion. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 400 errorCode: type: string enum: - BAD_REQUEST - TARGET_CLOSED - NO_BROWSER_CONTEXT - URL_NOT_RESOLVED - PDF_PRINTING_FAILED - TEMPLATE_EVAL_ERROR - INVALID_CREDENTIALS - HTTP_RESPONSE_FAILURE - UNEXPECTED_ERROR description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. SyncBadRequestApiError: type: object description: Standard JSON error response for 400 Bad Request on Sync conversion. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 400 errorCode: type: string enum: - BAD_REQUEST - TARGET_CLOSED - NO_BROWSER_CONTEXT - URL_NOT_RESOLVED - PDF_PRINTING_FAILED - TEMPLATE_EVAL_ERROR - CUSTOM_S3_UPLOAD_ERROR - INVALID_CREDENTIALS - HTTP_RESPONSE_FAILURE - UNEXPECTED_ERROR description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. AsyncBadRequestApiError: type: object description: Standard JSON error response for 400 Bad Request while accepting an Async conversion request. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 400 errorCode: type: string enum: - BAD_REQUEST description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. UnauthorizedApiError: type: object description: Standard JSON error response for 401 Unauthorized. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 401 errorCode: type: string enum: - UNAUTHORIZED description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. ForbiddenApiError: type: object description: Standard JSON error response for 403 Forbidden. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 403 errorCode: type: string enum: - FORBIDDEN description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. NotFoundApiError: type: object description: Standard JSON error response for 404 Not Found. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 404 errorCode: type: string enum: - NOT_FOUND description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. ConversionTimeoutApiError: type: object description: Standard JSON error response for 408 Conversion Timeout. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 408 errorCode: type: string enum: - CONVERSION_TIMEOUT description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. PayloadTooLargeApiError: type: object additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 413 errorCode: type: string enum: - PAYLOAD_TOO_LARGE - PDF_SIZE_TOO_LARGE description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. RequestPayloadTooLargeApiError: type: object description: Standard JSON error response for 413 request payload limits. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 413 errorCode: type: string enum: - PAYLOAD_TOO_LARGE description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. UnprocessableEntityApiError: type: object description: Standard JSON error response for 422 Unprocessable Entity. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 422 errorCode: type: string enum: - UNPROCESSABLE_ENTITY description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. TooManyRequestsApiError: type: object description: Standard JSON error response for 429 Too Many Requests. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 429 errorCode: type: string enum: - TOO_MANY_REQUESTS description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. ClientDisconnectedApiError: type: object description: Standard JSON error response for 499 Client Disconnected. additionalProperties: false required: - timestamp - httpErrorCode - errorCode - errorMessage properties: timestamp: type: string format: date-time description: Date and time when the error occurred. httpErrorCode: type: integer description: HTTP status code of the error. const: 499 errorCode: type: string enum: - CLIENT_DISCONNECTED description: PDFBolt API error code for programmatic handling. errorMessage: type: string description: Descriptive message explaining the error. ConversionStatus: type: string enum: - SUCCESS - FAILURE description: Final async conversion status. AsyncWebhookErrorCode: type: string enum: - BAD_REQUEST - FORBIDDEN - PDF_SIZE_TOO_LARGE - TEMPLATE_EVAL_ERROR - CUSTOM_S3_UPLOAD_ERROR - TARGET_CLOSED - NO_BROWSER_CONTEXT - URL_NOT_RESOLVED - PDF_PRINTING_FAILED - CONVERSION_TIMEOUT - UNEXPECTED_ERROR - INVALID_CREDENTIALS - HTTP_RESPONSE_FAILURE - UNPROCESSABLE_ENTITY description: Final async conversion error code. AsyncWebhookErrorCodeNullable: anyOf: - $ref: "#/components/schemas/AsyncWebhookErrorCode" - type: "null" description: Final async conversion error code, or `null` on success. examples: SyncSuccess: summary: Successful sync conversion value: requestId: db347fe5-7b72-45f6-92f9-a7b7755ab6c8 status: SUCCESS errorCode: null errorMessage: null documentUrl: https://s3.pdfbolt.com/pdfbolt_ec2950a1-f835-4be6-bab2-69490b53b1f9_2026-04-30T10-44-09Z.pdf expiresAt: 2026-05-01T10:44:09Z isAsync: false duration: 606 documentSizeMb: 0.02 isCustomS3Bucket: false SyncCustomS3Success: summary: Successful sync conversion with custom S3 upload value: requestId: 8e580d62-fc31-45d9-bb51-3f1ad3d5a09c status: SUCCESS errorCode: null errorMessage: null documentUrl: null expiresAt: null isAsync: false duration: 642 documentSizeMb: 0.02 isCustomS3Bucket: true AsyncAccepted: summary: Async job accepted value: requestId: 4da0a428-16e0-4c95-b1d3-a8f475ed717e AsyncWebhookSuccess: summary: Successful async conversion webhook value: requestId: 4da0a428-16e0-4c95-b1d3-a8f475ed717e status: SUCCESS errorCode: null errorMessage: null documentUrl: https://s3.pdfbolt.com/pdfbolt_89878444-79a5-4115-beeb-f36745d61cf7_2026-04-30T10-47-03Z.pdf expiresAt: 2026-05-01T10:47:03Z isAsync: true duration: 574 documentSizeMb: 0.02 isCustomS3Bucket: false AsyncWebhookFailure: summary: Failed async conversion webhook value: requestId: a3bf2ab7-5ef3-4d8b-a715-765697611dce status: FAILURE errorCode: CONVERSION_TIMEOUT errorMessage: Conversion process timed out. Please see https://pdfbolt.com/docs/parameters#timeout, https://pdfbolt.com/docs/parameters#waituntil and https://pdfbolt.com/docs/parameters#waitforfunction parameters. documentUrl: null expiresAt: null isAsync: true duration: 30541 documentSizeMb: null isCustomS3Bucket: false UsageSuccess: summary: Current plan and remaining conversions value: plan: BASIC_MONTHLY recurring: - total: 2000 left: 1322 expires: "2026-05-22T23:59:59Z" overage: 0 oneTime: [] TemplateApiSaveDraftMissingNameError: summary: Missing template name value: timestamp: 2026-07-28T20:22:14Z httpErrorCode: 400 errorCode: BAD_REQUEST errorMessage: "Template validation failed: Field 'name' is required. A new template draft requires a template name." TemplateApiMissingParametersError: summary: Missing required parameters value: timestamp: 2026-07-28T16:08:58Z httpErrorCode: 400 errorCode: BAD_REQUEST errorMessage: "Template validation failed: Field 'parameters' is required. Send parameters as a JSON object. Use {} for defaults." TemplateApiInvalidIdError: summary: Invalid template UUID value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 400 errorCode: BAD_REQUEST errorMessage: Request path or query parameter has an invalid value. Check UUID path parameters and scalar query parameter formats. TemplateApiNoActiveDraftError: summary: Template has no active draft value: timestamp: 2026-07-28T20:30:00Z httpErrorCode: 400 errorCode: BAD_REQUEST errorMessage: "Template '93fee603-cb2a-40db-8deb-b2e3cb1eed0f' does not have an active draft. Save a draft first, then call publish without an ad hoc payload." TemplateApiUnauthorizedError: summary: Personal Access Token authentication failed value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 401 errorCode: UNAUTHORIZED errorMessage: The personal access token is missing, invalid, inactive or blocked. TemplateApiTemplateLimitError: summary: Template plan limit reached value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 403 errorCode: FORBIDDEN errorMessage: Template limit reached for the current plan. Remove an existing template or upgrade the plan before creating another template. TemplateApiConversionCreditsError: summary: Conversion credits unavailable for preview value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 403 errorCode: FORBIDDEN errorMessage: "PDF conversion failed. FORBIDDEN: You have used all your available document conversions. Consider upgrading your plan, or enable overage in your settings for uninterrupted access." TemplateApiConversionDisabledError: summary: PDF conversions disabled for the team value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 403 errorCode: FORBIDDEN errorMessage: "PDF conversion failed. FORBIDDEN: PDF conversions have been disabled for security reasons. To restore access, please contact support." TemplateApiNotFoundError: summary: Template not found or not visible to the team value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 404 errorCode: NOT_FOUND errorMessage: Template '2b1124e7-7f8d-4fd9-9d0a-4f8cf0c58f98' was not found. Check the template id and make sure it belongs to the authenticated team. TemplateApiPayloadTooLargeError: summary: Template payload exceeds its static limit value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 413 errorCode: PAYLOAD_TOO_LARGE errorMessage: "Template validation failed: Template content exceeds the 2 MB limit. Reduce inline assets, CSS and HTML size before validating." TemplateApiValidatePayloadTooLargeError: summary: Template content exceeds the limit value: timestamp: 2026-07-28T16:14:43Z httpErrorCode: 413 errorCode: PAYLOAD_TOO_LARGE errorMessage: "Template validation failed: Template content exceeds the 2 MB limit. Reduce inline assets, CSS and HTML size before validating." TemplateApiPdfSizeTooLargeError: summary: Generated preview PDF exceeds the plan limit value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 413 errorCode: PDF_SIZE_TOO_LARGE errorMessage: "PDF conversion failed. PDF_SIZE_TOO_LARGE: The generated PDF exceeds the maximum allowed size for your plan." TemplateApiConversionTimeoutError: summary: Preview conversion timed out value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 408 errorCode: CONVERSION_TIMEOUT errorMessage: "PDF conversion failed. CONVERSION_TIMEOUT: Conversion process timed out. Please see https://pdfbolt.com/docs/parameters#timeout, https://pdfbolt.com/docs/parameters#waituntil and https://pdfbolt.com/docs/parameters#waitforfunction parameters." TemplateApiUnprocessableEntityError: summary: Preview conversion could not be processed value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 422 errorCode: UNPROCESSABLE_ENTITY errorMessage: "PDF conversion failed. UNPROCESSABLE_ENTITY: Your request could not be processed correctly. Please try again or contact us at contact@pdfbolt.com." TemplateApiTooManyRequestsError: summary: Fixed Template API management limit exceeded value: timestamp: 2026-07-13T12:00:00Z httpErrorCode: 429 errorCode: TOO_MANY_REQUESTS errorMessage: Request limit exceeded. Please retry after 60 seconds. BadRequestError: summary: BAD_REQUEST example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: BAD_REQUEST errorMessage: Exactly one of 'html', 'url', or 'templateId' must be provided (the others must be null). UnauthorizedError: summary: UNAUTHORIZED example value: timestamp: 2026-04-30T17:27:52Z httpErrorCode: 401 errorCode: UNAUTHORIZED errorMessage: The API key is missing, invalid or has been blocked. Please verify your key or contact support. ForbiddenError: summary: FORBIDDEN example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 403 errorCode: FORBIDDEN errorMessage: You have used all your available document conversions. Consider upgrading your plan, or enable overage in your settings for uninterrupted access. NotFoundError: summary: NOT_FOUND example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 404 errorCode: NOT_FOUND errorMessage: Endpoint not found. Refer to https://pdfbolt.com/docs for available endpoints. PayloadTooLargeError: summary: PAYLOAD_TOO_LARGE example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 413 errorCode: PAYLOAD_TOO_LARGE errorMessage: Request size exceeds the maximum allowed limit for your plan. PdfSizeTooLargeError: summary: PDF_SIZE_TOO_LARGE example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 413 errorCode: PDF_SIZE_TOO_LARGE errorMessage: The generated PDF exceeds the maximum allowed size for your plan. Use the compression parameter to reduce file size. TemplateEvalError: summary: TEMPLATE_EVAL_ERROR example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: TEMPLATE_EVAL_ERROR errorMessage: Template evaluation failed. Check your Handlebars syntax and templateData fields. TooManyRequestsError: summary: TOO_MANY_REQUESTS example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 429 errorCode: TOO_MANY_REQUESTS errorMessage: Request limit exceeded. Please wait and try again later. To increase your limit, upgrade your plan. ClientDisconnectedError: summary: CLIENT_DISCONNECTED example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 499 errorCode: CLIENT_DISCONNECTED errorMessage: Client disconnected before the response could be fully delivered. UnprocessableEntityError: summary: UNPROCESSABLE_ENTITY example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 422 errorCode: UNPROCESSABLE_ENTITY errorMessage: Your request could not be processed correctly. Please try again or contact us at contact@pdfbolt.com. CustomS3UploadError: summary: CUSTOM_S3_UPLOAD_ERROR example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: CUSTOM_S3_UPLOAD_ERROR errorMessage: "Failed to upload the object. Response code: 403, body: AccessDenied" TargetClosedError: summary: TARGET_CLOSED example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: TARGET_CLOSED errorMessage: The target page became unavailable or was closed. Please verify the URL and try again. NoBrowserContextError: summary: NO_BROWSER_CONTEXT example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: NO_BROWSER_CONTEXT errorMessage: Failed to establish a connection with the browser. Please check your provided source (html or url). UrlNotResolvedError: summary: URL_NOT_RESOLVED example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: URL_NOT_RESOLVED errorMessage: Could not resolve the server name. Please verify the URL. PdfPrintingFailedError: summary: PDF_PRINTING_FAILED example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: PDF_PRINTING_FAILED errorMessage: Failed to print PDF. The file may be too large or complex. Please reduce the size or complexity of the PDF. ConversionTimeoutError: summary: CONVERSION_TIMEOUT example value: timestamp: 2026-04-30T10:28:43Z httpErrorCode: 408 errorCode: CONVERSION_TIMEOUT errorMessage: Conversion process timed out. Please see https://pdfbolt.com/docs/parameters#timeout, https://pdfbolt.com/docs/parameters#waituntil and https://pdfbolt.com/docs/parameters#waitforfunction parameters. UnexpectedError: summary: UNEXPECTED_ERROR example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: UNEXPECTED_ERROR errorMessage: An unexpected error occurred during conversion. Please try again or contact us at contact@pdfbolt.com. InvalidCredentialsError: summary: INVALID_CREDENTIALS example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: INVALID_CREDENTIALS errorMessage: Authentication credentials provided are invalid or missing. Please check username and password. HttpResponseFailureError: summary: HTTP_RESPONSE_FAILURE example value: timestamp: 2026-05-04T14:29:09Z httpErrorCode: 400 errorCode: HTTP_RESPONSE_FAILURE errorMessage: Received an unexpected HTTP status code from the server. Please verify that the requested URL or resource is correct and accessible.