API versions

Lenz versions the shape of its responses by date. Choose a version with the X-Lenz-API-Version request header. Every response names the version it used in its own X-Lenz-API-Version header.

Contents

Version	Shape
`2026-10-11`	Current. One name for each field, status and error code across every endpoint.
`2026-05-13`	The original shape. Served to integrations built before 2026-10-11.

Which version a request gets #

Lenz uses the first rule that applies:

The header you send. Any date before 2026-10-11 gets the original shape.
The official Lenz clients (the Python and Node SDKs, the CLI, the n8n node, the Zapier app, the MCP connector and the Google Docs add-on) get the version their release was built against.
Your account. Accounts created on or after 2026-10-09 19:36 UTC get 2026-10-11. Older accounts get 2026-05-13.

Code that works today keeps working without a change. To deploy code written for the original shape on a newer account, send X-Lenz-API-Version: 2026-05-13.

Move to 2026-10-11 #

Add X-Lenz-API-Version: 2026-10-11 to one request and update the fields below. The header applies per request, so you can move one call at a time.

What	2026-05-13	2026-10-11
Input with nothing checkable	`not_a_claim` (/extract, /verify), `no_claim` (/assess, /review)	`no_checkable_claim` everywhere
An error response	varies; `detail` can be a list; some have no `code`	`{detail, code}`; a 422 adds `errors[]`
Something that failed inside a response (an /assess row, a verification, a review, a webhook)	`error`, `error_code`, `failure_reason` at different places	`status: "failed"` and `failure: {code, detail, hint, failure_class, retryable, docs_url}`
An /assess row with no verdict	`verdict: "Error"`, `confidence: "low"`	`status: "failed"`, `verdict` and `confidence` `null`
Link to the docs in an error	`doc_url`	`docs_url`
Seconds to wait before retrying	`reset_in_seconds`, `retry_after_seconds`	`retry_after`
A citation check's 402	`remaining` and `credits_remaining` (the same number)	`remaining`
Claims found by /extract	`claim` + `identified_claims` (empty for one) + `locations`	`claims: [{claim, positions}]`, always a list
Unchecked claims on an /assess or review row	`identified_claims`	`more_claims`
Claim text in receipts and `needs_input` options	`claim_text`, `text`	`claim`
`candidate_claims`	always `[]`	removed
When a verification finished	`modified_at` (null on the same day)	`completed_at`
Receipts	200 for a repeated /verify; `chain_id` on /verify	202 for every receipt; no `chain_id`
Review limit flags	`claim_limit_reached` (>=), `citation_limit_reached` (>)	`claim_limit_exceeded`, `citation_limit_exceeded`: true when some were left out
/me/usage	per-capability blocks, `credits.bonus`, `quota_resets_at`	the `credits` pool, `costs`, `cost_options`
A run you cancelled (`POST /verify/{task_id}/cancel`, `/reviews/{id}/cancel`, `/citechecks/{id}/cancel`)	`status: "failed"` with `failure_class: "cancelled"`; `verification.failed`, `review.failed`, `citecheck.failed`	`status: "cancelled"`; `verification.cancelled`, `review.cancelled`, `citecheck.cancelled`
`webhook_url: ""`	/verify: your key's default; /review, /citecheck: no webhook	no webhook, on every endpoint (omit it for your key's default)
Webhooks	verification events flat, no `event_id`; review events nested	one envelope: `event`, `event_id`, the id, `status`, and the body polling returns

Both versions have status on /assess (ok, error, and not_a_claim / no_checkable_claim). Every response and webhook names its version in the X-Lenz-API-Version header.

no_checkable_claim: the input states nothing that can be checked against public evidence (an opinion, a forecast, a claim about a private person, a statement whose only source is unidentified). hint says which.

The API reference describes 2026-10-11: a field 2026-05-13 still sends under an older name is listed as deprecated beside the current one, and where a shape differs, the operation names the ...Legacy component that version receives.

Webhooks #

The version applies to responses and webhooks alike: a webhook uses the version of the request that asked for it. In 2026-10-11 every event carries event_id (the same on every retry, so you can deduplicate), and a failure carries the same failure block as polling: code, detail, hint, failure_class, retryable and docs_url.

A run you cancel (POST /verify/{task_id}/cancel, or the review and citation-check equivalents) ends as status: "cancelled". In 2026-10-11 the webhook is verification.cancelled, review.cancelled or citecheck.cancelled, and polling reads cancelled too. A request made in 2026-05-13 keeps status: "failed" with failure_class: "cancelled", and its webhook is the matching *.failed event. A cancelled run is not charged.