Conventions

Rules that apply across the whole API, so each endpoint page doesn't have to repeat them.

Coordinates

Positions are PDF points (1/72 inch) with a top-left origin, Y down, the same coordinate space a visual editor uses:

• x: 72, y: 72 is one inch from the top-left corner of the page.
• A US Letter page is 612 × 792 points; A4 is 595 × 842 points.
• Every field is a box: x, y, width, height, plus a 1-based page number (clamped to the document's page count).

There is nothing to flip or convert: place a field where you see it.

Naming

• Field and property names are snake_case (client_name, page_count).
• Path segments are kebab-case (/v1/templates/{templateId}/generate-batch).
• Timestamps are ISO 8601 UTC (2026-08-01T17:20:04.211Z).

Content types

• Request bodies are application/json.
• Successful generation returns either the PDF bytes (application/pdf) or a JSON result with a download URL, your choice via response.mode (Generating documents).
• Every error is RFC 9457 application/problem+json (Errors).

Request bodies are strictly validated: unknown fields are rejected with 400 UNKNOWN_FIELD rather than silently ignored, so typos surface immediately.

Pagination

List endpoints take limit (1–100, default 25) and an opaque cursor; responses carry next_cursor, which is null on the last page.

curl -s "https://api.pdfs.ecourtdate.com/v1/templates?limit=50" \
  -H "x-api-key: $API_KEY"
# → { "templates": [...], "next_cursor": "eyJ..." }

curl -s "https://api.pdfs.ecourtdate.com/v1/templates?limit=50&cursor=eyJ..." \
  -H "x-api-key: $API_KEY"

Cursors are opaque: pass them back exactly as received. A malformed cursor returns 400 INVALID_CURSOR.

Common headers

Header	Direction	Purpose
x-api-key	request	Authentication (Authentication)
X-On-Behalf-Of	request	Actor recorded in the audit trail; required on writes
Idempotency-Key	request	Safe retries (Idempotency)
Idempotent-Replay	response	Present (true) when the response is a replay
Location	response	URL of a newly created resource (201/202)
X-Warning-Count, X-Warnings	response	Rendering warnings on binary responses (Warnings)

Limits and lifecycles

Limit	Value
Fields per document	200
Pages per document	100
Base PDF upload	20 MB
Asset upload (PNG/JPEG)	2 MB
HTML document content	1 MB
HTML field content	64 KB
Batch items per job	200
Download URL validity	1 hour (re-sign any time via GET /v1/outputs/{outputId})
Generated output retention	~20 hours
Job status retention	48 hours
Base-PDF upload window	15 minutes

Throttling

Clients should be prepared for HTTP 429 responses under load: back off and retry with exponential backoff and jitter. Pair retries with an Idempotency-Key so they are always safe. Treat sustained throttling as a signal to batch work: the batch endpoint renders up to 200 documents from a single request.

Open sets

Error codes, warning codes, field types, and merge-tag types are open sets: new values may be added without notice as the API grows. Handle unknown values gracefully. See Versioning.