swagger: "2.0" info: title: LightningPDF API description: | Generate PDFs from HTML, CSS, and Markdown via REST API. Dual engine: Go-native for simple docs (<100ms), Chromium for complex layouts. Free tier with 50 PDFs/month. version: "1.0.0" contact: name: LightningPDF Support email: hello@lightningpdf.dev url: https://lightningpdf.dev termsOfService: https://lightningpdf.dev/terms host: lightningpdf.dev basePath: /api/v1 schemes: - https consumes: - application/json produces: - application/json securityDefinitions: BearerAuth: type: apiKey name: Authorization in: header description: "Bearer token. Example: Bearer YOUR_API_KEY" tags: - name: PDF Generation description: Generate PDFs from HTML, CSS, Markdown, or templates - name: Post-Processing description: Merge, split, compress, protect, and analyze PDFs - name: Async Jobs description: Queue PDF generation for async processing - name: Batch description: Generate multiple PDFs in a single request - name: Templates description: Create and manage reusable PDF templates - name: Starter Templates description: Browse and import pre-built template library - name: Records description: Stored PDF retrieval and pricing - name: API Keys description: Manage API keys for programmatic access - name: Usage description: Credit usage and billing stats - name: Health description: API health check definitions: APIError: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Invalid request parameters details: type: object additionalProperties: type: string ErrorResponse: type: object properties: success: type: boolean example: false error: $ref: '#/definitions/APIError' ResponseMeta: type: object properties: request_id: type: string example: req_abc123 timestamp: type: string example: "2026-03-15T10:30:00Z" PDFOptions: type: object properties: format: type: string description: "Page format: A4, Letter, Legal, A3, A5, Tabloid" example: A4 landscape: type: boolean description: Landscape orientation example: false width: type: string description: Custom page width (e.g. 210mm, 8.5in) example: "210mm" height: type: string description: Custom page height (e.g. 297mm, 11in) example: "297mm" margin_top: type: string description: Top margin with unit example: "20mm" margin_bottom: type: string description: Bottom margin with unit example: "20mm" margin_left: type: string description: Left margin with unit example: "15mm" margin_right: type: string description: Right margin with unit example: "15mm" scale: type: number description: Scale factor (0.1 to 2.0) example: 1.0 print_background: type: boolean description: Print background graphics example: true prefer_css_page_size: type: boolean description: Use CSS @page size instead of format example: false display_header_footer: type: boolean description: Enable header and footer templates example: false header_template: type: string description: HTML template for page header example: "

Page

" footer_template: type: string description: HTML template for page footer example: "

" StorageOptions: type: object properties: enabled: type: boolean description: Enable Records as a Service storage example: true tier: type: string description: "Storage tier: free, paid, premium" example: paid file_name: type: string description: Custom filename for the stored PDF example: invoice-2026.pdf retention_hours: type: integer description: Custom retention in hours (max depends on plan) example: 168 GeneratePDFRequest: type: object description: Request body for generating a PDF properties: html: type: string description: HTML content (required if template_id and markdown not provided) example: "

Hello World

My first PDF

" markdown: type: string description: Markdown content (converted to HTML if html not provided) example: "# Hello World\nMy first PDF" css: type: string description: Additional CSS styles example: "h1 { color: blue; }" template_id: type: string description: Template ID to use instead of raw HTML example: 550e8400-e29b-41d4-a716-446655440000 variables: type: object additionalProperties: true description: Variables to inject into the template options: $ref: '#/definitions/PDFOptions' storage: $ref: '#/definitions/StorageOptions' GeneratePDFResponse: type: object properties: success: type: boolean example: true data: $ref: '#/definitions/PDFGenerationData' error: $ref: '#/definitions/APIError' meta: $ref: '#/definitions/ResponseMeta' PDFGenerationData: type: object properties: pdf: type: string description: Base64-encoded PDF data (if not stored) size: type: integer description: PDF size in bytes example: 12345 generation_time_ms: type: integer description: Generation time in milliseconds example: 85 engine_used: type: string description: "Engine used: native or chromium" example: chromium record: $ref: '#/definitions/RecordInfo' RecordInfo: type: object properties: id: type: string example: 550e8400-e29b-41d4-a716-446655440000 file_name: type: string example: invoice-2026.pdf download_url: type: string example: https://lightningpdf.dev/api/v1/records/550e8400.../download expires_at: type: string example: "2026-03-22T10:30:00Z" tier: type: string example: paid BatchPDFItem: type: object properties: html: type: string markdown: type: string css: type: string template_id: type: string variables: type: object additionalProperties: true options: $ref: '#/definitions/PDFOptions' storage: $ref: '#/definitions/StorageOptions' webhook_url: type: string description: URL to receive webhook when this item completes example: https://example.com/webhook BatchPDFRequest: type: object properties: items: type: array description: Array of PDF generation requests (1-100 items) items: $ref: '#/definitions/BatchPDFItem' BatchJobResponse: type: object properties: batch_id: type: string example: batch_abc123 total: type: integer example: 5 jobs: type: array items: $ref: '#/definitions/BatchJobItemRef' BatchJobItemRef: type: object properties: index: type: integer example: 0 job_id: type: string example: job_xyz789 CreateJobRequest: type: object properties: html: type: string example: "

Hello

" markdown: type: string css: type: string template_id: type: string variables: type: object additionalProperties: true options: $ref: '#/definitions/PDFOptions' storage: $ref: '#/definitions/StorageOptions' webhook_url: type: string example: https://example.com/webhook PDFInfo: type: object properties: page_count: type: integer example: 3 page_width: type: number description: Page width in points example: 595.28 page_height: type: number description: Page height in points example: 841.89 file_size: type: integer description: File size in bytes example: 245678 version: type: string example: "1.7" encrypted: type: boolean example: false TemplateRequest: type: object properties: name: type: string example: Invoice Template description: type: string example: Professional invoice template html: type: string example: "

Template content

" css: type: string example: "body { font-family: sans-serif; }" json_schema: type: string example: '{"type":"object"}' is_public: type: boolean example: false CreateAPIKeyRequest: type: object properties: name: type: string example: Production Key expires_in: type: integer description: Expiration in days example: 365 StarterTemplate: type: object properties: slug: type: string example: invoice-standard name: type: string example: Standard Invoice description: type: string example: Clean, professional invoice template category: type: string example: invoice is_premium: type: boolean example: false StarterCategory: type: object properties: slug: type: string example: invoice name: type: string example: Invoices TierInfo: type: object properties: name: type: string description: type: string retention: type: string price_per_pdf: type: number paths: /health: get: summary: API Health Check description: Check if the API is healthy tags: [Health] produces: [application/json] responses: "200": description: OK schema: type: object properties: status: type: string example: ok # ── PDF Generation ── /pdf/generate: post: summary: Generate PDF (base64 response) description: | Generate a PDF from HTML, CSS, Markdown, or a saved template. Returns base64-encoded PDF data in JSON response. Optionally store the PDF via Records as a Service. tags: [PDF Generation] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: body name: request required: true schema: $ref: '#/definitions/GeneratePDFRequest' responses: "200": description: PDF generated successfully schema: $ref: '#/definitions/GeneratePDFResponse' "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' "402": description: Insufficient credits schema: $ref: '#/definitions/ErrorResponse' "413": description: HTML content exceeds size limit for plan schema: $ref: '#/definitions/ErrorResponse' "500": description: Internal Server Error schema: $ref: '#/definitions/ErrorResponse' /pdf/download: post: summary: Generate PDF (direct download) description: | Generate a PDF and return it as a binary file download. Same inputs as /pdf/generate but returns raw PDF bytes. tags: [PDF Generation] security: - BearerAuth: [] consumes: [application/json] produces: [application/pdf] parameters: - in: body name: request required: true schema: $ref: '#/definitions/GeneratePDFRequest' responses: "200": description: PDF file schema: type: file "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' "413": description: HTML content exceeds size limit for plan schema: $ref: '#/definitions/ErrorResponse' # ── Async Jobs ── /pdf/jobs: post: summary: Create async PDF job description: | Queue a PDF generation job for async processing. Returns immediately with a job ID. Poll the job status endpoint or use a webhook URL to be notified when complete. tags: [Async Jobs] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: body name: request required: true schema: $ref: '#/definitions/CreateJobRequest' responses: "202": description: Job accepted schema: type: object properties: success: type: boolean example: true data: type: object properties: job_id: type: string example: job_abc123 status: type: string example: queued "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' /pdf/jobs/{id}: get: summary: Get PDF job status description: Get the status and result of an async PDF job tags: [Async Jobs] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: id required: true type: string description: Job ID responses: "200": description: Job status schema: type: object properties: success: type: boolean data: type: object properties: job_id: type: string status: type: string enum: [queued, processing, completed, failed] pdf: type: string description: Base64-encoded PDF (when completed) error: type: string description: Error message (when failed) "404": description: Job not found schema: $ref: '#/definitions/ErrorResponse' /pdf/jobs/{id}/download: get: summary: Download completed job PDF description: Download the PDF result of a completed async job as a binary file tags: [Async Jobs] security: - BearerAuth: [] produces: [application/pdf] parameters: - in: path name: id required: true type: string description: Job ID responses: "200": description: PDF file schema: type: file "404": description: Job not found or PDF not available schema: $ref: '#/definitions/ErrorResponse' # ── Batch ── /pdf/batch: post: summary: Batch generate PDFs description: | Generate multiple PDFs in a single request (1-100 items). Each item is queued as an async job. Credits consumed upfront. Requires Business plan or higher. tags: [Batch] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: body name: request required: true schema: $ref: '#/definitions/BatchPDFRequest' responses: "202": description: Batch accepted schema: type: object properties: success: type: boolean example: true data: $ref: '#/definitions/BatchJobResponse' "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' "402": description: Insufficient credits schema: $ref: '#/definitions/ErrorResponse' # ── Post-Processing ── /pdf/merge: post: summary: Merge PDFs description: | Merge 2-50 PDF files into a single PDF. Upload PDFs as multipart form data. tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/pdf] parameters: - in: formData name: files type: file required: true description: PDF files to merge (2-50 files, 100MB total limit) responses: "200": description: Merged PDF file schema: type: file "400": description: Bad Request (less than 2 files, invalid PDF, etc.) schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' /pdf/split: post: summary: Split PDF into pages description: Split a PDF into individual pages, returned as base64-encoded PDFs tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/json] parameters: - in: formData name: file type: file required: true description: PDF file to split (100MB limit) responses: "200": description: Split pages schema: type: object properties: success: type: boolean example: true data: type: object properties: page_count: type: integer example: 5 pages: type: array items: type: string description: Base64-encoded PDF pages "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' /pdf/compress: post: summary: Compress PDF description: | Reduce PDF file size with optimized compression. Response includes X-Original-Size and X-Compressed-Size headers. tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/pdf] parameters: - in: formData name: file type: file required: true description: PDF file to compress (100MB limit) - in: formData name: quality type: string required: false description: "Compression quality: screen, ebook (default), printer, prepress" enum: [screen, ebook, printer, prepress] responses: "200": description: Compressed PDF file headers: X-Original-Size: type: integer description: Original file size in bytes X-Compressed-Size: type: integer description: Compressed file size in bytes schema: type: file "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' /pdf/protect: post: summary: Password-protect PDF description: Add AES-256 password protection to a PDF tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/pdf] parameters: - in: formData name: file type: file required: true description: PDF file to protect (100MB limit) - in: formData name: owner_password type: string required: true description: Owner password (full permissions) - in: formData name: user_password type: string required: true description: User password (restricted permissions) responses: "200": description: Protected PDF file schema: type: file "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' /pdf/pdfa: post: summary: Convert to PDF/A description: | Convert a PDF to PDF/A format for archival compliance. Requires Pro plan or higher. tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/pdf] parameters: - in: formData name: file type: file required: true description: PDF file to convert (100MB limit) responses: "200": description: PDF/A compliant file schema: type: file "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "402": description: Requires Pro plan or higher schema: $ref: '#/definitions/ErrorResponse' /pdf/info: post: summary: Get PDF metadata description: Extract metadata from a PDF (page count, dimensions, version, encryption status) tags: [Post-Processing] security: - BearerAuth: [] consumes: [multipart/form-data] produces: [application/json] parameters: - in: formData name: file type: file required: true description: PDF file to analyze (100MB limit) responses: "200": description: PDF information schema: type: object properties: success: type: boolean example: true data: $ref: '#/definitions/PDFInfo' "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' # ── Templates ── /templates: get: summary: List templates description: Get all templates for the authenticated user tags: [Templates] security: - BearerAuth: [] produces: [application/json] parameters: - in: query name: page type: integer default: 1 description: Page number - in: query name: limit type: integer default: 20 description: Items per page (max 100) responses: "200": description: Template list schema: type: object properties: success: type: boolean data: type: object "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' post: summary: Create template description: Create a new reusable PDF template tags: [Templates] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: body name: request required: true schema: $ref: '#/definitions/TemplateRequest' responses: "201": description: Template created schema: type: object properties: success: type: boolean data: type: object "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' /templates/{id}: get: summary: Get template description: Get a template by ID tags: [Templates] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: id required: true type: string description: Template ID responses: "200": description: Template details schema: type: object properties: success: type: boolean data: type: object "404": description: Template not found schema: $ref: '#/definitions/ErrorResponse' put: summary: Update template description: Update an existing template tags: [Templates] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: path name: id required: true type: string description: Template ID - in: body name: request required: true schema: $ref: '#/definitions/TemplateRequest' responses: "200": description: Template updated schema: type: object properties: success: type: boolean data: type: object "404": description: Template not found schema: $ref: '#/definitions/ErrorResponse' delete: summary: Delete template description: Delete a template by ID tags: [Templates] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: id required: true type: string description: Template ID responses: "200": description: Template deleted schema: type: object properties: success: type: boolean "404": description: Template not found schema: $ref: '#/definitions/ErrorResponse' # ── Starter Templates ── /starter-templates: get: summary: List starter templates description: Browse the pre-built template library grouped by category. No authentication required. tags: [Starter Templates] produces: [application/json] responses: "200": description: Template library schema: type: object properties: success: type: boolean example: true data: type: object properties: categories: type: array items: type: object properties: category: type: string example: invoice templates: type: array items: $ref: '#/definitions/StarterTemplate' total: type: integer example: 15 /starter-templates/categories: get: summary: List template categories description: Get available starter template categories. No authentication required. tags: [Starter Templates] produces: [application/json] responses: "200": description: Category list schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: '#/definitions/StarterCategory' /starter-templates/{slug}: get: summary: Get starter template description: Get a specific starter template by slug. No authentication required. tags: [Starter Templates] produces: [application/json] parameters: - in: path name: slug required: true type: string description: Template slug (e.g. invoice-standard) responses: "200": description: Template details schema: type: object properties: success: type: boolean data: $ref: '#/definitions/StarterTemplate' "404": description: Template not found schema: $ref: '#/definitions/ErrorResponse' /starter-templates/{slug}/import: post: summary: Import starter template description: Import a starter template into your account as a reusable template tags: [Starter Templates] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: slug required: true type: string description: Template slug to import responses: "201": description: Template imported schema: type: object properties: success: type: boolean data: type: object "404": description: Template not found schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' # ── Records ── /records/{id}: get: summary: Get stored PDF record description: Retrieve information about a stored PDF and get download URL tags: [Records] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: id required: true type: string description: Record ID responses: "200": description: Record details schema: type: object properties: success: type: boolean data: $ref: '#/definitions/RecordInfo' "404": description: Record not found schema: $ref: '#/definitions/ErrorResponse' /records/pricing: get: summary: Get Records pricing tiers description: Get pricing information for PDF storage tiers tags: [Records] produces: [application/json] responses: "200": description: Pricing tiers schema: type: object additionalProperties: $ref: '#/definitions/TierInfo' # ── API Keys ── /keys: get: summary: List API keys description: Get all API keys for the authenticated user tags: [API Keys] security: - BearerAuth: [] produces: [application/json] responses: "200": description: API key list schema: type: object properties: success: type: boolean data: type: object "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' post: summary: Create API key description: Create a new API key for programmatic access tags: [API Keys] security: - BearerAuth: [] consumes: [application/json] produces: [application/json] parameters: - in: body name: request required: true schema: $ref: '#/definitions/CreateAPIKeyRequest' responses: "201": description: API key created (key value only shown once) schema: type: object properties: success: type: boolean data: type: object "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse' /keys/{id}: delete: summary: Delete API key description: Revoke and delete an API key tags: [API Keys] security: - BearerAuth: [] produces: [application/json] parameters: - in: path name: id required: true type: string description: API Key ID responses: "200": description: API key deleted schema: type: object properties: success: type: boolean "404": description: API key not found schema: $ref: '#/definitions/ErrorResponse' # ── Usage ── /usage: get: summary: Get usage statistics description: Get credit usage stats for the current billing period tags: [Usage] security: - BearerAuth: [] produces: [application/json] responses: "200": description: Usage stats schema: type: object properties: success: type: boolean data: type: object properties: plan: type: string example: starter credits_used: type: integer example: 150 credits_limit: type: integer example: 2000 credits_remaining: type: integer example: 1850 "401": description: Unauthorized schema: $ref: '#/definitions/ErrorResponse'