--- title: Create Session | Luma Agents --- POST /v1/sessions Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/sessions'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', '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); } ``` ```sh curl --request POST \ --url https://agents.lumalabs.ai/v1/sessions \ --header 'Authorization: Bearer ' \ --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." }' ``` - Productionagents.lumalabs.ai/v1/sessions 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 - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Header Parameters **Idempotency-Key** Any of: - [string](#tab-panel-0-0) - [null](#tab-panel-0-1) string <= 255 characters null ## Request Bodyrequired Media typeapplication/json *CreateSessionRequest* object **agents** Any of: - [object](#tab-panel-1-0) - [null](#tab-panel-1-1) 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](#tab-panel-2-0) - [null](#tab-panel-2-1) string Allowed values: all each null **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](#tab-panel-3-0) - [null](#tab-panel-3-1) integer \>= 1 null **max\_turns** *Max Turns* Max LLM turns before the sub-agent is force-completed. integer default: 10 >= 1 <= 50 **model\_override** Any of: - [string](#tab-panel-4-0) - [null](#tab-panel-4-1) string <= 256 characters null **system\_context** Any of: - [string](#tab-panel-5-0) - [null](#tab-panel-5-1) string <= 8192 characters null **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\ <= 64 items null **app** Any of: - [string](#tab-panel-6-0) - [null](#tab-panel-6-1) string <= 128 characters null **callback\_url** Any of: - [string](#tab-panel-7-0) - [null](#tab-panel-7-1) string <= 2048 characters null **cost\_policy** Any of: - [SessionCostPolicy](#tab-panel-8-0) - [null](#tab-panel-8-1) *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](#tab-panel-9-0) - [null](#tab-panel-9-1) integer \>= 1 <= 100000000 null **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 null **default\_generation\_models** Any of: - [Array\](#tab-panel-10-0) - [null](#tab-panel-10-1) Array\ <= 32 items null **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](#tab-panel-11-0) - [null](#tab-panel-11-1) string <= 255 characters null **metadata** Any of: - [object](#tab-panel-12-0) - [null](#tab-panel-12-1) object ***key*** additional properties string null **model** Any of: - [string](#tab-panel-13-0) - [null](#tab-panel-13-1) string <= 256 characters null **platform\_skills** Any of: - [boolean](#tab-panel-14-0) - [null](#tab-panel-14-1) boolean null **platform\_tools** Any of: - [PlatformToolsetV1](#tab-panel-15-0) - [null](#tab-panel-15-1) *PlatformToolsetV1* Versioned selection of the platform tools a bare session carries. object **configs** *Configs* Array\ <= 6 items *PlatformToolConfig* object **enabled** required *Enabled* boolean **name** required Any of: - [ConfigurablePlatformToolName](#tab-panel-16-0) - [PlatformToolGroup](#tab-panel-16-1) *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 *PlatformToolGroup* 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. string Allowed values: app\_tools **default\_config** *PlatformToolDefaultConfig* object **enabled** *Enabled* boolean **type** required *Type* string Allowed value: platform\_toolset\_v1 null **scope\_id** required *Scope Id* UUID of the scope (workspace) to create this session in. string **skills** Any of: - [Array\](#tab-panel-17-0) - [null](#tab-panel-17-1) Array\ <= 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](#tab-panel-18-0) - [string](#tab-panel-18-1) integer \>= 1 string Allowed value: latest null **system\_context** Any of: - [string](#tab-panel-19-0) - [null](#tab-panel-19-1) string <= 8192 characters null **tools** Any of: - [Array\](#tab-panel-20-0) - [null](#tab-panel-20-1) Array\ <= 64 items *ClientToolDefinition* A tool definition from the SDK client (may be webhook or client-side). object **context\_hint** Any of: - [string](#tab-panel-21-0) - [null](#tab-panel-21-1) string <= 1024 characters null **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 null ## Responses ### 201 Successful Response Media typeapplication/json *CreateSessionResponse* object **app** Any of: - [AppRef](#tab-panel-22-0) - [null](#tab-panel-22-1) *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 null **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\ **callback\_url** Any of: - [string](#tab-panel-23-0) - [null](#tab-panel-23-1) string null **judge\_calls\_remaining** Any of: - [integer](#tab-panel-24-0) - [null](#tab-panel-24-1) integer null **platform\_skills** *Platform Skills* The platform skills on the agent's menu, by slug (`platform-`). The agent reads them with read\_skill. Array\ **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\ **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\ *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](#tab-panel-25-0) - [null](#tab-panel-25-1) string null ##### Example ```json { "replayed": false, "state": "active" } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```