Scopes

Scopes follow the SMART on FHIR system/<Resource>.<perms> format. Request only the scopes your integration requires.

#Permission letters

• r — read a single resource by ID
• s — search (query with parameters, paginated Bundle response)
• c — create a new resource
• u — update an existing resource
• d — delete a resource

#Scope reference

#Patient

#system/Patient.rs

Read and search patients

Allows reading individual Patient records by ID and searching the patient list. Does not permit creating or modifying patient data.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Patient.cru

Create, read, and update patients

Allows creating new Patient records, reading existing ones, and updating demographic or contact information. Includes all operations of system/Patient.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#Appointment

#system/Appointment.rs

Read and search appointments

Allows reading individual Appointment resources and searching the appointment list by patient, practitioner, date, or status.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Appointment.cru

Create, read, and update appointments

Allows booking new appointments, reading existing ones, and updating appointment status (e.g. cancellation). Includes all operations of system/Appointment.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#Encounter

#system/Encounter.rs

Read and search encounters

Allows reading individual Encounter records (clinical consultations) and searching by patient, date, status, or class.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Encounter.cru

Create, read, and update encounters

Allows creating new Encounter records, reading existing ones, and updating encounter status or details. Includes all operations of system/Encounter.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#Observation

#system/Observation.rs

Read and search observations

Allows reading individual Observation resources (vital signs, lab results, exam findings) and searching by patient, encounter, LOINC code, date, status, or category.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Observation.cru

Create, read, and update observations

Allows recording new Observation values, reading existing ones, and amending previously recorded observations. LOINC codes are validated on write.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#MedicationRequest

#system/MedicationRequest.rs

Read and search medication requests

Allows reading individual MedicationRequest resources (prescription orders) and searching by patient or encounter.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/MedicationRequest.c

Create medication requests

Allows creating MedicationRequest resources (each auto-links to a draft prescription).

Permissions granted: c — create a new resource

#system/MedicationRequest.cru

Create, read, and update medication requests

Allows creating, reading, and updating MedicationRequest resources. Updates are read-then-merge and preserve app-only fields; a signed or cancelled prescription cannot be modified.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#ServiceRequest

#system/ServiceRequest.rs

Read and search service requests

Allows reading individual ServiceRequest resources (study / procedure orders) and searching by patient or encounter.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/ServiceRequest.c

Create service requests

Allows creating ServiceRequest resources (a single-item order).

Permissions granted: c — create a new resource

#system/ServiceRequest.cru

Create, read, and update service requests

Allows creating, reading, and updating ServiceRequest resources. Updates are read-then-merge on draft orders and preserve app-only fields; a signed or cancelled order cannot be modified, and multi-item orders are read-only.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#Composition

#system/Composition.rs

Read and search clinical notes

Allows reading individual Composition resources (the clinical-note projection of an encounter) and searching by patient, date, or type.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Composition.cru

Create, read, and update clinical notes

Allows creating Composition resources, reading existing ones, and updating the clinical narrative (with optimistic concurrency via If-Match). Includes all operations of system/Composition.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#DocumentReference

#system/DocumentReference.rs

Read and search document references

Allows reading individual DocumentReference resources (lab results, imaging, scanned files; the binary is served via a 30-minute signed URL) and searching by patient, category, type, or date.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/DocumentReference.cru

Create, read, and update document references

Allows uploading document binaries ($upload — base64 inline or multipart, 25 MB ceiling), reading existing ones, and updating their metadata. Includes all operations of system/DocumentReference.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource

#Practitioner

#system/Practitioner.rs

Read practitioners

Allows reading individual Practitioner resources (healthcare providers). Practitioner data is read-only in the public API.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#Organization

#system/Organization.rs

Read organization

Allows reading the Organization resource that corresponds to your API key organization. Organization data is read-only in the public API.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#Subscription

#system/Subscription.rs

Read and search webhook subscriptions

Allows reading a webhook Subscription by ID and listing the subscriptions registered for your API key organization.

Permissions granted: r — read a single resource by ID, s — search (query with parameters, paginated Bundle response)

#system/Subscription.crud

Manage webhook subscriptions

Allows creating, reading, updating, and deleting outbound-webhook Subscriptions. Requires a signed BAA on the API key. Includes all operations of system/Subscription.rs.

Permissions granted: c — create a new resource, r — read a single resource by ID, u — update an existing resource, d — delete a resource

#Requesting scopes

Include the scope parameter in your token request. Separate multiple scopes with spaces:

curl -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/Patient.rs system/Appointment.rs"

If scope is omitted, all scopes registered for the API key are granted. The issued token includes the granted scopes in the scope response field.