> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucenthq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data API

> Read issues, signals, and insights over REST, and update issue status using bearer tokens.

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

## Base URL

```text theme={null}
https://app.lucenthq.com
```

All endpoints below are relative to this base URL.

## Authentication

Send a bearer token in the `Authorization` header:

```bash theme={null}
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](/mcp/oauth) and request only
the scopes they need.

<Note>
  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.
</Note>

## Endpoints

| Method | Path | Scope | Query params | Description |
| - | - | - | - | - |
| `GET` | [`/api/v1/issues`](/api-reference/list-issues) | `read:lucent` | `limit`, `status`, `cursor` | List issues for the token's organization. |
| `GET` | [`/api/v1/issues/{issueId}`](/api-reference/get-an-issue) | `read:lucent` | — | Fetch a single issue by UUID. |
| `PATCH` | [`/api/v1/issues/{issueId}`](/api-reference/update-issue-status) | `write:issues` | — | Update an issue's status. |
| `GET` | [`/api/v1/signals`](/api-reference/list-signals) | `read:lucent` | `limit`, `cursor` | List configured signals and match counts. |
| `GET` | [`/api/v1/insights`](/api-reference/list-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`:

```json theme={null}
{
  "issues": [],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAyLTI0VDEwOjMyOjE5LjA2NloiLCJpZCI6Ijg3YjNhNmI2LTVhZjUtNDM4Yi1hMzljLWVmZjE0OGE2OGNjYiJ9"
}
```

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

```http theme={null}
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:

```http theme={null}
WWW-Authenticate: Bearer scope="read:lucent"
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.