Working with Records

Once a consultation is finalized, its data lives in the consultation records system. Records are immutable by default — every change creates a new version, preserving the full history for regulatory compliance and audit trails.

Retrieving a Record

Fetch the current state of a finalized consultation:

curl
Python

curl -X GET "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}" \
  -H "x-api-key: $DELPHOS_API_KEY"

response = httpx.get(
    f"https://your-instance.delphos.app/v1/consultation-records/{consultation_id}",
    headers={"x-api-key": DELPHOS_API_KEY},
)

record = response.json()
print(f"Status: {record['status']}")
print(f"Version: {record['version_info']['current_version']}")
print(f"SOAP Subjective: {record['soap']['subjective'][:100]}...")

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_consultation_id": "ATD-2024-001234",
  "external_patient_id": "PAT-5678",
  "status": "GENERATED",
  "soap": {
    "subjective": "Paciente relata cefaleia tensional há 3 dias...",
    "objective": "PA 120/80 mmHg, FC 72 bpm...",
    "assessment": "Cefaleia tensional episódica...",
    "plan": "Prescrição de analgésico..."
  },
  "doctor_notes": "",
  "source_transcript": "Médico: Bom dia...",
  "version_info": {
    "current_version": 1,
    "total_versions": 1,
    "last_edited_by": "DOC-123",
    "last_edited_at": "2026-04-14T10:45:00Z"
  },
  "created_at": "2026-04-14T10:30:00Z",
  "updated_at": "2026-04-14T10:45:00Z"
}

Record Statuses

Status	Description
`GENERATED`	Initial SOAP note created by DELPHOS
`REVIEWED`	Physician has reviewed the note
`APPROVED`	Physician approved — ready for the medical record
`REJECTED`	Physician rejected — needs revision
`AMENDED`	Modified after initial approval

Editing Doctor Notes

Update the physician’s notes on a finalized consultation. This creates a new version snapshot automatically:

curl
Python

curl -X PATCH "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/notes" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doctor_notes": "Paciente orientado sobre retorno em 15 dias para reavaliação.",
    "edited_by": "DOC-123"
  }'

response = httpx.patch(
    f"https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/notes",
    headers={"x-api-key": DELPHOS_API_KEY},
    json={
        "doctor_notes": "Paciente orientado sobre retorno em 15 dias.",
        "edited_by": "DOC-123",
    },
)

updated = response.json()
print(f"Version: {updated['version_info']['current_version']}")

Regenerating the SOAP Note

If the physician wants a fresh SOAP note (for example, after adding extensive notes), they can trigger regeneration:

curl -X POST "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/regenerate-soap" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edited_by": "DOC-123",
    "source": "notes+transcript"
  }'

The source parameter controls what input is used:

Source	Description
`notes+transcript`	Uses both physician notes and the original transcript (default)
`notes_only`	Uses only physician notes, ignoring the transcript

A version snapshot is created before the regeneration, so the previous SOAP is always recoverable.

Version History

Every edit creates an immutable version snapshot. List all versions:

curl -X GET "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/versions" \
  -H "x-api-key: $DELPHOS_API_KEY"

{
  "consultation_id": "550e8400-e29b-41d4-a716-446655440000",
  "versions": [
    {
      "version_number": 1,
      "edited_by": "SYSTEM",
      "edited_at": "2026-04-14T10:45:00Z"
    },
    {
      "version_number": 2,
      "edited_by": "DOC-123",
      "edited_at": "2026-04-14T11:00:00Z"
    }
  ],
  "total": 2
}

Retrieving a Specific Version

Fetch the full content of any historical version:

curl -X GET "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/versions/1" \
  -H "x-api-key: $DELPHOS_API_KEY"

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "consultation_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_number": 1,
  "content": {
    "subjective": "...",
    "objective": "...",
    "assessment": "...",
    "plan": "..."
  },
  "content_hash": "a3f2b1c4d5e6...",
  "edited_by": "SYSTEM",
  "edited_at": "2026-04-14T10:45:00Z"
}

Addendums

Addendums are append-only annotations attached to a finalized record. Unlike edits to doctor notes, addendums cannot be modified or deleted after creation — they are a permanent addition to the medical record.

Creating an Addendum

curl -X POST "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/addendums" \
  -H "x-api-key: $DELPHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Resultado de exame laboratorial recebido: hemograma completo normal.",
    "author": "DOC-123"
  }'

Response (201 Created):

{
  "id": "aa0e8400-e29b-41d4-a716-446655440006",
  "consultation_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Resultado de exame laboratorial recebido: hemograma completo normal.",
  "author": "DOC-123",
  "created_at": "2026-04-15T09:00:00Z"
}

Listing Addendums

curl -X GET "https://your-instance.delphos.app/v1/consultation-records/{consultation_id}/addendums" \
  -H "x-api-key: $DELPHOS_API_KEY"

Returns all addendums in chronological order.

Error Handling

Status	Cause
`404 Not Found`	Consultation or version does not exist
`409 Conflict`	Consultation not yet finalized (records endpoints only work on finalized consultations)
`503 Service Unavailable`	SOAP regeneration service temporarily unavailable

Next Steps

Consultation Lifecycle — Session creation and management
Clinical Summaries — Patient intelligence from consultation history
Real-time Transcription — Audio chunk streaming