API endpoints and fields
Choose the resource you need. Each page lists its endpoints and fields, with links to types shared by other resources. Start with the PDF generation API guide or generate your first PDF with the API if this is your first request.
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/api-reference and help me choose the right thirds.ai endpoint and write a request. Check the fields and credentials in this reference.
Request examples
Use curl, Node 24 or later, or Python 3. Save Node examples as .mjs files. Replace the API key and use a new idempotency key for each new output. The first command uses jq to save a gallery template as request.json, and the PDF example sends that file. See the quickstart for polling and download steps.
curl --fail --silent --show-error https://thirds.ai/gallery/monthly-report/template \
| jq '{html: .source, data: .sample, wait: false}' > request.json
curl --fail-with-body --silent --show-error https://thirds.ai/v1/pdf \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_UNIQUE_PDF_REQUEST' \
--data @request.jsonimport { readFile } from "node:fs/promises";
const response = await fetch("https://thirds.ai/v1/pdf", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
"Idempotency-Key": "YOUR_UNIQUE_PDF_REQUEST"
},
body: await readFile("request.json"),
redirect: "error",
signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("retry-after") ?? "none"}`);
console.log(await response.text());import json
from urllib.error import HTTPError
from pathlib import Path
from urllib.request import HTTPRedirectHandler, Request, build_opener
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
request = Request("https://thirds.ai/v1/pdf",
method="POST",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
"Idempotency-Key": "YOUR_UNIQUE_PDF_REQUEST"
},
data=Path("request.json").read_bytes(),
)
try:
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(response.read().decode("utf-8"))
except HTTPError as error:
retry = error.headers.get("Retry-After", "none")
raise RuntimeError(f"HTTP {error.code}; Retry-After: {retry}") from Nonecurl --fail-with-body --silent --show-error https://thirds.ai/v1/image \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_UNIQUE_IMAGE_REQUEST' \
--data '{"html":"<h1>Quarterly report</h1><p>Ready to share.</p>","image":{"format":"png","width":1200,"height":630},"wait":false}'const response = await fetch("https://thirds.ai/v1/image", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
"Idempotency-Key": "YOUR_UNIQUE_IMAGE_REQUEST"
},
body: JSON.stringify({
"html": "<h1>Quarterly report</h1><p>Ready to share.</p>",
"image": {
"format": "png",
"width": 1200,
"height": 630
},
"wait": false
}),
redirect: "error",
signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("retry-after") ?? "none"}`);
console.log(await response.text());import json
from urllib.error import HTTPError
from urllib.request import HTTPRedirectHandler, Request, build_opener
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
request = Request("https://thirds.ai/v1/image",
method="POST",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
"Idempotency-Key": "YOUR_UNIQUE_IMAGE_REQUEST"
},
data=json.dumps({
"html": "<h1>Quarterly report</h1><p>Ready to share.</p>",
"image": {
"format": "png",
"width": 1200,
"height": 630
},
"wait": False
}).encode("utf-8"),
)
try:
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(response.read().decode("utf-8"))
except HTTPError as error:
retry = error.headers.get("Retry-After", "none")
raise RuntimeError(f"HTTP {error.code}; Retry-After: {retry}") from NoneResources
PDF renders: Create PDFs from HTML or saved templates, check each render, and read the result fields and limits.
Image renders: Create PNG, JPEG, or WebP images from HTML or saved templates, then check each render and download the result.
Image packs: Render one saved template version at several sizes, poll each size, retry failed sizes, and download a ZIP of the files that succeeded. See how to make static ad variations from one design for a worked example.
Carousels: Render selected pages of one saved template version as images, poll each slide, retry failed slides, and download a ZIP of the files that succeeded.
Batches: Render one saved template version once per data row, poll each row, retry failed rows, and download a ZIP of the files that succeeded.
File downloads: Download a finished PDF or image with its signed link, and check the response types and download limits. The guide to retrying requests and downloading files explains safe retries with an idempotency key.
Saved templates: Create and manage editable templates, start one from an AI chat message, preview changes, and publish fixed versions for repeat renders.
AI template chat: Send changes to a template's AI chat, check each draft, and save the draft you choose as the next version.
Brand kits: Manage brand colours, logos, and fonts, then apply the same brand kit when you create a template or image.
Image assets: Upload or generate private images for your templates, read prompt history, and check file limits.
Webhook endpoints: Manage webhook receivers, rotate secrets, check deliveries, and replay failed events for your account.
Account and API keys: Manage API keys and account identity requests, with the required credentials and response fields for each endpoint.
Public endpoints: Read the public API contract and service facts, or submit a testimonial with the required safety check.
Shared types and security: Look up shared request and response fields, error types, response headers, and API authentication schemes. See API error codes and how to fix them to resolve a named error.
API contract
Download the OpenAPI file to use with your tools. These reference pages come from that same contract. Browser writes need a session and its CSRF token; endpoints that support API keys state that on their resource page.