Reference

API v1

Base path /api/public/v1. Versioned from the start — a future v2 will live alongside v1 rather than replacing it.

Live endpoints

Served today. Each requires the listed scope unless marked public.

Endpoint	Scope	Description
GET /health	public	Service status and API version.
GET /clinical/encounters	clinical.read	List encounters created by the calling application.
POST /clinical/encounters	clinical.write	Create an encounter using opaque partner-side references only.
GET /clinical/notes	clinical.read	List SOAP notes for the application's own encounters.
GET /clinical/notes/{id}	clinical.read	Retrieve one SOAP note by encounter id.
GET /clinical/notes/{id}/fhir	clinical.read	Export a clinician-approved note as a FHIR R4 collection Bundle.
GET /clinical/notes/{id}/hl7	clinical.read	Export a clinician-approved note as an HL7 v2.5.1 ORU R01 message.
POST /transcription	transcription.create	Submit encounter audio for transcription and SOAP drafting.
POST /soap	transcription.create	One-call SOAP intake: submit a transcript or encounter audio and receive the note, ICD-10 candidates, WHO/IMCI triage and NHIS billing items.
GET /academy/courses	academy.read	Public Academy course catalogue.
GET /academy/courses/{slug}	academy.read	One Academy course with its module outline.
GET /global-health/signals	global_health.read	Aggregated, de-identified syndromic signal counts.
GET /global-health/surveillance	surveillance.read	Aggregated surveillance series.
GET /early-warning/signals	early_warning.read	Aggregated early-warning status and trends.
GET /academy/certificates/{certificateId}	academy.read	Verify an Academy credential.
GET /billing/subscription	billing.read	The calling organisation's subscription state.
POST /stream/sessions	transcription.stream	Open a live transcription session for an encounter.
POST /stream/sessions/{sessionId}/chunks	transcription.stream	Send one numbered audio chunk; returns its text and the running transcript.
GET /stream/sessions/{sessionId}	transcription.stream	Running transcript and any missing chunk numbers.
POST /stream/sessions/{sessionId}/finalize	transcription.stream	Close the session and queue note drafting.
GET /codes/icd10	codes.read	Search ICD-10-CM codes by description.
GET /specialties	consultations:read	List specialty documentation engines (behavioral health, refugee health, PT/OT and core specialties).

Planned endpoints

Documented contracts with no data source yet. They authenticate and check scopes, then return 501 with status: planned. Do not build against their response bodies.

Endpoint	Scope	Why it is not live

Examples

GET /clinical/encounters

{
  "data": [
    {
      "id": "b0f1…",
      "external_encounter_id": "clinic-4821",
      "status": "note_ready",
      "encounter_type": "consultation",
      "created_at": "2026-09-21T09:14:22Z"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "count": 1, "total": 1, "has_more": false }
}

POST /clinical/encounters

curl -X POST https://gelypticmd.com/api/public/v1/clinical/encounters \
  -H "Authorization: Bearer $GELYPTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_encounter_id":"clinic-4821","encounter_type":"consultation"}'

FHIR R4 approved-note export

curl https://gelypticmd.com/api/public/v1/clinical/notes/{id}/fhir \
  -H "Authorization: Bearer $GELYPTIC_API_KEY" \
  -H "Accept: application/fhir+json"

HL7 v2.5.1 approved-note export

curl https://gelypticmd.com/api/public/v1/clinical/notes/{id}/hl7 \
  -H "Authorization: Bearer $GELYPTIC_API_KEY" \
  -H "Accept: application/hl7-v2" \
  --output note.hl7

Creating an encounter is idempotent on external_encounter_id — retrying a failed request returns the existing record instead of duplicating it.

Interoperability exports are available only after clinician approval and contain opaque partner identifiers. The API generates standards-based payloads; it does not write directly to a hospital system or HL7 listener.

Scopes

clinical.read: Read encounters and SOAP notes the application itself created.
clinical.write: Create and update encounters owned by the application.
transcription.create: Submit audio for transcription and SOAP drafting.
transcription.stream: Open live transcription sessions and send audio chunks while the visit runs.
codes.read: Search the ICD-10-CM reference list.
global_health.read: Read aggregated, de-identified global health indicators. Never clinical records.
surveillance.read: Read aggregated syndromic surveillance summaries.
early_warning.read: Read aggregated early-warning status and trends.
academy.read: Read the public Academy course catalogue.
billing.read: Read the calling organisation's own subscription state.
consultations:create: Create consultation records owned by the application.
consultations:read: Read consultation metadata owned by the application.
consultations:update: Update consultation records owned by the application.
audio:upload: Upload consultation audio for transcription.
transcripts:read: Read transcripts for the application's own consultations.
soap_notes:read: Read SOAP drafts and approved notes for the application's own consultations.
clinical_summaries:read: Read generated clinical summaries for the application's own consultations.
quality_reviews:read: Read automated quality-review results.
patient_summaries:read: Read de-identified patient-facing summaries the application generated.
coding_suggestions:read: Read suggested billing codes for the application's own consultations.
webhooks:manage: Register and remove webhook endpoints for the application.

Machine-readable contract

OpenAPI 3.1

/api/public/v1/openapi.json

Generated from the same endpoint catalogue this page renders, so the specification cannot describe an endpoint that does not exist.