API reference

REST API reference

Base URL: https://api.lumen.com · All endpoints require a Bearer token · All bodies and responses are JSON.

Prefer a machine-readable spec (e.g. for codegen, or pointing an AI coding assistant at it)? The full OpenAPI 3.0 spec (also at /openapi.json) is served directly by the API itself, so it never drifts from what's actually deployed.

Profiles

POST/v1/profiles/lookup

Kick off a business profile resolve by name + country. Requires the profiles:write scope. This is asynchronous — a cold resolve runs the full discovery → crawl → extraction → reconciliation pipeline and can take from several seconds to a few minutes, so this endpoint returns immediately and you poll for the result (see below).

Request body

Field	Type	Required	Description
`businessName`	string	✓	Company name.
`countryHint`	string	✓	ISO 3166-1 alpha-2 country code
`mode`	"preview" \| "full"	—	preview = fast partial data; full = complete profile (default: full)
`localityHint`	string	—	City or region hint
`force_refresh`	boolean	—	Bypass the cached profile (if any) and run a fresh resolve

Request body (verified)

json

{
  "businessName": "Blispa Barbershop & Spa",
  "countryHint": "KE",
  "mode": "full"
}

Response — 202 Accepted

json

{
  "businessId": "616de6d1-7732-4ece-a551-5e3187923aa8",
  "pollUrl": "/v1/profiles/616de6d1-7732-4ece-a551-5e3187923aa8",
  "status": "processing"
}

Poll pollUrl (i.e. GET /v1/profiles/{businessId}) every few seconds until it stops returning 202. See that endpoint below for the shape of the finished result.

GET/v1/profiles/{id}

Poll for a resolve's result, or re-fetch an already-completed profile by its business ID — the same ID returned by POST /v1/profiles/lookup. Requires profiles:read.

Query parameters

Parameter	Type	Description
`include_attributions`	boolean	Include per-field source attribution in the response

Response by state

HTTP status	Meaning
`202`	Still resolving — { "businessId": "…", "status": "processing" }. Poll again shortly.
`200`	Resolve finished — { "profile": { /* see Data model */ }, "profileId": "…" }
`500`	Resolve finished but failed — { "error": { "code": "INTERNAL_ERROR", "message": "…" } }

POST/v1/profiles/{id}/refresh

Force a full re-generation of a profile, bypassing all caches. Counts against your lookup quota.

POST/v1/profiles/{id}/corrections

Submit a data correction for a specific field. Corrections are reviewed and applied to future profile generations.

Request body

Field	Type	Required	Description
`field_path`	string	✓	Dot-path of the field to correct (e.g. "contact.website")
`correct_value`	any	✓	The correct value as JSON
`explanation`	string	—	Optional human-readable explanation

GET/v1/profiles/{id}/attribution/{fieldPath}

Return per-field source attribution — which sources contributed to a specific field and at what confidence.

Not yet available in production — this currently returns 501 NOT_IMPLEMENTED. Every field in the main profile response already carries its own metadata.sources and metadata.confidence inline (see Data model), which covers most attribution needs today.

POST/v1/profiles/{id}/ask

Ask a natural language question about a profile. Requires the ask_lumen feature on your plan.

Request body

Field	Type	Required	Description
`question`	string	✓	Natural language question, max 1000 characters
`conversation_history`	string[]	—	Previous turns for multi-turn conversations

POST/v1/profiles/lookup/stream

Stream profile generation as Server-Sent Events. Each event is a JSON object. The stream ends with an event: done sentinel.

Event types

type	Description
`source_discovered`	A data source URL was found
`source_completed`	A source finished extraction
`section_completed`	A profile section (e.g. contact) is ready
`partial_profile`	Preview-quality partial profile available
`complete`	Full profile is ready
`error`	A non-fatal error occurred

GET/v1/profiles

List profiles in the account, paginated.

Query parameters

Parameter	Type	Description
`cursor`	string	Pagination cursor from a previous response
`limit`	number	Items per page (default 20, max 100)
`q`	string	Filter by name or domain

Lookup notifications

Get called back when a lookup finishes instead of polling — see Lookup notifications for the full guide (payload shape, signature verification). Requires webhooks:manage. Covers only profile.resolved / profile.failed — not a general eventing system.

POST/v1/webhooks/subscriptions

GET/v1/webhooks/subscriptions

List your registered URLs.

DELETE/v1/webhooks/subscriptions/{id}

Remove a registered URL.

GET/v1/webhooks/deliveries

List recent delivery attempts across your subscriptions.

GET/v1/webhooks/deliveries/{id}

Inspect one delivery attempt.

POST/v1/webhooks/deliveries/{id}/retry

Manually retry one delivery.

GET/v1/webhooks/dead-letter

List deliveries that exhausted all automatic retries.

POST/v1/webhooks/dead-letter/{id}/replay

Re-attempt a dead-lettered delivery.

POST/v1/webhooks/test

Send a synthetic test event to a URL before relying on it.

Billing

POST/v1/billing/portal

Create a short-lived Paddle customer portal session. Returns links to manage payment method and cancel a subscription — both handled on Paddle's own hosted pages.

Response

json

{
  "overview_url": "https://customer-portal.paddle.com/...",
  "cancel_url": "https://customer-portal.paddle.com/.../cancel",
  "update_payment_method_url": "https://customer-portal.paddle.com/.../payment-method"
}

GET/v1/billing/invoices

List the account's billing/invoice history.

GET/v1/billing/invoices/{id}/pdf

Get a short-lived (~1 hour) signed PDF URL for one invoice.

Usage & account

GET/v1/usage

Full usage metrics for the current billing period, including per-resource used/limit/remaining.

GET/v1/usage/summary

Condensed summary view matching the dashboard's usage page.

GET/v1/usage/timeseries

Daily usage breakdown for the current billing period.

GET/v1/account

Account details including tier, features enabled, and support info.

POST/v1/account/keys

Create a new API key. The rawKey in the response is shown exactly once.

GET/v1/account/keys

List all active API keys (raw keys are never returned — only metadata).

DELETE/v1/account/keys/{id}

Revoke an API key immediately. Requests using the revoked key fail within 60 seconds.

Health checks

GET/health

Liveness check. Returns 200 OK if the gateway process is running. No auth required.

GET/ready

Readiness check. Returns 200 OK when all downstream services are reachable. No auth required.