Skip to content
SubsidiaDevelopers Get an API keyAPI key

Conversations

Multi-agent debates: put a question to all the agents of a workspace, let them argue for several rounds, and get a structured synthesis.

A conversation is a round table. You create one with a title, then submit a question: the agents of your workspace each give a first position, challenge each other over several rounds, and a synthesis comes back with the points of agreement, the risks, the conditions and a recommended action. It is the endpoint for decisions where one voice is not enough: a go/no-go, a pricing choice, a contract clause with commercial and legal readings.

For a dialogue with a single persona, use Agent chat instead. A debate is much heavier: it runs several model calls per agent per round.

  1. Your question
  2. Initial positions (round 0)
  3. Debate rounds 1 to 3
  4. Convergence check
  5. Synthesis
One call to POST /v1/conversations/:id/message runs the whole debate and returns once the synthesis is ready.

How a debate runs

  1. Who sits at the table. Up to five regular agents of the workspace (any agent not flagged isDevilsAdvocate) plus the workspace's devil's advocate, who is created automatically on first use and always joins. If the workspace has more than five regular agents, only the first five are seated. The workspace needs at least one regular agent, otherwise the call fails.
  2. Round 0. Each agent answers the question in character, drawing on its memories and the documents linked to it.
  3. Debate rounds. Up to three rounds in which each agent reads the others' positions and responds. After each round a convergence score is computed; at 0.85 or above the debate stops early.
  4. Synthesis. A final pass summarises where the table agrees, what was disputed, what could go wrong, and what to do. totalRounds is the number of debate rounds actually run.

Agents form memories during a debate like they do in chat (Agent memory), and the same conversation can receive several questions: each new message continues the same table with the earlier exchange as history.

Authentication and scopes

Use a developer API key (Authentication). On a restricted key, the conversation routes need the conversations scope in addition to your capability scope. A readonly key can list and read conversations but cannot create, run or delete them. Conversations are scoped to the workspace of the key.

Endpoints

POST/v1/conversations

Create a conversation.

API key (Bearer or x-api-key)conversations

Creates an empty conversation (a table with no question yet). The title is shown in lists and is given to the agents as the topic of the debate, so write it as the question or the decision at stake, not as "Session 1".

Request body

  • titlestringrequired
    Topic of the conversation. At least one character.

Request examples

curl https://api.subsidia.protypa.fr/v1/conversations \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Should we open a second office in Lyon?"}'

Responses

The created conversation.

Example response
{ "conversation": {
  "id": "cm2ke7p3b000gqz0fz5c1v8mn",
  "userId": "cm1u0a0000000qz0fowner001",
  "workspaceId": "cm1w0b0000000qz0fworksp01",
  "title": "Should we open a second office in Lyon?",
  "createdAt": "2026-10-09T10:02:44.318Z",
  "tokensUsed": 0,
  "shareToken": null,
  "isPublic": false,
  "goalOverride": null
} }

Errors

  • 400The body has no title, or it is empty.
  • 403read_only_keyThe key carries the readonly scope.
  • 403scope_deniedA restricted key without the conversations scope.

POST/v1/conversations/:id/message

Submit a question and run the debate.

API key (Bearer or x-api-key)conversations

Stores your message, runs the full debate (see How a debate runs) and returns the synthesis. The individual positions are not in this response: they are saved as messages of the conversation, retrieve them with GET /v1/conversations/:id. There is no streaming variant on the public API.

Put everything the table needs in the message: the numbers, the options, the constraint. Agents read the documents linked to them, but a debate is only as good as its question.

Path parameters

  • idstringrequired
    The conversation id.

Request body

  • contentstringrequired
    The question or statement the agents debate.

Request examples

curl https://api.subsidia.protypa.fr/v1/conversations/$CONVERSATION_ID/message \
  --max-time 600 \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "We have 3 letters of intent in Lyon and 5 months of cash buffer. Open an office now, wait, or hire remotely first?"}'

Responses

The synthesis, the number of rounds and the token accounting. synthesis.agentInsights has one entry per participant, the devil's advocate included; shifted is true when that agent changed position during the debate. confidenceLevel and urgency are short free-text labels (for example "low", "medium", "high"). biasNotes and raw (the unparsed synthesis text) may also be present.

Example response
{
  "synthesis": {
    "summary": "The table favours opening in Lyon, but only after the second sales hire is confirmed.",
    "debateEvolution": "Claire moved from opposed to conditional after the cash-flow figures were put on the table.",
    "devilsAdvocateMainAttack": "A second office doubles fixed costs before the pipeline in Lyon is proven.",
    "agentInsights": [
      { "name": "Claire", "role": "Contrôle de gestion", "keyPoint": "Break-even needs 14 months at current margins.", "stance": "conditional", "shifted": true },
      { "name": "Marc", "role": "Directeur commercial", "keyPoint": "Three signed letters of intent in Lyon.", "stance": "for" }
    ],
    "consensus": ["The Lyon market is real.", "Do not sign a lease before the hire."],
    "riskPoints": ["Fixed-cost exposure", "Management attention split across two sites"],
    "recommendedAction": "Hire the Lyon sales lead first; revisit the lease in six months.",
    "conditions": ["Sales lead hired", "Cash reserve above three months"],
    "confidenceLevel": "medium",
    "urgency": "low",
    "roundCount": 2,
    "raw": "..."
  },
  "totalRounds": 2,
  "tokenUsage": { "totalTokensUsed": 41230, "remainingBalance": 958770 }
}

Errors

  • 400Empty or missing content.
  • 404Unknown conversation, or it belongs to another workspace.
  • 500No regular agent in the workspace, insufficient allowance, or model failure. Unlike chat, an exhausted allowance is not a 402 here: read the error message.
  • 429rate_limitedMore than 30 calls per minute on this route, or the key's own limit.

Notes

The first message of a conversation uses the conversation title as the topic when the title was set by you. Reuse a conversation to ask follow-ups on the same decision ("and if we delay the lease by six months?"): the table remembers the earlier exchange.

GET/v1/conversations

List the conversations of the workspace.

API key (Bearer or x-api-key)conversations

Newest first, each with _count.messages. This list is the whole workspace table: it contains debates and the sessions created by Agent chat, since both are conversations. It is not paginated.

Request examples

curl https://api.subsidia.protypa.fr/v1/conversations -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

An object with a conversations array.

Example response
{ "conversations": [
  {
  "id": "cm2ke7p3b000gqz0fz5c1v8mn",
  "userId": "cm1u0a0000000qz0fowner001",
  "workspaceId": "cm1w0b0000000qz0fworksp01",
  "title": "Should we open a second office in Lyon?",
  "createdAt": "2026-10-09T10:02:44.318Z",
  "tokensUsed": 0,
  "shareToken": null,
  "isPublic": false,
  "goalOverride": null,
  "_count": { "messages": 9 }
}
] }

GET/v1/conversations/:id

Get a conversation with its messages and debate rounds.

API key (Bearer or x-api-key)conversations

Returns the full transcript: every message in chronological order and the debate rounds with their convergence scores. Message senderType is one of user, agent, devils-advocate and synthesizer. Agent messages carry metadata.phase (initial for round 0, debate for later rounds), metadata.roundNumber and metadata.isDevilsAdvocate; the synthesizer message holds the synthesis as content and its parsed fields in metadata.

Path parameters

  • idstringrequired
    The conversation id.

Request examples

curl https://api.subsidia.protypa.fr/v1/conversations/$CONVERSATION_ID \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

The conversation with messages and debates.

Example response
{
  "conversation": {
    "id": "cm2ke7p3b000gqz0fz5c1v8mn",
    "title": "Should we open a second office in Lyon?",
    "messages": [
      { "id": "cm2ke8a1c000hqz0f3k2m9d7x", "senderType": "user", "content": "We have 3 letters of intent in Lyon...", "createdAt": "2026-10-09T10:03:01.002Z" },
      {
        "id": "cm2ke8d4e000iqz0fp8w6n1ba",
        "senderType": "agent",
        "agentId": "cm2k8x1ab0001qz0f7h3d9t4e",
        "agentName": "Claire",
        "agentRole": "Contrôle de gestion",
        "content": "Break-even needs 14 months at current margins...",
        "metadata": { "phase": "initial", "roundNumber": 0, "isDevilsAdvocate": false },
        "createdAt": "2026-10-09T10:03:19.554Z"
      }
    ],
    "debates": [
      { "id": "cm2ke9z8f000jqz0fq4t1h6cy", "roundNumber": 1, "convergenceScore": 0.62, "createdAt": "2026-10-09T10:03:40.101Z" },
      { "id": "cm2kea5ng000kqz0fb7r3e9wk", "roundNumber": 2, "convergenceScore": 0.88, "createdAt": "2026-10-09T10:04:02.667Z" }
    ]
  }
}

Errors

  • 404No conversation with this id in the workspace.

DELETE/v1/conversations/:id

Delete a conversation and its messages.

API key (Bearer or x-api-key)conversations

Removes the conversation and its messages. It works for chat sessions. Memories the agents formed along the way are not removed.

Path parameters

  • idstringrequired
    The conversation id.

Request examples

curl
curl -X DELETE https://api.subsidia.protypa.fr/v1/conversations/$CONVERSATION_ID \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

Deleted. No body.

Errors

  • 404No conversation with this id in the workspace.
  • 403read_only_keyThe key carries the readonly scope.

Notes

The route deletes the messages and the conversation row only. A conversation that has run a debate also has debate-round records attached, which this route does not remove, so deleting such a conversation can fail with a 500. Chat sessions have no such records.

Working with debates

  • Seat the right people. The cast is the first five regular agents of the workspace, in creation order. Keep a workspace for debates lean and deliberately diverse (finance, sales, legal, operations), and rely on the built-in devil's advocate rather than creating one.
  • Read the dissent, not just the summary. devilsAdvocateMainAttack, riskPoints and conditions are where a debate earns its cost. A consensus reached in one round with a high convergence score on a weak question is a sign that your agents are too similar.
  • Store the transcript. GET /v1/conversations/:id is the record of who said what in which round. Keep the conversation id next to the decision it informed.
  • A debate informs, a human decides. The synthesis is a structured opinion, not a verdict.

Related

Agents
Create, read, update and delete the agents (personas) of a workspace through the API.
Agent chat
Talk to one agent, or let Subsidia pick the best-fit agent: multi-turn sessions, knowledge citations, tool calls, structured JSON and a server-sent event stream.
Sessions
Chat sessions keep the history of a conversation with an agent: create one, continue it, list and replay it.
Model addressing
The model field is an address: prefixes pick who answers (Synapse, a full model, a local model, one of your agents) and +flags add or remove capabilities.