v1 · stable

API reference

A REST API for building on top of the Lumen client platform. JSON in, JSON out. Every endpoint uses cursor pagination, ETags, and idempotency keys for writes.

Base URLhttps://api.lumen.consulting

Authentication

POST/v1/auth/session

Public

Exchange credentials for a bearer token.

Request

{
  "email": "ava@northwind.io",
  "password": "•••••••••"
}

Response · 200 OK

{
  "token": "lc_live_...",
  "user": {
    "id": "u_client",
    "role": "client",
    "name": "Ava Whitfield"
  },
  "expiresAt": "2026-07-20T18:00:00Z"
}

DELETE/v1/auth/session

Bearer

Invalidate the current session.

Response · 200 OK

{ "ok": true }

Service requests

GET/v1/requests

Bearer

List requests, scoped by role.

Response · 200 OK

{
  "data": [
    {
      "id": "r_001",
      "service": "Strategic Advisory",
      "status": "meeting_scheduled",
      "priority": "high",
      "summary": "Fund needs a portfolio-level thesis refresh…",
      "createdAt": "2026-07-16T09:12:00Z"
    }
  ],
  "meta": { "total": 6, "page": 1 }
}

POST/v1/requests

Bearer

Create a new service request. The response includes the auto-generated summary and tags.

Request

{
  "service": "AI Advisory",
  "budget": "$50k – $100k",
  "timeline": "This quarter",
  "problem": "We want to deploy AI triage across our clinic network …"
}

Response · 200 OK

{
  "id": "r_010",
  "status": "new",
  "summary": "Client is exploring ai advisory: We want to deploy…",
  "tags": ["ai", "healthcare", "governance"]
}

GET/v1/requests/{id}

Bearer

Fetch a single request.

Response · 200 OK

{ "id": "r_001", "status": "in_review", "…": "…" }

PATCH/v1/requests/{id}

Bearer

Update status, priority, or problem statement.

Request

{ "status": "in_progress" }

Response · 200 OK

{ "id": "r_001", "status": "in_progress" }

DELETE/v1/requests/{id}

Bearer

Archive a request. Administrators only.

Response · 200 OK

{ "ok": true }

Meetings

GET/v1/meetings

Bearer

Upcoming and past meetings.

Response · 200 OK

{ "data": [{ "id": "m1", "topic": "…", "at": "2026-07-21T16:00:00Z", "durationMin": 60 }] }

POST/v1/meetings

Bearer

Book a meeting on an engagement.

Request

{
  "requestId": "r_001",
  "at": "2026-07-24T15:00:00Z",
  "durationMin": 45,
  "topic": "Kickoff — thesis pressure-test"
}

Response · 200 OK

{ "id": "m_042", "at": "2026-07-24T15:00:00Z" }

DELETE/v1/meetings/{id}

Bearer

Cancel a scheduled meeting.

Response · 200 OK

{ "ok": true }

Engagement notes

GET/v1/notes?requestId={id}

Bearer

List internal notes for an engagement. Consultants and admins only.

Response · 200 OK

{ "data": [{ "id": "n1", "content": "…", "createdAt": "2026-07-17T10:00:00Z" }] }

POST/v1/notes

Bearer

Add an internal note.

Request

{ "requestId": "r_001", "content": "Kickoff scheduled. Need two operator refs." }

Response · 200 OK

{ "id": "n_10", "createdAt": "2026-07-18T09:00:00Z" }

Analytics

GET/v1/analytics/overview

Bearer

Firm-wide KPIs. Administrators only.

Response · 200 OK

{
  "totalRequests": 128,
  "conversionRate": 0.61,
  "avgCycleDays": 14,
  "bookingsTrailing12M": [42, 55, 61, 58, 72, 84, 79, 91, 96, 103, 112, 118]
}