Modify a session's title, metadata, environment_variables, vault_ids, session-level agent configuration, and session-level MCP request headers. Updating a session is the only operation that triggers a session.updated event.
Prerequisites
Endpoint and authentication configuration must be completed. For details, see Overview and authentication.
Endpoint
POST /sessions/{session_id}
You can modify title, metadata, environment_variables, vault_ids, session-level agent configuration (agent), and session-level MCP request headers (mcp_configs). Array and object fields are replaced as a whole; empty values clear them. Updating a session is the only operation that triggers a session.updated event.
Request body
| Field | Required | Type | Description |
|---|---|---|---|
title | No | string | Session title. Omitted keeps the current value; null performs no update |
metadata | No | object | Custom key-value pairs for business use. Replaced as a whole; omitted keeps the current value, null performs no update |
environment_variables | No | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name. Replaced as a whole; an empty object clears them, omitted keeps the current value |
vault_ids | No | array of string | Replaces vault bindings as a whole; an empty array clears them, omitted keeps the current value |
agent | No | object | Session-level agent configuration patch. Can only carry the system / tools / mcp_servers / skills override fields; carrying other fields (such as type / id / version / model) returns invalid_parameter. See Session-level configuration patch |
mcp_configs | No | array | Replaces session-level MCP request headers as a whole; same structure as in Create Session. An empty array clears them, omitted keeps the current value, null is invalid |
Session-level configuration patch
The agent patch only modifies the configuration snapshot of the current session and never creates a new agent version. Sub-field semantics (consistent with the override semantics in Create Session):
| Value | Effect |
|---|---|
| Omitted | Keep the existing override |
null | Delete the override for that field and re-inherit the agent's source configuration |
[] (array fields) | Explicitly override to empty |
"" (only for system) | Explicitly use an empty prompt |
Request example
Response example
Returns the updated session details: new values of title / metadata / etc. after overwrite, agent (full snapshot with overrides merged), mcp_configs, vault_ids, updated_at, and request_id.
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Session ID |
type | string | Fixed as session |
status | string | Current session status (update does not change the status) |
title / metadata | string / object | New values after overwrite from the request body |
updated_at | string | Last update time, ISO 8601 |
request_id | string | Unique identifier for this request |
environment_variables | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name |
agent | object | Updated agent configuration snapshot with session-level overrides merged. Fields are the same as in Get Session |
vault_ids | array of string | Updated vault bindings |
mcp_configs | array of object | Updated session-level MCP request headers; each item contains mcp_server_name and headers |