Sessions
Chat sessions and messages, including the streaming UI message protocol.
A session is a chat thread between users and agents. It owns a list of messages and may be attached to a project and an agent. Streaming responses are delivered through the AI SDK v6 UI message stream protocol.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/sessions | List recent sessions. |
POST | /api/v1/sessions | Create a session. |
GET | /api/v1/sessions/:id | Fetch one session. |
PATCH | /api/v1/sessions/:id | Update session fields. |
DELETE | /api/v1/sessions/:id | Soft-delete a session. |
GET | /api/v1/sessions/:id/messages | List messages with cursor pagination. |
POST | /api/v1/sessions/:id/messages | Append a user or assistant message. |
POST | /api/v1/chat | Send a turn and receive a streamed UI message stream. |
GET | /api/v1/chat/:sessionId/stream | Server-Sent Events for live session updates. |
POST | /api/v1/chat/:sessionId/stop | Cancel an in-flight turn. |
POST | /api/v1/chat/:sessionId/resume | Resume a paused/awaiting session. |
List sessions
GET /api/v1/sessions returns up to 50 non-deleted sessions ordered by updatedAt desc.
Query parameters:
| Name | Type | Description |
|---|---|---|
projectId | string | Filter to one project (UUID or slug). |
copilot | "true" | Restrict to copilot-surface sessions. |
Each item is the session row enriched with agentName and agentAvatar when an agent is attached.
Create session
POST /api/v1/sessions
| Field | Type | Required | Description |
|---|---|---|---|
label | string | no | Up to 255 chars. Defaults to New chat. |
projectId | string | no | Must belong to the caller's org and visible workspace. |
agentId | string | no | Must belong to the caller's org and visible workspace. |
metadata | object | no | Free-form JSON. |
The caller is added as a user participant, and the agent (if any) as an agent participant.
Response (201): the session record.
Get / update / delete
GET /api/v1/sessions/:id— Returns a single session.PATCH /api/v1/sessions/:id— Acceptslabel,status(active,awaiting_peer,idle,completed,failed),metadata,projectId,agentId. SettingprojectIdoragentIdtonullor""clears the link.DELETE /api/v1/sessions/:id— Soft-delete. Returns{ "deleted": true }.
Messages
GET /api/v1/sessions/:id/messages returns messages ordered by createdAt then id ascending.
Query parameters:
| Name | Type | Description |
|---|---|---|
pageSize | number | 1–500, default 200. |
cursor | string | Message ID returned as nextCursor from the previous page. |
countOnly | "true" | Return { "total": N } only. |
Tool-call parts are sanitized server-side; assistant messages without persistable content are filtered out.
POST /api/v1/sessions/:id/messages
| Field | Type | Required | Description |
|---|---|---|---|
content | string | yes | 1–100,000 chars. |
role | "user" | "assistant" | no | Defaults to user. |
The session's updatedAt is bumped. Returns the inserted message (201).
Streaming a turn
POST /api/v1/chat runs a single agent turn and streams the response as a UI message stream (Content-Type: text/event-stream). The response is produced via AI SDK v6 streamText + createUIMessageStreamResponse. Clients should consume it with the AI SDK UI helpers (useChat, readUIMessageStream, etc.) rather than parsing raw SSE.
GET /api/v1/chat/:sessionId/stream is a separate Server-Sent Events channel that surfaces canvas-side activity for the session (new messages, peer activity, status). It uses keep-alive pings and closes on idle timeout.
POST /api/v1/chat/:sessionId/stop cancels the active turn by terminating its job; safe to call when no turn is running. POST /api/v1/chat/:sessionId/resume restarts a session that was paused awaiting peer input.
curl -N -X POST https://alumia.com/api/v1/chat \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"id": "<sessionId>",
"messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Hello" }] }]
}'Errors
| Code | When |
|---|---|
UNAUTHORIZED | No valid key. |
BAD_REQUEST | Invalid label, metadata, role, oversized content, unknown projectId/agentId, invalid status. |
FORBIDDEN | Caller has no workspace access. |
NOT_FOUND | Session, project, or agent not visible to the caller. |