API overview
This page documents the current /v1 API surface.
The Lumen Index /v1 API provides a structured way to pull external organisational context into your own systems and workflows. It supports portfolio triage and company drill-down so teams can prioritise attention and understand what is changing outside the relationship.
What you can do
Portfolio triage
See where external change is concentrating across a book of accounts.
Use the API to surface which companies are accumulating the most external signals in the window we observe, so your team can prioritise attention and review. This is designed for portfolio-level sense-making: identify outliers, spot concentration, and decide where a closer look is warranted.
Company drill-down
Understand why a specific company is appearing.
When a company rises in a portfolio triage view, the API lets you pull a time-ordered view of observed signals for that company and related entities in its resolved parent scope. This is intended to support fast context gathering: what changed externally, roughly when it changed, and whether the pattern is sustained or recent.
Authentication
All /v1 requests require an API key. Access is provisioned manually today and is typically set up as part of a guided evaluation or integration conversation.
You can pass your key using either header style:
X-API-Key: YOUR_API_KEYAuthorization: Bearer YOUR_API_KEY
Authentication error behavior:
- Missing key returns 401 Unauthorized
- Incorrect key returns 403 Forbidden
Examples
Portfolio triage (ranked company list)
curl -sS "https://thelumenindex.com/v1/portfolio/companies?limit=10" \
-H "X-API-Key: YOUR_API_KEY"
Company drill-down (risk timeline for a company)
curl -sS "https://thelumenindex.com/v1/companies/{company_id}/risk-timeline" \
-H "Authorization: Bearer YOUR_API_KEY"
Endpoint details
GET /v1/portfolio/companies
Purpose: ranked company list for portfolio-level triage.
Parameters:
- as_of (optional): RFC3339 datetime with timezone offset.
- limit (optional): default 50, max 200.
- cursor (optional): offset cursor for pagination.
Response notes:
- Returns pagination metadata and ranked company items.
- risk_mass is a concentration magnitude, not a prediction or verdict.
- Use meta.next_cursor to request the next page.
GET /v1/companies/{company_id}/risk-timeline
Purpose: time-ordered risk context for one company.
Parameters:
- days (optional): default 90, min 1, max 365.
- limit (optional): min 1, max request value 1000, effective cap 200.
Response notes:
- Includes external signals for the requested company and its resolved parent scope when applicable.
- risk.raw_total is the preferred concentration metric.
- risk.score and risk.band are retained for compatibility.
How to interpret risk
Risk, in The Lumen Index, is a way to see where external change is concentrating across the signals we observe. Use it to prioritise attention, add context to account reviews, and prepare for better customer conversations.
Treat it as a portfolio lens rather than an outcome. It helps you understand what is showing up and when, so you can ask better questions and decide what to look into next.
A couple of practical notes: - Coverage reflects the sources we track and what we can observe at a point in time. - A quiet timeline can be normal for many companies. - The value is in pattern and concentration, then human judgement on what to do with it.
Request access
If you want to see how this fits into your presales or post-sales workflow, request access for a short evaluation call. Access is provisioned manually while we keep the surface stable with early teams.