API Reference

Complete reference for the TemplateFox REST API.

Base URL


https://api.templatefox.com

Authentication

All requests require an API key passed in the x-api-key header.


x-api-key: YOUR_API_KEY

Create an API key in the API keys section of your dashboard . Keys start with sk_.

Interactive Documentation

Swagger Documentation — interactive API explorer
Postman Collection — fork and test all endpoints

Main endpoints

POST

/v1/pdf/create

Synchronous PDF generation. Returns a signed URL (or binary bytes) immediately.

POST

/v1/pdf/create-async

Queue a job, receive the result via polling or webhook. Best for large docs, batches, or long-running renders.

Other endpoints

GET /v1/templates

List all templates belonging to your team. Useful for no-code integrations (Zapier, Make, n8n).

No credits consumed.


curl https://api.templatefox.com/v1/templates \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "templates": [
    {
      "id": "HMQywVpZxqAM",
      "name": "Invoice Template",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:45:00Z"
    }
  ]
}

GET /v1/templates/{template_id}/fields

Get the dynamic fields (variables) declared in a template. Useful for building dynamic forms in integrations.

No credits consumed.


curl https://api.templatefox.com/v1/templates/HMQywVpZxqAM/fields \
  -H "x-api-key: YOUR_API_KEY"

Response


[
  {
    "key": "customer_name",
    "label": "customer_name",
    "type": "string",
    "required": false,
    "helpText": "e.g. John Doe"
  },
  {
    "key": "items",
    "label": "items",
    "type": "string",
    "required": false,
    "helpText": "JSON array, e.g. [{\"name\": \"Product\", \"price\": 99}]"
  }
]

Field	Type	Description
`key`	string	Field identifier to use in the `data` object
`label`	string	Human-readable label
`type`	string	Field type: `string`, `integer`, `number`, `boolean`
`required`	boolean	Whether the field is required
`helpText`	string	Help text with example value

GET /v1/account

Current account info including remaining credits.

No credits consumed.


curl https://api.templatefox.com/v1/account \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "credits": 142,
  "email": "user@example.com"
}

GET /v1/account/transactions

Transaction history with pagination.

No credits consumed.

Parameter	Type	Default	Description
`limit`	number	300	Number of records to return (1-1000)
`offset`	number	0	Number of records to skip


curl "https://api.templatefox.com/v1/account/transactions?limit=10&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "transactions": [
    {
      "transaction_ref": "550e8400-e29b-41d4-a716-446655440000",
      "transaction_type": "PDFGEN",
      "template_id": "HMQywVpZxqAM",
      "exec_tm": 1250,
      "credits": 1,
      "created_at": "2026-01-20T14:30:00Z"
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0
}

Transaction Type	Description
`PDFGEN`	PDF generation (credits consumed)
`PURCHASE`	Credit purchase (credits added)
`REFUND`	Credit refund on failed generation
`BONUS`	Bonus credits

Positive credits = consumed, negative = added.

PDF Tools

Direct PDF manipulation endpoints — no template required. Each call costs 1 credit and accepts the input as either an HTTPS URL (pdf_url) or a base64 string (pdf_base64).

All three return the same payload as POST /v1/pdf/create (URL + filename + remaining credits + expiration).

POST /v1/pdf-tools/merge

Concatenate 2 or more PDFs in the order provided.


curl -X POST https://api.templatefox.com/v1/pdf-tools/merge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs": [
      { "pdf_url": "https://example.com/cover.pdf" },
      { "pdf_url": "https://example.com/report.pdf" },
      { "pdf_url": "https://example.com/appendix.pdf" }
    ],
    "filename": "merged-report"
  }'

Field	Type	Required	Description
`pdfs`	array	Yes	Ordered list (min 2). Each entry has `pdf_url` or `pdf_base64`.
`filename`	string	No	Custom filename without `.pdf`.
`expiration`	integer	No	Signed URL TTL in seconds (60–604800, default 86400).
`export_type`	string	No	`url` (default) or `binary` (returns raw bytes).

POST /v1/pdf-tools/extract-pages

Return a single PDF containing only the selected pages of the input — in the order specified. Use this to split, reorder, or pick pages.


curl -X POST https://api.templatefox.com/v1/pdf-tools/extract-pages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/report.pdf",
    "pages": "1-3, 5, 7-9"
  }'

Field	Type	Required	Description
`pdf_url` or `pdf_base64`	string	Yes	Source PDF (exactly one).
`pages`	string	Yes	1-indexed page selection. Supports ranges + singles, e.g. `1-3, 5, 7-9`. Order is preserved (`5,1,3` outputs those 3 pages in that order).
`filename`, `expiration`, `export_type`	—	No	Same as merge.

POST /v1/pdf-tools/rotate

Rotate every page by a single angle (rotation) or apply a per-page map (page_rotations). Allowed angles: 0, 90, 180, 270. Rotations are cumulative with the page’s existing rotation.


# Rotate every page 90°
curl -X POST https://api.templatefox.com/v1/pdf-tools/rotate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/scan.pdf",
    "rotation": 90
  }'
 
# Rotate page 1 by 90° and page 3 by 180°
curl -X POST https://api.templatefox.com/v1/pdf-tools/rotate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/scan.pdf",
    "page_rotations": { "1": 90, "3": 180 }
  }'

Field	Type	Required	Description
`pdf_url` or `pdf_base64`	string	Yes	Source PDF (exactly one).
`rotation` or `page_rotations`	int / object	Yes	Provide exactly one. `rotation` applies globally; `page_rotations` is a `{ "<page>": <degrees> }` map.
`filename`, `expiration`, `export_type`	—	No	Same as merge.

Jobs

Async-job inspection endpoints (paired with POST /v1/pdf/create-async).

GET /v1/pdf/jobs

List async PDF generation jobs for your team.

No credits consumed.

Parameter	Type	Default	Description
`limit`	integer	20	Max results (1–100).
`offset`	integer	0	Records to skip.
`status`	string	—	Filter by `pending`, `processing`, `completed`, `failed`.


curl "https://api.templatefox.com/v1/pdf/jobs?status=completed&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "jobs": [
    {
      "id": "8e1c8c5d-4a4f-4c1a-9b13-3d2c9c3f4e6a",
      "status": "completed",
      "template_id": "HMQywVpZxqAM",
      "filename": "invoice-001.pdf",
      "result_url": "https://cdn.templatefox.com/generated/abc/invoice-001.pdf",
      "created_at": "2026-04-25T12:00:00Z",
      "completed_at": "2026-04-25T12:00:04Z"
    }
  ],
  "total": 1
}

See GET /v1/pdf/jobs/{job_id} on the Create PDF (Async) page for polling a single job.

Template Versions

GET /v1/templates/{template_id}/versions

List tagged versions of a template. Use this to pin generation to a specific snapshot for reproducibility (e.g. month-end invoice runs always rendered with the version that was live at month-start).

No credits consumed.


curl https://api.templatefox.com/v1/templates/HMQywVpZxqAM/versions \
  -H "x-api-key: YOUR_API_KEY"

Response


{
  "versions": [
    { "id": "v3", "tag": "2026-Q2", "created_at": "2026-04-01T09:00:00Z" },
    { "id": "v2", "tag": "2026-Q1", "created_at": "2026-01-02T09:00:00Z" },
    { "id": "v1", "tag": null,      "created_at": "2025-11-10T09:00:00Z" }
  ]
}

Pass the desired id as the version field on POST /v1/pdf/create or POST /v1/pdf/create-async to render against that version. Omit version to render the live draft.

S3 Storage Integration

Configure your own S3-compatible storage to have generated PDFs uploaded directly to your bucket.

GET /v1/integrations/s3

Get current S3 storage configuration (secret key is masked).


curl https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

Response (configured)


{
  "configured": true,
  "endpoint_url": "https://s3.amazonaws.com",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "bucket_name": "my-pdf-bucket",
  "default_prefix": "invoices/"
}

POST /v1/integrations/s3

Save or update S3 storage configuration.

Field	Type	Required	Description
`endpoint_url`	string	Yes	S3-compatible endpoint URL (must start with `https://`)
`access_key_id`	string	Yes	Access key ID (16-128 characters)
`secret_access_key`	string	No	Secret access key (required on first setup)
`bucket_name`	string	Yes	Bucket name (3-63 characters, lowercase)
`default_prefix`	string	No	Default path prefix for uploaded files


curl -X POST https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://s3.amazonaws.com",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "bucket_name": "my-pdf-bucket",
    "default_prefix": "invoices/"
  }'

DELETE /v1/integrations/s3

Delete S3 storage configuration.


curl -X DELETE https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

POST /v1/integrations/s3/test

Test S3 connection with stored credentials.


curl -X POST https://api.templatefox.com/v1/integrations/s3/test \
  -H "x-api-key: YOUR_API_KEY"

See Create PDF → S3 parameters to use your configured bucket from the generation endpoint.

Error Codes

Status	Code	Description
400	`INVALID_REQUEST`	Missing or invalid request parameters
401	`UNAUTHORIZED`	Invalid or missing API key
402	`INSUFFICIENT_CREDITS`	No credits remaining
403	`FORBIDDEN`	Access denied (not your template)
404	`TEMPLATE_NOT_FOUND`	Template ID not found
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Error response format


{
  "error": "TEMPLATE_NOT_FOUND",
  "message": "Template with ID 'xyz' not found"
}

Rate Limits

Plan	Requests/min	Requests/day
Free	10	100
Pro	60	10,000
Enterprise	Custom	Custom

Rate limit headers included on every response:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704384000