API Reference · Sessions & Messages

Chat Sessions & Messages API

Create, list, rename, pin, star, and delete chat sessions, and manage individual messages within them — including tracked edit history and undo.

← Back to Docs Jump to Endpoints

Session Endpoints

POST /api/v1/sessions

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}/messages

PATCH /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

Message Endpoints

GET /api/v1/messages/{message_id}

PATCH /api/v1/messages/{message_id}

GET /api/v1/messages/{message_id}/history

POST /api/v1/messages/{message_id}/undo

DELETE /api/v1/messages/{message_id}

Create Session — Request Body

json

{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id is not accepted from the client in personal runtime, and is required to match the active workspace runtime context otherwise — it is never taken as an arbitrary client override.

List — Query Parameters & Response

kindagent_idpinnedlimit (default 50, max 200)offset (default 0)

json

{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Update Session (PATCH)

At least one field must be present in the request body — an empty PATCH is rejected.

titlepinnedstarredmarked_unread

json

{
  "pinned": true,
  "starred": false
}

Session Behaviors

A session belongs to exactly one owner (a user, optionally scoped to a workspace) — determined by the authenticated request context, not by client input.
Deleting a session is a soft delete (deleted_at is set); the session and its messages remain in the database but are excluded from all standard queries.
GET /sessions/{session_id}/messages returns a message count computed live from the messages themselves, not a cached counter.
session_id and message_id path parameters are validated as UUIDs — a malformed ID returns a clean validation error, not a server error.
Marketing website demo sessions are limited to 3 per user and return 403 once that limit is reached.

Message Edit History & Undo

Every edit to a message's content or payload is recorded before the change is applied, preserving the prior version.

json

[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]

A message can only be edited or deleted by the owner of the session it belongs to.
Undo restores the most recent recorded version and removes that history entry — it does not step further back than the last edit.
Editing or deleting a message does not currently adjust the session's cached message count field; it always reflects the live count instead.

Error Models

400

Invalid request — including an empty PATCH body or no detected changes.

401

Missing or invalid authentication.

404

Session or message not found (or not owned by the caller).

Examples

Create a Session

bash

curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Pin a Session

bash

curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Edit a Message

bash

curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Undo the Last Edit

bash

curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"