API Reference: Sessions

POST /sessions/

Summary: Create a New Chat Session

Description: Create a New Chat Session

Request Body

Required: Yes

• Media Type: application/json
• Schema: SessionCreate (Define in Models)

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /sessions/

Summary: Get All Chat Sessions

Description: Get All Chat Sessions

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
  -H 'accept: application/json'

DELETE /sessions/

Summary: Delete All Sessions for Feature

Description: Delete All Sessions for Feature

Parameters

Responses

Example Usage

curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/?user_id=<user_id>&feature_name=<feature_name>' \
  -H 'accept: application/json'

POST /sessions/{session_id}/chat

Summary: Send a Message in a Session (Streaming)

Description: Streams AI response using Server-Sent Events (SSE). Yields tokens, reasoning, and tool executions in real-time.

Parameters

Request Body

Required: Yes

• Media Type: application/json
• Schema: ChatRequest (Define in Models)

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/chat' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /sessions/{session_id}/messages

Summary: Get Session Chat History

Description: Get Session Chat History

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/messages' \
  -H 'accept: application/json'

POST /sessions/{session_id}/clear-history

Summary: Clear Chat History (Preserve Session)

Description: Deletes all messages for a session but preserves the session itself (node attachments, workspace ID, sync config, title all remain intact). Useful in Swarm Control to start a fresh chat without losing the file sync workspace.

Parameters

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/clear-history' \
  -H 'accept: application/json'

GET /sessions/{session_id}/tokens

Summary: Get Session Token Usage

Description: Get Session Token Usage

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/tokens' \
  -H 'accept: application/json'

GET /sessions/{session_id}

Summary: Get a Single Session

Description: Get a Single Session

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json'

PATCH /sessions/{session_id}

Summary: Update a Chat Session

Description: Update a Chat Session

Parameters

Request Body

Required: Yes

• Media Type: application/json
• Schema: SessionUpdate (Define in Models)

Responses

Example Usage

curl -X 'PATCH' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /sessions/{session_id}

Summary: Delete a Chat Session

Description: Delete a Chat Session

Parameters

Responses

Example Usage

curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/{session_id}' \
  -H 'accept: application/json'

POST /sessions/messages/{message_id}/audio

Summary: Upload audio for a specific message

Description: Upload audio for a specific message

Parameters

Request Body

Required: Yes

• Media Type: multipart/form-data
• Schema: Body_upload_message_audio_sessions_messages__message_id__audio_post (Define in Models)

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/file'

GET /sessions/messages/{message_id}/audio

Summary: Get audio for a specific message

Description: Get audio for a specific message

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/messages/{message_id}/audio' \
  -H 'accept: application/json'

POST /sessions/{session_id}/nodes

Summary: Attach Nodes to Session

Description: Attach one or more Agent Nodes to a chat session.

Parameters

Request Body

Required: Yes

• Media Type: application/json
• Schema: NodeAttachRequest (Define in Models)

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /sessions/{session_id}/nodes

Summary: Get Session Node Status

Description: Returns all nodes attached to a session and their current sync status. Merges persisted sync_status with live connection state from the registry.

Parameters

Responses

Example Usage

curl -X 'GET' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes' \
  -H 'accept: application/json'

DELETE /sessions/{session_id}/nodes/{node_id}

Summary: Detach Node from Session

Description: Detach Node from Session

Parameters

Responses

Example Usage

curl -X 'DELETE' \
  'http://localhost:8000/api/v1/sessions/{session_id}/nodes/{node_id}' \
  -H 'accept: application/json'

POST /sessions/{session_id}/cancel

Summary: Cancel Running AI Task

Description: Cancel Running AI Task

Parameters

Responses

Example Usage

curl -X 'POST' \
  'http://localhost:8000/api/v1/sessions/{session_id}/cancel' \
  -H 'accept: application/json'