> ## Documentation Index > Fetch the complete documentation index at: https://docs.sudopdf.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate PDF > Generate a single PDF ## OpenAPI ````yaml POST /pdf/generate openapi: 3.1.0 info: title: SudoPdf - Do Pdf like you do UI description: >- Generate beautiful PDFs from HTML, URLs, or templates with powerful rendering options and webhook support license: name: MIT version: 1.0.0 servers: - url: http://app.sudopdf.com/api/v1 security: - ApiKeyAuth: [] paths: /pdf/generate: post: description: Generate a single PDF parameters: - name: sync in: query description: >- Whether to generate the PDF synchronously. Not recomended for production use schema: type: boolean default: false required: false requestBody: description: PDF to generate content: application/json: schema: $ref: '#/components/schemas/PdfGenerateRequestBody' required: true responses: '200': description: PDF generation response content: application/json: schema: $ref: '#/components/schemas/PdfSuccessResponse' examples: sync_response: summary: Synchronous response (sync=true) value: success: true mode: sync message: PDF generated successfully environment: production data: url: https://app.sudopdf.com/files/abc123.pdf creditsUsed: 1 async_response: summary: Asynchronous response (sync=false) value: success: true mode: async message: PDF generation job accepted environment: production data: status: accepted '400': description: Bad Request - Invalid input or fetch failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: fetch_failed_bad_response: summary: URL Fetch Failed – Bad Response value: success: false errorCode: '400' subCode: FETCH_FAILED_BAD_RESPONSE message: Failed to fetch content from provided URL fetch_failed_network_error: summary: URL Fetch Failed – Network Error value: success: false errorCode: '400' subCode: FETCH_FAILED_NETWORK_ERROR message: Failed to fetch content from provided URL details: 'NetworkError: Failed to fetch' '401': description: Unauthorized - Authentication errors content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_api_key: summary: Missing API Key value: success: false errorCode: '401' subCode: MISSING_API_KEY message: Missing X-API-KEY header invalid_api_key: summary: Invalid API Key value: success: false errorCode: '401' subCode: INVALID_API_KEY message: Invalid API key expired_api_key: summary: Expired API Key value: success: false errorCode: '401' subCode: EXPIRED_API_KEY message: API KEY EXPIRED '402': description: Payment Required - Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_credits: summary: Insufficient Credits value: success: false errorCode: '402' subCode: INSUFFICIENT_CREDITS message: >- You have 0 credits remaining. Please purchase more credits. meta: requiredCredits: 1 availableCredits: 0 activeSubscriptions: [] expiringCredits: [] '404': description: Not Found - Template not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: template_not_found: summary: Template Not Found value: success: false errorCode: '404' subCode: TEMPLATE_NOT_FOUND message: Template not found '422': description: Unprocessable Entity - Validation errors content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_request_body: summary: Invalid Request Body value: success: false errorCode: '422' subCode: INVALID_REQUEST_BODY message: Invalid input provided meta: issues: - path: - templateId message: Either templateId, url, or html must be provided code: custom '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: pdf_generation_failed: summary: PDF Generation Failed value: success: false errorCode: '500' subCode: PDF_GENERATION_FAILED message: PDF generation failed details: Template compilation error - Invalid React component credit_consumption_failed: summary: Credit Consumption Failed value: success: false errorCode: '500' subCode: CREDIT_CONSUMPTION_FAILED message: >- PDF was generated but credit consumption failed. Please contact support. internal_error: summary: Internal Server Error value: success: false errorCode: '500' subCode: INTERNAL_ERROR message: Internal server error during PDF generation x-codeSamples: - lang: JavaScript source: |- import Sudopdf from '@sudopdf/sdk'; const client = new Sudopdf({ apiKey: 'My API Key', // process.env['SUDOPDF_API_KEY'] is the default and can be omitted. }); const response = await client.pdf.generate({ templateId: 22 data: { foo: 'bar' } }); console.log(response.data); components: schemas: PdfGenerateRequestBody: type: object required: - data properties: templateId: type: string description: Unique Id of your template you like to render data: type: object description: >- Any data that use inside the template. Prefer metadata if you are not planning to use that data inside template additionalProperties: true url: type: string description: You can pass a url directly and get the webpage rendered. format: uri html: type: string metadata: type: object description: Data associated with this render but not used inside template. additionalProperties: true renderOptions: $ref: '#/components/schemas/RenderOptions' PdfSuccessResponse: type: object description: Unified PDF generation success response required: - success - mode - message - data properties: success: type: boolean description: Indicates if the request was successful example: true mode: type: string enum: - sync - async description: >- Response mode - sync for immediate PDF generation, async for background processing message: type: string description: Human-readable summary of the response example: PDF generated successfully environment: type: string enum: - development - production description: Environment where the PDF was generated data: oneOf: - $ref: '#/components/schemas/SyncPdfData' - $ref: '#/components/schemas/AsyncPdfData' ErrorResponse: type: object description: Common error response structure required: - success - errorCode - subCode - message properties: success: type: boolean description: Indicates if the request was successful (always false for errors) example: false errorCode: type: string enum: - '400' - '401' - '402' - '404' - '422' - '500' description: HTTP status code as string subCode: type: string description: Specific error subcode example: MISSING_API_KEY message: type: string description: Human-readable error message details: type: string description: >- Optional detailed error information (e.g., stack traces, network errors) meta: type: object description: Optional structured metadata for the error additionalProperties: true example: requiredCredits: 1 availableCredits: 0 activeSubscriptions: [] expiringCredits: [] issues: [] RenderOptions: type: object description: Advanced rendering options for PDF generation properties: path: type: string description: File path where the PDF should be saved (server-side only) scale: type: number minimum: 0.1 maximum: 2 default: 1 description: Scale factor for the PDF rendering (1 = 100%, 0.5 = 50%, 2 = 200%) displayHeaderFooter: type: boolean description: Whether to display header and footer on each page headerTemplate: type: string description: >- HTML template for the page header. Use placeholders like {{pageNumber}}, {{totalPages}}, {{date}}, {{title}} footerTemplate: type: string description: >- HTML template for the page footer. Use placeholders like {{pageNumber}}, {{totalPages}}, {{date}}, {{title}} printBackground: type: boolean description: Whether to print CSS backgrounds and images landscape: type: boolean description: Whether to render pages in landscape orientation pageRanges: type: string description: Page ranges to render (e.g., "1-3,5,8-10" or "1" for single page) format: type: string enum: - Letter - Legal - Tabloid - Ledger - A0 - A1 - A2 - A3 - A4 - A5 - A6 description: Paper format for the PDF. Overrides width and height if specified width: type: string description: Page width in CSS units (e.g., "8.5in", "21cm", "800px") height: type: string description: Page height in CSS units (e.g., "11in", "29.7cm", "600px") margin: type: object description: Page margins in CSS units properties: top: type: string description: Top margin (e.g., "1in", "2.54cm", "20px") right: type: string description: Right margin (e.g., "1in", "2.54cm", "20px") bottom: type: string description: Bottom margin (e.g., "1in", "2.54cm", "20px") left: type: string description: Left margin (e.g., "1in", "2.54cm", "20px") preferCSSPageSize: type: boolean description: Whether to use CSS @page size instead of format/width/height timeout: type: integer description: >- Maximum time in milliseconds to wait for page load before generating PDF omitBackground: type: boolean description: Whether to omit the background graphics and only render the content SyncPdfData: type: object description: Data payload for synchronous PDF generation required: - url - creditsUsed properties: url: type: string format: uri description: Direct URL to the generated PDF file example: https://app.sudopdf.com/files/abc123.pdf creditsUsed: type: integer description: Number of credits consumed for this PDF generation example: 1 AsyncPdfData: type: object description: Data payload for asynchronous PDF generation required: - status properties: status: type: string enum: - accepted description: Status of the PDF generation job example: accepted securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````