Chat & Conversations

Overview

Chat conversations are the primary interface between users and the Praxiom AI copilot. Each conversation belongs to a workspace and a user, and contains an ordered list of messages. Conversations support archiving, search across messages, and pagination.

---

Create Conversation

POST /api/chat/conversations

Create a new conversation in a workspace.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
title	string	No	Conversation title (default: "New Conversation")

Example Request

curl -X POST https://api.praxiomai.xyz/api/chat/conversations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Onboarding analysis"
  }'

Response (201 Created)

{
  "id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Onboarding analysis",
  "purpose": null,
  "working_state": null,
  "is_archived": false,
  "resumed_from": null,
  "created_at": "2026-03-27T15:00:00Z"
}

---

List Conversations

GET /api/chat/conversations

List conversations for a workspace with pagination. Sorted by most recent message.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
limit	integer	No	Max results (default: 20, max: 100)
offset	integer	No	Pagination offset (default: 0)
include_archived	boolean	No	Include archived conversations (default: false)

Response (200 OK)

{
  "conversations": [ ... ],
  "total": 12,
  "has_more": true
}

---

Search Conversations

GET /api/chat/conversations/search

Search across all messages in a workspace.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
q	string	Yes	Search query (min 1 character)
limit	integer	No	Max results (default: 20, max: 100)

Response (200 OK)

{
  "results": [
    {
      "conversation_id": "a7b8c9d0-...",
      "title": "Onboarding analysis",
      "message_content": "The onboarding flow has several friction points...",
      "message_created_at": "2026-03-27T15:05:00Z"
    }
  ],
  "total": 3
}

---

Get Conversation

GET /api/chat/conversations/{conversation_id}

Get a conversation with all messages. Only the conversation owner can access.

Response (200 OK)

Returns the conversation object with a messages array containing all messages in chronological order.

---

Conversation Intelligence Fields

Conversations track rich metadata for multi-session workflows:

Field	Type	Description
purpose	string	Inferred purpose of the conversation (set after first agent response)
working_state	string	Current activity: planning, researching, drafting, or executing
resumed_from	UUID	ID of a prior conversation this one continues from

These fields are set automatically by the agent and enable conversation briefing on resumption.

---

Update Conversation

PATCH /api/chat/conversations/{conversation_id}

Rename or archive a conversation.

Request Body

Name	Type	Required	Description
title	string	No	New title
is_archived	boolean	No	Archive or unarchive

---

Archive Conversation

POST /api/chat/conversations/{conversation_id}/archive

Soft-delete a conversation by archiving it.

---

Restore Conversation

POST /api/chat/conversations/{conversation_id}/restore

Restore an archived conversation.

---

Delete Conversation

DELETE /api/chat/conversations/{conversation_id}

Hard delete a conversation and all its messages.

Response (204 No Content)

---

List Messages

GET /api/chat/conversations/{conversation_id}/messages

List messages in a conversation with optional cursor-based pagination.

Query Parameters

Name	Type	Required	Description
limit	integer	No	Max messages (default: 100, max: 500)
before	datetime	No	ISO datetime to load messages before (for pagination)

Response (200 OK)

[
  {
    "id": "b8c9d0e1-f2a3-4567-bcde-890123456789",
    "conversation_id": "a7b8c9d0-...",
    "role": "user",
    "content": "What are the main onboarding pain points?",
    "created_at": "2026-03-27T15:05:00Z"
  },
  {
    "id": "c9d0e1f2-a3b4-5678-cdef-901234567890",
    "conversation_id": "a7b8c9d0-...",
    "role": "assistant",
    "content": "Based on the 12 research sources in your workspace...",
    "inferred_intent": "research_query",
    "thinking_blocks": [],
    "decision_context": {"model": "claude-sonnet-4-20250514", "effort": "high"},
    "created_at": "2026-03-27T15:05:15Z"
  }
]

Message Intelligence Fields

Field	Type	Description
inferred_intent	string	Classified intent of the message
thinking_blocks	array	Agent reasoning chains (when extended thinking is enabled)
decision_context	object	Configuration snapshot (model, effort, intent) for replay and auditing
execution_metadata	object	Tool step details with timing information