lenz-io Account API

openapi: 3.2.0
info:
  title: Lenz — AI Fact-Checking Account 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: Account
  description: Your credit balance, the price list, and rate-limit usage.
paths:
  /api/v1/me/usage:
    get:
      operationId: getUsage
      summary: Me Usage
      parameters:
      - $ref: '#/components/parameters/XLenzApiVersion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeUsageOut'
          x-lenz-versions:
            '2026-10-11':
              $ref: '#/components/schemas/MeUsageOut'
            '2026-05-13':
              $ref: '#/components/schemas/MeUsageOutLegacy'
          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: 'Return the calling account''s credit balance and what it can still buy.


        **``credits`` is the balance.** One pool funds every billable capability,

        at the weights in ``costs`` — today ``verify`` 10, ``assess`` 1, ``ask`` 1.

        It has two buckets: the monthly allowance for the current ``plan``, which

        resets at ``resets_at``, and non-expiring ``extra`` credits from grants and

        top-ups, spent only once the allowance is gone. ``remaining`` is the sum,

        and is what a call is actually checked against.


        The current shape is ``credits``, ``costs``, ``cost_options``, ``extract``,

        ``plan``, ``plan_label`` and ``has_webhook_secret``. Callers on API version

        ``2026-05-13`` also get the deprecated fields below, which are kept for

        them: ``credits.bonus``, ``quota_resets_at`` (the same

        as ``credits.resets_at``) and the ``verify`` / ``ask`` / ``assess`` blocks.


        ``credits.bonus`` (``2026-05-13`` only) is the deprecated old name of

        ``credits.extra``, the same number. Read ``extra``.


        ``plan`` is the stable slug to branch on; ``plan_label`` is the same tier

        as display copy ("Pro"). Two fields rather than one humanised

        string, so a reworded label cannot break a client comparing tiers.

        The Pro plan''s ``plan`` is ``pro``; it read ``developer`` before

        2026-09-15, while ``plan_label`` already read "Pro".


        **The per-capability blocks are deprecated** (``2026-05-13`` only). ``verify`` / ``ask`` /

        ``assess`` are **projections** of that one pool into each capability''s own

        unit — "how many of these could I still make" — not separate allowances.

        Spending on one moves all of them, and they are floor divisions, so a

        verify block ticks once per 10 credits spent anywhere.


        Read ``credits`` and ``costs`` instead; the blocks and the per-block

        ``credits`` alias stay for ``2026-05-13`` callers. Derive them::


        remaining = credits.remaining // costs[capability]

        total = credits.total // costs[capability]

        used = total - remaining


        Two capabilities at the same price emit identical blocks — ``ask`` and

        ``assess`` are both 1 credit — which is the clearest sign the shape

        describes an allowance that no longer exists.


        ``bonus`` in each block is ``credits.extra`` in that capability''s unit. The

        older key ``credits`` is its deprecated alias, kept for the same callers.


        ``costs`` is one entry per capability at its DEFAULT price. Prices that

        depend on a request parameter live in ``cost_options``, nested capability

        → parameter → value — ``{"verify": {"depth": {"standard": 10, "low": 5}}}``.

        Two maps rather than a flat one with a ``verify_low`` key, so a future

        tuning parameter nests instead of adding an entry that reads like a fifth

        capability. Every capability in ``cost_options`` also appears in ``costs``

        at its default, so reading only ``costs`` is always correct.


        ``extract`` is free at the pool (``costs.extract`` is 0) and is bounded by

        a per-account daily fair-use cap instead, reported separately here and

        rejected with 429 rather than 402.


        **Versions.** 200: `2026-10-11` receives `MeUsageOut`, `2026-05-13` receives `MeUsageOutLegacy`; default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`.'
      tags:
      - Account
      security:
      - APIKeyBearerAuth: []
      x-codeSamples:
      - lang: Python
        source: 'from lenz_io import Lenz


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

          u = client.usage()

          # One credit pool funds every call; `costs` is the price list.

          print(u.credits.remaining, "credits left", u.costs)

          # The same balance in one capability''s unit: credits.remaining // costs[capability].

          print(u.credits.remaining // u.costs["verify"], "verify calls left")

          print(u.credits.remaining // u.costs["assess"], "assess calls left")

          print(u.credits.extra, "of them extra credits (grants and top-ups, never expiring)")

          '
      - lang: TypeScript
        source: 'import { Lenz } from "lenz-io";


          const client = new Lenz({ apiKey: "lenz_..." });

          const u = await client.usage();

          console.log(`${u.credits.remaining} credits left`, u.costs);

          // The same balance in one capability''s unit: credits.remaining / costs[capability].

          console.log(`${Math.floor(u.credits.remaining / u.costs["verify"])} verify calls left`);

          console.log(`${Math.floor(u.credits.remaining / u.costs["assess"])} assess calls left`);

          '
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
    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
    MeUsageQuotaOut:
      description: "DEPRECATED. One capability's share of the pool, projected into its unit.\n\nSent only to API version ``2026-05-13`` callers and kept for them, with\nthe per-block ``credits`` alias below. Read\n``MeUsageOut.credits`` and ``MeUsageOut.costs`` instead and do the\ndivision — it is one line, and it is the same one this block does::\n\n    remaining = credits.remaining // costs[capability]\n    total     = credits.total     // costs[capability]\n    used      = total - remaining\n\nThese are **projections, not allowances**. Every billable capability draws\non the single balance in ``MeUsageOut.credits``, at the weight in\n``MeUsageOut.costs``; this block answers \"how many ``/verify`` calls could\nI still make if I spent everything on them\". Spending on any capability\nmoves every block, and the division floors — a ``verify`` block whose\nweight is 10 ticks once per 10 credits spent anywhere.\n\nThey predate the pool, when each really was its own allowance, and that is\nwhy the current shape leaves them out: two capabilities at the same price emit\nbyte-identical objects (``ask`` and ``assess`` are both 1 credit today),\nso the shape suggests a per-capability allowance that no longer exists.\n\n``bonus`` is ``MeUsageOut.credits.extra``, the non-expiring balance, in\nthis capability's unit.\n``quota_used`` is derived as ``quota_total - quota_remaining``, so\n``used + remaining == total`` always holds.\n\n``credits`` is a DEPRECATED alias of ``bonus``, kept for the same callers;\nread ``MeUsageOut.credits`` for the pool. It never meant the pool — before the pool existed it\nmeant this capability's one-off top-up balance, which is exactly what\n``bonus`` now reports."
      properties:
        quota_used:
          default: 0
          title: Quota Used
          type: integer
        quota_total:
          default: 0
          title: Quota Total
          type: integer
        quota_remaining:
          default: 0
          title: Quota Remaining
          type: integer
        bonus:
          default: 0
          title: Bonus
          type: integer
        credits:
          default: 0
          title: Credits
          type: integer
        remaining:
          default: 0
          title: Remaining
          type: integer
      title: MeUsageQuotaOut
      type: object
    MeUsageOutLegacy:
      description: '`/me/usage` as `2026-05-13` sends it: the current body plus `quota_resets_at`, `credits.bonus` and the `verify` / `ask` / `assess` blocks, every one always present.'
      properties:
        plan:
          default: free
          title: Plan
          type: string
        plan_label:
          default: Free
          title: Plan Label
          type: string
        quota_resets_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Quota Resets At
        credits:
          $ref: '#/components/schemas/MeUsageCreditsOut'
        costs:
          additionalProperties:
            type: integer
          title: Costs
          type: object
        cost_options:
          additionalProperties:
            additionalProperties:
              additionalProperties:
                type: integer
              type: object
            type: object
          default: {}
          title: Cost Options
          type: object
        verify:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
        ask:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
        assess:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
        extract:
          $ref: '#/components/schemas/MeUsageExtractOut'
        has_webhook_secret:
          default: false
          title: Has Webhook Secret
          type: boolean
      required:
      - credits
      - costs
      - extract
      title: MeUsageOutLegacy
      type: object
    MeUsageOut:
      description: 'The calling account''s credit balance, and what it can still buy.


        ``credits`` is the balance and ``costs`` is the price list. Those two,

        plus ``cost_options``, are the whole contract for a new integration. The

        current shape is ``credits``, ``costs``, ``cost_options``, ``extract``,

        ``plan``, ``plan_label`` and ``has_webhook_secret``.


        Callers on API version ``2026-05-13`` also get the DEPRECATED fields, kept

        for them: the ``verify`` / ``ask`` / ``assess`` blocks

        (projections of that same pool into each capability''s unit) with their

        ``credits`` alias, ``credits.bonus`` and ``quota_resets_at``.


        ``extract`` is free at the pool (``costs.extract`` is 0) and carries a

        per-account daily fair-use cap instead; it rejects with 429, not 402.


        The Pro plan''s ``plan`` is ``pro`` since 2026-09-15; it was ``developer``

        before. ``plan_label`` reads "Pro" either way.'
      properties:
        plan:
          default: free
          title: Plan
          type: string
        plan_label:
          default: Free
          title: Plan Label
          type: string
        quota_resets_at:
          anyOf:
          - type: string
          - type: 'null'
          deprecated: true
          title: Quota Resets At
          description: Sent only to callers on `2026-05-13`; use `credits.resets_at`.
        credits:
          $ref: '#/components/schemas/MeUsageCreditsOut'
        costs:
          additionalProperties:
            type: integer
          title: Costs
          type: object
        cost_options:
          additionalProperties:
            additionalProperties:
              additionalProperties:
                type: integer
              type: object
            type: object
          default: {}
          title: Cost Options
          type: object
        verify:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
          deprecated: true
          description: Sent only to callers on `2026-05-13`; divide `credits` by `costs`.
        ask:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
          deprecated: true
          description: Sent only to callers on `2026-05-13`; divide `credits` by `costs`.
        assess:
          anyOf:
          - $ref: '#/components/schemas/MeUsageQuotaOut'
          - type: 'null'
          deprecated: true
          description: Sent only to callers on `2026-05-13`; divide `credits` by `costs`.
        extract:
          $ref: '#/components/schemas/MeUsageExtractOut'
        has_webhook_secret:
          default: false
          title: Has Webhook Secret
          type: boolean
      required:
      - credits
      - costs
      - extract
      title: MeUsageOut
      type: object
    MeUsageCreditsOut:
      description: 'The account''s credit balance — the one pool every capability spends.


        Two buckets: the monthly allowance for the current plan (resets at

        ``resets_at``) and non-expiring ``extra`` credits from grants and top-ups,

        which are spent only once the allowance is gone. ``remaining`` is the sum

        and is what a call is checked against.


        ``bonus`` is a DEPRECATED alias of ``extra`` (the balance''s name until

        2026-09-15); read ``extra``. It stays for existing callers. It was renamed because the balance holds top-ups you paid for as

        well as grants.'
      properties:
        total:
          default: 0
          title: Total
          type: integer
        used:
          default: 0
          title: Used
          type: integer
        remaining:
          default: 0
          title: Remaining
          type: integer
        extra:
          default: 0
          title: Extra
          type: integer
        bonus:
          default: 0
          deprecated: true
          title: Bonus
          type: integer
          description: Sent only to callers on `2026-05-13`; use `extra`.
        resets_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Resets At
      title: MeUsageCreditsOut
      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
    MeUsageExtractOut:
      description: 'Daily ``/extract`` usage (rate-limited per day, not credit-based).


        ``calls_today`` is the ACCOUNT''s counter, shared across all of its keys;

        ``unlimited`` reports whether the CALLING key bypasses the cap.'
      properties:
        calls_today:
          default: 0
          title: Calls Today
          type: integer
        daily_limit:
          default: 0
          title: Daily Limit
          type: integer
        unlimited:
          default: false
          title: Unlimited
          type: boolean
      title: MeUsageExtractOut
      type: object
  headers:
    XLenzApiVersion:
      description: The API version this response is in.
      schema:
        type: string
  securitySchemes:
    APIKeyBearerAuth:
      type: http
      scheme: bearer