Create a batch
curl --request POST \
--url https://api.pdfbase.dev/v1/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{}
],
"webhook_url": "<string>",
"parallel": 123,
"stop_on_failure": true,
"output": "<string>",
"metadata": {}
}
'import requests
url = "https://api.pdfbase.dev/v1/batches"
payload = {
"items": [{}],
"webhook_url": "<string>",
"parallel": 123,
"stop_on_failure": True,
"output": "<string>",
"metadata": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{}],
webhook_url: '<string>',
parallel: 123,
stop_on_failure: true,
output: '<string>',
metadata: {}
})
};
fetch('https://api.pdfbase.dev/v1/batches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pdfbase.dev/v1/batches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
]
],
'webhook_url' => '<string>',
'parallel' => 123,
'stop_on_failure' => true,
'output' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pdfbase.dev/v1/batches"
payload := strings.NewReader("{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pdfbase.dev/v1/batches")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pdfbase.dev/v1/batches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_bodyBatches
Create a batch
Generate multiple PDFs in a single request. Each item can use HTML, URL, or a template.
POST
/
v1
/
batches
Create a batch
curl --request POST \
--url https://api.pdfbase.dev/v1/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{}
],
"webhook_url": "<string>",
"parallel": 123,
"stop_on_failure": true,
"output": "<string>",
"metadata": {}
}
'import requests
url = "https://api.pdfbase.dev/v1/batches"
payload = {
"items": [{}],
"webhook_url": "<string>",
"parallel": 123,
"stop_on_failure": True,
"output": "<string>",
"metadata": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{}],
webhook_url: '<string>',
parallel: 123,
stop_on_failure: true,
output: '<string>',
metadata: {}
})
};
fetch('https://api.pdfbase.dev/v1/batches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pdfbase.dev/v1/batches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
]
],
'webhook_url' => '<string>',
'parallel' => 123,
'stop_on_failure' => true,
'output' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pdfbase.dev/v1/batches"
payload := strings.NewReader("{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pdfbase.dev/v1/batches")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pdfbase.dev/v1/batches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {}\n ],\n \"webhook_url\": \"<string>\",\n \"parallel\": 123,\n \"stop_on_failure\": true,\n \"output\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_bodyPhase
Phase 1 (Launch)Request
array
required
Array of PDF generation requests. Each item follows the same schema as
POST /v1/pdfs, plus an optional template_id + data for template-based generation.Max items per batch: plan-dependent (5 for Free, up to 2,000 for Scale).string
URL to receive webhook notifications for this batch. Overrides your account-level webhook for this job. Events:
batch.completed, batch.failed, batch.item.completed, batch.item.failed.integer
default:"5"
Max items to render concurrently within this batch. Capped by your plan’s concurrency limit.
boolean
default:"false"
If
true, stop processing remaining items when any item fails. Completed items are still available.string
default:"individual"
How to deliver results:
individual— Each item gets its own PDF URL.merged— All items are merged into a single PDF in order.zip— All items are bundled into a ZIP file.
object
Metadata attached to the batch job.
Item schema
Each item in theitems array accepts:
{
"html": "<h1>Invoice #1</h1>",
"format": "a4",
"metadata": { "invoice_id": "1" }
}
{
"template_id": "tpl_abc123",
"data": { "number": "INV-001", "customer": "Acme" },
"metadata": { "invoice_id": "1" }
}
POST /v1/pdfs are supported per-item (format, margin, compress, etc.).
Response
Batches are asynchronous. The response returns immediately with aprocessing status:
{
"id": "bat_def456",
"object": "batch",
"status": "processing",
"total_items": 50,
"completed_items": 0,
"failed_items": 0,
"output": "individual",
"parallel": 5,
"stop_on_failure": false,
"metadata": {},
"created_at": "2026-05-19T11:00:00Z",
"estimated_completion": "2026-05-19T11:02:30Z"
}
GET /v1/batches/:id or listen for webhooks to track progress.
Example
curl -X POST https://api.pdfbase.dev/v1/batches \
-H "Authorization: Bearer pk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: monthly-invoices-2026-05" \
-d '{
"items": [
{
"template_id": "tpl_abc123",
"data": { "number": "INV-042", "customer": "Acme", "total": "$500" }
},
{
"template_id": "tpl_abc123",
"data": { "number": "INV-043", "customer": "Globex", "total": "$750" }
},
{
"template_id": "tpl_abc123",
"data": { "number": "INV-044", "customer": "Initech", "total": "$200" }
}
],
"output": "individual",
"parallel": 10,
"webhook_url": "https://your-app.com/webhooks/batch-done"
}'
const batch = await pdfbase.batches.create({
items: invoices.map(inv => ({
template_id: 'tpl_abc123',
data: { number: inv.number, customer: inv.customer, total: inv.total },
metadata: { invoice_id: inv.id },
})),
output: 'merged',
parallel: 10,
})
// Poll for completion
const result = await pdfbase.batches.poll(batch.id) // convenience method