lenz-io Library API

openapi: 3.2.0
info:
  title: Lenz — AI Fact-Checking Library API
  version: 1.0.0
  description: '# Four API calls and one to run them


    A research-depth ladder: find claims, judge fast, prove deep, citecheck; `/review` runs them all. - `POST /extract` — enumerate every major verifiable claim in a document (up to 100, most check-worthy first, inputs to 50k chars), or in a public web page given its URL; an optional `focus` narrows the list to the claims you care about, and `locate: true` keeps only the claims traced back to the text, with where each is made. Costs no credits; fair-use cap 1,000/account/day. - `POST /assess` — a fast panel verdict, with the pages the reviewers looked at, typically 10-25s. Sync, 1 credit per claim. Send one text in `claim`, or a list of up to 20 in `claims` — one row per claim, same order, all checked in parallel. A text that makes more claims than one call checks gets the most check-worthy checked and the rest back as `more_claims`, free, to send on. - `POST /verify` — a full investigation, with verified citations, in ~90s. Async, 10 credits — or 5 with `depth: "low"`, a shallower check that comes back sooner. - `POST /citecheck` — does each cited source say what the text attributes to it: send pairs of a statement and its URL or DOI, or a whole text. Async; 1 credit per checked citation, refunded when a citation could not be checked (guide). - `POST /review` — the extract → assess → verify ladder on a whole draft, returning the issues with suggested rewrites in 2-4 min. Async, 1 credit per claim assessed + 10 (5 at `depth: "low"`) per claim verified. With `escalate.max_citations` (0-20, default 0) it also checks whether each source the draft cites says what the draft attributes to it, at 1 credit per checked citation (one that could not be checked is refunded) (guide). `more_claims` and `more_citations` list what the review found and did not check, at no cost; send them to `/assess` and `/citecheck` to check the rest. - Also `POST /ask/{id}` — ask follow-up questions grounded on a verification. ## Built for teams whose AI output is async or document-shaped


    Legal-memo generators, AI deep-research, due-diligence platforms, vertical agents producing structured deliverables, "report-as-a-service" companies. `/assess` opens the door to sync UX too — fast enough to gate a chat completion or a UI submit. ## API versions


    Lenz versions the shape of its responses by date: send `X-Lenz-API-Version: 2026-10-11` to choose this shape. This reference describes `2026-10-11`. A field `2026-05-13` still sends under an older name is listed `deprecated` beside the current one, and where its shape differs, the operation names the `...Legacy` component it receives (`x-lenz-versions` on the response). Every response carries `X-Lenz-API-Version`, naming the version it is in. Which version a request gets without the header, and what changed: https://lenz.io/docs/api-versions. ## Install the SDK


    ```bash

    pip install lenz-io # Python

    npm install lenz-io # Node / TypeScript

    ```


    Source on GitHub: lenz-io-python · lenz-io-node. ## The canonical integration: one /review call


    ```python

    from lenz_io import Lenz

    client = Lenz(api_key="lenz_...")


    # Extract, assess, and verify the doubtful claims in one call (async, 2-4 min)

    draft = "The EU AI Act took effect in March 2024. It sorts AI systems into four risk tiers."

    review = client.review_and_wait(text=draft)

    for i in review.issues:

    print(i.verdict, i.claim, i.suggested_rewrite)

    ```


    The default policy: a quick verdict on every claim (up to 20), and the deep check on the rows whose quick verdict is `False`, `Mostly False`, `Mixed` or `No Public Record`, or whose confidence is `low`, up to five. Change it in `escalate`. To deep-check the rows the cap left out (`escalation.disposition == "cap"`), send them to `/verify/batch`. A resend with the same `Idempotency-Key` within 24 hours returns the same review; a new key is a new review.'
  termsOfService: https://lenz.io/terms
servers:
- url: https://lenz.io
  description: Production
tags:
- name: Library
  description: Browse the public catalog of verifications. No API key required.
paths:
  /api/v1/library:
    get:
      operationId: listLibrary
      summary: List Library
      parameters:
      - in: query
        name: domain
        schema:
          default: ''
          title: Domain
          type: string
        required: false
      - in: query
        name: entity
        schema:
          default: ''
          title: Entity
          type: string
        required: false
      - in: query
        name: search
        schema:
          default: ''
          title: Search
          type: string
        required: false
      - in: query
        name: sort
        schema:
          default: recent
          title: Sort
          type: string
        required: false
      - in: query
        name: page
        schema:
          default: 1
          title: Page
          type: integer
        required: false
      - in: query
        name: curated
        schema:
          default: ''
          title: Curated
          type: string
        required: false
      - in: query
        name: verdict
        schema:
          default: ''
          title: Verdict
          type: string
        required: false
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationListOut'
          x-lenz-versions:
            '2026-10-11':
              $ref: '#/components/schemas/VerificationListOut'
            '2026-05-13':
              $ref: '#/components/schemas/VerificationListOutLegacy'
          headers:
            X-Lenz-API-Version:
              $ref: '#/components/headers/XLenzApiVersion'
        '422':
          description: A field to fix
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorOut'
          x-lenz-versions:
            '2026-10-11':
              $ref: '#/components/schemas/ValidationErrorOut'
            '2026-05-13':
              $ref: '#/components/schemas/ValidationErrorOutLegacy'
          headers:
            X-Lenz-API-Version:
              $ref: '#/components/headers/XLenzApiVersion'
        default:
          description: An error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
          x-lenz-versions:
            '2026-10-11':
              $ref: '#/components/schemas/ErrorOut'
            '2026-05-13':
              $ref: '#/components/schemas/ErrorOutLegacy'
          headers:
            X-Lenz-API-Version:
              $ref: '#/components/headers/XLenzApiVersion'
      description: 'Search and browse the public catalog of verified claims.


        Returns paginated results from the Lenz Library. Only publicly

        published verifications are included.


        **Sort options:** `recent`, `most_true`, `most_untrue`,

        `relevance` (only when `search` is provided), and `random`.


        **`curated`** restricts results to one or more named curated collections,

        comma-separated. Currently supported: `trivia` (the LLM-curated,

        trivia-worthy pool behind the open-source quiz demo).


        **`verdict`** filters to one or more verdict labels, comma-separated

        (e.g. `True,False`). Labels: `True`, `Mostly True`, `Mixed`,

        `Mostly False`, `False`.


        **Versions.** 200: `2026-10-11` receives `VerificationListOut`, `2026-05-13` receives `VerificationListOutLegacy`; 422: `2026-10-11` receives `ValidationErrorOut`, `2026-05-13` receives `ValidationErrorOutLegacy`; default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Library
      x-codeSamples:
      - lang: Python
        source: "from lenz_io import Lenz\n\nclient = Lenz()  # no api_key needed for the public library\npage = client.library.list(page=1, sort=\"recent\")\nfor v in page.items:\n    print(v.claim, \"→\", v.verdict)\n"
      - lang: TypeScript
        source: 'import { Lenz } from "lenz-io";


          const client = new Lenz();  // no api_key needed

          const page = await client.library.list({ page: 1, sort: "recent" });

          page.items.forEach(v => console.log(v.claim, "→", v.verdict));

          '
components:
  schemas:
    EntityRef:
      description: 'An entity (person, place, organization, concept) referenced in the

        submitted claim.


        ``qid`` is the Wikidata Q identifier (e.g. ``Q42`` for Douglas Adams)

        when Lenz resolved the entity against its own entity catalog; ``null``

        otherwise. Customers can join on ``qid`` to their own Wikidata-indexed

        corpus, or hit the Wikidata API directly for richer metadata.'
      properties:
        name:
          title: Name
          type: string
        qid:
          anyOf:
          - type: string
          - type: 'null'
          title: Qid
      required:
      - name
      title: EntityRef
      type: object
    ValidationErrorItemOut:
      title: ValidationErrorItemOut
      type: object
      description: 'One field to fix: where (`loc`, as the request names it), what (`msg`) and the kind (`type`).'
      properties:
        loc:
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
        ctx:
          type: object
          description: Pydantic's context for the error (the limit that was exceeded, ...).
      required:
      - loc
      - msg
      - type
      additionalProperties: true
    VerificationListOut:
      description: Paginated verifications response. Shared by /library + /verifications.
      properties:
        items:
          items:
            $ref: '#/components/schemas/VerificationListItemOut'
          title: Items
          type: array
        total:
          title: Total
          type: integer
        page:
          title: Page
          type: integer
        page_size:
          title: Page Size
          type: integer
      required:
      - items
      - total
      - page
      - page_size
      title: VerificationListOut
      type: object
    VerificationListOutLegacy:
      description: The ``2026-05-13`` paginated list (see ``VerificationListItemOutLegacy``).
      properties:
        items:
          items:
            $ref: '#/components/schemas/VerificationListItemOutLegacy'
          title: Items
          type: array
        total:
          title: Total
          type: integer
        page:
          title: Page
          type: integer
        page_size:
          title: Page Size
          type: integer
      required:
      - items
      - total
      - page
      - page_size
      title: VerificationListOutLegacy
      type: object
    ErrorOut:
      title: ErrorOut
      type: object
      description: 'Every error response: `detail` is one sentence on what happened and `code` names it (every code is listed at https://lenz.io/docs/errors#codes). A field you must fix adds `errors`. Waits are `retry_after` (seconds, the same value as the `Retry-After` header); a docs link is `docs_url`. Some codes add their own fields: a 402 carries `upgrade_url`, `wall_id`, `cost` and the balance, a 429 `limit` and `upgrade_url`.'
      properties:
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItemOut'
        hint:
          type: string
        docs_url:
          type: string
        retry_after:
          type: integer
        upgrade_url:
          type: string
        wall_id:
          type: string
        remaining:
          type: integer
        credits_remaining:
          type: integer
        cost:
          type: integer
        requested:
          type: integer
        resets_at:
          type: string
        limit:
          type: integer
        scope:
          type: string
        task_id:
          type: string
        purged_at:
          anyOf:
          - type: string
          - type: 'null'
        doc_url:
          type: string
          deprecated: true
          description: Sent only to callers on `2026-05-13`; use `docs_url`.
        reset_in_seconds:
          type: integer
          deprecated: true
          description: Sent only to callers on `2026-05-13`; use `retry_after`.
        retry_after_seconds:
          type: integer
          deprecated: true
          description: Sent only to callers on `2026-05-13`; use `retry_after`.
        error:
          type: string
          deprecated: true
          description: Sent only to callers on `2026-05-13`; use `code`.
      required:
      - detail
      - code
      additionalProperties: true
    VerificationListItemOut:
      description: 'Single item in a list of verifications: ``GET /verifications``

        (authed-owner listing) and ``GET /library`` (public catalog), one shape.


        Slim shape: no ``url`` (customers reference claims by

        ``verification_id``), no ``visibility``.'
      properties:
        verification_id:
          title: Verification Id
          type: string
        claim:
          title: Claim
          type: string
        domain:
          title: Domain
          type: string
        entities:
          default: []
          items:
            $ref: '#/components/schemas/EntityRef'
          title: Entities
          type: array
        verdict:
          default: ''
          title: Verdict
          type: string
        confidence:
          default: low
          title: Confidence
          type: string
        lenz_score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lenz Score
        key_finding:
          default: ''
          title: Key Finding
          type: string
        executive_summary:
          default: ''
          title: Executive Summary
          type: string
        suggested_rewrite:
          anyOf:
          - type: string
          - type: 'null'
          description: 'A suggested rewrite of `claim` that this verification''s findings support, to use in place of the original sentence. It has not been verified itself: before using it, review it or run it through `/verify`. `null` for a true claim, when no correction is established, and on verifications that predate the field. On every verification, single or listed; not on `/assess` rows.'
          title: Suggested Rewrite
        created_at:
          default: ''
          title: Created At
          type: string
        completed_at:
          default: ''
          description: 'When the verification finished (ISO 8601). Always set on a completed verification; a rerun moves it. API version `2026-05-13` sends `modified_at` instead: this time, but only when it falls on a later UTC calendar day than `created_at`, else null.'
          title: Completed At
          type: string
        language:
          title: Language
          type: string
      required:
      - verification_id
      - claim
      - domain
      - language
      title: VerificationListItemOut
      type: object
    ValidationErrorOutLegacy:
      title: ValidationErrorOutLegacy
      type: object
      properties:
        detail:
          anyOf:
          - type: string
          - type: array
            items:
              type: object
              additionalProperties: true
        code:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  anyOf:
                  - type: string
                  - type: integer
              msg:
                type: string
        hint:
          type: string
        doc_url:
          type: string
        unrecognized_fields:
          type: array
          items:
            type: string
        error:
          type: string
      required:
      - detail
      description: A 422 as `2026-05-13` sends it. `detail` is a sentence, or (for a field of the wrong type or a missing one) the list of validation errors, each `{type, loc, msg}`, with `hint`, `doc_url` and `unrecognized_fields` beside it. `code` is on some (an /assess `claims` list, /review, /citecheck); `errors`, each `{loc, msg}`, only on /review and /citecheck.
    VerificationListItemOutLegacy:
      description: 'The ``2026-05-13`` list item: ``modified_at`` (set only when completed

        on a later UTC day) where ``VerificationListItemOut`` has

        ``completed_at``. It is the shape a caller on that version receives.'
      properties:
        verification_id:
          title: Verification Id
          type: string
        claim:
          title: Claim
          type: string
        domain:
          title: Domain
          type: string
        entities:
          default: []
          items:
            $ref: '#/components/schemas/EntityRef'
          title: Entities
          type: array
        verdict:
          default: ''
          title: Verdict
          type: string
        confidence:
          default: low
          title: Confidence
          type: string
        lenz_score:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Lenz Score
        key_finding:
          default: ''
          title: Key Finding
          type: string
        executive_summary:
          default: ''
          title: Executive Summary
          type: string
        suggested_rewrite:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: 'A suggested rewrite of `claim` that this verification''s findings support, to use in place of the original sentence. It has not been verified itself: before using it, review it or run it through `/verify`. `null` for a true claim, when no correction is established, and on verifications that predate the field. On every verification, single or listed; not on `/assess` rows.'
          title: Suggested Rewrite
        created_at:
          default: ''
          title: Created At
          type: string
        modified_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Modified At
        language:
          title: Language
          type: string
      required:
      - verification_id
      - claim
      - domain
      - language
      title: VerificationListItemOutLegacy
      type: object
    ErrorOutLegacy:
      title: ErrorOutLegacy
      type: object
      description: 'An error as `2026-05-13` sends it: `detail`, and `code` on most (not on a 401, a 404 or 405 outside /review and /citecheck, a malformed body, or an idempotency conflict); `doc_url`, `reset_in_seconds` (the /extract daily cap), `retry_after_seconds` (a review or citation check already running) and `error` (a repeat of some codes) where the current version has other names.'
      properties:
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItemOut'
        hint:
          type: string
        docs_url:
          type: string
        retry_after:
          type: integer
        upgrade_url:
          type: string
        wall_id:
          type: string
        remaining:
          type: integer
        credits_remaining:
          type: integer
        cost:
          type: integer
        requested:
          type: integer
        resets_at:
          type: string
        limit:
          type: integer
        scope:
          type: string
        task_id:
          type: string
        purged_at:
          anyOf:
          - type: string
          - type: 'null'
        doc_url:
          type: string
        reset_in_seconds:
          type: integer
        retry_after_seconds:
          type: integer
        error:
          type: string
      required:
      - detail
      additionalProperties: true
    ValidationErrorOut:
      title: ValidationErrorOut
      type: object
      description: 'A 422: `detail` names the first field to fix by its public name (`claims[2].text: ...`), `code` says what kind of problem it is (`validation_error`, `blank_input`, `unsupported_language`, `too_many_items`, ...), and `errors` lists every field. `unrecognized_fields` lists keys the endpoint does not take.'
      properties:
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItemOut'
        hint:
          type: string
        docs_url:
          type: string
        unrecognized_fields:
          type: array
          items:
            type: string
      required:
      - detail
      - code
      additionalProperties: true
  parameters:
    XLenzApiVersion:
      name: X-Lenz-API-Version
      in: header
      required: false
      schema:
        type: string
        examples:
        - '2026-05-13'
      description: The API version to answer in, as a date. A date before `2026-10-11` (or a value that is not a date) gets `2026-05-13`. See https://lenz.io/docs/api-versions.
  headers:
    XLenzApiVersion:
      description: The API version this response is in.
      schema:
        type: string
  securitySchemes:
    APIKeyBearerAuth:
      type: http
      scheme: bearer