Radiology Service — API Contracts

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

---

1. Base Path and Auth

Attribute	Value
REST base path	/v1/radiology
FHIR base path	/fhir/R4 (via interop-service gateway)
Auth	Bearer JWT (Keycloak)
Module guard	ModuleEntitlementGuard — requires diag.radiology
Idempotency	Idempotency-Key header required on POST mutations

---

2. PACS Endpoints

GET /v1/radiology/pacs-endpoints

List registered PACS endpoints for the tenant.

Attribute	Value
Auth scope	svc:radiology:admin

Response 200:

{
  "data": [{
    "id": "PACS_01J...",
    "name": "KMC Radiology PACS",
    "qidoUrl": "https://pacs.kmc.af/wado/qido-rs",
    "wadoUrl": "https://pacs.kmc.af/wado/wado-rs",
    "authMode": "bearer",
    "facilityId": "FAC_01J..."
  }],
  "meta": { "total": 2, "page": 1, "pageSize": 20 }
}

POST /v1/radiology/pacs-endpoints

Register a PACS endpoint.

Request body:

{
  "name": "KMC Radiology PACS",
  "qidoUrl": "https://pacs.kmc.af/wado/qido-rs",
  "wadoUrl": "https://pacs.kmc.af/wado/wado-rs",
  "stowUrl": "https://pacs.kmc.af/wado/stow-rs",
  "authMode": "bearer",
  "authConfig": { "tokenUrl": "...", "clientId": "..." },
  "facilityId": "FAC_01J..."
}

Response 201: Created endpoint.

---

3. Imaging Studies

GET /v1/radiology/studies

Search imaging studies.

Query params	patientId, orderId, modality, from, to, status, page, pageSize
Auth scope	svc:radiology:read

Response 200:

{
  "data": [{
    "id": "STU_01J...",
    "patientId": "PAT_01J...",
    "orderId": "SRQ_01J...",
    "modality": "CT",
    "startedAt": "2026-04-18T10:00:00Z",
    "pacsStudyUid": "1.2.840.10008.5.1.4.1.1.2",
    "status": "final",
    "reportSummary": "No acute intracranial findings."
  }],
  "meta": { "total": 5, "page": 1, "pageSize": 20 }
}

GET /v1/radiology/studies/:id

Get study detail with reports.

Response 200: Full study including reports[] array with status and version.

POST /v1/radiology/studies

Register a study (manual or from integration).

Request body:

{
  "patientId": "PAT_01J...",
  "encounterId": "ENC_01J...",
  "orderId": "SRQ_01J...",
  "modality": "MR",
  "startedAt": "2026-04-18T09:00:00Z",
  "pacsStudyUid": "1.2.840.10008...",
  "pacsEndpointId": "PACS_01J..."
}

Response 201: Created ImagingStudyRef.

POST /v1/radiology/studies/:id/viewer-launch

Generate a signed viewer launch URL.

Attribute	Value
Auth scope	svc:radiology:read
ABAC check	Clinician must have access to patient

Response 200:

{
  "viewerUrl": "https://viewer.ghasi.af/launch",
  "token": "signed-jwt",
  "expiresAt": "2026-04-18T11:00:00Z",
  "viewerType": "ohif"
}

Errors:

Code	HTTP	Meaning
RAD_ACCESS_DENIED	403	Clinician lacks patient access
RAD_STUDY_NOT_FOUND	404	Study does not exist
RAD_PACS_UNAVAILABLE	503	PACS endpoint unreachable

---

4. Radiology Reports

POST /v1/radiology/studies/:studyId/reports

Ingest or submit a radiology report.

Request body:

{
  "status": "preliminary",
  "authorId": "PRV_01J...",
  "authoredAt": "2026-04-18T10:30:00Z",
  "contentText": "Preliminary read: No acute findings.",
  "criticalFindingFlag": false
}

Response 201: Report object with version=1.

POST /v1/radiology/reports/:id/sign

Finalize (sign) a report.

Attribute	Value
Auth scope	svc:radiology:sign

Response 200: Report with status: final.

POST /v1/radiology/reports/:id/amend

Submit an amendment to a final report.

Request body: { "contentText": "Amended: ...", "amendmentReason": "Additional finding noted" }

Response 201: New report version; prior version status: superseded.

GET /v1/radiology/reports/:id

Get a specific report version.

Response 200: Report object including priorReportId chain.

---

5. Radiologist Worklist

GET /v1/radiology/worklist

Get studies pending reporting for radiologist.

| Query params | status=registered, modality, priority, from, to, page, pageSize |

Response 200: Filtered, paginated study list sorted by urgency.

---

6. FHIR Endpoints (via interop-service gateway)

Interaction	Path	Notes
Search ImagingStudy	GET /fhir/R4/ImagingStudy?patient={id}	Routed to radiology-service
Read ImagingStudy	GET /fhir/R4/ImagingStudy/{id}
Search DiagnosticReport	GET /fhir/R4/DiagnosticReport?patient={id}&category=RAD	Imaging workflow reports

---

7. Common Error Codes

Code	HTTP	Description
RAD_STUDY_NOT_FOUND	404	Study ID not found
RAD_REPORT_NOT_FOUND	404	Report ID not found
RAD_REPORT_NOT_FINAL	409	Amendment requires final status
RAD_PACS_ENDPOINT_NOT_FOUND	404	PACS endpoint ID not found
RAD_PACS_UNAVAILABLE	503	DICOMweb endpoint unreachable
RAD_MODULE_NOT_LICENSED	403	diag.radiology not licensed
RAD_ACCESS_DENIED	403	ABAC policy denial
VALIDATION_FAILED	400	DTO validation error