--- title: Reference | Luma Agents description: Every Agents route, error code and limit on one page. --- Routes, errors, a pre-launch checklist and common questions in one place. Every field, with types and limits, is in the [API Reference](/guides/index.md). ## Routes Every route is under `https://agents.lumalabs.ai` and takes a session token, unless the table says otherwise. Workspaces are `scopes` on the wire. | Method | Path | What it does | | -------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- | | `POST` | `/v1/auth/token` | Mint a session token. API key only | | `POST` `GET` | `/v1/scopes` | Create a workspace (same `key` returns the same one), or list them | | `GET` `DELETE` | `/v1/scopes/{scope_id}` | Read or delete a workspace and its assets | | `POST` `GET` | `/v1/sessions` | Create a session, or list them | | `GET` `DELETE` | `/v1/sessions/{session_id}` | Read the session now, or close it | | `POST` | `/v1/sessions/{session_id}/events` | Send 1 to 20 inputs: messages, tool results, verdicts, interrupts | | `GET` | `/v1/sessions/{session_id}/events` | One page of the event log | | `GET` | `/v1/sessions/{session_id}/events/stream` | The event log as Server-Sent Events | | `POST` | `/v1/sessions/{session_id}/events/token` | A single-use stream token for a browser | | `POST` `GET` | `/v1/sessions/{session_id}/runs` | Start a run, or list them | | `GET` | `/v1/sessions/{session_id}/runs/{run_id}` | A run’s state and outputs. `wait_s` waits up to 30 seconds | | `POST` | `/v1/sessions/{session_id}/runs/{run_id}/cancel` | Cancel one run | | `GET` | `/v1/sessions/{session_id}/jobs` | Every generation, with fresh one-hour URLs | | `GET` | `/v1/sessions/{session_id}/jobs/{job_id}` | One generation’s state and outputs | | `GET` | `/v1/sessions/{session_id}/usage` | What the session, and the sessions it started, cost | | `GET` | `/v1/sessions/{session_id}/assets/{asset_id}` | A short-lived URL for one of the session’s assets | | `GET` | `/v1/sessions/{session_id}/plan-artifact/patches` | Changes to an app session’s document since a revision | | `POST` | `/v1/sessions/{session_id}/deliveries` | Save a file your app screen exported into the workspace | | `POST` | `/v1/sessions/{session_id}/read-token` | A ten-minute token that can only read this session | | `POST` | `/v1/sessions/{session_id}/runs/{run_id}/tool-response` | Answer what one run is waiting on | | `POST` | `/v1/attachments?session_id=…` | Upload a file to the session | | `GET` | `/v1/attachments/{attachment_id}?session_id=…` | Poll an upload until `ready` | | `POST` `GET` | `/v1/skills` | Upload or list [skills](/agents/skills/index.md). API key or session token | | `GET` `DELETE` | `/v1/skills/{skill_id}` | Read or delete a skill | | `POST` `GET` | `/v1/skills/{skill_id}/versions` | Publish a new version, or list them | | `GET` | `/v1/skills/{skill_id}/versions/{version}` | One version of a skill | | `GET` | `/v1/skills/{skill_id}/versions/{version}/files/{path}` | Read one text file of a version | | `GET` | `/v1/fonts` | List font families | | `GET` `DELETE` | `/v1/fonts/families/{family_id}` | Read or delete a font family | | `DELETE` | `/v1/fonts/faces/{face_id}` | Delete one font face | | `POST` | `/v1/fonts/uploads` | Start a font upload | | `POST` | `/v1/fonts/uploads/{face_id}/complete` | Finish a font upload | | `GET` | `/v1/apps` | The workflow apps you can run | | `GET` | `/v1/apps/{app_slug}` | One app and the inputs it takes | | `GET` | `/v1/apps/{app_slug}/releases` | An app’s published versions, newest first | | `GET` | `/v1/apps/{app_slug}/artifact-schema` | The shape of an app’s document | | `GET` | `/v1/apps/{app_slug}/surface-template` | An app’s intake form: pages, fields and labels | | `GET` | `/v1/models` | Models you can reach, with live credits | | `GET` | `/v1/models/{model_id}` | One model, by id or public name | | `GET` | `/v1/credits` | Your team’s balance. API key only | | `GET` | `/v1/usage` | Usage for the billing period or a date range | ## Send input Everything you send goes to `POST /v1/sessions/{session_id}/events`. One request carries 1 to 20 events, run in order. | Type | Fields | Explained in | | ------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `user.message` | `content`, up to 32,768 characters. Optional `attachment_ids`, `asset_ids` and `capability` | [Quickstart](/agents/quickstart/index.md), [Workflow apps](/agents/workflow-apps/index.md) | | `user.tool_result` | `invocation_id`, `result` (any JSON) | [Approvals and review](/agents/approvals/index.md) | | `user.gate_verdict` | `invocation_id`, `verdict` | [Approvals and review](/agents/approvals/index.md) | | `user.interrupt` | Optional `target_run_id` | [Sessions](/agents/sessions/index.md#interrupt-a-turn) | The route acknowledges each event separately, so a `200` can still contain a refusal. Read every acknowledgement’s `status`: | `status` | Means | | ---------- | ------------------------------------------------------------------------------------------------ | | `accepted` | Recorded and run. `id` and `seq` place it on the log. A message’s `result.run_id` names its run. | | `replayed` | You sent this key and body before. Nothing ran again. | | `rejected` | Refused. `error` has `code`, `message` and `retryable`. | | `skipped` | An earlier event in the request was rejected, so this one did nothing. Send it again. | Give every input an `idempotency_key`, derived from something stable on your side, such as your own message id or `tool-`. Resending the same key and body returns `replayed` with the first outcome, so a lost acknowledgement costs nothing. A retried `POST /v1/sessions` takes the key as an `Idempotency-Key` header instead. - `SESSION.INPUT_IN_FLIGHT` or `SESSION.INPUT_OUTCOME_UNKNOWN`: retry with the same key after a short backoff. A new key is the one way to run an input twice. - `SESSION.IDEMPOTENCY_CONFLICT`: the key was reused with a different body. - `retryable: false`: fix the input and send it with a new key. ## Events Every event carries `type`, `seq`, `id`, `created_at` and `direction` (`in` for what you sent, `out` for the agent’s). Skip types you don’t recognize: new ones can be added. | Group | Types | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Your inputs | `user.message`, `user.tool_result`, `user.gate_verdict`, `user.interrupt`, `user.consent`, `user.command` | | Session state | `session.status_running`, `session.status_idle`, `session.status_terminated`, `session.error`, `session.turn_retried`, `session.input_failed` | | Runs | `run.started`, `run.completed` | | Agent | `agent.message`, `agent.tool_use`, `agent.tool_result`, `agent.custom_tool_use`, `agent.gate`, `agent.preview`, `agent.skill_activated` | | Generations | `job.started`, `job.completed`, `job.failed` | | Workflow apps | `plan.updated`, `artifact.ready`, `stage.started`, `stage.done` | | Sub-agents | `agent.started`, `agent.done` | | Files | `artifact.attachment_ready` | | Cost and context | `session.usage`, `session.budget_warning`, `session.consent_required`, `session.config_changed`, `session.context_compacting` | These appear on the live stream only. They have no `id` or `seq`, and are never on the event page or a webhook: | Type | Carries | | ------------------------ | ---------------------------------------------------------------------------- | | `agent.message_delta` | Reply text as it is written. The `agent.message` after it has the full text. | | `agent.tool_use_started` | A tool call starting, before its `agent.tool_use` | | `agent.tool_progress` | Progress on a running tool | | `agent.preview_update` | Changes to a preview grid | | `job.progress` | Progress on a running generation | A field with no value is left out, never sent as `null`. An event over 64 KB is recorded cut down, with `truncated: true`; the live copy is whole. Check `truncated` first, then read the full content from the resource the event names, such as `GET /v1/sessions/{session_id}/jobs/{job_id}`. ## Errors Every error body has one shape: ```json { "detail": { "code": "REQUEST.INVALID", "message": "The request failed validation: body.scope_id: Field required", "request_id": "…" } } ``` **Branch on the HTTP status first, then refine with `code`.** `message` is for developers, never for your end user. `request_id` matches the `X-Request-Id` header; quote it to support. | Status | Means | Do | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | `401` | Token missing, expired or invalid | Mint a new token | | `402` | Money: the session’s cap or your balance is spent, or credits are frozen | Top up or raise the cap | | `403` | Not allowed. `AUTH.SCOPE_FORBIDDEN` names a missing token permission | Mint a token with it. Retrying won’t help | | `404` | Not found, or not yours. The API never tells the two apart | Check the id | | `409` | A conflict: reused idempotency key, busy session, stale revision | Read the code | | `410` | The session expired | Create a new one | | `422` | Malformed, or content refused | Fix the request | | `429` | `SESSION.RATE_LIMITED`: over your request rate. All session routes share one per-minute limit per API client, and responses carry no `X-RateLimit-*` headers | Wait for `Retry-After` | | `5xx` | Server error | Retry with backoff | The codes you’ll see most: | Code | When | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `SESSION.BUDGET_EXHAUSTED` (402) | The session’s cap or your balance stopped it | | `SESSION.IDEMPOTENCY_CONFLICT` (409) | A key reused with a different body | | `SESSION.INPUT_IN_FLIGHT` (503), `SESSION.INPUT_OUTCOME_UNKNOWN` (409) | Retry with the same key | | `RUN.SESSION_BUSY` (409) | The session is already working | | `TOOL_RESPONSE.UNKNOWN_INVOCATION` | Nothing was waiting for that `invocation_id`. Don’t resend | | `SPEC.TOOL_INVALID`, `SPEC.TOOL_NAME_COLLISION` (422) | A [tool](/agents/tools/index.md) declaration was refused | | `SESSION.CALLBACK_URL_INVALID` (422) | `callback_url` isn’t a public `https` URL | | `APP.NOT_FOUND` (404) | Unknown app, or one you can’t run | | `RUN.INVALID_INPUT` | An app’s form doesn’t match its schema. `fields` names each failing field | | `SCOPE.HAS_ACTIVE_SESSIONS` (409) | A workspace delete while a session in it is active | `POST …/events` answers `200` even when it refuses an input. Read `status` on every ack: a refused input is `rejected` with an `error` in the same shape. On the stream, `session.error` carries a code and a `retry_status`. `exhausted` means this turn is over and a new input can succeed. `terminal` means sending the same input again won’t help. A `job.failed` is narrower: one generation failed, and the agent carries on. ## Before you ship Each of these works in a demo and fails in production. 1. **Wait for `session.status_idle`.** `agent.message` means the agent finished writing, not working. If it started generations, a continuation turn starts on its own when they land. `stop_reason: requires_action` means it’s waiting on you. 2. **Resume from your last `seq`.** Store it and reconnect with `Last-Event-ID` or `?after_seq=`. The stream replays everything after it. 3. **Read every ack.** A retry under the same `idempotency_key` is `replayed` and runs nothing twice. Retry `INPUT_IN_FLIGHT` with the same key, and use a fresh key for each new operation. 4. **Store `asset_id`, never a URL.** Output URLs expire in one hour. `GET …/jobs` signs new ones. 5. **Treat `402` as money**, whatever the code. 6. **Answer every pending action**, with `{ "error": "…" }` if you can’t handle it. Key each answer on its `invocation_id`. 7. **Send `invocation` on every tool.** The default is `webhook`, and a tool on the wrong lane fails without an error. 8. **Poll attachments until `ready`.** No event tells you, and the poll needs the same `session_id` as the upload. 9. **Log `X-Request-Id`.** Send your own, so it’s already in your logs. 10. **Interrupt before you close.** `DELETE` doesn’t stop generations already started. Send `user.interrupt` first. ## FAQ **My session is stuck.** Read `GET /v1/sessions/{session_id}`. Anything in `pending` is waiting on you. If `pending` is empty, the session is `running`, and `pending_tool_invocations` lists a call you never saw on the stream, it’s a webhook tool your endpoint hasn’t answered. **Can I use a browser’s `EventSource`?** Not with a header. Stream with `fetch`, or mint a single-use token with `POST …/events/token` and pass it as `?token=`. Mint a new one for each reconnect: they last 60 seconds and die on first use. **I reconnected and I’m missing events.** A stream opened without a cursor starts live. Send your last `seq` back, or read `GET …/events?after_seq=` to catch up. `agent.message_delta` events are never replayed; the `agent.message` after them has the full text. **How do I get exact ad dimensions?** You choose an aspect ratio, not pixels. Generate at the nearest ratio and resize or crop on your side. **Do I need one API key per customer?** No. Use one key on your server and mint a session token per end user, with `tenant_id` set to your id for their company. One customer’s sessions and workspaces are then invisible to another’s. See [Workspaces and access](/agents/workspaces/index.md). **My session still uses an old skill version.** A session pins its skills at create. Start a new session to get the new version. **Can a workflow app change mid-session?** No. A session keeps its app release to its last turn. **What should I send support?** The `X-Request-Id` of the failing response, the `session_id`, the `job_id` if a generation failed, the time with a timezone, and whether it happens again. Send them to . ## Next - [Quickstart](/agents/quickstart/index.md): your first session in five calls. - [Tools](/agents/tools/index.md): answer the agent from your code. - [API Reference](/guides/index.md): every field.