API overview
This page documents the current /v1 API surface.
The Lumen Index /v1 API provides a structured way to pull public events tied to your accounts into your own systems and workflows. It supports portfolio triage and company drill-down so teams can review layoffs, breaches, vulnerabilities, leadership changes, funding activity, and other meaningful company changes beside the relationship data they already have.
What you can do
Portfolio triage
See which accounts may deserve a closer review.
Use the API to surface which companies are showing the most outside activity in the window we observe, so your team can prioritize 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 events 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 portfolio ranking
These rankings show where the most meaningful outside activity is clustering across the accounts you monitor. Use them to prioritize attention, add context to account reviews, and prepare for better customer conversations.
Treat the ranking 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 judgment 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.