Skip to content
Agents
Sessions

Create Session

POST
/v1/sessions
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.

Idempotency-Key
Any of:
string
<= 255 characters
Media typeapplication/json
CreateSessionRequest
object
agents
Any of:
object
<= 10 properties
key
additional properties
SubAgentDefinition

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
allow_dynamic_tool_discovery
Allow Dynamic Tool Discovery

Register query_creative_tools so the sub-agent can discover tools at runtime. When true, 'query_creative_tools' must also appear in tools.

boolean
description
Description

Human-readable summary of what this sub-agent does; shown to the orchestrator when it decides whether to delegate.

string
"" <= 1024 characters
fan_in
Any of:
string
Allowed values: all each
inherit_root_guidance
Inherit Root Guidance

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.

boolean
max_budget_credits
Any of:
integer
>= 1
max_turns
Max Turns

Max LLM turns before the sub-agent is force-completed.

integer
default: 10 >= 1 <= 50
model_override
Any of:
string
<= 256 characters
system_context
Any of:
string
<= 8192 characters
timeout_seconds
Timeout Seconds

Wall-clock timeout for the sub-agent delegation, in seconds.

integer
default: 300 >= 30
tools
Tools

Tool names this sub-agent may call; each must also be registered on the parent session's tools.

Array<string>
<= 64 items
app
Any of:
string
<= 128 characters
callback_url
Any of:
string
<= 2048 characters
cost_policy
Any of:
SessionCostPolicy

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.

object
max_total_credits
Any of:
integer
>= 1 <= 100000000
per_stage_caps
Per Stage Caps

Per-stage credit ceilings, keyed by the stage names this session's app emits (e.g. 'render_keyframes'). A stage not named here is bounded only by max_total_credits. Max 32 entries.

object
key
additional properties
integer
default_generation_models
Any of:
Array<string>
<= 32 items
expires_in_seconds
Expires In Seconds

Session TTL in seconds from creation. Max 7 days.

integer
default: 86400 >= 60 <= 604800
idempotency_key
Any of:
string
<= 255 characters
metadata
Any of:
object
key
additional properties
string
model
Any of:
string
<= 256 characters
platform_skills
Any of:
boolean
platform_tools
Any of:
PlatformToolsetV1

Versioned selection of the platform tools a bare session carries.

object
configs
Configs
Array<object>
<= 6 items
PlatformToolConfig
object
enabled
required
Enabled
boolean
name
required
Any of:
ConfigurablePlatformToolName

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.

string
Allowed values: search_web download_web_asset read search_for_assets judge_tool
default_config
PlatformToolDefaultConfig
object
enabled
Enabled
boolean
type
required
Type
string
Allowed value: platform_toolset_v1
scope_id
required
Scope Id

UUID of the scope (workspace) to create this session in.

string
skills
Any of:
Array<object>
<= 100 items
SessionSkillRef

One skill uploaded with POST /v1/skills to attach to a session.

object
skill_id
required
Skill Id

The skill's id from POST /v1/skills.

string
<= 36 characters
type
Type

Always 'custom': a skill you uploaded.

string
default: custom
Allowed value: custom
version
Any of:
integer
>= 1
system_context
Any of:
string
<= 8192 characters
tools
Any of:
Array<object>
<= 64 items
ClientToolDefinition

A tool definition from the SDK client (may be webhook or client-side).

object
context_hint
Any of:
string
<= 1024 characters
description
Description
string
"" <= 1024 characters
invocation
Invocation
string
default: webhook
Allowed values: client webhook
name
required
Name
string
<= 128 characters
parameters
Parameters
object
key
additional properties
any

Successful Response

Media typeapplication/json
CreateSessionResponse
object
app
Any of:
AppRef

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
package_digest
required
Package Digest

Sealed package digest of that release.

string
slug
required
Slug

Registered app slug, as named in POST /v1/sessions {app}.

string
version
required
Version

SemVer of the release that was active at session creation.

string
effective
SessionEffective

The tools, skills, judge budget and callback the session actually got.

object
app_tools
App Tools

The workflow-app tools the agent holds: list_apps, start_app and, on a root session, answer_gate.

Array<string>
callback_url
Any of:
string
judge_calls_remaining
Any of:
integer
platform_skills
Platform Skills

The platform skills on the agent's menu, by slug (platform-<slug>). The agent reads them with read_skill.

Array<string>
platform_tools
Platform Tools

The platform tools the agent holds, by name: the platform_tools menu (search_web, download_web_asset, read, search_for_assets, judge_tool).

Array<string>
expires_at
required
Expires At

UTC timestamp when the session will be automatically expired.

string format: date-time
replayed
Replayed

True when this idempotency_key had already opened a session: that session is echoed and no second one was created.

boolean
scope_id
required
Scope Id

UUID of the scope this session belongs to.

string
session_id
required
Session Id

UUID identifying this session. Use in all subsequent requests.

string
skills
Skills

The skill versions this session pinned, in request order. Empty when none were attached.

Array<object>
SessionSkill

A skill version a session pinned at creation.

object
name
required
Name
string
skill_id
required
Skill Id
string
version
required
Version

The version this session reads; latest already resolved.

integer
state
required
SessionState

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'.

string
Allowed values: active closing suspended error completed expired
webhook_secret
Any of:
string
Example
{
"replayed": false,
"state": "active"
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}