Reference
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.
Routes
Section titled “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. 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
Section titled “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, Workflow apps |
user.tool_result | invocation_id, result (any JSON) | Approvals and review |
user.gate_verdict | invocation_id, verdict | Approvals and review |
user.interrupt | Optional target_run_id | Sessions |
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-<invocation_id>. 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_FLIGHTorSESSION.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
Section titled “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
Section titled “Errors”Every error body has one shape:
{ "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 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
Section titled “Before you ship”Each of these works in a demo and fails in production.
- Wait for
session.status_idle.agent.messagemeans the agent finished writing, not working. If it started generations, a continuation turn starts on its own when they land.stop_reason: requires_actionmeans it’s waiting on you. - Resume from your last
seq. Store it and reconnect withLast-Event-IDor?after_seq=. The stream replays everything after it. - Read every ack. A retry under the same
idempotency_keyisreplayedand runs nothing twice. RetryINPUT_IN_FLIGHTwith the same key, and use a fresh key for each new operation. - Store
asset_id, never a URL. Output URLs expire in one hour.GET …/jobssigns new ones. - Treat
402as money, whatever the code. - Answer every pending action, with
{ "error": "…" }if you can’t handle it. Key each answer on itsinvocation_id. - Send
invocationon every tool. The default iswebhook, and a tool on the wrong lane fails without an error. - Poll attachments until
ready. No event tells you, and the poll needs the samesession_idas the upload. - Log
X-Request-Id. Send your own, so it’s already in your logs. - Interrupt before you close.
DELETEdoesn’t stop generations already started. Senduser.interruptfirst.
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.
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 support+luma-agents-api@lumalabs.ai.
- Quickstart: your first session in five calls.
- Tools: answer the agent from your code.
- API Reference: every field.