Data API

The Lucent Data API is a REST surface for reading Lucent data and updating issue status from scripts, dashboards, and services.

Base URL

https://app.lucenthq.com

All endpoints below are relative to this base URL.

Authentication

Send a bearer token in the Authorization header:

curl -sS https://app.lucenthq.com/api/v1/issues?limit=10 \
  -H "Authorization: Bearer luc_api_..."

The Data API accepts API keys and OAuth access tokens:

API keys that start with luc_api_
OAuth access tokens that start with luc_oat_

Legacy static keys with the luc_mcp_ prefix continue to work. Read endpoints require read:lucent. Updating issue status requires write:issues. Create API keys in Organization settings → MCP. Choose Allow issue status updates when the key needs to call PATCH /api/v1/issues/{issueId}. OAuth clients should follow the OAuth reference and request only the scopes they need.

Browser dashboard sessions do not authenticate the Data API. These endpoints are for bearer-token clients and return JSON errors when the token is missing or invalid.

Endpoints

Method	Path	Scope	Query params	Description
`GET`	`/api/v1/issues`	`read:lucent`	`limit`, `status`, `cursor`	List issues for the token’s organization.
`GET`	`/api/v1/issues/{issueId}`	`read:lucent`	—	Fetch a single issue by UUID.
`PATCH`	`/api/v1/issues/{issueId}`	`write:issues`	—	Update an issue’s status.
`GET`	`/api/v1/signals`	`read:lucent`	`limit`, `cursor`	List configured signals and match counts.
`GET`	`/api/v1/insights`	`read:lucent`	`limit`, `cursor`	List recent AI-generated insights.

Every request is scoped to the organization that owns the token. There is no orgId query parameter.

Limits

Endpoint	Default limit	Max limit
`/api/v1/issues`	`25`	`200`
`/api/v1/signals`	`50`	`200`
`/api/v1/insights`	`25`	`100`

limit must be an integer within the endpoint’s range. List endpoints are ordered by createdAt descending, then id descending.

Pagination

List responses include nextCursor:

{
  "issues": [],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAyLTI0VDEwOjMyOjE5LjA2NloiLCJpZCI6Ijg3YjNhNmI2LTVhZjUtNDM4Yi1hMzljLWVmZjE0OGE2OGNjYiJ9"
}

If nextCursor is not null, pass it back as the cursor query parameter to fetch the next page:

GET /api/v1/issues?limit=25&cursor=eyJjcmVhdGVkQXQiOiIyMDI2...
Authorization: Bearer luc_api_...

The cursor is opaque. Do not parse or construct it yourself.

Rate limits

Request type	Limit
Reads	300 requests per minute per token or OAuth client
Writes	60 requests per minute per token or OAuth client

Rate-limited responses return 429 and include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Errors

All error responses are JSON and include Cache-Control: no-store.

Status	Example body	Meaning
`400`	`{"error":"limit must be an integer between 1 and 200"}`	Invalid query parameter.
`400`	`{"error":"Request body must be valid JSON"}`	Invalid JSON body for a write request.
`400`	`{"error":"status must be one of: unresolved, ticket_created, transient, resolved"}`	Invalid issue status.
`401`	`{"error":"Missing or invalid bearer token"}`	Missing, malformed, revoked, or unknown bearer token.
`403`	`{"error":"Missing required scope: write:issues"}`	The token is valid but lacks the required scope.
`404`	`{"error":"Issue not found"}`	The requested issue was not found in the token’s organization.
`429`	`{"error":"Rate limit exceeded"}`	The token or OAuth client exceeded its per-minute limit.

401 responses include:

WWW-Authenticate: Bearer scope="read:lucent"

For write endpoints, the challenge scope is write:issues.

Introduction

Webhooks

Ingest

Data API

Base URL

Authentication

Endpoints

Limits

Rate limits

Errors

​Base URL

​Authentication

​Endpoints

​Limits

​Pagination

​Rate limits

​Errors

Base URL

Authentication

Endpoints

Limits

Pagination

Rate limits

Errors