Sessions group conversations and ingested documents together. Every chat message and ingested document belongs to a session.
All session endpoints require authentication.
List sessions
GET /api/v1/session/
Returns all sessions belonging to the authenticated user.
Response
200 OK
Array of session objects for the current user.
Example
curl -X GET http://localhost:3000/api/v1/session/ \
-H "Authorization: Bearer <token>"
[
{
"id": "sess_abc123",
"label": "Q3 Analysis",
"user_id": "usr_xyz",
"createdAt": "2026-04-01T09:00:00Z"
}
]
Create session
POST /api/v1/session/
Creates a new session for the authenticated user.
Request body
A human-readable name for the session (e.g. "Q3 Analysis").
Response
201 Created
The newly created session object.
Unique session identifier.
The label provided in the request.
ID of the authenticated user who owns this session.
ISO 8601 timestamp of when the session was created.
500 Internal Server Error
Always "Internal Server Error".
Machine-readable error code.
Example
curl -X POST http://localhost:3000/api/v1/session/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "label": "Q3 Analysis" }'
{
"data": {
"id": "sess_abc123",
"label": "Q3 Analysis",
"user_id": "usr_xyz",
"createdAt": "2026-04-01T09:00:00Z"
}
}
Rename session
PATCH /api/v1/session/:sessionId
Updates the label of an existing session.
Path parameters
The ID of the session to rename.
Request body
The new label for the session.
Response
200 OK
The updated session object.
Example
curl -X PATCH http://localhost:3000/api/v1/session/sess_abc123 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "label": "Q3 Final Report" }'
{
"data": {
"id": "sess_abc123",
"label": "Q3 Final Report",
"user_id": "usr_xyz"
}
}
Delete session
Deleting a session is permanent. Associated chat history and document references may also be removed.
DELETE /api/v1/session/:sessionId
Deletes a session by ID.
Path parameters
The ID of the session to delete.
Response
204 No Content
Returned on success. The response body is empty.
Example
curl -X DELETE http://localhost:3000/api/v1/session/sess_abc123 \
-H "Authorization: Bearer <token>"