> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Staff API guide

> Authentication, permissions, scoping, and endpoint coverage for staff clients and integrations.

The staff-facing API currently has 42 operations. Ten foundation and diagnostic-integration operations are documented separately under **Foundation and integrations**; the other 32 operations cover staff workflows.

## Workflow coverage

| Area               | Operations | Typical use                                                                                         |
| ------------------ | ---------: | --------------------------------------------------------------------------------------------------- |
| Patients           |          3 | Register, view, and update a patient                                                                |
| Appointments       |         11 | Availability, booking, rescheduling, status changes, and patient appointment history                |
| Outpatient visits  |          4 | Create, list, view, and update outpatient encounters                                                |
| Clinical workspace |         14 | Medical history, encounters, vitals, diagnoses, progress notes, orders, and diagnostic requisitions |

The API uses standard `GET`, `POST`, and `PATCH` methods. A custom query HTTP method is not required for phase one.

## Authentication and abilities

Use a dedicated Laravel Sanctum bearer token. Grant only the abilities required by the consuming staff application or integration.

| Ability              | Grants access to                                        |
| -------------------- | ------------------------------------------------------- |
| `patients:read`      | Patient lookup and details                              |
| `patients:write`     | Patient registration and updates                        |
| `appointments:read`  | Appointment lists, details, and availability            |
| `appointments:write` | Booking, rescheduling, cancellation, and status changes |
| `visits:read`        | Outpatient visit lists and details                      |
| `visits:write`       | Creating and updating outpatient visits                 |
| `clinical:read`      | Medical history and clinical workspace records          |
| `clinical:write`     | Vitals, diagnoses, notes, orders, and encounter changes |

The foundation, laboratory, and radiology endpoints declare their additional integration abilities in their individual reference pages.

## Clinic scoping and authorization

Tokens operate within the organization and clinic context assigned to their owner. Policies enforce access to individual records; clients must not assume that knowing a record identifier grants access to it.

Use pagination and the documented filters for collection endpoints. Treat response resource shapes as the API contract instead of relying on internal database fields.

## Current scope

The clinical history endpoint is a read-oriented summary assembled from the patient's existing clinical records. It is an endpoint because mobile and staff clients need a stable, authorized representation independent of the database model.

Phase one covers outpatient workflows. Inpatient admissions, wards, beds, transfers, discharge workflows, and inpatient medication administration are intentionally deferred, while identifiers and clinical concepts should remain compatible with that future module.