Skip to content
Reference

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.

Every route is under https://agents.lumalabs.ai and takes a session token, unless the table says otherwise. Workspaces are scopes on the wire.

MethodPathWhat it does
POST/v1/auth/tokenMint a session token. API key only
POST GET/v1/scopesCreate 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/sessionsCreate a session, or list them
GET DELETE/v1/sessions/{session_id}Read the session now, or close it
POST/v1/sessions/{session_id}/eventsSend 1 to 20 inputs: messages, tool results, verdicts, interrupts
GET/v1/sessions/{session_id}/eventsOne page of the event log
GET/v1/sessions/{session_id}/events/streamThe event log as Server-Sent Events
POST/v1/sessions/{session_id}/events/tokenA single-use stream token for a browser
POST GET/v1/sessions/{session_id}/runsStart 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}/cancelCancel one run
GET/v1/sessions/{session_id}/jobsEvery 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}/usageWhat 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/patchesChanges to an app session’s document since a revision
POST/v1/sessions/{session_id}/deliveriesSave a file your app screen exported into the workspace
POST/v1/sessions/{session_id}/read-tokenA ten-minute token that can only read this session
POST/v1/sessions/{session_id}/runs/{run_id}/tool-responseAnswer 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/skillsUpload 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}/versionsPublish 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/fontsList 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/uploadsStart a font upload
POST/v1/fonts/uploads/{face_id}/completeFinish a font upload
GET/v1/appsThe workflow apps you can run
GET/v1/apps/{app_slug}One app and the inputs it takes
GET/v1/apps/{app_slug}/releasesAn app’s published versions, newest first
GET/v1/apps/{app_slug}/artifact-schemaThe shape of an app’s document
GET/v1/apps/{app_slug}/surface-templateAn app’s intake form: pages, fields and labels
GET/v1/modelsModels you can reach, with live credits
GET/v1/models/{model_id}One model, by id or public name
GET/v1/creditsYour team’s balance. API key only
GET/v1/usageUsage for the billing period or a date range

Everything you send goes to POST /v1/sessions/{session_id}/events. One request carries 1 to 20 events, run in order.

TypeFieldsExplained in
user.messagecontent, up to 32,768 characters. Optional attachment_ids, asset_ids and capabilityQuickstart, Workflow apps
user.tool_resultinvocation_id, result (any JSON)Approvals and review
user.gate_verdictinvocation_id, verdictApprovals and review
user.interruptOptional target_run_idSessions

The route acknowledges each event separately, so a 200 can still contain a refusal. Read every acknowledgement’s status:

statusMeans
acceptedRecorded and run. id and seq place it on the log. A message’s result.run_id names its run.
replayedYou sent this key and body before. Nothing ran again.
rejectedRefused. error has code, message and retryable.
skippedAn 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_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.

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.

GroupTypes
Your inputsuser.message, user.tool_result, user.gate_verdict, user.interrupt, user.consent, user.command
Session statesession.status_running, session.status_idle, session.status_terminated, session.error, session.turn_retried, session.input_failed
Runsrun.started, run.completed
Agentagent.message, agent.tool_use, agent.tool_result, agent.custom_tool_use, agent.gate, agent.preview, agent.skill_activated
Generationsjob.started, job.completed, job.failed
Workflow appsplan.updated, artifact.ready, stage.started, stage.done
Sub-agentsagent.started, agent.done
Filesartifact.attachment_ready
Cost and contextsession.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:

TypeCarries
agent.message_deltaReply text as it is written. The agent.message after it has the full text.
agent.tool_use_startedA tool call starting, before its agent.tool_use
agent.tool_progressProgress on a running tool
agent.preview_updateChanges to a preview grid
job.progressProgress 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}.

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.

StatusMeansDo
401Token missing, expired or invalidMint a new token
402Money: the session’s cap or your balance is spent, or credits are frozenTop up or raise the cap
403Not allowed. AUTH.SCOPE_FORBIDDEN names a missing token permissionMint a token with it. Retrying won’t help
404Not found, or not yours. The API never tells the two apartCheck the id
409A conflict: reused idempotency key, busy session, stale revisionRead the code
410The session expiredCreate a new one
422Malformed, or content refusedFix the request
429SESSION.RATE_LIMITED: over your request rate. All session routes share one per-minute limit per API client, and responses carry no X-RateLimit-* headersWait for Retry-After
5xxServer errorRetry with backoff

The codes you’ll see most:

CodeWhen
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_INVOCATIONNothing 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_INPUTAn 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.

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.

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.