Rename a session

POST /v1/sessions/{session_id}

Changes a session’s title and returns the updated session.

Only the title can change. Sending agent, vault_ids, budget or a non-empty metadata returns 400. An empty body, or metadata: {}, returns 200 and changes nothing.

The key must have the tasks:create capability. For what each capability allows, see Keys.

Path parameters

Name	Type	Required	Default	Description
`session_id`	`string`	Yes		The ID of the session to rename.

Body

Name	Type	Required	Default	Description
`title`	`string \| null`	No		The new title. Must be between 1 and 280 characters after trimming (Anthropic: 500). Send `null` to clear the title.

Response

Returns 200 with the session object. For every field, see Sessions.

{
  "id": "dd13d728-93e3-440a-874c-4efeb58c97e0",
  "agent": {
    "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
    "description": "Answers questions about the sales pipeline",
    "execution_identity": {
      "type": "service_account"
    },
    "mcp_servers": [],
    "model": {
      "id": "default"
    },
    "multiagent": null,
    "name": "Research Assistant",
    "skills": [],
    "system": null,
    "tools": [],
    "type": "agent",
    "version": 1
  },
  "archived_at": null,
  "budget": null,
  "created_at": "2026-10-21T01:42:16.079Z",
  "environment_id": "env_default",
  "metadata": {},
  "outcome_evaluations": [],
  "resources": [
    {
      "id": "329409ba-f288-4b44-9c73-14a18150edee",
      "created_at": "2026-10-21T01:41:11.028Z",
      "file_id": "329409ba-f288-4b44-9c73-14a18150edee",
      "mount_path": "inputs/cities.csv",
      "type": "file",
      "updated_at": "2026-10-21T01:41:11.028Z"
    }
  ],
  "stats": {},
  "status": "idle",
  "title": "Q3 city report",
  "type": "session",
  "updated_at": "2026-10-21T01:42:29.719Z",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 318,
    "cache_read_input_tokens": 133496,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2210,
      "ephemeral_1h_input_tokens": 0
    },
    "active_seconds": 7.331,
    "list_cost": {
      "amount": "6",
      "currency": "USD"
    }
  },
  "vault_ids": []
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	The title is empty, contains only whitespace or is longer than 280 characters. Send a title of 1 to 280 characters, or `null` to clear it.
400	`invalid_request_error`	The body includes `agent`, `vault_ids`, `budget` or a non-empty `metadata`. Send only `title`.
403	`permission_error`	The key does not act for the session’s owner, or the owner is no longer an active member. Use the owner’s personal key or the service account key that created the session.
404	`not_found_error`	No session with this ID exists, or this key can’t read it. Check the session ID.

Example

curl -sS -X POST "$CONTEXT_BASE_URL/v1/sessions/dd13d728-93e3-440a-874c-4efeb58c97e0" -H "x-api-key: $CONTEXT_API_KEY" \
  -H "content-type: application/json" -d '{"title": "Q3 city report"}'

session = client.beta.sessions.update("dd13d728-93e3-440a-874c-4efeb58c97e0", title="Q3 city report")

const session = await client.beta.sessions.update("dd13d728-93e3-440a-874c-4efeb58c97e0", { title: "Q3 city report" })