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

# API Reference

> REST endpoints for Lumina Protocol. Source-of-truth OpenAPI 3.0.3 spec at /openapi.json.

The Lumina API is a thin REST surface over the on-chain protocol. The spec
served at [`/openapi.json`](https://lumina-api-production-ac85.up.railway.app/openapi.json)
is the canonical contract — this section is a human-friendly tour.

## Base URL

```
https://lumina-api-production-ac85.up.railway.app
```

Local dev points at `http://localhost:3000` by default (override the port
via `PORT` env in the `lumina-api` repo).

## Authentication

| Surface                                                                               | Auth                                                   |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `/health`, `/products`, `/policies/:p/:i`, `/sandbox/*`, `/openapi.json`, `/api-docs` | None                                                   |
| `/api/v1/agent/onboard`                                                               | None — the request body itself is signed by the wallet |
| `/api/v1/policies`, `/bonds`, `/marketplace/listings`, `/agent/keys`, `/webhooks`, …  | `x-api-key: lk_…`                                      |
| `/api/v1/keys/generate` (legacy admin issuer)                                         | `x-admin-token: <secret>`                              |

## Live OpenAPI / Swagger UI

* Machine-readable: [`GET /openapi.json`](https://lumina-api-production-ac85.up.railway.app/openapi.json)
* Browser explorer: [`GET /api-docs`](https://lumina-api-production-ac85.up.railway.app/api-docs)

## Idempotency

`POST /api/v1/policies` honours an optional `Idempotency-Key` header (UUIDv4
recommended). Replays return the cached response without double-spending.

## Numeric encoding

Every on-chain integer (USDC base units, LUMINA wei, prices) is returned as
a **decimal string** to avoid JavaScript Number precision loss. Convert with
`BigInt(str)`.

## Error envelope

```json theme={null}
{ "error": "machine_code", "message": "human-readable", "code": "machine_code" }
```

The SDK maps non-2xx into `LuminaError` with `.status`, `.code`, `.message`.

## Postman collection

A complete collection is available in the lumina-api repo:
[`docs/lumina-api.postman_collection.json`](https://github.com/org-lumina/lumina-api/blob/main/docs/lumina-api.postman_collection.json).
Import into Postman → set `baseUrl` and `apiKey` collection variables → done.

## Endpoint examples

The next sub-pages walk through GET / CREATE / DELETE / WEBHOOK examples
auto-generated by Mintlify from the `openapi.json` snapshot.