Conversations

Conversations are the core unit of PersonAI Debates. Each conversation holds a thread of user messages and multi-agent responses. When you send a message, all configured agents respond in debate rounds until they converge on a recommendation.

List all conversations in your workspace, ordered by most recent.

Response

{
  "conversations": [
    {
      "id": "clx1a2b3c",
      "title": "Q4 expansion strategy",
      "createdAt": "2026-06-03T10:00:00Z",
      "_count": { "messages": 14 }
    }
  ]
}

curl https://api.yourdomain.com/v1/conversations \
  -H "x-api-key: sk_live_xxx"

Create a new conversation thread.

Request body

Name	Type	Required	Description
`title`	`string`	required	Descriptive title for the conversation

Response

{
  "conversation": {
    "id": "clx1a2b3c",
    "title": "Q4 expansion strategy",
    "userId": "usr_xxx",
    "workspaceId": "ws_xxx",
    "createdAt": "2026-06-03T10:00:00Z"
  }
}

curl -X POST https://api.yourdomain.com/v1/conversations \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q4 expansion strategy"}'

Get a single conversation with its full message history and debate rounds.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Conversation ID

Response

{
  "conversation": {
    "id": "clx1a2b3c",
    "title": "Q4 expansion strategy",
    "messages": [...],
    "debates": [
      { "roundNumber": 1, "convergenceScore": 0.72 }
    ]
  }
}

Send a message to the conversation. Triggers a full multi-agent debate round. All agents respond, then a synthesis is produced. Returns agent messages and a convergence score.

Path / Query parameters

Name	Type	Required	Description
`id`	`string`	required	Conversation ID

Request body

Name	Type	Required	Description
`content`	`string`	required	The user message or question to debate

Response

{
  "messages": [
    { "senderType": "user", "content": "Should we expand into Europe?" },
    { "senderType": "agent", "agentName": "Victoria Chen", "content": "..." },
    { "senderType": "agent", "agentName": "Marcus Wells", "content": "..." },
    { "senderType": "synthesis", "content": "Consensus summary..." }
  ],
  "convergenceScore": 0.81
}

curl -X POST https://api.yourdomain.com/v1/conversations/<id>/message \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Should we expand into Europe this quarter?"}'