ChatAgents Session Management API — CRUD Endpoints

The Sessions API gives you full CRUD control over ChatAgents conversation history. Each session is persisted as a JSON file under data/sessions/<session_id>.json, with a lightweight index at data/sessions/index.json that tracks metadata for all sessions. The API does not require any authentication headers — all endpoints are open. In normal usage, sessions are created and updated automatically by /stream_agent; the management endpoints exist for UI integrations and administrative tooling that need to list, rename, or delete conversations.

GET /api/sessions

Returns the metadata for every session, sorted by updated_at descending (most recently active first). Individual message histories are not included — use GET /api/sessions/{session_id} to load the full content of a single session. No request parameters.

Response Body

sessions

array

required

An array of session metadata objects, sorted by updated_at descending.

Show Session metadata object

session_id

string

The unique identifier for this session, typically a UUID.

title

string

Human-readable session title. Auto-generated from the first message when the session is created by /stream_agent.

created_at

string

ISO 8601 timestamp of when the session was first created.

updated_at

string

ISO 8601 timestamp of the most recent write to this session.

message_count

integer

Total number of messages (user + assistant) stored in the session.

Example

curl http://localhost:8080/api/sessions

{
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "What is LangGraph?",
      "created_at": "2024-01-01T12:00:00",
      "updated_at": "2024-01-01T12:05:00",
      "message_count": 4
    },
    {
      "session_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "title": "Compare LangChain and LangGraph",
      "created_at": "2024-01-01T09:30:00",
      "updated_at": "2024-01-01T09:45:00",
      "message_count": 6
    }
  ]
}

GET /api/sessions/{session_id}

Returns the full session object including the complete ordered message history. Use this endpoint to restore a prior conversation in the UI or to export a session’s content.

Path Parameters

session_id

string

required

The unique session identifier. Must match a session that exists in the index.

Response Body

session_id

string

The session’s unique identifier.

title

string

The session title.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 timestamp of the last update.

messages

array

Ordered list of all messages in the conversation.

Show Message object

role

string

Either "user" or "assistant".

content

string

The full text of the message.

timestamp

string

ISO 8601 timestamp of when this message was recorded.

tool_calls

array

Present on assistant messages only when the agent invoked one or more tools during that turn. Each entry records the tool interaction details.

Returns 404 Not Found if no session file exists for the given session_id.

Example

curl http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "What is LangGraph?",
  "created_at": "2024-01-01T12:00:00",
  "updated_at": "2024-01-01T12:05:00",
  "messages": [
    {
      "role": "user",
      "content": "What is LangGraph?",
      "timestamp": "2024-01-01T12:00:01"
    },
    {
      "role": "assistant",
      "content": "LangGraph is a library for building stateful, multi-actor applications with LLMs...",
      "timestamp": "2024-01-01T12:00:15",
      "tool_calls": []
    }
  ]
}

POST /api/sessions

Creates a new, empty session. The session file is written to data/sessions/<session_id>.json and the index at data/sessions/index.json is updated atomically.

Request Body

session_id

string

required

The identifier to use for the new session. Should be a UUID to avoid collisions with sessions created by /stream_agent.

title

string

Optional display title. If omitted, the session_id string is used as the title.

Response Body

Returns the newly created session data object (identical shape to GET /api/sessions/{session_id}), with an empty messages array.

Example

curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My new conversation"
  }'

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "My new conversation",
  "created_at": "2024-01-01T12:00:00",
  "updated_at": "2024-01-01T12:00:00",
  "messages": []
}

PUT /api/sessions/{session_id}

Renames a session by updating its title field in both the session file and the index. The updated_at timestamp is refreshed automatically.

Path Parameters

session_id

string

required

The identifier of the session to rename.

Request Body

title

string

required

The new display title for the session.

Response Body

success

boolean

true when the rename completed successfully.

message

string

A confirmation message.

Returns 404 Not Found if no session file exists for the given session_id.

Example

curl -X PUT http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{"title": "LangGraph deep dive"}'

{
  "success": true,
  "message": "重命名成功"
}

DELETE /api/sessions/{session_id}

Permanently deletes a session. Both the session file (data/sessions/<session_id>.json) and its entry in the index (data/sessions/index.json) are removed. This operation cannot be undone.

Path Parameters

session_id

string

required

The identifier of the session to delete. If the session file does not exist, the endpoint still succeeds after cleaning up the index entry.

Response Body

success

boolean

true when the delete completed without error.

message

string

A confirmation message.

Example

curl -X DELETE http://localhost:8080/api/sessions/550e8400-e29b-41d4-a716-446655440000

{
  "success": true,
  "message": "删除成功"
}

Sessions are created and updated automatically by the /stream_agent endpoint at the end of every streaming turn. In most UI integrations you only need to call POST /api/sessions if you want to pre-register a session with a custom title before the first message is sent.

The index file at data/sessions/index.json is the source of truth for the session list and stores only lightweight metadata. Full message content lives in the individual per-session files at data/sessions/<session_id>.json. All writes use a FileLock to prevent race conditions when multiple requests update the index concurrently.

Backend API

ChatAgents Session Management API — CRUD Endpoints

GET /api/sessions

Response Body

Example

GET /api/sessions/{session_id}

Path Parameters

Response Body

Example

POST /api/sessions

Request Body

Response Body

Example

PUT /api/sessions/{session_id}

Path Parameters

Request Body

Response Body

Example

DELETE /api/sessions/{session_id}

Path Parameters

Response Body

Example

Build docs developers (and LLMs) love

Backend API

Documentation Index

​GET /api/sessions

​Response Body

​Example

​GET /api/sessions/{session_id}

​Path Parameters

​Response Body

​Example

​POST /api/sessions

​Request Body

​Response Body

​Example

​PUT /api/sessions/{session_id}

​Path Parameters

​Request Body

​Response Body

​Example

​DELETE /api/sessions/{session_id}

​Path Parameters

​Response Body

​Example

Build docs developers (and LLMs) love

GET /api/sessions

Response Body

Example

GET /api/sessions/{session_id}

Path Parameters

Response Body

Example

POST /api/sessions

Request Body

Response Body

Example

PUT /api/sessions/{session_id}

Path Parameters

Request Body

Response Body

Example

DELETE /api/sessions/{session_id}

Path Parameters

Response Body

Example