Update Session

Storage and ownership

Start the example API server and create a run or precreate a session. Keep the returned session_id. Use db_id when multiple registered databases exist; selecting table requires db_id and a configured adapter. It does not create a table on demand.

The session-type query parameter is type=agent, type=team or type=workflow. JWT user isolation is opt-in; non-admin service-account PAT callers always self-scope. A supplied user_id is a filter for unscoped callers, not permission to access another owner's records. Configured authorization also requires the relevant session read, write or delete scope.

Update dictionaries deliberately

session_state and metadata replace their existing dictionaries; they are not deep merges. Send the full dictionary to retain other entries. {} clears one, while omission or null leaves it unchanged. Reserved run-metadata keys are removed.

For example, using the linked server and an existing Agent session:

SESSION_ID="returned-session-id"
curl --fail-with-body -X PATCH "http://127.0.0.1:7777/sessions/$SESSION_ID?type=agent" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"session_name":"Support conversation","session_state":{"stage":"review"},"metadata":{}}'

The response is a complete Agent, Team or Workflow session-detail object, including IDs and timestamps. The generated response examples below instead resemble partial request bodies; do not parse the response as only those submitted fields.

Current Workflow session updates can accept summary and return 200 without persisting that summary. Use summary updates for Agent or Team sessions; do not rely on this field for Workflow summary storage.

PATCH/sessions/{session_id}

Update session properties such as session_name, session_state, metadata, or summary. Use this endpoint to modify the session name, update state, add metadata, or update the session summary.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

session_id*Session Id

Session ID to update

Query Parameters

type?|

Session type (agent, team, or workflow). If not provided, auto-detected from session data.

user_id?|

User ID

db_id?|

Database ID to use for update operation

table?|

Table to use for update operation

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Session update data

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request PATCH 'https://example.com/sessions/string' \  --header 'Content-Type: application/json' \  --data-raw '{}'

{  "summary": {    "summary": "The user discussed project planning with the agent.",    "updated_at": "2025-10-21T14:30:00Z"  }}