lenz-io Discovery API

openapi: 3.2.0
info:
  title: Lenz — AI Fact-Checking Discovery 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: Discovery
  description: Machine-readable index of the API root.
paths:
  /api/v1/:
    get:
      operationId: apiRoot
      summary: Api Root
      parameters:
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRootOut'
          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: 'Service discovery root — links to docs, OpenAPI spec, and endpoints.


        Returned at ``GET /api/v1/`` so curious humans and probing clients

        get a useful JSON payload instead of a 404.


        **Versions.** default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Discovery
components:
  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.
  schemas:
    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
    ApiRootOut:
      title: ApiRootOut
      type: object
      description: 'The machine-readable index of the API: where the docs, the endpoints, the SDKs and the MCP server are.'
      properties:
        name:
          type: string
        version:
          type: string
        docs_url:
          type: string
        openapi_url:
          type: string
        quickstart_url:
          type: string
        developer_portal_url:
          type: string
        endpoints:
          type: object
          additionalProperties:
            type: string
        sdks:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
        mcp:
          type: object
          additionalProperties:
            type: string
    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
    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
  headers:
    XLenzApiVersion:
      description: The API version this response is in.
      schema:
        type: string
  securitySchemes:
    APIKeyBearerAuth:
      type: http
      scheme: bearer