API reference

Public Delivery API — endpoints, parameters and headers

A compact, readable reference for the Public Delivery API: three read-only GET endpoints serve already-published legal texts as JSON, an HTML fragment or a PDF. The full OpenAPI 3.1 specification is also available interactively below.

Download openapi.jsonSame spec the interactive reference renders — served as a static file.

Overview

Read-only delivery of published legal texts

The Public Delivery API is the read-only interface for retrieving already-published legal texts and embedding them in websites, SaaS apps, shops and transactional emails. It serves only approved, live versions — write operations and unpublished drafts are not reachable through it. Every request addresses a site and a document type and returns the artifact as a JSON envelope, an HTML fragment or a PDF.

Formats

The same published version is available in three artifact forms:

JSON: Structured envelope with sections, typed blocks and metadata — for your own template and rendering logic.
HTML fragment: Sanitized HTML for direct embedding in pages, app footers, checkout steps or emails.
PDF artifact: Approved version as a PDF for archiving or attaching to order and contract confirmations.

Endpoint groups

Three GET endpoints over a shared path. {siteID} addresses the site, {typeCode} the document type (e.g. privacy, terms, imprint).

GET/v1/delivery/sites/{siteID}/documents/{typeCode}
JSON envelope
Live document as a structured JSON envelope with sections, blocks and version metadata.
GET/v1/delivery/sites/{siteID}/documents/{typeCode}/html
HTML fragment
Live document as a sanitized HTML fragment for direct embedding.
GET/v1/delivery/sites/{siteID}/documents/{typeCode}/pdf
PDF artifact
Live document as a PDF artifact with Content-Disposition for download or attachment.

Only GET is supported. All three endpoints share the same path/query parameters and caching headers.

Parameters & delivery context

Path parameters

siteID: Required. Site identifier from the backoffice. No workspace or tenant reference is exposed publicly.
typeCode: Required. Stable document type code, e.g. privacy, terms, imprint.

Conditional-request header

If-None-Match: Conditional GET. If the supplied value matches the current ETag, the API responds 304 Not Modified with no body.

Query parameters

locale: Locale code such as de-DE — selects the language version of the published document.
market: Market code such as DE — selects the market-specific projection.
profile: Site profile code such as B2C — selects the profile-specific projection.
version: Pins a specific live version (positive integer). On a mismatch the API responds 409 and names the currently live version.
effective_at: Resolves the version that was live at this point in time — answers “which version applied back then?”.
api: Optional contract pin. Only v1 is currently accepted.

Response headers & caching

Responses are cache-friendly and carry version and validation headers:

ETag: Strong validator derived from version number and projection — for conditional GETs via If-None-Match.
Cache-Control: Cache directive; short TTL for JSON/HTML, longer TTL for PDF, each with stale-while-revalidate.
Last-Modified: Timestamp of the most recently built projection (RFC 7231).
X-Termshelf-Document-Version: Numeric version of the row served — on 409 the currently live version.
X-Termshelf-Published-At: ISO-8601 timestamp of the document's first publication.
Content-Disposition: PDF only. Forces download with a deterministic filename.
Content-Length: PDF only. Byte size of the artifact.
X-Correlation-Id: Per-request correlation id — useful when filing issues.

Status & error codes

Errors arrive as a stable JSON envelope { error: { code, message } }. The key codes:

Status	Code
200	—	Success. Artifact in the requested format with caching headers.
304	—	Conditional-GET match. No body, only ETag and caching headers.
400	invalid_request / unsupported_version	Malformed request — e.g. an invalid parameter or unsupported api pin.
403	entitlement_required	The resolved plan does not entitle the requested artifact form.
404	not_found	No live projection for the requested site/type/context tuple.
405	method_not_allowed	A method other than GET on a delivery path.
409	version_mismatch	?version=N does not match the live version; the response names the currently live version.
429	quota_exceeded / rate_limited	Per-IP rate limit or plan quota exceeded.
500	internal	Unexpected server error while reading or rendering.
503	pdf_unavailable	PDF endpoint only. PDF delivery is not configured for this installation.

Typical integration paths

Website legal page: Embed the HTML fragment server-side into the legal page; cache it via ETag.
SaaS app footer / sign-up: Show the current version in the footer or sign-up flow — JSON for your own layout, HTML for direct embedding.
Shop checkout / order confirmation: Pin and reference the version that applied at contract conclusion.
Transactional email: Embed HTML sections directly into the mail, or render JSON into your own template.
PDF attachment: Fetch the approved PDF artifact and attach it to order, contract or sign-up emails.

Integration checklist

1Determine the site and profile (siteID, optionally profile/market).
2Choose the document type (typeCode).
3Choose the format (JSON, HTML or PDF).
4Decide on a versioning strategy (live, version or effective_at).
5Account for caching (ETag, If-None-Match, Cache-Control).
6Handle errors (403, 404, 409, 429 cleanly).
7Have legal content reviewed/approved externally.

Interactive OpenAPI 3.1 specification

The full spec with every schema, example and a “Try it” view. Identical to the static openapi.json above.