lenz-io Extract API

openapi: 3.2.0
info:
  title: Lenz — AI Fact-Checking Extract 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: Extract
  description: Pull verifiable claims out of any text. Costs no credits; fair-use cap 1,000/account/day.
paths:
  /api/v1/extract:
    post:
      operationId: extract
      summary: Extract
      parameters:
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractOut'
          x-lenz-versions:
            '2026-10-11':
              $ref: '#/components/schemas/ExtractOut'
            '2026-05-13':
              $ref: '#/components/schemas/ExtractOutLegacy'
          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: 'Extract verifiable claims from arbitrary text.


        Runs the extraction step on its own — no research, no debate, no credit

        charge. Enumerates every distinct major factual

        claim in the input (up to 100), ordered most-check-worthy-first, in

        `claims` (one item for a single claim, `[]` for none). Claims returned

        here verify cleanly when submitted verbatim to `POST /verify`.


        Pass `focus` to narrow the result to the claims you care about — a short

        description such as `"market size, growth and competitors"`, at most 300

        characters. A focus selects from the claims the extractor found and

        nothing else: it cannot add a claim, reword one, reorder them, change the

        language, or change what counts as a claim. Ordering stays

        most-check-worthy-first.


        `status` is one of:


        - `ready` — claims were found (and, with a `focus`, at least one matched).

        - `no_checkable_claim` — no claim in the input could be checked against

        public evidence.

        - `no_match` — claims were found but none fall within your `focus`. The

        unfocused list is never substituted; widen the focus and call again.


        `text` can also be a single public web page URL (http or https, nothing

        else in the field). Lenz reads the page, or a YouTube video''s transcript,

        and extracts the claims from its first 50,000 characters. Pages behind a

        login (Facebook, Instagram, Threads, LinkedIn) can''t be read. A URL call

        typically takes 5-40 seconds, so give it a 90-second client timeout (SDK

        2.13 and later do). A page that cannot be read answers 502

        `extraction_failed`; when the services that read pages are down, 503

        `upstream_unavailable` with `Retry-After`. Neither uses a unit of the

        daily cap.


        Pass `locate: true` to keep only the claims that can be traced directly

        back to your text, and get each claim''s `positions`: the passages that

        make it, with `start` / `end` offsets into `text` as you

        sent it, in Unicode code points. A claim the text does not make, or makes

        with a different figure, is left out, so the list says what the author

        wrote and nothing else. Offsets count code points, not UTF-16 units: in

        JavaScript slice with `Array.from(text).slice(start, end).join('''')`.

        For a URL the offsets are `null` and each position carries its passage.

        Locating adds a few seconds, never more than 20. If it cannot run,

        every `positions` is `null` and the claims are returned unfiltered. `locate`

        defaults to `false`.


        Accepts up to 50,000 characters (longer input is truncated). Free for

        API-key holders, capped at 1000 calls per ACCOUNT per day (resets at

        00:00 UTC) regardless of input length — a focused call costs the same one

        unit as an unfocused one. The cap is shared across all of the account''s

        keys.


        **Versions.** 200: `2026-10-11` receives `ExtractOut`, `2026-05-13` receives `ExtractOutLegacy`; 422: `2026-10-11` receives `ValidationErrorOut`, `2026-05-13` receives `ValidationErrorOutLegacy`; default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Extract
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractIn'
        required: true
      security:
      - APIKeyBearerAuth: []
      x-codeSamples:
      - lang: Python
        source: "from lenz_io import Lenz\n\nclient = Lenz(api_key=\"lenz_...\")\nout = client.extract(text=\"Coffee causes cancer and the earth is flat.\")\n# Add language=\"es\" to return extracted claims in Spanish.\nfor c in out.claims:\n    print(c.claim)\n"
      - lang: TypeScript
        source: "import { Lenz } from \"lenz-io\";\n\nconst client = new Lenz({ apiKey: \"lenz_...\" });\nconst out = await client.extract({\n  text: \"Coffee causes cancer and the earth is flat.\",\n});\n(out.claims ?? []).forEach(c => console.log(c.claim));\n"
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
    ExtractedEntityOut:
      properties:
        name:
          default: ''
          title: Name
          type: string
        type:
          default: ''
          title: Type
          type: string
      title: ExtractedEntityOut
      type: object
    PositionOut:
      properties:
        start:
          anyOf:
          - type: integer
          - type: 'null'
          description: 'Where the passage starts in `text` as you sent it, in Unicode code points (not UTF-16 units or bytes). Half-open with `end`. `null` when `text` was a URL: the page is not returned, so there is nothing to index, and `text` carries the passage instead.'
          title: Start
        end:
          anyOf:
          - type: integer
          - type: 'null'
          description: Where the passage ends, exclusive; `null` as for `start`.
          title: End
        text:
          anyOf:
          - type: string
          - type: 'null'
          description: The passage itself, as it appears in the text. `null` on a citation position, whose row already carries the statement.
          title: Text
      required:
      - start
      - end
      - text
      title: PositionOut
      type: object
    ExtractOutLegacy:
      description: 'The /extract body as `2026-05-13` sends it: the top claim in `claim`, the whole list in `identified_claims` (`[]` for one claim), `locations` with `locate: true`, and `not_a_claim` where the current version says `no_checkable_claim`.'
      properties:
        status:
          type: string
          enum:
          - ready
          - not_a_claim
          - no_match
        domain:
          default: ''
          title: Domain
          type: string
        key_entities:
          default: []
          items:
            $ref: '#/components/schemas/ExtractedEntityOut'
          title: Key Entities
          type: array
        presumed_intent:
          default: ''
          title: Presumed Intent
          type: string
        original_input:
          default: ''
          title: Original Input
          type: string
        language:
          anyOf:
          - type: string
          - type: 'null'
          description: 'The language the claims are written in, as an ISO 639-1 code: the one you sent, `en` when you sent none, or the detected one when you asked for detection. Pass it on to `/assess` or `/verify` to keep a chain in one language. Absent on a replay of a response stored before this field existed.'
          title: Language
        claim:
          type: string
        identified_claims:
          type: array
          items:
            type: string
        candidate_claims:
          type: array
          items:
            type: string
          maxItems: 0
          description: Always `[]`.
        locations:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/ClaimLocationOut'
          - type: 'null'
      title: ExtractOutLegacy
      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
    ExtractIn:
      properties:
        text:
          description: 'The document to extract claims from. Up to 50,000 characters; longer input is truncated. Or a single public web page URL (http or https, nothing else in the field): Lenz reads the page, or a YouTube video''s transcript, and extracts the claims from its first 50,000 characters.'
          title: Text
          type: string
        language:
          default: ''
          description: 'ISO 639-1 code for the language of the emitted claims. Omitted: English. `auto`: detected from the submitted text (the same rule as lenz.io: a supported language, or English when the text is short, English or in a language we do not answer in). A code always wins. Responses carry the code that was used, never `auto`. For a `text` that is one URL, `auto` reads the page.'
          title: Language
          type: string
        focus:
          default: ''
          description: 'Optional. Narrows the result to the claims this describes, e.g. "market size, growth and competitors". At most 300 characters — a longer focus is rejected, never truncated. A focus can only select from the claims the extractor found: it cannot add a claim, reword one, reorder them, or change what counts as a claim. When nothing matches, `status` is `no_match` and `claims` is empty; the unfocused list is never substituted.'
          maxLength: 300
          title: Focus
          type: string
        locate:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Optional, default `false`. When `true`, only claims that could be traced directly back to your text are returned, and each claim's `positions` say where in the text it is made. A claim found nowhere in the text, or found with a different figure, is left out; so is a list that ends up empty, which answers `no_checkable_claim`. Adds a few seconds, never more than 20. If the claims cannot be located, every `positions` is `null` and the list is returned unfiltered.
          title: Locate
      required:
      - text
      title: ExtractIn
      type: object
    ExtractedClaimOut:
      properties:
        claim:
          title: Claim
          type: string
        positions:
          anyOf:
          - items:
              $ref: '#/components/schemas/PositionOut'
            type: array
          - type: 'null'
          description: 'Only with `locate: true`: every place the text makes this claim, in text order, at most 10. `null` when `locate` was not set or the claims could not be located.'
          title: Positions
      required:
      - claim
      title: ExtractedClaimOut
      type: object
    ClaimLocationOut:
      properties:
        claim:
          description: The claim, exactly as it appears in the claim list it belongs to.
          title: Claim
          type: string
        positions:
          anyOf:
          - items:
              $ref: '#/components/schemas/PositionOut'
            type: array
          - type: 'null'
          description: Every place the text makes the claim, in text order, at most 10. `null` only when this claim could not be placed (on /extract every returned claim was placed).
          title: Positions
      required:
      - claim
      - positions
      title: ClaimLocationOut
      type: object
    ExtractOut:
      description: 'The claims found in the submitted text.


        `claims` lists every claim found, most check-worthy first: one item for a

        single claim, `[]` when there is none.


        `status` is `ready` when claims were found, `no_checkable_claim` when no

        claim in the text could be checked against public evidence, and

        `no_match` when a `focus` was given and no claim falls within it.


        With `locate: true`, only claims traced back to the text are listed, and

        each claim''s `positions` give the passages that make it.'
      properties:
        status:
          default: ready
          enum:
          - ready
          - no_checkable_claim
          - no_match
          title: Status
          type: string
        claims:
          default: []
          items:
            $ref: '#/components/schemas/ExtractedClaimOut'
          title: Claims
          type: array
        domain:
          default: ''
          title: Domain
          type: string
        key_entities:
          default: []
          items:
            $ref: '#/components/schemas/ExtractedEntityOut'
          title: Key Entities
          type: array
        presumed_intent:
          default: ''
          title: Presumed Intent
          type: string
        original_input:
          default: ''
          title: Original Input
          type: string
        language:
          anyOf:
          - type: string
          - type: 'null'
          description: 'The language the claims are written in, as an ISO 639-1 code: the one you sent, `en` when you sent none, or the detected one when you asked for detection. Pass it on to `/assess` or `/verify` to keep a chain in one language. Absent on a replay of a response stored before this field existed.'
          title: Language
      title: ExtractOut
      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