Functional standard / Interactions / Instance
Conversation
A conversation with an agent, about one patient or general. Turns can carry proposal ids.
- Kind
- conversation
- Collection
- /v1/conversations
- Initial state
- open
- Classification
- Operational
Scope and usage
The actor's role selects the conversation definition: clinician copilot, patient coach, coordinator. Reading a patient's conversation requires ai consent.
Boundaries and relationships
- The agent does not decide inside the transcript. A proposal id on a turn is a Proposal resource, still pending until a clinician accepts it.
- Prompt text is not part of this resource's normative content.
Resource content
Elements this resource adds. It also carries the Instance.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| patient_id | 0..1 | id | — | Required in spirit when scope is patient. Omitted for general. |
| scope | 1..1 | code | B | patient or general. |
| actor_role | 1..1 | code | — | Whose conversation: clinician, patient, coordinator. |
| title | 1..1 | string | — | Title. |
| structure | 0..1 | object | — | Copied from the definition. Sections and tone. |
| turns | 0..* | Turn | R | id, speaker, content, at, proposal ids. Harness-owned. |
State machine
open/ initial — Turns may be added.closed— Frozen.
open → closed.
Frozen: closed.
Invariants
ccs-conv-1— An agent reads a patient's conversation only when consent scope ai is granted.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/conversations | List conversation. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/conversations | Create a conversation. Body is the resource minus harness-owned elements. |
| GET | /v1/conversations/{id} | Read one conversation. |
| PATCH | /v1/conversations/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/conversations/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/conversations/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
| POST | /v1/conversations/{id}/turns | Append a turn. Body is { content }. |
Notes
- Agents may create. Definition kind conversation.
Example
{ "patient_id": "pat_…", "scope": "patient", "actor_role": "clinician", "definition_key": "conversation_clinician_copilot" }