Glossary

Terms and acronyms used throughout the gpdf-api documentation.

Glossary

Short definitions for terms that come up often in the rest of these docs.

Account

A workspace owned by one Firebase user (uid). Every API key, log entry, usage counter, and license belongs to exactly one account. Created on signup, never auto-created on first request.

API key

A 37-character secret of the form gpdf_ + 32 hex characters. Used as Authorization: Bearer <key> to call the production API. The first 13 characters (gpdf_ followed by 8 hex chars) are a prefix that identifies the key in logs, dashboards, and webhook bodies — the remaining 24 hex characters are the secret. The full raw key is shown once, at creation time. After that we only store an SHA-256 hash.

Addon pack

A one-time purchase of 1,000 extra successful renders, stacked on top of your monthly Pro quota. Stays usable until the end of the current billing period; never carries over.

CJK

Chinese, Japanese, Korean. We bundle Noto Sans CJK weights so the most common scripts render without any setup. See CJK & fonts.

Cloud Run

The runtime gpdf-api is hosted on (Google Cloud, region us-central1). Cloud Run is single-region per service in v1; multi-region failover is on the roadmap.

Data

The variables you pass into a Go template inside your JSON template. Optional. If you pass data, fields like {{.invoice.id}} are interpolated server-side before rendering.

Free / Pro / Self-host

The three subscription tiers. See pricing for the matrix; quotas and limits referenced in error messages always come from the active plan stored on your account.

License key

A different secret of the form gpdfl_…. Issued from the dashboard for self-host customers; verified once on container start by POST /v1/license/verify, then refreshed every 24 h by a heartbeat.

Quota

The monthly cap of successful (HTTP 200) renders for your plan. 4xx and 5xx responses are not counted against quota. Resets the first of each month, UTC 00:00:00.

Rate limit

A short-window cap on how many requests per second a single API key may send (10 r/s on Free, 20 r/s on Pro, ∞ on Self-host). Exceeding it gives a 429 with a Retry-After header. See Rate limits.

Render

A single successful (HTTP 200) response from POST /v1/pdf. One request = one render = one quota unit. Errors do not count.

Request ID

The value of X-Request-Id on every response (also embedded in error bodies as request_id). Quote this when reporting an issue — it lets us look up the exact server-side trace.

Slug

An optional, human-readable label (^[A-Za-z0-9._-]{1,64}$) you can attach to each request. Shows up in your logs and on the dashboard so you can answer "which template was that?" without reading the body. Different keys can use overlapping slugs; the slug is informational only.

Template

The JSON document that describes the PDF you want. The top-level key in your request body. See Document schema for the full grammar.

Watermark

A pale-grey "Generated by gpdf" stamp added to every PDF generated on the Free plan. The watermark sits roughly mid-page in 40 pt grey text — not rotated, deliberately hard to remove without leaving traces. Removed on Pro and Self-host production renders.

µs vs ms

Latency headers (X-GPDF-Latency-Us) report microseconds as a 64-bit integer for accuracy. Most rendering finishes in single-digit milliseconds, but for billing/SLA we keep µs precision so sub-ms renders aren't truncated to zero.

Something unclear or missing on this page?