API Reference

Response headers

Every response header Beliq sets, what it means, and which responses carry it.

Beliq reports a lot about each request in response headers, so you can log the audit trail without parsing the body (and read it at all when the body is raw PDF or XML bytes).

Two naming families, and the split is deliberate:

x-beliq-* carries platform facts that hold for any operation: which mode the key ran in, whether a quota unit was refunded.
x-<thing> carries per-document detail from the validation engine: the syntax, the detected profile, the rule versions that ran.

A result header is present only when Beliq has that value to report. Absence means “not reported for this request”, not “empty” or “false”. Treat a missing header as unknown rather than defaulting it, and do not switch logic on an empty string.

On every response

Header	Set on	Meaning
`x-request-id`	Every response, including errors	Request identifier (UUID) for log correlation. Quote it in a support request: it is the fastest way for us to find your call.
`x-beliq-livemode`	Every `/v1/*` response	`true` on a live key, `false` on a test key. Lets an SDK surface sandbox vs. live without decoding the key. See Test mode.

Validation result

Set by /v1/validate, /v1/parse and /v1/generate, each one only when the engine reported that value for your document.

Header	Meaning
`x-syntax`	The document’s format, one of the values of `format` in the validation result object. On `/v1/validate` it is the format the engine detected, and on `/v1/parse` `cii` or `ubl`, the two syntaxes parse reads. On `/v1/generate` it is the detected format, or with `verify: false` the one the request asked for. It is not the profile: a UBL XRechnung and a Peppol BIS Billing 3.0 invoice are both `ubl`.
`x-profile-detected`	Profile inferred from the document’s `CustomizationID` / guideline URN, e.g. `en16931`, `xrechnung`, `peppol-bis`, `facturx:basic`. Absent when the document carries no profile URN.
`x-schematron-version`	Version of CEN’s EN 16931 Schematron, present only where that pack judged the document. Absent for the Factur-X MINIMUM, BASIC WL, BASIC and EXTENDED profiles, which their own Factur-X pack judges in its place, for a document its syntax schema rejected, when the EN 16931 pack ran and gave no verdict, and for the formats validated against a schema only.
`x-validation`	One-line verdict summary, for logs and terminal output: `pass · 0 err · 2 warn`. The counts are the same `errors` and `warnings` arrays the JSON body carries; parse the body, not this string, when you need the detail. On `/v1/generate` with `verify: false` it reads `skipped`, with no counts, since no ruleset ran.
`x-ruleset-sha256`	Single fingerprint of the rule artifacts that judged the document. The header form of the body’s `rulesetSha256`.
`x-ruleset-artifacts`	JSON-encoded array of the component rows behind that fingerprint, `{ key, version, fileSha256 }` each.

x-ruleset-sha256 and x-ruleset-artifacts are the verifiability seal: you can reproduce the fingerprint yourself and cross-check every component against the public catalog. See Verify a hash and GET /v1/rulesets.

Ruleset pinning

Header	Set on	Meaning
`Beliq-Ruleset-Resolved`	`/v1/validate`, when the request sent a `Beliq-Ruleset` header, or sent none and your organisation’s default channel is `previous`	The ruleset selection that actually ran. For a channel: `previous` when a retained ruleset served the request, `latest` when nothing the request resolved had a retained ruleset the channel could reach, either because none is retained or because the authority has made its successor mandatory (which also sets `rulesetFellBack` in the body). For exact pins: the pins as `<artifactKey>:<version>`, joined with commas. See Ruleset versioning.

Generate

Header	Meaning
`x-pdf-kind`	`hybrid` (PDF/A-3 with the legal XML embedded) or `visualization` (human-readable rendering, no embedded XML). See PDF output for why the distinction matters.
`x-version-block`	Compact JSON object with the artifact versions in play for this request. Omitted when empty.

The validation-result headers above are set on /v1/generate too, since generating validates.

Convert

POST /v1/convert documents its own audit headers: x-source-format, x-target-format, x-profile-detected, x-lost-elements, x-lost-elements-count, x-conversion-tools, x-output-envelope and x-version-block. The conversion’s lossiness audit trail lives in those headers because the response body is raw bytes.

Throttling

x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset and Retry-After are documented with the limits themselves, in Authentication and limits.

Quota refunds

Header	Set on	Meaning
`x-beliq-quota-refunded`	Error responses where the failure was on Beliq’s side: an engine outage, a conversion tool failure, a body the engine refused as too large to process on `/v1/generate`, `/v1/validate`, `/v1/parse` or `/v1/convert` (`413`), a PDF that `POST /v1/generate` could not produce or did not return (`500 INTERNAL_ERROR`, `422 PDFA_VIOLATION`), or a `503 DATABASE_UNAVAILABLE` on a request that had spent a quota unit, or may have	`true` if the document’s quota unit was returned to your balance, `false` if the refund was attempted and could not be applied. Absent when no refund was applicable, which is the normal case for an error you caused.

Wrong method

Header	Set on	Meaning
`Allow`	The `404 NOT_FOUND` a known `/v1/*` path answers to a method it does not serve, for an authenticated caller or on a public route such as `/v1/rulesets`	The methods the path accepts, e.g. `POST`.

Reading headers from a browser

A cross-origin browser client can only read response headers a server explicitly exposes. Beliq exposes:

x-request-id, x-syntax, x-profile-detected, x-schematron-version, x-validation, x-ruleset-sha256, x-ruleset-artifacts, x-version-block, x-pdf-kind, x-source-format, x-target-format, x-lost-elements, x-lost-elements-count, x-conversion-tools, x-output-envelope, Beliq-Ruleset-Resolved, Retry-After, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.

x-beliq-livemode, x-beliq-quota-refunded and Allow are not exposed, so read them from a server-side call rather than browser JavaScript.

Example

curl -i -X POST https://api.beliq.eu/v1/validate \
  -H "Authorization: Bearer $BELIQ_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-request-id: 3f2a9c14-7b5e-4d8a-9e01-6c4b2f8a1d33
x-beliq-livemode: true
x-syntax: ubl
x-profile-detected: xrechnung
x-schematron-version: <EN 16931 UBL Schematron version>
x-validation: pass · 0 err · 2 warn
x-ruleset-sha256: 7a590a263701e50305677ec253c61d83a13336c0e8b10b01674573347a52de00
x-ruleset-artifacts: [{"key":"<artifact key>","version":"<version>","fileSha256":"<SHA-256 of the file>"},…]
x-ratelimit-limit: 300
x-ratelimit-remaining: 299
x-ratelimit-reset: 41

CEN’s EN 16931 UBL pack judged this XRechnung invoice, so x-schematron-version carries that pack’s version, 1.3.16. The XRechnung pack’s own version is the body’s ciusVersion.