13  Chat Sessions

9 operations.

13.0.1 listChatSessions

GET /api/chat-sessions

Lists your 50 most recent conversations.

Why it exists. ‡ List the caller’s saved conversations for the chat sidebar. Accepts a bearer token as well as a session, so tool callers can reach their own history.

Called by — hooks/use-chat-history.ts

Returns the caller’s 50 most recently updated chat sessions. Accepts a bearer JWT, a jwt_token query parameter, or the session cookie.

Authentication: SupabaseAuth, CookieAuth

Returns — sessions

Field names as the handler returns them; the source states no types for them.

Effect — reads chat_sessions

Parameters

Name	In	Required	Type	Notes
jwt_token	query	no	string

Responses

Status	Meaning	Body
200	Session list (max 50, newest first).
401	JWT token or session required.	Error
500	Failed to fetch chat sessions.	Error

13.0.2 createChatSession

POST /api/chat-sessions

Starts a new saved conversation.

Why it exists. ‡ Start a conversation, attributed to the caller and their organisation, so the exchange can be resumed and audited later.

Called by — hooks/use-chat-history.ts

Creates a chat session for the caller. Requires organization membership. Accepts a bearer JWT, a legacy jwt_token body field, or the session cookie.

Authentication: SupabaseAuth, CookieAuth

Returns — session

Field names as the handler returns them; the source states no types for them.

Effect — writes (insert) chat_sessions · organization_members

Request body

Field	Type	Required
title	string	no
system_type	string	no
jwt_token	string	no

Responses

Status	Meaning	Body
200	Created session (returned with status 200).
401	JWT token or session required.	Error
403	User must belong to an organization.	Error
500	Failed to create chat session.	Error

13.0.3 verifyChatStorage

GET /api/chat-sessions/verify

Produces a health report on your stored conversations (counts, anomalies).

Why it exists. ‡ Report on the integrity of the caller’s chat history — counts, and sessions or messages that have come adrift of each other.

Called by — components/chat-storage-monitor.tsx

Chat-storage integrity report for the caller — counts, recent sessions, and detected anomalies (empty sessions, orphaned messages). Uses the get_user_chat_stats RPC when available, with a paginated set-difference scan as fallback (an oversized history is reported as a truncated, partial scan). Cookie session only.

Authentication: CookieAuth

Returns — user_id · user_email · verification · timestamp

Field names as the handler returns them; the source states no types for them.

Effect — reads chat_sessions · messages

Responses

Status	Meaning	Body
200	Verification report.
401	Unauthorized.	Error
500	Verification query failed.	Error

13.0.4 cleanUpChatStorage

POST /api/chat-sessions/verify

Cleans up broken conversation data (empty sessions, orphaned messages).

Why it exists. † Repair the caller’s chat history by removing messages whose session is gone and sessions that hold no messages.

Destructive cleanup of the caller’s chat storage — deletes orphaned messages or empty sessions. Cookie session only.

Authentication: CookieAuth

Returns — action · deleted_count · status

Field names as the handler returns them; the source states no types for them.

Effect — writes (delete) chat_sessions · messages

Request body

Field	Type	Required
action	string — one of fix_orphaned_messages, cleanup_empty_sessions	yes

Responses

Status	Meaning	Body
200	Cleanup completed.
400	Unknown action.	Error
401	Unauthorized.	Error
409	Repair refused — the history exceeds the verification scan caps, so orphan classification would be unreliable.	Error
500	Cleanup failed.	Error

13.0.5 getChatSession

GET /api/chat-sessions/{sessionId}

Opens one conversation with all its messages.

Why it exists. ‡ Load one conversation with its messages, including the structured payloads behind rendered reports, so a session reopens exactly as it was.

Called by — hooks/use-agui-client.ts · hooks/use-chat-history.ts

Returns one owned session plus all its messages in chronological order.

Authentication: SupabaseAuth, CookieAuth

Returns — session · messages

Field names as the handler returns them; the source states no types for them.

Effect — reads chat_sessions · messages

Parameters

Name	In	Required	Type	Notes
sessionId	path	yes	string

Responses

Status	Meaning	Body
200	Session and messages.
401	JWT token or session required.	Error
404	Chat session not found (or not owned by the caller).	Error
500	Failed to fetch messages.	Error

13.0.6 renameChatSession

PATCH /api/chat-sessions/{sessionId}

Renames a conversation.

Why it exists. ‡ Rename a conversation, so a session can be given a title that says what it was about.

Called by — hooks/use-chat-history.ts

Renames an owned session. Accepts a bearer JWT or the session cookie (the same fallback GET/DELETE on this path use). A missing/unowned session surfaces as 500, not 404.

Authentication: SupabaseAuth, CookieAuth

Returns — session

Field names as the handler returns them; the source states no types for them.

Effect — writes (update) chat_sessions

Parameters

Name	In	Required	Type	Notes
sessionId	path	yes	string

Request body

Field	Type	Required
title	string	yes

Responses

Status	Meaning	Body
200	Updated session.
400	title is required.	Error
401	Unauthorized.	Error
500	Failed to update chat session (includes the not-found case).	Error

13.0.7 deleteChatSession

DELETE /api/chat-sessions/{sessionId}

Deletes a conversation and its messages.

Why it exists. ‡ Delete a conversation and its messages.

Called by — hooks/use-chat-history.ts

Deletes a session’s messages, then the session. Accepts a bearer JWT or the session cookie. Deleting a nonexistent session still returns success.

Authentication: SupabaseAuth, CookieAuth

Returns — success

Field names as the handler returns them; the source states no types for them.

Effect — writes (delete) chat_sessions · messages

Parameters

Name	In	Required	Type	Notes
sessionId	path	yes	string

Responses

Status	Meaning	Body
200	Deleted.
401	Unauthorized.	Error
500	Failed to delete messages or chat session.	Error

13.0.8 exportChatSession

GET /api/chat-sessions/{sessionId}/export

Downloads a conversation transcript as a spreadsheet (CSV) or document (Markdown).

Why it exists. ‡ Export a conversation as markdown or structured data, so an exchange that reached a conclusion can leave the platform as a record.

Called by — hooks/use-chat-history.ts

Downloads the transcript as CSV (default) or Markdown. Any format value other than “csv” yields Markdown. Accepts bearer JWT, jwt_token query parameter, or session cookie.

Authentication: SupabaseAuth, CookieAuth

Returns — not readable from the source: the handler returns a value assembled at run time rather than a literal.

Effect — reads chat_sessions · messages

Parameters

Name	In	Required	Type	Notes
sessionId	path	yes	string
format	query	no	string
jwt_token	query	no	string

Responses

Status	Meaning	Body
200	File download (Content-Disposition attachment).
401	Unauthorized.	Error
404	Session not found.	Error
500	Failed to fetch messages.	Error

13.0.9 appendChatSessionMessage

POST /api/chat-sessions/{sessionId}/messages

Adds a message to a conversation (the first message becomes its title).

Why it exists. † Append a message to a conversation, naming the first user message as the session title so the sidebar reads usefully without anyone titling anything.

Appends a message to an owned session, bumping its updated_at; the first user message auto-titles the session (truncated to 40 chars). Cookie session only.

Authentication: CookieAuth

Returns — message

Field names as the handler returns them; the source states no types for them.

Effect — writes (insert, update) chat_sessions · messages

Parameters

Name	In	Required	Type	Notes
sessionId	path	yes	string

Request body

Field	Type	Required
content	string	yes
is_user	boolean	no

Responses

Status	Meaning	Body
200	Created message.
400	Content is required.	Error
401	Unauthorized.	Error
404	Chat session not found.	Error
500	Failed to create message.	Error