API v1

Lumen API Reference

A read-only REST API for pulling your Lumen data - projects, scans, prompts, web mentions, website health, and time series - into dashboards, warehouses, and your own tools. All endpoints return JSON. The base URL is your Lumen host plus /api/v1.

Authentication

Every endpoint except the /api/v1 index requires an API key. Keys are configured on the server with the LUMEN_API_KEY environment variable (or several, comma-separated, in LUMEN_API_KEYS).

Send the key on every request, either way works:

  • Authorization: Bearer <key>
  • x-api-key: <key>

A missing or wrong key returns 401. If no key is configured on the server at all, the API returns 503.

Quick start

# list your projects and their latest scores
curl -H "Authorization: Bearer $LUMEN_API_KEY" \
  https://your-lumen-host/api/v1/projects

# latest scan for a project, with the raw AI answers
curl -H "Authorization: Bearer $LUMEN_API_KEY" \
  "https://your-lumen-host/api/v1/projects/{id}/scans/latest?include=responses"

Projects

GET/api/v1/projects

All projects: brand, competitors, engines, prompt counts, paused state.

Each project includes latestScan with its score, mention rate, share of voice, sentiment, and top citations.

GET/api/v1/projects/{id}

One project by id, same shape as the list entry.

The project with its latest scan summary, or 404.

Prompts

GET/api/v1/projects/{id}/prompts

The tracked prompts with tags, campaign, and active state.

?activetrue returns only scanned prompts, false only parked ones

Array of { id, text, tags, active, campaign }.

Scans

GET/api/v1/projects/{id}/scans

Scan history, newest first. Summaries only - scores, engine rollups, top citations.

?limitpage size, default 20, max 100
?offsetskip N scans for paging

{ total, offset, limit, scans: [...] } - no raw responses at this level.

GET/api/v1/projects/{id}/scans/{scanId}

Full detail for one scan. Use latest as the scanId to get the most recent run.

?includeresponses adds every raw AI answer with per-brand hits and citations

The scan with brand rollups, engine scores, all citations, opportunities, and cost. Raw responses only when requested - they are large.

Web data

GET/api/v1/projects/{id}/mentions

Off-site web mentions of the brand (press, reviews, forums, directories), newest first.

?limitmax mentions returned, default 50, max 300

{ summary, mentions, runs } - a sentiment/type rollup, the mentions with source and snippet, and the monitor's run history.

GET/api/v1/projects/{id}/website-health

The latest AI-readiness audit, duplicate-content scan, and readability scan.

Audit checks and score, duplicate clusters and canonical issues, per-page readability scores, and all recommendations. Crawled page bodies are not included.

Boosters & actions

GET/api/v1/projects/{id}/boosters

The recommendations backlog and action-board state.

?statustodo, in_progress, approved, or done
?includecontent adds saved briefs and generated drafts

Array of boosters with target prompt, priority, status, assignee, why-it-matters evidence, and applied date.

Time series

GET/api/v1/projects/{id}/timeseries

Per-prompt appearance-rate history across every scan, plus proven-lift attribution.

{ series, attributions } - one series per active prompt (oldest to newest), and before/after deltas for each applied action that targets a prompt.

Errors

Errors come back as { "error": "..." } with the matching status: 401 bad key, 404 unknown project or scan, 400 invalid parameter, 503 API not configured. The API is read-only - it never changes project data, and OAuth credentials are never exposed through it.

Back to Help Center