Rename 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.

Rename request

Send the new name as JSON:

{"session_name":"Support conversation"}

The response is the complete type-specific session detail, not just the new name. Agent and Team responses include chat_history; Workflow responses contain workflow/session state instead. Renaming does not rewrite stored run messages.

POST/sessions/{session_id}/rename

Update the name of an existing session. Useful for organizing and categorizing sessions with meaningful names for better identification and management.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

session_id*Session Id

Session ID to rename

Query Parameters

type?|

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

user_id?|

User ID to scope rename to

db_id?|

Database ID to use for rename operation

table?|

Table to use for rename operation

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/sessions/string/rename' \  --header 'Content-Type: application/json' \  --data-raw '{"session_name":"string"}'
{  "user_id": "123",  "agent_session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",  "session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",  "session_name": "What tools do you have?",  "session_summary": {    "summary": "The user and assistant engaged in a conversation about the tools the agent has available.",    "updated_at": "2025-09-05T18:02:12.269392"  },  "session_state": {},  "agent_id": "basic-agent",  "total_tokens": 160,  "agent_data": {    "name": "Basic Agent",    "agent_id": "basic-agent",    "model": {      "provider": "OpenAI",      "name": "OpenAIChat",      "id": "gpt-4o"    }  },  "metrics": {    "input_tokens": 134,    "output_tokens": 26,    "total_tokens": 160,    "audio_input_tokens": 0,    "audio_output_tokens": 0,    "audio_total_tokens": 0,    "cache_read_tokens": 0,    "cache_write_tokens": 0,    "reasoning_tokens": 0  },  "chat_history": [    {      "content": "<additional_information>\n- Use markdown to format your answers.\n- The current time is 2025-09-05 18:02:09.171627.\n</additional_information>\n\nYou have access to memories from previous interactions with the user that you can use:\n\n<memories_from_previous_interactions>\n- User really likes Digimon and Japan.\n- User really likes Japan.\n- User likes coffee.\n</memories_from_previous_interactions>\n\nNote: this information is from previous interactions and may be updated in this conversation. You should always prefer information from this conversation over the past memories.",      "from_history": false,      "stop_after_tool_call": false,      "role": "system",      "created_at": 1757088129    },    {      "content": "What tools do you have?",      "from_history": false,      "stop_after_tool_call": false,      "role": "user",      "created_at": 1757088129    },    {      "content": "I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!",      "from_history": false,      "stop_after_tool_call": false,      "role": "assistant",      "metrics": {        "input_tokens": 134,        "output_tokens": 26,        "total_tokens": 160      },      "created_at": 1757088129    }  ],  "created_at": "2025-09-05T16:02:09Z",  "updated_at": "2025-09-05T16:02:09Z"}