# For AI agents

> How an AI agent or coding assistant reads these docs — llms.txt, a Markdown copy of every page, and the OpenAPI document.

These docs are written to be read by people and by agents alike. Everything on
this site is also plain Markdown, at stable addresses, with nothing to scrape.

## Where to start

| Address | What it is |
|---|---|
| `https://docs.lumavox.ai/llms.txt` | The index: what the API does, then every page with a one-line summary, in reading order. Start here. |
| `https://docs.lumavox.ai/llms-full.txt` | Every guide in one file, for a model with room for all of it. The reference's sections are left out — `llms.txt` links each one, and the OpenAPI document is the whole contract. |
| Any page's address plus `.md` | That page as Markdown — `https://docs.lumavox.ai/quickstart.md`, `https://docs.lumavox.ai/agents/websocket.md`. Its links point at the other pages' Markdown, so an agent that follows one stays in Markdown. Every page names its copy in its head, as `<link rel="alternate" type="text/markdown">`. |
| `https://api.lumavox.ai/openapi.json` | The API's OpenAPI 3.1 document: every operation, parameter and schema, as deployed. The [TypeScript SDKs](https://docs.lumavox.ai/sdks/server.md) are typed from it; for another language, generate a client from it. |

The [API reference](https://docs.lumavox.ai/reference.md) on this site is rendered from that same
document, so the two never disagree.

## Point your assistant at the docs

Give a coding assistant the index and let it fetch what it needs:

```text title="Prompt"
Read https://docs.lumavox.ai/llms.txt, then the pages it links to that this task needs.
Use the API at https://api.lumavox.ai; its OpenAPI document is https://api.lumavox.ai/openapi.json.
Read the API key from the API_KEY environment variable, never from source code.
```

## What an agent should know first

- **Base URL**: `https://api.lumavox.ai`. Every operation but `GET /health` and a
  template's example images takes `Authorization: Bearer <key>` (or
  `X-API-Key: <key>`). See [Authentication](https://docs.lumavox.ai/authentication.md).
- **One way to write every value**: fields are `snake_case`; a time is UTC
  with milliseconds (`2026-10-24T09:30:00.000Z`); credits are integers of
  micro-credits, in fields ending `_micros`; every list is
  `{"data": [...], "next_cursor": ...}`, the next page asked for with
  `cursor`; a response has every field, `null` for none. See [Conventions](https://docs.lumavox.ai/conventions.md).
- **Keys stay on a server.** An API key in a browser or a mobile app can spend
  your credit. An end user's device gets a short-lived ephemeral token instead —
  see [End users and their keys](https://docs.lumavox.ai/agents/end-users.md).
- **Errors are JSON** with one envelope — switch on `error.code`, read
  `error.issues` for the fields a `422` refused — and every response carries
  `X-Request-Id`. See [Errors and limits](https://docs.lumavox.ai/errors.md).
- **Speech answers in the request; images, video, stored audio and long
  transcriptions are queued**: a `202` with an id, then poll. See
  [Queued jobs](https://docs.lumavox.ai/jobs.md).
- **Agents talk on a WebSocket**, which the OpenAPI document cannot describe:
  [The WebSocket](https://docs.lumavox.ai/agents/websocket.md) is the whole protocol.
- **A 403 is a missing scope, not a bad key** — the key is valid, but it may not
  call that operation. See [Authentication](https://docs.lumavox.ai/authentication.md).