Documentation
Conversational Triage API
Build your solution
Conversations

Conversations

A conversation is the server-owned container for a triage session. This page covers creating one, reading it back, and the instance metadata endpoint.

Create a conversation

POST /conversations

The body is a ConversationInput with two required objects, settings and assessment. Every field inside them is optional.

cURL
curl "https://api.infermedica.com/api/ct/v2/conversations" \
  -X "POST" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "language": "en",
      "channel": "text",
      "ui_widgets_enabled": false,
      "opening_message_enabled": false
    },
    "assessment": {
      "age": { "value": 35, "unit": "year" },
      "sex": "female",
      "relationship": "self",
      "evidence": []
    }
  }'

Response: 201 Created, body is a Conversation.

JSON
{
  "id": "68d9a84d-711c-4a55-a9dd-da6363e58e38",
  "status": "in_progress",
  "settings": {
    "language": "en",
    "channel": "text",
    "ui_widgets_enabled": false,
    "opening_message_enabled": false,
    "risk_factors_enabled": true,
    "geographic_risk_factors_enabled": false,
    "handoff_policies": [],
    "max_message_length": 1500
  },
  "assessment": {
    "age": { "value": 35, "unit": "year" },
    "sex": "female",
    "relationship": "self",
    "evidence": [],
    "unmatched_evidence": [],
    "conditions": [],
    "recommendation": null
  },
  "messages": [],
  "is_terminated": false
}

Seeding the assessment

assessment on create is a seed, not a full write model: recommendation, unmatched_evidence and conditions are read-only and rejected.

FieldTypeDescription
ageAge{ "value": 35, "unit": "year" }. unit is year or month; value may be 0 only for months, and the maximum is 130 years.
sex"male" or "female"Patient sex.
relationshipPatientRelationshipself, child, or other — who the user is answering for.
evidenceEvidenceInput[]Pre-collected evidence, each { "id": "s_21", "state": "present" }.

Seeded evidence is recorded with origin: "seeded" so you can tell it apart from what the assistant collected. Ids must exist in the knowledge base — an unknown id fails the whole create with unknown_evidence (422), or closes the WebSocket after an unknown_evidence error event.

ℹ️

Evidence ids are the same concept ids used across the Infermedica platform (s_21, p_9, c_49, …). Use Engine API search or the medical content lists to resolve them.

Read a conversation

GET /conversations/{conversation_id}

Returns the current snapshot: 200 OK with a Conversation. This is the call to make after a reconnect, when a second surface joins an in-flight session, or whenever you need history.

JSON
{
  "id": "68d9a84d-711c-4a55-a9dd-da6363e58e38",
  "status": "in_progress",
  "settings": { "...": "..." },
  "assessment": { "...": "..." },
  "messages": [
    {
      "role": "user",
      "content": "I have a headache",
      "id": "68d9a84d-711c-4a55-a9dd-da6363e58e38",
      "turn_id": "a1b2c3d4-0000-0000-0000-000000000000"
    },
    {
      "role": "assistant",
      "id": "6f605890-ff28-4b6d-a17f-d410f9faf558",
      "kind": "follow_up",
      "content_parts": [
        { "type": "text", "text": "How long have you had it?" }
      ],
      "turn_id": "a1b2c3d4-0000-0000-0000-000000000000"
    }
  ],
  "is_terminated": false
}

messages is a union discriminated by role: user rows carry content only, assistant rows carry content_parts only. Branch on role — see Messages and content parts.

Snapshot reads are also self-healing: any assistant output the server has since invalidated is already absent, so history needs no client-side reconciliation.

Update settings

PATCH /conversations/{conversation_id}/settings

A partial update — omitted fields keep their current value. Response: 200 OK with the full effective ConversationSettings. See Settings.

JSON
{ "language": "pl", "channel": "voice" }

Instance metadata

GET /info

Returns metadata for the authenticated instance — currently the SNOMED CT version behind the deployed medical model. Use it to record which terminology version produced a given assessment.

JSON
{
  "snomed_ct_version": "http://snomed.info/sct/900000000000207008/version/20260501"
}
FieldTypeDescription
snomed_ct_versionstring or nullSNOMED CT version URI used by the instance's medical model mappings, per the SNOMED URI Standard.

Next

Once the conversation exists, drive it with turns, or open a realtime connection.

Errors and rate limitsTurns

Was this page helpful?