Create Session
const url = 'https://agents.lumalabs.ai/v1/sessions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agents":{"copywriter":{"description":"Writes the headline and body copy for one ad.","fan_in":"each","max_turns":6,"system_context":"You write short, punchy ad copy. Answer with the headline, then the body."}},"metadata":{"campaign":"spring-launch"},"scope_id":"3f6c2a9e-1b7d-4c58-9e0a-6d2b8f4c1a73","system_context":"You are the creative lead for a sneaker brand\'s spring campaign."}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://agents.lumalabs.ai/v1/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agents": { "copywriter": { "description": "Writes the headline and body copy for one ad.", "fan_in": "each", "max_turns": 6, "system_context": "You write short, punchy ad copy. Answer with the headline, then the body." } }, "metadata": { "campaign": "spring-launch" }, "scope_id": "3f6c2a9e-1b7d-4c58-9e0a-6d2b8f4c1a73", "system_context": "You are the creative lead for a sneaker brand'\''s spring campaign." }'Create a session within an existing scope.
Per-session config falls back to the scope's config for any field
not overridden in the request body. Tools and agents are frozen at
creation — they can't change turn-to-turn.
Capability enforcement runs on the EFFECTIVE (post-scope-merge) tool
and agent lists, not just the request body. Otherwise a partner could
pre-load tools or sub-agents in a scope config (where the create-scope
endpoint does not capability-check) and silently bypass the gates by
omitting tools / agents from POST /v1/sessions.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
One entry in a partner-supplied agents map.
extra='forbid' is load-bearing: it structurally enforces the
master plan's "one level of nesting" rule. A nested agents key —
or any other unrecognized key — is rejected with 422 at the API
boundary instead of being silently truncated by the runtime, which
only materializes a single level of sub-agent topology (PR #10267
security review).
The field surface mirrors the runtime wire contract consumed by
agents.runner_types.AgentDef.from_dict so every existing valid
topology still validates. name is intentionally absent — it is
the map key, injected by the runtime at session creation, not part of
the value.
object
Register query_creative_tools so the sub-agent can discover tools at runtime. When true, 'query_creative_tools' must also appear in tools.
Human-readable summary of what this sub-agent does; shown to the orchestrator when it decides whether to delegate.
Splice the session's own guidance into this sub-agent's system prompt. Off by default — a sub-agent's prompt is its system_context alone unless it asks for the session guidance too.
Max LLM turns before the sub-agent is force-completed.
Wall-clock timeout for the sub-agent delegation, in seconds.
Tool names this sub-agent may call; each must also be registered on the parent session's tools.
Credit ceilings a caller may set for one session.
Both the whole-session ceiling and per-stage ceilings only tighten limits already applied to the account or app.
Session TTL in seconds from creation. Max 7 days.
Versioned selection of the platform tools a bare session carries.
object
object
Stable platform tools a partner may select on a bare session.
The wire name is the value, sourced from :class:ToolName — the same
registry KernelSessionTool reads — so this selection and the kernel
offering it resolves to cannot drift apart on a rename.
A platform_tools config entry that switches a group of Luma's tools rather than naming one tool.
app_tools is list_apps, start_app and answer_gate. Only
enabled: false changes anything: the group is on wherever the key holds
workflow_apps, and default_config never reaches it.
object
UUID of the scope (workspace) to create this session in.
One skill uploaded with POST /v1/skills to attach to a session.
A tool definition from the SDK client (may be webhook or client-side).
Responses
Section titled “ Responses ”Successful Response
object
The workflow app a session is running, frozen at creation. package_digest is the sealed digest of the release that served the session's configuration — the identity two runs are compared by, since a version label can be reused.
object
Sealed package digest of that release.
Registered app slug, as named in POST /v1/sessions {app}.
SemVer of the release that was active at session creation.
The tools, skills, judge budget and callback the session actually got.
object
The workflow-app tools the agent holds: list_apps, start_app and, on a root session, answer_gate.
The platform skills on the agent's menu, by slug (platform-<slug>). The agent reads them with read_skill.
The platform tools the agent holds, by name: the platform_tools menu (search_web, download_web_asset, read, search_for_assets, judge_tool).
UTC timestamp when the session will be automatically expired.
True when this idempotency_key had already opened a session: that session is echoed and no second one was created.
UUID of the scope this session belongs to.
UUID identifying this session. Use in all subsequent requests.
The skill versions this session pinned, in request order. Empty when none were attached.
A skill version a session pinned at creation.
object
The version this session reads; latest already resolved.
Initial session state. Always 'active' on a fresh create; a replayed create echoes the state the original session is in now, which may be 'completed'.
Example
{ "replayed": false, "state": "active"}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}