Katixo/API DocumentationBeta

Operation Theatre

Manage operation theatres, schedule surgeries, assign surgical teams, and record pre-operative and post-operative notes. The OT module integrates with IPD admissions to ensure only admitted patients can be scheduled for surgery.

Base URL

https://hospital.katixo.com/api/v1

Endpoints

GET/api/v1/ot/theatres

POST/api/v1/ot/surgeries

GET/api/v1/ot/surgeries

PUT/api/v1/ot/surgeries/{surgeryId}/start

PUT/api/v1/ot/surgeries/{surgeryId}/complete

GET/api/v1/ot/surgeries/{surgeryId}

Authentication: All endpoints require a valid JWT Bearer token in the Authorization header. All IDs are UUIDs.

The SurgeryResponse object

{
  "success": true,
  "message": "Surgery retrieved successfully",
  "data": {
    "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
    "surgeryNumber": "SRG-2026-00187",
    "patientName": "Ramesh Kumar Sharma",
    "patientUhid": "UHID-2026-004521",
    "procedureName": "Total Knee Replacement - Right",
    "theatreName": "OT-1 (Major)",
    "surgeonName": "Dr. Vikram Singh",
    "anesthetistName": "Dr. Meena Iyer",
    "scheduledDate": "2026-06-15",
    "scheduledTime": "09:00",
    "estimatedDuration": 180,
    "actualStartTime": "2026-06-15T09:12:00Z",
    "actualEndTime": "2026-06-15T12:05:00Z",
    "status": "COMPLETED",
    "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done. Blood group: B+ve, 2 units packed RBCs arranged.",
    "postOpNotes": "Procedure completed successfully. Implant: Smith & Nephew Genesis II. Drain placed. Patient shifted to recovery.",
    "createdAt": "2026-06-12T10:30:00Z"
  },
  "errors": null
}

Surgery statuses

Status	Description
`SCHEDULED`	Surgery has been scheduled and the OT slot is reserved.
`IN_PROGRESS`	Surgery has started. The theatre is marked as in use.
`COMPLETED`	Surgery has been completed. Post-operative notes have been recorded.
`CANCELLED`	Surgery was cancelled. The OT slot is released back to available.

Theatre types

Type	Description
`MAJOR`	Fully equipped for major surgical procedures including orthopaedic, cardiac, and neuro surgeries.
`MINOR`	For minor procedures, biopsies, wound debridement, and day-care surgeries.
`EMERGENCY`	Dedicated emergency OT available 24/7 for trauma and emergency surgical cases.

List theatres

GET/api/v1/ot/theatres

Returns a list of all operation theatres with their current availability status.

curl https://hospital.katixo.com/api/v1/ot/theatres \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Theatres retrieved successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "OT-1 (Major)",
      "type": "MAJOR",
      "status": "AVAILABLE",
      "floor": "3rd Floor",
      "equipment": ["C-Arm", "Laparoscopy Unit", "Cautery Machine"]
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "OT-2 (Major)",
      "type": "MAJOR",
      "status": "IN_USE",
      "floor": "3rd Floor",
      "equipment": ["Cardiac Monitor", "Heart-Lung Machine", "Cautery Machine"]
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
      "name": "OT-3 (Minor)",
      "type": "MINOR",
      "status": "AVAILABLE",
      "floor": "2nd Floor",
      "equipment": ["Cautery Machine", "Suction Unit"]
    },
    {
      "id": "d4e5f6a7-b8c9-0123-def0-345678901234",
      "name": "Emergency OT",
      "type": "EMERGENCY",
      "status": "AVAILABLE",
      "floor": "Ground Floor",
      "equipment": ["Ventilator", "Defibrillator", "C-Arm", "Cautery Machine"]
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-456789012345",
      "name": "OT-4 (Major)",
      "type": "MAJOR",
      "status": "MAINTENANCE",
      "floor": "3rd Floor",
      "equipment": ["Microscope", "Neuro Navigation", "Cautery Machine"]
    }
  ],
  "errors": null
}

Theatre statuses

Status	Description
`AVAILABLE`	Theatre is free and can be booked for surgery.
`IN_USE`	Surgery is currently in progress in this theatre.
`MAINTENANCE`	Theatre is undergoing maintenance or sterilization and cannot be booked.

Schedule a surgery

POST/api/v1/ot/surgeries

Schedules a new surgery and reserves the specified OT slot. The patient must have an active IPD admission. Returns 201 Created on success.

Request body

Field	Type	Required	Description
`patientId`	UUID	Yes	ID of the patient.
`admissionId`	UUID	Yes	Active IPD admission ID for the patient.
`theatreId`	UUID	Yes	ID of the operation theatre to book.
`surgeonId`	UUID	Yes	ID of the lead surgeon (staff member).
`anesthetistId`	UUID	Yes	ID of the anesthetist (staff member).
`scheduledDate`	LocalDate	Yes	Date of the surgery (YYYY-MM-DD).
`scheduledTime`	String	Yes	Start time in HH:mm format (e.g. "09:00").
`estimatedDuration`	int	Yes	Estimated duration in minutes.
`procedureName`	String	Yes	Name of the surgical procedure.
`procedureType`	String	Yes	`ELECTIVE` or `EMERGENCY`.
`preOpNotes`	String	No	Pre-operative clinical notes, patient preparation details.

Example: schedule a knee replacement surgery

curl -X POST https://hospital.katixo.com/api/v1/ot/surgeries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "admissionId": "a8b9c0d1-e2f3-4567-890a-bcdef1234567",
    "theatreId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "surgeonId": "d1e2f3a4-b5c6-7890-def0-123456789abc",
    "anesthetistId": "e2f3a4b5-c6d7-8901-ef01-234567890bcd",
    "scheduledDate": "2026-06-15",
    "scheduledTime": "09:00",
    "estimatedDuration": 180,
    "procedureName": "Total Knee Replacement - Right",
    "procedureType": "ELECTIVE",
    "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done. Blood group: B+ve, 2 units packed RBCs arranged. Consent obtained."
  }'

# Response (201 Created)
{
  "success": true,
  "message": "Surgery scheduled successfully",
  "data": {
    "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
    "surgeryNumber": "SRG-2026-00187",
    "patientName": "Ramesh Kumar Sharma",
    "patientUhid": "UHID-2026-004521",
    "procedureName": "Total Knee Replacement - Right",
    "theatreName": "OT-1 (Major)",
    "surgeonName": "Dr. Vikram Singh",
    "anesthetistName": "Dr. Meena Iyer",
    "scheduledDate": "2026-06-15",
    "scheduledTime": "09:00",
    "estimatedDuration": 180,
    "actualStartTime": null,
    "actualEndTime": null,
    "status": "SCHEDULED",
    "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done. Blood group: B+ve, 2 units packed RBCs arranged. Consent obtained.",
    "postOpNotes": null,
    "createdAt": "2026-06-12T10:30:00Z"
  },
  "errors": null
}

List surgeries

GET/api/v1/ot/surgeries

Returns a paginated list of surgeries. Use query parameters to filter by date, theatre, surgeon, or status. The response is wrapped in ApiResponse<PagedResponse<SurgeryResponse>>.

Query parameters

Parameter	Type	Description
`date`	LocalDate	Filter surgeries scheduled on this date (YYYY-MM-DD).
`theatreId`	UUID	Filter by specific operation theatre.
`surgeonId`	UUID	Filter by lead surgeon.
`status`	String	Filter by status: `SCHEDULED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`page`	int	Page number (zero-based, default: 0).
`size`	int	Results per page (default: 20).

curl "https://hospital.katixo.com/api/v1/ot/surgeries?date=2026-06-15&status=SCHEDULED&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Surgeries retrieved successfully",
  "data": {
    "content": [
      {
        "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
        "surgeryNumber": "SRG-2026-00187",
        "patientName": "Ramesh Kumar Sharma",
        "patientUhid": "UHID-2026-004521",
        "procedureName": "Total Knee Replacement - Right",
        "theatreName": "OT-1 (Major)",
        "surgeonName": "Dr. Vikram Singh",
        "anesthetistName": "Dr. Meena Iyer",
        "scheduledDate": "2026-06-15",
        "scheduledTime": "09:00",
        "estimatedDuration": 180,
        "actualStartTime": null,
        "actualEndTime": null,
        "status": "SCHEDULED",
        "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done.",
        "postOpNotes": null,
        "createdAt": "2026-06-12T10:30:00Z"
      },
      {
        "id": "d5e6f7a8-b9c0-1234-def0-567890123456",
        "surgeryNumber": "SRG-2026-00188",
        "patientName": "Sunita Devi Gupta",
        "patientUhid": "UHID-2026-004530",
        "procedureName": "Laparoscopic Cholecystectomy",
        "theatreName": "OT-2 (Major)",
        "surgeonName": "Dr. Priya Nair",
        "anesthetistName": "Dr. Rajesh Kapoor",
        "scheduledDate": "2026-06-15",
        "scheduledTime": "10:30",
        "estimatedDuration": 90,
        "actualStartTime": null,
        "actualEndTime": null,
        "status": "SCHEDULED",
        "preOpNotes": "Ultrasound confirms multiple gallstones. Patient consented.",
        "postOpNotes": null,
        "createdAt": "2026-06-12T11:15:00Z"
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 2,
    "totalPages": 1,
    "last": true
  },
  "errors": null
}

Start a surgery

PUT/api/v1/ot/surgeries/{surgeryId}/start

Transitions the surgery from SCHEDULED to IN_PROGRESS. Records the actual start time and marks the theatre as IN_USE.

curl -X PUT https://hospital.katixo.com/api/v1/ot/surgeries/c4d5e6f7-a8b9-0123-cdef-456789012345/start \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Response
{
  "success": true,
  "message": "Surgery started successfully",
  "data": {
    "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
    "surgeryNumber": "SRG-2026-00187",
    "patientName": "Ramesh Kumar Sharma",
    "patientUhid": "UHID-2026-004521",
    "procedureName": "Total Knee Replacement - Right",
    "theatreName": "OT-1 (Major)",
    "surgeonName": "Dr. Vikram Singh",
    "anesthetistName": "Dr. Meena Iyer",
    "scheduledDate": "2026-06-15",
    "scheduledTime": "09:00",
    "estimatedDuration": 180,
    "actualStartTime": "2026-06-15T09:12:00Z",
    "actualEndTime": null,
    "status": "IN_PROGRESS",
    "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done. Blood group: B+ve, 2 units packed RBCs arranged. Consent obtained.",
    "postOpNotes": null,
    "createdAt": "2026-06-12T10:30:00Z"
  },
  "errors": null
}

Complete a surgery

PUT/api/v1/ot/surgeries/{surgeryId}/complete

Marks the surgery as COMPLETED, records the actual end time, and releases the theatre back to AVAILABLE. Post-operative notes and complication details should be provided in the request body.

Request body

Field	Type	Required	Description
`postOpNotes`	String	Yes	Post-operative clinical notes, procedure details, and outcome.
`complications`	String	No	Any intra-operative or immediate post-operative complications. Null if none.
`bloodUnitsUsed`	int	No	Number of blood units transfused during surgery (default: 0).

curl -X PUT https://hospital.katixo.com/api/v1/ot/surgeries/c4d5e6f7-a8b9-0123-cdef-456789012345/complete \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "postOpNotes": "Procedure completed successfully. Implant: Smith & Nephew Genesis II. Drain placed. Patient shifted to recovery. Vitals stable.",
    "complications": null,
    "bloodUnitsUsed": 1
  }'

# Response
{
  "success": true,
  "message": "Surgery completed successfully",
  "data": {
    "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
    "surgeryNumber": "SRG-2026-00187",
    "patientName": "Ramesh Kumar Sharma",
    "patientUhid": "UHID-2026-004521",
    "procedureName": "Total Knee Replacement - Right",
    "theatreName": "OT-1 (Major)",
    "surgeonName": "Dr. Vikram Singh",
    "anesthetistName": "Dr. Meena Iyer",
    "scheduledDate": "2026-06-15",
    "scheduledTime": "09:00",
    "estimatedDuration": 180,
    "actualStartTime": "2026-06-15T09:12:00Z",
    "actualEndTime": "2026-06-15T12:05:00Z",
    "status": "COMPLETED",
    "preOpNotes": "Patient NPO since midnight. Pre-anesthesia checkup done. Blood group: B+ve, 2 units packed RBCs arranged. Consent obtained.",
    "postOpNotes": "Procedure completed successfully. Implant: Smith & Nephew Genesis II. Drain placed. Patient shifted to recovery. Vitals stable.",
    "createdAt": "2026-06-12T10:30:00Z"
  },
  "errors": null
}

Get surgery details

GET/api/v1/ot/surgeries/{surgeryId}

Retrieves the full details of a single surgery by its UUID. Returns ApiResponse<SurgeryResponse>.

curl https://hospital.katixo.com/api/v1/ot/surgeries/c4d5e6f7-a8b9-0123-cdef-456789012345 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Error handling

All error responses follow the standard ApiResponse wrapper with success: false and details in the errors array.

# 400 Bad Request — validation error
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "patientId: must not be null",
    "scheduledDate: must be a future date",
    "theatreId: OT-4 (Major) is currently under maintenance"
  ]
}

# 409 Conflict — scheduling conflict
{
  "success": false,
  "message": "Theatre booking conflict",
  "data": null,
  "errors": ["OT-1 (Major) is already booked for 2026-06-15 09:00-12:00 (SRG-2026-00185)"]
}

# 422 Unprocessable Entity — invalid state transition
{
  "success": false,
  "message": "Invalid surgery status transition",
  "data": null,
  "errors": ["Cannot start surgery: current status is COMPLETED, expected SCHEDULED"]
}