Update Session

Update session properties

PATCH /v1/sessions/

Updates properties of an existing session. Only the fields provided in the request body will be updated.

Path Parameters

session_id · string · required

The ID of the session to update. Must be a valid session ID with the session_ prefix.

Request Body

All fields are optional. Only include the fields you want to update.

title · string

Updated title for the session.

tags · string[]

Updated tags for the session. Replaces existing tags entirely.

model_id · string

Updated model override for this session. Set to override the agent’s default model.

capabilities · object[]

Updated session-level capabilities. Replaces existing session capabilities entirely.

Session capabilities are additive to the agent’s capabilities:

1. Agent capabilities are applied first
2. Session capabilities are applied after (additive)

Each capability object contains:

• ref (string, required): Capability reference ID (e.g., “current_time”, “web_fetch”)
• config (object, optional): Configuration overrides for the capability

Response

Returns the updated Session object.

id · string

The session’s public ID with the session_ prefix.

agent_id · string

The ID of the agent assigned to this session (cannot be changed).

title · string

The updated session title.

tags · string[]

Updated tags associated with the session.

model_id · string

Updated model override for this session.

capabilities · object[]

Updated session-level capabilities.

status · string

Current session status: started, active, or idle.

features · string[]

Computed at read time by aggregating features from all active capabilities.

created_at · string

ISO 8601 timestamp when the session was created.

updated_at · string

ISO 8601 timestamp when the session was last updated.

Examples

Update title

curl -X PATCH https://api.everruns.com/v1/sessions/session_01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Research Session"
  }'

Update capabilities

curl -X PATCH https://api.everruns.com/v1/sessions/session_01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": [
      { "ref": "current_time" },
      { "ref": "web_fetch", "config": { "timeout_ms": 30000 } },
      { "ref": "session_file_system" }
    ]
  }'

Update multiple fields

curl -X PATCH https://api.everruns.com/v1/sessions/session_01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Session",
    "tags": ["updated", "v2"],
    "model_id": "gpt-4o-mini"
  }'

Error Responses

• 404 Not Found - Session does not exist or is not accessible
• 400 Bad Request - Invalid request body or parameters
• 401 Unauthorized - Missing or invalid authentication

Notes

• This endpoint uses PATCH semantics: only provided fields are updated
• The agent_id cannot be changed after session creation
• Updating capabilities replaces the entire session capabilities array
• Updating tags replaces the entire tags array
• Session capabilities are always additive to agent capabilities