lenz-io Ask API

openapi: 3.2.0
info:
  title: Lenz — AI Fact-Checking Ask 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: Ask
  description: Ask follow-up questions grounded on an existing verification.
paths:
  /api/v1/ask/{verification_id}:
    get:
      operationId: getAskHistory
      summary: Get Ask History
      parameters:
      - in: path
        name: verification_id
        schema:
          title: Verification Id
          type: string
        required: true
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskHistoryOut'
          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: 'Get ask history and remaining quota for a verification.


        **Versions.** default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Ask
      security:
      - APIKeyBearerAuth: []
    delete:
      operationId: resetAsk
      summary: Reset Ask
      parameters:
      - in: path
        name: verification_id
        schema:
          title: Verification Id
          type: string
        required: true
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OkOut'
          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: 'Delete all ask messages for this user on a verification.


        **Versions.** default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Ask
      security:
      - APIKeyBearerAuth: []
    post:
      operationId: sendAsk
      summary: Send Ask
      parameters:
      - in: path
        name: verification_id
        schema:
          title: Verification Id
          type: string
        required: true
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskMessageOut'
          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: 'Send a question and get an expert response.


        The reply (``content`` field on the response) is plain text with a

        small markdown subset baked in by the chat model:


        - ``**bold**`` and ``*italic*``

        - ``- `` or ``* `` bullet lists

        - Blank-line paragraph breaks; single newlines inside a paragraph

        mean line break

        - ``label`` links, only ever to one of the verification''s

        sources: any other link is reduced to its label before the reply

        is returned


        The model only produces these — no headings, no tables, no code

        blocks. Pass the reply through any markdown library or display it

        verbatim.


        Documented at https://lenz.io/docs/quickstart#ask-reply-format.


        **Versions.** 422: `2026-10-11` receives `ValidationErrorOut`, `2026-05-13` receives `ValidationErrorOutLegacy`; default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Ask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskIn'
        required: true
      security:
      - APIKeyBearerAuth: []
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
    AskHistoryOut:
      title: AskHistoryOut
      type: object
      description: The follow-up conversation on a verification, oldest message first.
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AskMessageOut'
        exchanges_used:
          type: integer
        exchange_limit:
          type: integer
        can_send:
          type: boolean
      required:
      - messages
      - exchanges_used
      - exchange_limit
      - can_send
    AskMessageOut:
      title: AskMessageOut
      type: object
      description: One message of a follow-up conversation; `POST /ask/{verification_id}` answers with the reply.
      properties:
        role:
          type: string
          enum:
          - user
          - expert
        content:
          type: string
          description: Markdown.
        created_at:
          type: string
      required:
      - role
      - content
      - created_at
    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
    OkOut:
      title: OkOut
      type: object
      description: The deletion or reset was done.
      properties:
        ok:
          type: boolean
          const: true
      required:
      - ok
    AskIn:
      properties:
        message:
          description: The follow-up question. Maximum 500 characters.
          title: Message
          type: string
        language:
          default: ''
          description: 'ISO 639-1 code for the language of the answer. Omitted, or `auto`: the verification''s own language (English for older ones); the question is never language-detected. A code overrides it.'
          title: Language
          type: string
      required:
      - message
      title: AskIn
      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.
    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
  headers:
    XLenzApiVersion:
      description: The API version this response is in.
      schema:
        type: string
  securitySchemes:
    APIKeyBearerAuth:
      type: http
      scheme: bearer