Authentication

Create a key in Settings → API. It is shown once, so store it somewhere safe. Every key is scoped to a single organization and can be revoked at any time.

curl https://getlens.xyz/api/public/v1/workspaces \
  -H "Authorization: Bearer lens_sk_your_key_here"

Rate limits

Per key, per minute. Endpoints that spend AI credits, such as starting an Index run or generating a memo, use the stricter allowance.

Plan	Standard	AI endpoints
Starter	60 / min	5 / min
Pro	300 / min	20 / min
Institutional	1000 / min	60 / min

Endpoints

get/workspaces

List workspaces

Deals, matters or projects, depending on your vertical.

Parameters

limit	query	—
offset	query	—
status	query	—
vertical	query	—
archived	query	—

Responses

200A page of workspaces.

{
  "data": [
    {
      "id": "3f1c9b0e-11a4-4f2e-9c7d-8b2a5e6d4c31",
      "name": "Project Atlas — Bolt-on acquisition",
      "description": "Mid-market logistics carve-out",
      "vertical": "pe",
      "status": "due_diligence",
      "archived": false,
      "created_at": "2026-07-02T09:14:00.000Z",
      "updated_at": "2026-08-01T16:40:12.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

post/workspaces

Create a workspace

Request body

{
  "name": "Project Meridian",
  "vertical": "pe",
  "description": "Secondary buyout, French logistics"
}

Responses

201Created.

400Validation error.

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

get/workspaces/{id}

Get a workspace

Parameters

id*

path

—

Responses

200The workspace.

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

404No such resource in your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

get/index-runs

List Index runs

Cells are omitted; fetch a single run to get extracted values.

Parameters

workspace_id	query	—
status	query	—
limit	query	—
offset	query	—

Responses

200A page of Index runs.

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

get/index-runs/{id}

Get an Index run with its results

Parameters

id*

path

—

Responses

200The run, including every extracted cell.

{
  "data": {
    "id": "9c2f7a41-5d3b-4a80-b1e6-77a0c9d2f118",
    "workspace_id": "3f1c9b0e-11a4-4f2e-9c7d-8b2a5e6d4c31",
    "name": "Q3 diligence extraction",
    "status": "completed",
    "columns": [
      {
        "id": "col_1",
        "name": "Change of control clause",
        "prompt": "Does this contract contain a change of control provision?",
        "type": "text"
      }
    ],
    "document_ids": [
      "b7d4…"
    ],
    "cells": [
      {
        "document_id": "b7d4…",
        "column_id": "col_1",
        "value": "Yes — clause 14.2 requires written consent of the lender.",
        "status": "completed",
        "citations": []
      }
    ],
    "created_at": "2026-07-20T11:00:00.000Z",
    "updated_at": "2026-07-20T11:06:31.000Z"
  }
}

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

404No such resource in your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

post/index-runs/{id}/run

Start an Index run

Asynchronous. Consumes AI cell credits. Poll the returned job for completion.

Parameters

id*

path

—

Responses

202Run queued.

{
  "data": {
    "job_id": "c81e…",
    "index_run_id": "9c2f…",
    "status": "queued"
  }
}

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

402Plan document cap or monthly cell credits exhausted.

404No such resource in your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

409The run is already in progress.

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

get/knowledge

Query the Knowledge Base

Entities extracted across every document in the organization. Requires the Pro or Institutional plan.

Parameters

search	query	Substring match on entity name.
types	query	Comma-separated, e.g. `company,person`.
limit	query	—

Responses

200Matching entries.

{
  "data": [
    {
      "id": "e3a1…",
      "type": "company",
      "name": "Meridian Logistics SAS",
      "description": "Target company, French 3PL operator",
      "mention_count": 42,
      "document_count": 7,
      "sample_citation": "Meridian Logistics SAS operates 14 depots across France…",
      "first_seen": "2026-07-02T10:22:14.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "total": 1
  }
}

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

402Starter plan — upgrade required.

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

post/memos

Generate a synthesis memo

Asynchronous and AI-billed. Returns a job id; the finished markdown lands in the job result. Requires the Pro or Institutional plan.

Request body

{
  "workspace_id": "3f1c9b0e-11a4-4f2e-9c7d-8b2a5e6d4c31",
  "sections": [
    "Executive Summary",
    "Key Risks",
    "Valuation"
  ],
  "language": "en",
  "detail_level": "standard"
}

Responses

202Memo generation queued.

{
  "data": {
    "job_id": "f0a9…",
    "status": "queued",
    "poll_url": "/api/public/v1/jobs/f0a9…"
  }
}

400Validation error.

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

402Plan or AI credit limit.

404No such resource in your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}

get/jobs/{id}

Poll an asynchronous job

Parameters

id*

path

—

Responses

200Job state. `result` is populated once `status` is `completed`.

{
  "data": {
    "id": "f0a9…",
    "type": "generate_ic_memo",
    "status": "completed",
    "result": {
      "markdown": "## Executive Summary\n\nMeridian Logistics is…"
    },
    "error": null,
    "created_at": "2026-08-01T12:00:00.000Z",
    "completed_at": "2026-08-01T12:03:44.000Z"
  }
}

401Missing, unknown, revoked or expired API key.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required"
  }
}

404No such resource in your organization.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

429Rate limit exceeded for this key. Check the `Retry-After` header.

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Too many requests. Please slow down."
  }
}