canonical: https://jentic.com/apis/lucis.life/lucis

# Lucis Life Lucis public API

The Lucis public API publishes the biomarker catalog behind the Lucis preventive wellness membership, listing each panel marker with its stable uuid, display unit, category, translations, and flags for premium or internally computed markers. A template parameter selects the panel variant, such as the complete or light EU panels and their UK v2 counterparts. The catalog is readable without authentication, an optional OAuth 2.0 client_credentials token with scope catalog.read is available from the token endpoint, and discovery documents describe the authorization server and protected resource. It never returns individual member results or other health data.

## For AI agents

Read the public Lucis biomarker catalog for EU and UK panels, including marker units, categories, and translations. No authentication required; an optional client_credentials token is available.

## Scope

Does not return member test results, book blood draws, or manage memberships. Use for reading the public Lucis biomarker catalog and its OAuth discovery documents only.

## Capabilities

- List the biomarkers on a Lucis panel with uuid, unit, category, and translations via GET `/v1/biomarkers/public`
- Switch between panel variants with the template parameter, such as public-complete-eu, public-light-eu, public-v2-complete-uk, or public-v2-light-uk
- Tell premium markers and internally computed markers apart using the premium and computedInternally fields
- Read the live RateLimit and RateLimit-Policy headers on catalog responses to pace requests
- Obtain an optional client_credentials access token with scope catalog.read through POST `/oauth/token`
- Fetch OAuth 2.0 authorization server and protected resource metadata from the /.well-known discovery documents

## Use cases

### Answering panel questions with an agent through Jentic

A wellness assistant answers 'what does the Lucis panel test for?' from the live catalog instead of a stale copy. It searches Jentic for 'list Lucis biomarkers', receives GET `/v1/biomarkers/public` with its template parameter, and summarises the returned markers by category and unit. No credential is involved, because the catalog is public.

Example prompt: Call GET `/v1/biomarkers/public` with template public-complete-eu and group the returned biomarkers by category, listing each marker's unit

### Panel comparison

Show a prospective member what they gain by moving from a light panel to a complete one. Fetching the catalog twice, once with public-light-eu and once with public-complete-eu, and diffing the uuid sets gives the exact markers added, and the premium flag marks those on a premium panel.

Example prompt: Call GET `/v1/biomarkers/public` with template public-light-eu and again with public-complete-eu, then list the biomarkers present only in the complete panel

### Localised marker glossaries

Build a marker glossary in the reader's language. Each catalog item carries translations alongside its stable uuid, so a site or app can render marker names in the language it needs and keep links stable across catalog updates by keying on the uuid.

Example prompt: Call GET `/v1/biomarkers/public` with template public-v2-complete-uk and produce a glossary of uuid, translated name, and unit for each marker

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/biomarkers/public` | List public Lucis biomarkers |
| POST | `/oauth/token` | Issue a client_credentials access token |
| GET | `/.well-known/oauth-authorization-server` | OAuth 2.0 authorization server metadata |
| GET | `/.well-known/oauth-protected-resource` | OAuth 2.0 protected resource metadata |
| GET | `/openapi.json` | Download the OpenAPI document as JSON |

## Key resources

- **Biomarker catalog** — Public panel markers with uuid, unit, category, translations, and premium or computed flags
- **OAuth 2.0 endpoints** — Optional client_credentials token issuance and RFC 8414 / RFC 9728 discovery metadata
- **OpenAPI documents** — The Lucis OpenAPI description in JSON and YAML

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 76 / 100
- **Maturity:** AI-Ready
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 65 / 100
  - Agent Usability: 94 / 100
  - Security: 85 / 100
  - AI Discoverability: 78 / 100
- **View full report:** https://jentic.com/apis/lucis.life/lucis/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Lucis biomarker list by hand means choosing the right panel template and pacing requests against its RateLimit headers; the optional client_credentials token adds a token request you rarely need. Through Jentic you install once, import Lucis from the API Directory, and your agent calls it.
- **Permission scoping:** Rules filter by method and path, and the panel choice travels in the template query parameter rather than the path, so bound the agent to the operations it needs, such as reading the public biomarker list, rather than to one panel. Token issuance and discovery operations stay out unless you add them.
- **Credential handling:** Reading biomarkers needs no credential. If you choose to use the optional client_credentials client, it is stored encrypted by your own Jentic One instance and injected at execution time, never entering the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Lucis biomarkers' or 'compare Lucis panels', and Jentic returns GET `/v1/biomarkers/public` with its input schema, including the template enum, so the agent picks a valid panel without reading the docs.

## Related APIs

- **Clinical Table Search Service** — NLM lookup tables for lab tests, conditions, and other clinical terms
- **Junction API** — Orders diagnostic lab tests and collects wearable health data
- **Oura API** — Sleep, activity, and readiness data from Oura rings

## FAQ

### What authentication does the Lucis public API use?

The biomarker catalog needs no authentication. Per its OpenAPI spec, an optional oauth2 client_credentials token with scope catalog.read can be requested from POST `/oauth/token`, and the catalog accepts it as a Bearer token but ignores it for authorization. Public clients may omit client authentication at the token endpoint.

### Does the Lucis public API return member test results?

No. The spec states that it never returns individual member results or other health data. It publishes the catalog of markers on each panel, with their units, categories, translations, and premium or computed flags, plus OAuth and OpenAPI discovery documents.

### What are the rate limits for the Lucis public API?

Per the spec, the catalog policy is advertised as RateLimit-Policy "catalog";q=60;w=60, with RateLimit-Limit 60, a live RateLimit header on each catalog response, and Retry-After on HTTP 429. The quota is best-effort per compute instance. See https://www.lucis.life/developers for current details.

### Which panels can I query in the Lucis biomarker catalog?

The template parameter on GET `/v1/biomarkers/public` accepts public-complete-eu, public-light-eu, public-v2-complete-uk, and public-v2-light-uk, and defaults to public-complete-eu. An unknown template returns HTTP 400.

### How do I list Lucis biomarkers through Jentic?

Install Jentic One, add the Lucis public API from the Jentic directory, and have your agent search for 'list Lucis biomarkers'. Jentic returns GET `/v1/biomarkers/public` with its template parameter, and the agent calls it without any credential because the endpoint is public. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Lucis public API?

Yes. A rule that allows only GET `/v1/biomarkers/public` lets the agent read panel markers and nothing else, keeping token issuance and discovery documents out of its reach. The agent's calls are logged for review.