# Asynchronous Request Source: https://docs.pdfnoodle.com/api-reference/convert-html-to-pdf/asynchronous POST /v1/html-to-pdf/async Asynchronous means that the request will return immediately with a requestId (if the request passes validation), but the pdf file will be sent after a few seconds to your custom webhook. We recommend using asynchronous requests for better performance on your application. POST [https://api.pdfnoodle.com/v1/html-to-pdf/async](https://api.pdfnoodle.com/v1/html-to-pdf/async) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/async' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "html": "

Your HTML here!

", "webhook": "https://webhook.url" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/async", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ html: "

Your HTML here!

", webhook: "https://webhook.url", }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/html-to-pdf/async', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'html': '

Your HTML here!

', 'webhook': 'https://webhook.url' } ) result = response.json() ``` ## Response ```json Immediate Response (200 OK) theme={null} { "requestId": "pdfnoodle_request_123456789" } ``` ```json Webhook Response (SUCCESS) theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` ```json Webhook Response (FAILED) theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "FAILED", "signedUrl": "", "metadata": {} } ``` This endpoint responds with `200 OK` immediately with a `requestId`. After a few seconds, the PDF file will be generated and we will send a POST to your webhook with the response body shown above. The `renderStatus` could be either `SUCCESS` or `FAILED`. If the request `FAILED`, you should contact support to figure out why your PDF generation failed. The response body will contain a `signedUrl` key which is a temporary URL pointing to the generated PDF file on our S3 bucket. If you passed a custom `s3_bucket`, it'll be stored there instead. This URL will expire after the time specified in `signedUrlExpiresIn` (default: 1 hour). ### PDF Render Metadata We'll also bring some additional metadata from your PDF render with every response: * **executionTime** - Time in seconds it took to generate your PDF * **fileSize** - PDF size in kiloBytes ## Parameters The HTML content you want to render The url of your webhook The object containing the parameters for your PDF. [See all the options here](/api-reference/options/pdf-params). If true, will return a .PNG file instead of a .PDF file This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) Number of seconds that the generated signed URL will take to expire (default: 1 hour) If true, will hide the footer and the header elements on the first page of the generated PDF ## Checking PDF Status Instead of waiting for the webhook, you can also check the status of your PDF generation by polling the [Get PDF Status](/api-reference/pdf-status/get) endpoint using the `requestId` returned from this request. # Batch Request Source: https://docs.pdfnoodle.com/api-reference/convert-html-to-pdf/batch POST /v1/html-to-pdf/batch Convert multiple HTML documents to PDFs in a single request. Process up to 20 PDFs at once, with optional merging into a single file. Batch HTML to PDF allows you to convert up to 20 HTML documents into PDFs in a single API call. You can also merge all generated PDFs into a single file. POST [https://api.pdfnoodle.com/v1/html-to-pdf/batch](https://api.pdfnoodle.com/v1/html-to-pdf/batch) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/batch' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "html": "

Invoice #001

Total: $150.00

" }, { "html": "

Invoice #002

Total: $250.00

" } ], "merge": false }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/batch", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ items: [ { html: "

Invoice #001

Total: $150.00

", }, { html: "

Invoice #002

Total: $250.00

", }, ], merge: false, }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/html-to-pdf/batch', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'items': [ { 'html': '

Invoice #001

Total: $150.00

' }, { 'html': '

Invoice #002

Total: $250.00

' } ], 'merge': False } ) result = response.json() ``` ## Response By default, the request waits for all PDFs to be generated before returning a response (synchronous behavior). If the batch takes longer than 30 seconds, it will return a `202 Accepted` response with a status URL to poll. ```json Success (200 OK) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "SUCCESS", "total": 2, "completed": 2, "merge": false, "results": [ { "requestId": "pdfnoodle_request_abc123", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } }, { "requestId": "pdfnoodle_request_def456", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "2.103 seconds", "fileSize": "5.200 kB" } } ] } ``` ```json Partial Success (200 OK) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "PARTIAL_SUCCESS", "total": 2, "completed": 2, "merge": false, "results": [ { "requestId": "pdfnoodle_request_abc123", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } }, { "requestId": "pdfnoodle_request_def456", "renderStatus": "FAILED", "signedUrl": "", "metadata": {} } ] } ``` ```json Timeout (202 Accepted) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789", "message": "Batch couldn't complete within 30 seconds. Check the batch status URL for progress." } ``` The `status` field indicates the overall outcome of the batch: * **SUCCESS** - All PDFs were generated successfully * **PARTIAL\_SUCCESS** - Some PDFs were generated, but at least one failed * **FAILED** - All PDFs failed to generate ### Merged Response When `merge` is set to `true`, the response will also include a `mergedUrl` pointing to a single PDF containing all successfully generated PDFs combined: ```json theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "SUCCESS", "total": 2, "completed": 2, "merge": true, "mergedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/merged/...", "results": [...] } ``` ## Parameters An array of HTML to PDF conversion items. Minimum 1 item, maximum 20 items per batch. Each item accepts the following properties: The HTML content you want to render The object containing the parameters for your PDF. [See all the options here](/api-reference/options/pdf-params). If true, will return a .PNG file instead of a .PDF file The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). If true, will hide the footer and the header elements on the first page of the generated PDF If true, will enter Debug Mode and show additional properties on the response to help you figure out your variables and html rendered content. [Here's everything you need to know about Debug Mode](/api-reference/options/debug-mode) If true, the request will return immediately with a `batchRequestId` and `statusUrl`. You can poll the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint to track progress. If true, all successfully generated PDFs will be merged into a single file. The merged file URL will be available in the `mergedUrl` field of the response. Cannot be used when any item has `convertToImage` set to `true`. A URL to receive a POST request when the batch is complete. The webhook payload will contain the full batch status and results. Number of seconds that the generated signed URLs will take to expire (default: 1 hour) ## Async Mode When `async` is set to `true`, the request returns immediately with a `batchRequestId` and a `statusUrl`: ```json theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789", "total": 2, "subRequestIds": ["pdfnoodle_request_abc123", "pdfnoodle_request_def456"], "message": "Batch PDF generation started. Check the status URL for progress." } ``` You can then check the status of your batch using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint. ## Payload Size Limit The request body is limited to **3MB**. Since batch requests contain multiple items with raw HTML content, this limit can be reached quickly when sending many items with large HTML documents. If your request exceeds this limit, you'll receive a `413` status code with the following error: ```json theme={null} { "message": "request entity too large" } ``` If you're hitting the 3MB payload limit, consider splitting your batch into multiple smaller requests. For example, instead of sending 20 items in a single request, send two requests with 10 items each. ## Checking Batch Status You can check the status of your batch at any time using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint with the `batchRequestId`. To check the status of an individual PDF within the batch, use the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the individual `requestId` from the results. # Synchronous request Source: https://docs.pdfnoodle.com/api-reference/convert-html-to-pdf/synchronous POST /v1/html-to-pdf/sync Synchronous means that when calling the API the request will wait for the pdf file to be generated before returning a response. We recommend using asynchronous requests for better performance on your application. POST [https://api.pdfnoodle.com/v1/html-to-pdf/sync](https://api.pdfnoodle.com/v1/html-to-pdf/sync) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/sync' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "html": "

Your HTML here!

" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/sync", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ html: "

Your HTML here!

", }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/html-to-pdf/sync', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'html': '

Your HTML here!

' } ) result = response.json() ``` ## Response ```json Success (200 OK) theme={null} { "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` ```json Timeout (202 Accepted) theme={null} { "requestId": "pdfnoodle_request_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_request_123456789", "message": "Couldn't generate PDF within 30 seconds, a queue was added to generate it asynchronously. Check the queue status on this URL." } ``` This endpoint responds with `200 OK` once the PDF has been generated. The response body will contain a `signedUrl` key which is a temporary URL pointing to the generated PDF file on our S3 bucket. If you passed a custom `s3_bucket`, it'll be stored there instead. This URL will expire after the time specified in `signedUrlExpiresIn` (default: 1 hour). If your PDF takes more than 30 seconds to render, it will automatically be added to an asynchronous queue and you'll receive a `202 Accepted` response with a `requestId`. You can check the status using the [Get PDF Status](/api-reference/pdf-status/get) endpoint. ### PDF Render Metadata We'll also bring some additional metadata from your PDF render with every response: * **executionTime** - Time in seconds it took to generate your PDF * **fileSize** - PDF size in kiloBytes ## Parameters The HTML content you want to render The object containing the parameters for your PDF. [See all the options here](/api-reference/options/pdf-params). If true, will return a .PNG file instead of a .PDF file This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) Number of seconds that the generated signed URL will take to expire (default: 1 hour) If true, will hide the footer and the header elements on the first page of the generated PDF ## Request Timeout (>30 seconds) Synchronous requests are useful when you want to get the results back immediately. However, if your PDF takes more than 30 seconds to render, it will automatically be added to an asynchronous queue. Sometimes, your PDF might take more than 30 seconds to render, if it has a lot of heavy images/charts and a lot of pages being generated. **If that's the case and your PDF takes more than 30 seconds to render synchronously**, we'll automatically add it to an asynchronous queue to render it. You'll be able to check if the PDF is completed using the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the requestId you just received (or just by making a GET request on the statusUrl). If the PDF is still rendering, you'll get a response like this: ```json theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "ONGOING", "signedUrl": "", "metadata": {} } ``` And **once the PDF is ready**, you'll receive a response like this: ```json theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` # Asynchronous request Source: https://docs.pdfnoodle.com/api-reference/generate-pdf-from-template/asynchronous POST /v1/pdf/async Asynchronous means that the request will return immediately with a requestId (if the request passes validation), but the pdf file will be sent after a few seconds to your custom webhook. We recommend using asynchronous requests for better performance on your application. POST [https://api.pdfnoodle.com/v1/pdf/async](https://api.pdfnoodle.com/v1/pdf/async) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/async' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "webhook": "https://webhook.url", "data": { "currentDDate": "01/12/2025", "user": { "name": "John Doe", "email": "john.doe@email.com" }, "details": [{"score": "100", "description": "high score"}] } }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/pdf/async", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ templateId: "check", webhook: "https://webhook.url", data: { currentDDate: "01/12/2025", user: { name: "John Doe", email: "john.doe@email.com", }, details: [{ score: "100", description: "high score" }], }, }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/pdf/async', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'templateId': 'check', 'webhook': 'https://webhook.url', 'data': { 'currentDDate': '01/12/2025', 'user': { 'name': 'John Doe', 'email': 'john.doe@email.com' }, 'details': [{'score': '100', 'description': 'high score'}] } } ) result = response.json() ``` ## Response ```json Immediate Response (200 OK) theme={null} { "requestId": "pdfnoodle_request_123456789" } ``` ```json Webhook Response (SUCCESS) theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` ```json Webhook Response (FAILED) theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "FAILED", "signedUrl": "", "metadata": {} } ``` This endpoint responds with `200 OK` immediately with a `requestId`. After a few seconds, the PDF file will be generated and we will send a POST to your webhook with the response body shown above. The `renderStatus` could be either `SUCCESS` or `FAILED`. If the request `FAILED`, you should contact support to figure out why your PDF generation failed. The response body will contain a `signedUrl` key which is a temporary URL pointing to the generated PDF file on our S3 bucket. If you passed a custom `s3_bucket`, it'll be stored there instead. This URL will expire after the time specified in `signedUrlExpiresIn` (default: 1 hour). ### PDF Render Metadata We'll also bring some additional metadata from your PDF render with every response: * **executionTime** - Time in seconds it took to generate your PDF * **fileSize** - PDF size in kiloBytes ## Parameters The id of your PDF template The url of your webhook The object containing the variables from your PDF template If true, will return a .PNG file instead of a .PDF file This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) Number of seconds that the generated signed URL will take to expire (default: 1 hour) If you're using our embedded white-label solution, you can pass the UUID of your customer to generate the PDF of the customized template If true, will hide the footer and the header elements on the first page of the generated PDF If true, will enter Debug Mode and show additional properties on the response to help you figure out your variables and html rendered content. [Here's everything you need to know about Debug Mode](/api-reference/options/debug-mode) ## Checking PDF Status Instead of waiting for the webhook, you can also check the status of your PDF generation by polling the [Get PDF Status](/api-reference/pdf-status/get) endpoint using the `requestId` returned from this request. # Batch Request Source: https://docs.pdfnoodle.com/api-reference/generate-pdf-from-template/batch POST /v1/pdf/batch Generate multiple PDFs from templates in a single request. Process up to 20 PDFs at once, with optional merging into a single file. Batch PDF generation allows you to generate up to 20 PDFs in a single API call. Each item in the batch can use a different template and data. You can also merge all generated PDFs into a single file. POST [https://api.pdfnoodle.com/v1/pdf/batch](https://api.pdfnoodle.com/v1/pdf/batch) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/batch' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "templateId": "invoice", "data": { "invoiceNumber": "INV-001", "customer": { "name": "John Doe" }, "total": "$150.00" } }, { "templateId": "invoice", "data": { "invoiceNumber": "INV-002", "customer": { "name": "Jane Smith" }, "total": "$250.00" } } ], "merge": false }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/pdf/batch", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ items: [ { templateId: "invoice", data: { invoiceNumber: "INV-001", customer: { name: "John Doe" }, total: "$150.00", }, }, { templateId: "invoice", data: { invoiceNumber: "INV-002", customer: { name: "Jane Smith" }, total: "$250.00", }, }, ], merge: false, }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/pdf/batch', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'items': [ { 'templateId': 'invoice', 'data': { 'invoiceNumber': 'INV-001', 'customer': {'name': 'John Doe'}, 'total': '$150.00' } }, { 'templateId': 'invoice', 'data': { 'invoiceNumber': 'INV-002', 'customer': {'name': 'Jane Smith'}, 'total': '$250.00' } } ], 'merge': False } ) result = response.json() ``` ## Response By default, the request waits for all PDFs to be generated before returning a response (synchronous behavior). If the batch takes longer than 30 seconds, it will return a `202 Accepted` response with a status URL to poll. ```json Success (200 OK) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "SUCCESS", "total": 2, "completed": 2, "merge": false, "results": [ { "requestId": "pdfnoodle_request_abc123", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } }, { "requestId": "pdfnoodle_request_def456", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "2.103 seconds", "fileSize": "5.200 kB" } } ] } ``` ```json Partial Success (200 OK) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "PARTIAL_SUCCESS", "total": 2, "completed": 2, "merge": false, "results": [ { "requestId": "pdfnoodle_request_abc123", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } }, { "requestId": "pdfnoodle_request_def456", "renderStatus": "FAILED", "signedUrl": "", "metadata": {} } ] } ``` ```json Timeout (202 Accepted) theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789", "message": "Batch couldn't complete within 30 seconds. Check the batch status URL for progress." } ``` The `status` field indicates the overall outcome of the batch: * **SUCCESS** - All PDFs were generated successfully * **PARTIAL\_SUCCESS** - Some PDFs were generated, but at least one failed * **FAILED** - All PDFs failed to generate ### Merged Response When `merge` is set to `true`, the response will also include a `mergedUrl` pointing to a single PDF containing all successfully generated PDFs combined: ```json theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "status": "SUCCESS", "total": 2, "completed": 2, "merge": true, "mergedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/merged/...", "results": [...] } ``` ## Parameters An array of PDF generation items. Minimum 1 item, maximum 20 items per batch. Each item accepts the following properties: The id of your PDF template The object containing the variables from your PDF template If you're using our embedded white-label solution, you can pass the UUID of your customer to generate the PDF of the customized template If true, will return a .PNG file instead of a .PDF file The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). If true, will hide the footer and the header elements on the first page of the generated PDF If true, will enter Debug Mode and show additional properties on the response to help you figure out your variables and html rendered content. [Here's everything you need to know about Debug Mode](/api-reference/options/debug-mode) If true, the request will return immediately with a `batchRequestId` and `statusUrl`. You can poll the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint to track progress. If true, all successfully generated PDFs will be merged into a single file. The merged file URL will be available in the `mergedUrl` field of the response. Cannot be used when any item has `convertToImage` set to `true`. A URL to receive a POST request when the batch is complete. The webhook payload will contain the full batch status and results. Number of seconds that the generated signed URLs will take to expire (default: 1 hour) ## Async Mode When `async` is set to `true`, the request returns immediately with a `batchRequestId` and a `statusUrl`: ```json theme={null} { "batchRequestId": "pdfnoodle_batch_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789", "total": 2, "subRequestIds": ["pdfnoodle_request_abc123", "pdfnoodle_request_def456"], "message": "Batch PDF generation started. Check the status URL for progress." } ``` You can then check the status of your batch using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint. ## Payload Size Limit The request body is limited to **3MB**. Since batch requests contain multiple items, this limit can be reached when sending many items with large `data` objects. If your request exceeds this limit, you'll receive a `413` status code with the following error: ```json theme={null} { "message": "request entity too large" } ``` If you're hitting the 3MB payload limit, consider splitting your batch into multiple smaller requests. For example, instead of sending 20 items in a single request, send two requests with 10 items each. ## Checking Batch Status You can check the status of your batch at any time using the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint with the `batchRequestId`. To check the status of an individual PDF within the batch, use the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the individual `requestId` from the results. # Synchronous request Source: https://docs.pdfnoodle.com/api-reference/generate-pdf-from-template/synchronous POST /v1/pdf/sync Synchronous means that when calling the API the request will wait for the pdf file to be generated before returning a response. We recommend using asynchronous requests for better performance on your application. POST [https://api.pdfnoodle.com/v1/pdf/sync](https://api.pdfnoodle.com/v1/pdf/sync) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "data": { "currentDDate": "01/12/2025", "user": { "name": "John Doe", "email": "john.doe@email.com" }, "details": [{"score": "100", "description": "high score"}] } }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.pdfnoodle.com/v1/pdf/sync", { method: "POST", headers: { Authorization: "Bearer pdfnoodle_api_123456789", "Content-Type": "application/json", }, body: JSON.stringify({ templateId: "check", data: { currentDDate: "01/12/2025", user: { name: "John Doe", email: "john.doe@email.com", }, details: [{ score: "100", description: "high score" }], }, }), }); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.pdfnoodle.com/v1/pdf/sync', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789', 'Content-Type': 'application/json' }, json={ 'templateId': 'check', 'data': { 'currentDDate': '01/12/2025', 'user': { 'name': 'John Doe', 'email': 'john.doe@email.com' }, 'details': [{'score': '100', 'description': 'high score'}] } } ) result = response.json() ``` ## Response ```json Success (200 OK) theme={null} { "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` ```json Timeout (202 Accepted) theme={null} { "requestId": "pdfnoodle_request_123456789", "statusUrl": "https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_request_123456789", "message": "Couldn't generate PDF within 30 seconds, a queue was added to generate it asynchronously. Check the queue status on this URL." } ``` This endpoint responds with `200 OK` once the PDF has been generated. The response body will contain a `signedUrl` key which is a temporary URL pointing to the generated PDF file on our S3 bucket. If you passed a custom `s3_bucket`, it'll be stored there instead. This URL will expire after the time specified in `signedUrlExpiresIn` (default: 1 hour). If your PDF takes more than 30 seconds to render, it will automatically be added to an asynchronous queue and you'll receive a `202 Accepted` response with a `requestId`. You can check the status using the [Get PDF Status](/api-reference/pdf-status/get) endpoint. ### PDF Render Metadata We'll also bring some additional metadata from your PDF render with every response: * **executionTime** - Time in seconds it took to generate your PDF * **fileSize** - PDF size in kiloBytes ## Parameters The id of your PDF template The object containing the variables from your PDF template If true, will return a .PNG file instead of a .PDF file This object containing the metadata for your PDF. [See all the options here](/api-reference/options/pdf-metadata). The id of the active s3 connection you want to store your generated file on. (only available in the high plan) The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3\_bucket) Number of seconds that the generated signed URL will take to expire (default: 1 hour) If you're using our embedded white-label solution, you can pass the UUID of your customer to generate the PDF of the customized template If true, will hide the footer and the header elements on the first page of the generated PDF If true, will enter Debug Mode and show additional properties on the response to help you figure out your variables and html rendered content. [Here's everything you need to know about Debug Mode](/api-reference/options/debug-mode) ## Request Timeout (>30 seconds) Synchronous requests are useful when you want to get the results back immediately. However, if your PDF takes more than 30 seconds to render, it will automatically be added to an asynchronous queue. Sometimes, your PDF might take more than 30 seconds to render, if it has a lot of heavy images/charts and a lot of pages being generated. **If that's the case and your PDF takes more than 30 seconds to render synchronously**, we'll automatically add it to an asynchronous queue to render it. You'll be able to check if the PDF is completed using the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the requestId you just received (or just by making a GET request on the statusUrl). If the PDF is still rendering, you'll get a response like this: ```json theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "ONGOING", "signedUrl": "", "metadata": {} } ``` And **once the PDF is ready**, you'll receive a response like this: ```json theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` # Authentication Source: https://docs.pdfnoodle.com/api-reference/getting-started/authentication To authenticate you need to add an *Authorization* header with the contents of the header being `Bearer pdfnoodle_api_123456789` where `pdforge_api_123456789` is your API Key. Example: ``` Authorization: Bearer pdfnoodle_api_123456789 ``` When you create your account, we'll automatically generate 2 API Keys for you, but you can create how many more you'd like. You can access them on the API Keys menu on the sidebar. # Rate limit Source: https://docs.pdfnoodle.com/api-reference/getting-started/rate-limit Your rate limit for **synchronous requests** will depend on your plan. | Plan | Sync Rate Limit | | ------------ | ----------------------- | | **Starter** | 60 requests per minute | | **Business** | 240 requests per minute | | **Scale** | 360 requests per minute | **Asynchronous requests** have a higher rate limit of **1.000 request per minute for both plans**. **Batch requests** (`/batch` endpoints) have a rate limit of **50 requests per minute for both plans**. Since each batch request can contain up to 20 items, this still allows generating up to 1.000 PDFs per minute. After that, you'll hit the rate limit and receive a `429` response error code. To prevent this, we recommend reducing the rate at which you request the API. This can be done by introducing a queue mechanism or reducing the number of concurrent requests per second. If you have specific requirements, [contact support](mailto:support@pdforge.com) to request a rate increase. # Migration guide: from pdforge to pdf noodle Source: https://docs.pdfnoodle.com/api-reference/guides/migration-guide-from-pdforge-to-pdf-noodle # Migration guide: from pdforge to pdf noodle Migrating from pdforge to pdf noodle is designed to be smooth and low-risk. This guide explains what is changing, what remains exactly the same, and the minimal steps you can take to align your stack with the new brand and domain without breaking any existing workflows.
Whether you are a developer, no-code builder, automation enthusiast, or SaaS founder, this article will help you migrate with confidence. *** ### 1. Introduction pdf noodle is the new name and brand identity for what used to be pdforge. Under the hood, it is the same platform, the same infrastructure, and the same PDF engine you’re already using in production.
**A quick overview:** * Your templates, variables, and payloads still work the same way * Your API keys, auth, and rate limits remain unchanged * Your integrations (n8n, Make, Zapier, Bubble, custom code) continue to run normally * All pdforge URLs are redirected to the new domain and will keep working until the end of 2026
This guide explains what is changing at the branding and domain level and gives you a short, practical migration path you can follow at your own pace. *** ### 2. What’s Changing Here’s what is actually new with the rebrand. * **New brand name** * From pdforge to pdf noodle * **New domain** * From pdforge.com to pdfnoodle.com * **Updated documentation and dashboard UI** * Logo, colors, and wording now reflect the PDF Noodle brand * Navigation and features remain familiar * **New endpoints** (optional but recommended) * New base URL under api.pdfnoodle.com * Old api.pdforge.com URLs are redirected and remain valid until end of 2026
Nothing in your payload structure, Handlebars variables, or template conventions changes with this rebrand. *** ### 3. What’s Not Changing Under the hood, pdf noodle is the same engine you already trust. The rebrand does not affect: * **API behavior** * Same endpoints, same request/response shape, same error codes * **Template schemas** * Your Handlebars variables like `{{customer_name}}`, `{{{html_block}}}`, loops, conditions, and visibility logic stay exactly the same * **Auth tokens and API keys** * No need to regenerate keys or rotate credentials * **PDF generation engine** * Same reliability, performance, and rendering behavior * **Integrations** * n8n, Make, Zapier, Bubble, custom scripts keep working as they are * **Existing pdforge URLs** * All existing endpoints and dashboard URLs under pdforge.com will keep working until the end of 2026 You can migrate gradually, on your own timeline, without risking downtime or breaking existing PDF flows. *** ### 4. Recommended Migration Path You don’t need to do everything at once. The recommended approach is: 1. **Update your API base URLs** * Switch from api.pdforge.com to api.pdfnoodle.com in your code and integrations 2. **Test via Debug Mode** * Use Debug Mode (where available) to inspect rendered HTML, variables, and template schemas when testing the new domain 3. **Update environment variables** * Centralize your base URL and keep it configurable (for staging, production, etc.) 4. **Update webhooks and callback URLs** (optional but recommended) * If you have callbacks pointing to pdforge.com, update them to pdfnoodle.com for long-term consistency 5. **Validate template rendering** * Trigger example runs in staging or sandbox environments * Make sure variables are being sent and resolved correctly 6. **Roll out to production** * Once validated, deploy your changes and monitor as usual **Tip:** If you already use environment variables for your base URL, this migration can often be done with a single config change and a quick smoke test. *** ### 5. Update Your API URLs The most important technical change is the base URL. Paths and behavior remain identical. **Old base URL:** ``` https://api.pdforge.com ``` **New base URL:** ``` https://api.pdfnoodle.com ``` What stays the same: * All endpoint paths remain the same * No changes to request bodies or response formats * No changes to auth headers or token usage * api.pdforge.com will remain active until the end of 2026 **Example: if you previously used:** ```bash theme={null} curl --location 'https://api.pdforge.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdforge_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "data":{ "currentDDate": "01/12/2025", "user": { "name":"John Doe", "email": "john.doe@email.com" }, "details": [{"score":"100", "description":"high score"}] } } ' ``` **You can safely update to:** ```bash theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdforge_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "data":{ "currentDDate": "01/12/2025", "user": { "name":"John Doe", "email": "john.doe@email.com" }, "details": [{"score":"100", "description":"high score"}] } } ' ``` The Handlebars variables convention (e.g. `{{customer_name}}`, `{{{html_block}}}`) remains exactly the same inside your templates. *** ### 6. Environment Variables If you already use environment variables for configuration, migration becomes much easier and safer. A typical setup might look like this: ``` PDF_API_URL=https://api.pdforge.com PDF_API_KEY=your-existing-key ``` You can update it to: ``` PDF_API_URL=https://api.pdfnoodle.com PDF_API_KEY=your-existing-key ``` * No API key changes are required * You can switch back to the old URL at any time during testing if needed * This pattern keeps your staging and production environments flexible
**Tip:** If you are dynamically sending variables as payload to pdf noodle (for example, building a variables object from your own identifiers), nothing changes. The “Send data dynamically” convention still applies exactly as before. *** ### 8. n8n • Make.com • Zapier • Bubble Integrations If you use pdf noodle (formerly pdforge) through no-code or automation platforms, here’s what you need to know. #### n8n * The current pdforge node / package will continue to work as is * The underlying API will keep working through redirects until end of 2026 * At first, we will only change the branding and description to reflect pdf noodle * In the future, we plan to release a new, dedicated pdf noodle package * When we do that, the older pdforge package will be gradually deprecated * You will be informed well in advance and given a clear migration path #### Make.com * Existing custom modules or HTTP integrations that point to api.pdforge.com will continue to work through redirects * You can optionally update HTTP modules and custom integrations to use [https://api.pdfnoodle.com](https://api.pdfnoodle.com) to align with the new domain
#### Zapier * If you use Zapier via webhooks or custom integrations that call api.pdforge.com, no immediate change is required * You can update the URLs to api.pdfnoodle.com when convenient for consistency
#### Bubble and Other API Connectors * If you use Bubble’s API Connector (or similar tools) with `https://api.pdforge.com` as the base URL: * Update the base URL to `https://api.pdfnoodle.com` * No changes are required to the request structure or JSON payload
Overall, all existing integrations keep working. The main change is branding and base URL alignment, which you can adopt progressively. *** ### 9. Frequently Asked Questions #### Do I need a new API key? No. Your existing API keys remain valid and continue to work for both pdforge.com and pdfnoodle.com domains. #### Are my templates affected? No. All your templates, Handlebars variables, visibility rules, and margins continue to work exactly as they did before. #### Do redirects affect speed? Redirects add a minimal overhead, but for most use cases this is negligible. For optimal performance and future-proofing, we recommend updating to `https://api.pdfnoodle.com` when convenient. #### Will pdforge URLs stop working immediately? No. All pdforge URLs are expected to remain functional through the end of 2026 via permanent 301 redirects. You have plenty of time to migrate gradually. #### Do I need to update my plan or billing? No. Your plan, pricing, and billing setup remain exactly the same. This is a brand and domain change only, not a pricing or product reset. *** **If you have any questions about migration or run into any issues, feel free to reach out:** **📩 `support@pdfnoodle.com`**
We’re here to help you switch over smoothly and keep your PDFs running flawlessly. # Overview Source: https://docs.pdfnoodle.com/api-reference/index Welcome to PDF Noodle API Reference # API Reference Welcome to the PDF Noodle API Reference. Here you'll find everything you need to integrate PDF generation into your application. ## Getting Started Learn how to authenticate your API requests Understand API rate limits and usage ## PDF Generation Generate PDFs using reusable templates Convert HTML directly to PDF ## PDF Tools Check the status of async tool operations Get presigned URLs for uploading and downloading PDFs Combine multiple PDF files into one document Split a PDF into parts by ranges or intervals Reduce PDF file size with configurable compression Convert Markdown content into styled PDFs Update title, author, and other PDF metadata ## Templates Create new templates using AI based on text prompts Retrieve all templates available for your company Extract variable schema from templates Retrieve complete template details and check creation status # Debug Mode Source: https://docs.pdfnoodle.com/api-reference/options/debug-mode # Debug Mode Debug Mode helps you quickly troubleshoot why a template didn’t render as expected, without guessing. Use it while building or debugging; turn it off for production runs. It only works on the PDF from templates endpoints. ### What you get with Debug Mode When debug is enabled, the response includes: * **Rendered HTML** – the final HTML string sent to the PDF engine. * **Sent Variables** – the exact payload received by the template. * **Template Schema** – variables the template expects (including each arrays). * **Are Variables Valid**? – If the schema from sent variables equals template schema. * **Missing Variables** – list of required variables not provided on the payload * **Has Draft Version** – If there's a draft version of this template that has not been published yet (The API only has access to published versions) **Performance note:** Debug Mode adds extra work and slows down the request. Use it only for investigation. ### How to activate Debug Mode Just add `debug: true` to your request body. **Example of request:** ```bash theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "debug": true, "data":{ "currentDDate": "01/12/2025", "user": { "name":"John Doe", "email": "john.doe@email.com" }, "details": [{"score":"100", "description":"high score"}] } } ' ``` On your response, you'll get an additional object with the debug information: ```json theme={null} { "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" }, "debug":{ "renderedHtml": "....", "templateSchema": {...}, "sentVariables": {...}, "isVariablesValid": true, "missingVariables": [...], "hasDraftVersion": true } } ``` # How render PNG instead of PDF Source: https://docs.pdfnoodle.com/api-reference/options/how-render-png-instead-of-pdf # How render PNG instead of PDF ## How to do it To generate the same layout but as a .PNG instead of a .PDF file, you can use the same endpoints `/v1/pdf/sync` and `/v1/pdf/async`, but passing an extra parameter `convertToImage:true` on the body payload. If you want to generate the image synchronously, you can use this guide: [Generate PDF from Template Synchronously](/api-reference/generate-pdf-from-template/synchronous) Or if you want to generate the image asynchronously, you can use this guide: [Generate PDF from Template Asynchronously](/api-reference/generate-pdf-from-template/asynchronous) **Here's a request example for a synchronous render:** ``` curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "check", "convertToImage": true, "data":{ "currentDDate": "01/12/2025", "user": { "name":"John Doe", "email": "john.doe@email.com" }, "details": [{"score":"100", "description":"high score"}] } } ' ``` The result will be the same **signedUrl** described on the guides, but with a .PNG file instead. # PDF metadata Source: https://docs.pdfnoodle.com/api-reference/options/pdf-metadata # PDF metadata ### PDF Metadata options Here's a list of all the **optional parameters** that you can send as an object "metadata" while using our endpoints: A human-readable name for the document, like a book title. Default: the name of the template The individual or organization that created the document. Default: `pdfnoodle` A brief description of the document's topic. A list of keywords describing the content. The original software that created the content before it was turned into a PDF. Default: `pdfnoodle` These values will appear in the PDF's file details. On macOS, you can check them by right-clicking the file and selecting **Get Info** in Finder. The only field you can't override is the **Encoding software.** It's automatically set by our system. # PDF Params Source: https://docs.pdfnoodle.com/api-reference/options/pdf-params # PDF Params **When using reusable templates**, these parameters are set on the interface, so you don't need send any extra parameters on the API. ### PDF Params options Here's a list of all the **optional parameters** that you can send as an object "pdfParams" while using our HTML to PDF endpoint: Whether to show the header and footer. Default: `false` HTML template for the header. [See valid HTML markup bellow](#header-and-footer-valid-html-markups). HTML template for the footer. [See valid HTML markup bellow](#header-and-footer-valid-html-markups). Set to `true` to print background graphics. Default: `false` Whether to print in landscape orientation. Default: `false` All the valid paper format types when printing a PDF. [See all format options here](#paper-formats). Default: `Letter` Paper width, accepts values labeled with units. Paper height, accepts values labeled with units. Object that sets the margin of every page. [See all margin options here](#margin-options). Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option. Default: `false` Whether or not to embed the document outline into the PDF. Default: `false` The **width**, **height**, and **margin** options accept values labeled with units. Unlabeled values are treated as pixels. All possible formats: * `width`: 100 (prints with width set to 100 pixels) * `width`: '100px' (prints with width set to 100 pixels) * `width`: '100in' (prints with width set to 100 inches) * `width`: '100cm,' (prints with width set to 100 centimeters) * `width`: '100mm' (prints with width set to 100 millimeters) *** ### Header and Footer: Valid HTML Markups HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: * `'date'` formatted print date * `'title'` document title * `'url'` document location * `'pageNumber'` current page number * `'totalPages'` total pages in the document **Example:** ```html theme={null}

Some custom footer text here

Page of

``` *** ### Paper format options | Format name | Size in inches | Size in cm | | ----------- | ---------------- | --------------- | | `Letter` | 8.5in x 11in | 21.6cm x 27.9cm | | `Legal` | 8.5in x 14in | 21.6cm x 35.6cm | | `Tabloid` | 11in x 17in | 27.9cm x 43.2cm | | `Ledger` | 17in x 11in | 43.2cm x 27.9cm | | `A0` | 33.1in x 46.8in | 84cm x 118.9cm | | `A1` | 23.4in x 33.1in | 59.4cm x 84cm | | `A2` | 16.54in x 23.4in | 42cm x 59.4cm | | `A3` | 11.7in x 16.54in | 29.7cm x 42cm | | `A4` | 8.27in x 11.7in | 21cm x 29.7cm | | `A5` | 5.83in x 8.27in | 14.8cm x 21cm | | `A6` | 4.13in x 5.83in | 10.5cm x 14.8cm | *** ### Margin Options Top margin, accepts values labeled with units. Default: `0` Right margin, accepts values labeled with units. Default: `0` Left margin, accepts values labeled with units. Default: `0` Bottom margin, accepts values labeled with units. Default: `0` * Example: ```json theme={null} { "margin": { "top": 10, "right": "10px", "bottom": "10in", "left": "10cm" } } ``` # Storage Options (s3) Source: https://docs.pdfnoodle.com/api-reference/options/storage-options-s3 # Storage Options (s3) ### Setting Up S3 Storage You're on the **High plan** and want to store your files in a custom S3 bucket? We’ve got a full guide on how to set up S3 connections and switch the default bucket directly from the dashboard. [**Check out the guide**](https://app.gitbook.com/s/0ZiE10OwIphqlXGMhEL6/guides/saving-to-your-s3-storage). ### Configuration Options #### `s3_bucket` Set this to the ID of an active S3 connection to override the default storage location. #### `s3_key` default: `pdforge/{`[`template_id`](#user-content-fn-1)[^1]`}/`[`{auto_generated_filename}`](#user-content-fn-2)[^2] Define the path (folders and filename, without extension) where your file will be saved inside your S3 bucket. **Don’t include the file extension** — we’ll handle that based on the file type (e.g., .pdf, .png). **Here's a request example for a synchronous render:** ``` curl --location 'https://api.pdfnoodle.com/v1/pdf/sync' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' \ --header 'Content-Type: application/json' \ --data '{ "templateId": "template_id", "s3_bucket": "s3_123456789", "s3_key": "path/to/your/file", "data":{ "currentDDate": "01/12/2025", "user": { "name":"John Doe", "email": "john.doe@email.com" }, "details": [{"score":"100", "description":"high score"}] } } ' ``` [^1]: Your template id [^2]: An auto generated random hash # Get PDF Status Source: https://docs.pdfnoodle.com/api-reference/pdf-status/get GET /v1/pdf/status/:requestId Retrieve the status of a PDF generation request using the requestId returned from asynchronous requests or when synchronous requests timeout. Use this endpoint to check the status of a single PDF generation request. This is particularly useful when:

You've made an asynchronous request and want to poll for status instead of waiting for the webhook
A synchronous request timed out (>30 seconds) and was automatically queued asynchronously

If you're looking to check the status of a batch PDF generation, use the [Get Batch PDF Status](/api-reference/pdf-status/get-batch) endpoint instead. GET [https://api.pdfnoodle.com/v1/pdf/status/:requestId](https://api.pdfnoodle.com/v1/pdf/status/:requestId) ## Request ```bash cURL theme={null} curl --location 'https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_request_123456789' \ --header 'Authorization: Bearer pdfnoodle_api_123456789' ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_request_123456789", { method: "GET", headers: { Authorization: "Bearer pdfnoodle_api_123456789", }, } ); const result = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.pdfnoodle.com/v1/pdf/status/pdfnoodle_request_123456789', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789' } ) result = response.json() ``` ## Response The endpoint responds with `200 OK` and returns the current status of the PDF generation: ```json ONGOING theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "ONGOING", "signedUrl": "", "metadata": {} } ``` ```json SUCCESS theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "SUCCESS", "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...", "metadata": { "executionTime": "1.805 seconds", "fileSize": "4.066 kB" } } ``` ```json FAILED theme={null} { "requestId": "pdfnoodle_request_123456789", "renderStatus": "FAILED", "signedUrl": "", "metadata": {} } ``` ## Parameters The requestId returned from an asynchronous request or from a synchronous request that timed out ## Response Fields The unique identifier for this PDF generation request The current status of the PDF generation. Possible values: - `ONGOING` - The PDF is still being generated - `SUCCESS` - The PDF has been successfully generated - `FAILED` - The PDF generation failed A temporary URL pointing to the generated PDF file. This will be empty (`""`) when `renderStatus` is `ONGOING` or `FAILED`. The URL expires after 1 hour. Additional metadata about the PDF render. Contains: - **executionTime** - Time in seconds it took to generate your PDF (only present when `renderStatus` is `SUCCESS`) - **fileSize** - PDF size in kiloBytes (only present when `renderStatus` is `SUCCESS`) If the `renderStatus` is `FAILED`, you should contact support to figure out why your PDF generation failed. ## Usage Example Here's a complete example of polling for PDF status: ```javascript theme={null} async function checkPdfStatus(requestId) { const maxAttempts = 60; // Poll for up to 5 minutes (60 * 5 seconds) let attempts = 0; while (attempts < maxAttempts) { const response = await fetch( `https://api.pdfnoodle.com/v1/pdf/status/${requestId}`, { method: "GET", headers: { Authorization: "Bearer pdfnoodle_api_123456789", }, } ); const result = await response.json(); if (result.renderStatus === "SUCCESS") { return result.signedUrl; } if (result.renderStatus === "FAILED") { throw new Error("PDF generation failed"); } // Wait 5 seconds before checking again await new Promise((resolve) => setTimeout(resolve, 5000)); attempts++; } throw new Error("PDF generation timed out"); } ``` ```python theme={null} import requests import time def check_pdf_status(request_id): max_attempts = 60 # Poll for up to 5 minutes (60 * 5 seconds) attempts = 0 while attempts < max_attempts: response = requests.get( f'https://api.pdfnoodle.com/v1/pdf/status/{request_id}', headers={ 'Authorization': 'Bearer pdfnoodle_api_123456789' } ) result = response.json() if result['renderStatus'] == 'SUCCESS': return result['signedUrl'] if result['renderStatus'] == 'FAILED': raise Exception('PDF generation failed') # Wait 5 seconds before checking again time.sleep(5) attempts += 1 raise Exception('PDF generation timed out') ``` # Get Batch PDF Status Source: https://docs.pdfnoodle.com/api-reference/pdf-status/get-batch GET /v1/pdf/batch/status/:batchRequestId Retrieve the status of a batch PDF generation request using the batchRequestId. Use this endpoint to check the status of a batch PDF generation request. This is useful when:

You've sent a batch request with `async: true` and want to poll for progress
A synchronous batch request timed out (>30 seconds) and you need to check on its progress

You've set `async: true` and want to poll for the result
A synchronous request timed out (>30 seconds) and was automatically processed in the background