Skip to content
Nightingale

API Reference

v1.0.0
OpenAPI 3.1.0

API

API documentation for API

Client Libraries
Shell Curl

nightingale.platform.alerts.v1.AlertService

​

AlertService lists the alerts raised for patients by alert scripts, tracks whether the patient and caregivers have seen them, and manages a patient's subscriptions to alert scripts.

Alerts are raised automatically: when a record such as a laboratory result or imaging report is saved, the scripts that apply to the patient run and may raise alerts. There is no RPC to create one. Staff see alerts on their organization's records, plus alerts from global scripts their organization subscribes to for patients who have fully accepted it, in both cases only for patients they may see (every patient of the organization, or only the ones they follow); alerts are part of monitoring, which every plan includes. Patients see all of their own alerts.

An RPC that needs a feature of the organization's plan (MONITORING) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.alerts.v1.AlertService Operations

ListAlerts returns a page of alerts: your organization's queue, or one patient's alerts when filter.patient_id is set. The queue holds only the patients you may see: if you may see only the patients you follow, it holds only their alerts (a follow the patient requested but nobody has accepted does not count). Patients always get their own.

​

Fails with INVALID_ARGUMENT for a malformed patient_id, visit_id or tag ID or an invalid date_range, and with PERMISSION_DENIED when filter.patient_id names a patient you may not see (for a patient, anyone but themselves).

Query Parameters

  • filter.patientId
    Type: string

    Only this patient's alerts. Patients may leave it empty or send their own ID; they always get their own alerts.

  • filter.priority
    Type: enumnullable

    Only alerts with this priority.

    How urgent an alert is, from HIGH to INFO.

    values
    • ALERT_PRIORITY_UNSPECIFIED
    • ALERT_PRIORITY_HIGH
    • ALERT_PRIORITY_MEDIUM
    • ALERT_PRIORITY_LOW
    • ALERT_PRIORITY_INFO
  • filter.seenByPatient
    Type: boolean

    Only alerts the patient has (true) or has not (false) seen.

  • filter.seenByCaregiver
    Type: boolean

    Only alerts someone in your organization has (true) or has not (false) acknowledged. Meant for staff: a patient sees no acknowledgements, so for a patient true matches nothing and false matches every alert.

  • filter.visitId
    Type: string

    Only alerts raised from records of this visit. A visit that has been deleted lists nothing.

  • filter.tagIds
    Type: array of string

    Only alerts for patients carrying all of these tag IDs. Staff only; ignored when a patient calls.

  • dateRange.from.year
    Type: integerFormat: int32

    Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.

  • dateRange.from.month
    Type: integerFormat: int32

    Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.

  • dateRange.from.day
    Type: integerFormat: int32

    Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

  • dateRange.to.year
    Type: integerFormat: int32

    Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.

  • dateRange.to.month
    Type: integerFormat: int32

    Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.

  • dateRange.to.day
    Type: integerFormat: int32

    Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

  • pagination.size
    Type: integer

    Number of items per page. Omitted or 0 uses the endpoint's default. A size above the endpoint's maximum (1000 unless the endpoint says otherwise) fails with INVALID_ARGUMENT rather than being reduced.

  • pagination.params.orderBy
    Type: string

    Sort order: a column name, optionally followed by a space and ASC or DESC, such as created_at DESC. Each list endpoint states the columns it accepts, its default and its default direction; any other value fails with INVALID_ARGUMENT.

  • pagination.params.page
    Type: integer

    Page number, starting at 1. Omitted or 0 returns the first page.

  • pagination.cursor.cursor
    Type: string

    The cursor returned in the previous page's PaginationResponse, unchanged. It carries that listing's sort order, and on most endpoints its filters. Empty, altered or foreign cursors fail with INVALID_ARGUMENT.

  • pagination.cursor.skip
    Type: integer

    Number of rows to jump over after the cursor's position before this page starts. Omitted or 0 returns the page directly after the previous one.

Responses

  • application/json
Request Example for get/alerts/v1
curl /alerts/v1

{
  "alerts": [
    {
      "id": "string",
      "patientId": "string",
      "datetime": "2023-01-15T01:30:15.01Z",
      "timezone": "string",
      "priority": "ALERT_PRIORITY_UNSPECIFIED",
      "seenByPatient": true,
      "titleId": "string",
      "descriptionId": "string",
      "reasonIds": [
        "string"
      ],
      "parameters": {
        "additionalProperty": 1
      },
      "createdAt": "2023-01-15T01:30:15.01Z",
      "seenByCaregivers": [
        {
          "alertId": "string",
          "organizationId": "string",
          "caregiverId": "string",
          "caregiverComment": null,
          "datetime": "2023-01-15T01:30:15.01Z",
          "timezone": "string",
          "createdAt": "2023-01-15T01:30:15.01Z"
        }
      ],
      "organizationId": null,
      "visitId": null
    }
  ],
  "pagination": {
    "totalCount": 1,
    "cursor": null
  }
}

Success

ListAvailableAlertScripts

​

ListAvailableAlertScripts returns the global alert scripts a patient can subscribe to directly (those with a published version), sorted by name, and whether they already are. Fails with PERMISSION_DENIED when patient_id is set to anything but the caller's own ID. Patients only.

Query Parameters

  • patientId
    Type: string

    May be left empty; if set, it must be the caller's own ID.

Responses

  • application/json
Request Example for get/alerts/v1/scripts
curl /alerts/v1/scripts

{
  "scripts": [
    {
      "id": 1,
      "name": "string",
      "triggers": [
        "string"
      ],
      "isSubscribed": true
    }
  ]
}

Success

SubscribeToAlertScript

​

SubscribeToAlertScript subscribes the calling patient to a global alert script from ListAvailableAlertScripts, so it runs on their data. Fails with NOT_FOUND for a script ListAvailableAlertScripts does not offer (one that does not exist, is not global, or has no published version), with ALREADY_EXISTS if already subscribed, and with INVALID_ARGUMENT when alert_script_id is missing. Patients only.

Body·

required
application/json

Request for SubscribeToAlertScript.

  • alertScriptId
    Type: integerFormat: int32

    The script to subscribe to, from ListAvailableAlertScripts. Required.

Responses

  • application/json
Request Example for post/alerts/v1/subscriptions
curl /alerts/v1/subscriptions \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "alertScriptId": 1
}'

{
  "createdAt": "2023-01-15T01:30:15.01Z"
}

Success

UnsubscribeFromAlertScript

​

UnsubscribeFromAlertScript removes the calling patient's subscription to an alert script. Fails with INVALID_ARGUMENT when alert_script_id is missing, and with NOT_FOUND if they were not subscribed. Patients only.

Path Parameters

  • alertScriptId
    Type: integerFormat: int32
    required

    The script to unsubscribe from. Required.

Responses

  • application/json
Request Example for delete/alerts/v1/subscriptions/{alertScriptId}
curl /alerts/v1/subscriptions/1 \
  --request DELETE

{
  "success": true
}

Success

GetAlert

​

GetAlert returns one alert, with your organization's acknowledgements (none when a patient calls). Fails with INVALID_ARGUMENT for a malformed alert_id, and with NOT_FOUND if the alert does not exist, was deleted, or is not visible to you.

Path Parameters

  • alertId
    Type: string
    required

    The alert to return.

Responses

  • application/json
Request Example for get/alerts/v1/{alertId}
curl '/alerts/v1/{alertId}'

{
  "alert": {
    "id": "string",
    "patientId": "string",
    "datetime": "2023-01-15T01:30:15.01Z",
    "timezone": "string",
    "priority": "ALERT_PRIORITY_UNSPECIFIED",
    "seenByPatient": true,
    "titleId": "string",
    "descriptionId": "string",
    "reasonIds": [
      "string"
    ],
    "parameters": {
      "additionalProperty": 1
    },
    "createdAt": "2023-01-15T01:30:15.01Z",
    "seenByCaregivers": [
      {
        "alertId": "string",
        "organizationId": "string",
        "caregiverId": "string",
        "caregiverComment": null,
        "datetime": "2023-01-15T01:30:15.01Z",
        "timezone": "string",
        "createdAt": "2023-01-15T01:30:15.01Z"
      }
    ],
    "organizationId": null,
    "visitId": null
  }
}

Success

MarkAlertSeenByCaregiver

​

MarkAlertSeenByCaregiver records that you, a staff member, saw an alert, with an optional comment. Each staff member acknowledges an alert once. Staff only. Marking an alert you already acknowledged returns the existing acknowledgement unchanged. Fails with INVALID_ARGUMENT when alert_id is missing or malformed, datetime or timezone is missing, or patient_id is missing or malformed; with PERMISSION_DENIED when you may not see the patient; and with NOT_FOUND when the alert does not exist, was deleted, is not visible to you, or does not belong to the patient.

Path Parameters

  • alertId
    Type: string
    required

    The alert to acknowledge.

Body·MarkAlertSeenByCaregiverRequest

required
application/json

Request for MarkAlertSeenByCaregiver.

  • caregiverComment
    Type: string | null

    Optional note to leave with the acknowledgement.

  • datetime
    Type: Format: date-time

    When you saw the alert. Required.

  • patientId
    Type: string

    The patient the alert is about. Required.

  • timezone
    Type: string

    Your IANA time zone, for example "America/Mexico_City". Required.

Responses

  • application/json
Request Example for post/alerts/v1/{alertId}/seen-by-caregiver
curl '/alerts/v1/{alertId}/seen-by-caregiver' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "patientId": "",
  "caregiverComment": null,
  "datetime": "2023-01-15T01:30:15.01Z",
  "timezone": ""
}'

{
  "seenByCaregiver": {
    "alertId": "string",
    "organizationId": "string",
    "caregiverId": "string",
    "caregiverComment": null,
    "datetime": "2023-01-15T01:30:15.01Z",
    "timezone": "string",
    "createdAt": "2023-01-15T01:30:15.01Z"
  }
}

Success

MarkAlertSeenByPatient

​

MarkAlertSeenByPatient marks one of the patient's own alerts as seen. Patients only. Marking an alert that is already seen succeeds and changes nothing; an alert cannot be marked unseen again. Fails with INVALID_ARGUMENT for a malformed alert_id, with PERMISSION_DENIED when patient_id is set to another patient's ID (empty means the caller), and with NOT_FOUND when the alert does not exist, was deleted, or is not the caller's.

Path Parameters

  • alertId
    Type: string
    required

    The alert to mark as seen.

Body·MarkAlertSeenByPatientRequest

required
application/json

Request for MarkAlertSeenByPatient.

  • patientId
    Type: string | null

    Omit it, send an empty string, or send the caller's own ID; all three mean the caller. Any other value fails with PERMISSION_DENIED.

Responses

  • application/json
Request Example for post/alerts/v1/{alertId}/seen-by-patient
curl '/alerts/v1/{alertId}/seen-by-patient' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "patientId": null
}'

{
  "alert": {
    "id": "string",
    "patientId": "string",
    "datetime": "2023-01-15T01:30:15.01Z",
    "timezone": "string",
    "priority": "ALERT_PRIORITY_UNSPECIFIED",
    "seenByPatient": true,
    "titleId": "string",
    "descriptionId": "string",
    "reasonIds": [
      "string"
    ],
    "parameters": {
      "additionalProperty": 1
    },
    "createdAt": "2023-01-15T01:30:15.01Z",
    "seenByCaregivers": [
      {
        "alertId": "string",
        "organizationId": "string",
        "caregiverId": "string",
        "caregiverComment": null,
        "datetime": "2023-01-15T01:30:15.01Z",
        "timezone": "string",
        "createdAt": "2023-01-15T01:30:15.01Z"
      }
    ],
    "organizationId": null,
    "visitId": null
  }
}

Success

nightingale.platform.automation_rules.v1.AutomationRuleService (Collapsed)

​

AutomationRuleService manages your organization's automation rules: actions applied automatically to every patient or staff user your organization creates that a rule matches, such as adding a tag, starting monitoring, or making the creator a follower. It is for staff only.

Reading rules needs the automation:rule:view permission; creating, changing and deleting them needs automation:rule:manage. To save a rule you also need the permission each of its actions needs when done by hand: patient:tags:manage or user:tags:manage for adding tags, patient:monitoring for starting monitoring, and patient:assign both for assigning the patient to the creator and for making the creator a follower.

Rules run whoever creates the patient or user, without needing those permissions themselves, and only at creation: a rule never changes patients or users that already exist. An action that cannot happen (the tag was deleted, or the monthly monitored-patient limit is reached) does not stop the patient or user from being created; the create response lists it as a warning.

Your plan limits how many rules can be enabled at once: 3 on Essentials, 10 on Professional, by contract on Enterprise. The automation rule pack add-on adds 90. Disabled rules do not count.

nightingale.platform.automation_rules.v1.AutomationRuleService Operations

nightingale.platform.care_plans.v1.CarePlanService (Collapsed)

​

CarePlanService enrolls patients in care plans and tracks their progress. A care plan is structured care from the catalog (see CarePlanCatalogService): tasks to tick off, such as taking a medication, and goals measured against the patient's readings, such as a blood pressure target.

The same plan can run for the same patient under several owners at once: each organization that enrolls them, and the patient themselves. Each enrollment has its own history, and only one of each owner's enrollments in a plan can be active at a time.

Organization staff see their organization's enrollments and, once the patient has accepted the organization, the patient's self-enrollments. A patient sees all of their enrollments. Staff need access to the patient's care plans (and, to enroll, update or tick tasks, permission to assign them); care plans are part of monitoring, which every plan includes.

An RPC that needs a feature of the organization's plan (MONITORING) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.care_plans.v1.CarePlanService Operations

nightingale.platform.catalogs.care_plan.v1.CarePlanCatalogService (Collapsed)

​

CarePlanCatalogService lists the care plans the caller can enroll a patient in. A plan is structured care: tasks to tick off, such as taking a medication, and goals measured against the patient's readings, such as a blood pressure target.

For organization staff the catalog is the organization's own plans plus the shared plans assigned to it. For a patient it is the shared plans, which they can enroll themselves in. Either way, only plans with a published version are listed, and each is described by that version.

Organization staff need access to care plans; care plans are part of monitoring, which every plan includes.

An RPC that needs a feature of the organization's plan (MONITORING) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.catalogs.care_plan.v1.CarePlanCatalogService Operations

nightingale.platform.catalogs.disease.v1.DiseaseService (Collapsed)

​

DiseaseService is the read-only catalog of diseases: conditions coded with ICD-10, with a name and description in the caller's language and the symptoms each one is known to cause. Chronic and visit diagnoses reference a disease from this catalog by its id.

Any signed-in organization staff member or patient can read the whole catalog; it is the same for everyone. Names and descriptions are returned in the caller's language, falling back to English.

nightingale.platform.catalogs.disease.v1.DiseaseService Operations

nightingale.platform.catalogs.drug.v1.DrugService (Collapsed)

​

DrugService is the read-only drug catalog. Each drug is a generic medicine in one strength, presentation and administration route, for example "Rosiglitazone 4mg Oral Tablet". A drug can also be sold as one or more commercial variants: a brand name from a vendor in a country. Prescriptions and drug intakes reference a drug from this catalog by its id.

Any signed-in organization staff member or patient can read the whole catalog; it is the same for everyone. Names are returned in the caller's language, falling back to English. Every RPC fails with UNAUTHENTICATED when the call carries no valid credentials.

nightingale.platform.catalogs.drug.v1.DrugService Operations

nightingale.platform.catalogs.edible.v1.EdibleService (Collapsed)

​

EdibleService gives read-only access to the shared catalog of foods, drinks and supplements. The catalog is the same for every organization and cannot be changed through this API. Staff and patients can both call it; names and descriptions come back in the caller's language.

nightingale.platform.catalogs.edible.v1.EdibleService Operations

nightingale.platform.catalogs.imaging.v1.ImagingCatalogService (Collapsed)

​

ImagingCatalogService provides read-only access to the catalog of imaging studies that can be ordered. The catalog is shared reference data, the same for every organization. Both organization staff and patients can read it, and names are returned in the caller's language.

nightingale.platform.catalogs.imaging.v1.ImagingCatalogService Operations

nightingale.platform.catalogs.laboratory.v1.LaboratoryCatalogService (Collapsed)

​

LaboratoryCatalogService provides read-only access to the catalog of laboratory tests that can be ordered and the parameters each test measures. The catalog is shared reference data, the same for every organization. Both organization staff and patients can read it, and names are returned in the caller's language.

nightingale.platform.catalogs.laboratory.v1.LaboratoryCatalogService Operations

nightingale.platform.catalogs.risk_script.v1.RiskScriptCatalogService (Collapsed)

​

RiskScriptCatalogService provides read-only access to the risk scripts that compute patient risk scores, so that a score can be shown with its script's name, colour and levels. Scripts are created and published by Nightingale, not through this API.

For organization staff, the catalog holds the active scripts their organization uses: the shared scripts assigned to it and every script it owns. Staff need permission to view the organization's risk scripts, otherwise both RPCs fail with PERMISSION_DENIED. A patient can call ListRiskScripts only. Deleted and inactive scripts are never returned.

nightingale.platform.catalogs.risk_script.v1.RiskScriptCatalogService Operations

nightingale.platform.catalogs.symptom_catalog.v1.SymptomCatalogService (Collapsed)

​

SymptomCatalogService is the read-only catalog of symptoms a patient can report, such as headache or shortness of breath, grouped into categories such as respiratory or neurological. Symptom logs reference a symptom from this catalog by its id.

Any signed-in organization staff member or patient can read the whole catalog; it is the same for everyone. Names, descriptions and categories are returned in the caller's language, falling back to English.

nightingale.platform.catalogs.symptom_catalog.v1.SymptomCatalogService Operations

nightingale.platform.catalogs.workout.v1.WorkoutService (Collapsed)

​

WorkoutService gives read-only access to the shared catalog of workouts. The catalog is the same for every organization and cannot be changed through this API. Staff and patients can both call it; names and descriptions come back in the caller's language.

nightingale.platform.catalogs.workout.v1.WorkoutService Operations

nightingale.platform.clinical.allergy.v1.AllergyService (Collapsed)

​

AllergyService records a patient's allergies, whether reported by the patient or documented by a caregiver.

Every RPC can be called both by organization staff and by patients. Staff always name the patient with patient_id, and the patient must be linked to your organization; otherwise the call fails with PERMISSION_DENIED (or INVALID_ARGUMENT when patient_id is missing or malformed). Staff can work with a patient's allergies only while the patient shares clinical records with your organization. If the patient does not, or the sharing has expired, ListAllergies returns no allergies, AddAllergy fails with PERMISSION_DENIED, and the other RPCs fail with NOT_FOUND. Patients act on their own record: they may omit patient_id, and sending anyone else's fails with PERMISSION_DENIED.

Allergies a patient adds are self-reported. Allergies staff add are professional records owned by the staff member's organization. Patients can change and delete only their self-reported allergies; staff can change and delete only their own organization's allergies.

nightingale.platform.clinical.allergy.v1.AllergyService Operations

nightingale.platform.clinical.chronic_diagnosis.v1.ChronicDiagnosisService (Collapsed)

​

ChronicDiagnosisService records a patient's chronic conditions and the diseases diagnosed in their relatives (family history).

Every chronic-diagnosis RPC, and ListRelativeDiagnoses, can be called by organization staff and by patients; adding and removing family history is for patients only. Staff must name the patient with patient_id; the patient must be linked to the staff member's organization and accepted by it, or the call fails with PERMISSION_DENIED. Staff can neither read nor add diagnoses once the patient stops sharing clinical records with the organization or that sharing has expired, or when the staff member's account is restricted to patient tags the patient does not carry. Patients always act on their own record: they may omit patient_id, and supplying another patient's ID fails with PERMISSION_DENIED.

A chronic diagnosis is either PROFESSIONAL (recorded by organization staff) or SELF_REPORTED (recorded by the patient). Staff see their own organization's professional diagnoses, never another organization's, and can change only those. They also see the patient's self-reported ones once the patient has accepted the organization too, but cannot change them. Patients see every diagnosis on their record, from any organization, but can change only the ones they reported themselves.

Diseases are identified by disease_id, an entry from the disease catalog (see the disease catalog's ListDiseases and GetDisease).

nightingale.platform.clinical.chronic_diagnosis.v1.ChronicDiagnosisService Operations

nightingale.platform.clinical.drug_intake.v1.DrugIntakeService (Collapsed)

​

DrugIntakeService records the doses of medication a patient has taken.

Both patients and organization staff record intakes. A patient sees every intake recorded about them, but can delete only the ones they recorded. Staff see their own organization's records plus the ones the patient recorded, once the patient has also accepted the organization, and can delete only their organization's records. Staff see and record intakes only while the patient shares their lifestyle records with the organization.

Staff must name the patient with patient_id and the patient must be linked to their organization, otherwise the call fails with PERMISSION_DENIED. A patient acts on their own record; naming another patient fails with PERMISSION_DENIED.

nightingale.platform.clinical.drug_intake.v1.DrugIntakeService Operations

nightingale.platform.clinical.drug_prescription.v1.DrugPrescriptionService (Collapsed)

​

DrugPrescriptionService manages the drug prescriptions issued to a patient.

A prescription is either issued by organization staff, or self-reported by the patient: a prescription the patient got elsewhere and recorded themselves, which belongs to no organization and no caregiver.

Staff must name the patient in patient_id; it is INVALID_ARGUMENT to omit it, and PERMISSION_DENIED when the patient is not affiliated with the caller's organization. Staff see the prescriptions their organization issued while the patient shares clinical records with it, and the patient's self-reported ones once the patient has also accepted the organization. Any staff member of the issuing organization may change or delete one of its prescriptions.

A patient may omit patient_id; if they supply it, it must be their own, otherwise the call fails with PERMISSION_DENIED. A patient reads every prescription issued to them, from every organization, and can change or delete only the prescriptions they recorded themselves.

nightingale.platform.clinical.drug_prescription.v1.DrugPrescriptionService Operations

nightingale.platform.clinical.emotional_state.v1.EmotionalStateService (Collapsed)

​

EmotionalStateService records a patient's emotional state over time and returns individual entries and averaged statistics.

Each entry records one day's mood and stress level; two scores (indices) are computed from them when the entry is created. Both the patient and organization staff can record entries. Staff see the entries recorded by their own organization, plus the patient's own entries once the patient has accepted the organization, in both cases only while the patient shares lifestyle data with it. A patient sees every entry about them. Staff can delete any entry their organization recorded; a patient can delete only the entries they recorded themselves.

An RPC that needs a feature of the organization's plan (LIFESTYLE_STATISTICS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.clinical.emotional_state.v1.EmotionalStateService Operations

nightingale.platform.clinical.imaging.v1.ImagingService (Collapsed)

​

ImagingService manages imaging studies from order to result: ordered (UNFULFILLED), performed (ACQUIRED), reported (FULFILLED), or cancelled. Status changes made by staff are recorded as events on the study.

Staff run the whole lifecycle. Ordering, recording and changing studies needs the IMAGING feature of the organization's plan: without it they fail with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED. Reading studies and their history needs no plan feature, so they stay readable after a downgrade. Patients can read their own studies, report studies done elsewhere with SubmitImagingResults, and attach files with AddImagingAttachment. The other write RPCs are for staff. An RPC marked "Staff only" returns PERMISSION_DENIED to a patient, whatever the study's status.

A performed study stays with the location it was performed at: once a study has an acquisition location, staff change it only if they may manage imaging at that location (they are assigned there and the permission is not excluded for them there); anyone else gets PERMISSION_DENIED. Reading the study, and adding or removing its attachments, are not limited by location.

Each route has two forms. Staff use the one with a patient segment, since every RPC except ListImagings needs to know the patient. Patients may use either, as the patient is always themselves; a patient naming any other patient gets PERMISSION_DENIED.

A study that does not exist and a study the caller is not allowed to see both return NOT_FOUND. An action the study's current status does not allow returns FAILED_PRECONDITION.

nightingale.platform.clinical.imaging.v1.ImagingService Operations

nightingale.platform.clinical.laboratory.v1.LaboratoryService (Collapsed)

​

LaboratoryService manages laboratory tests from order to result: ordered (UNFULFILLED), sample collected (COLLECTED), results recorded per parameter (IN_PROGRESS, then FULFILLED), or cancelled. Status changes made by staff are recorded as events.

Staff run the whole lifecycle. Patients can read their own tests, report results they already hold with SubmitLaboratoryResults, and attach files with AddLaboratoryAttachment; the other write RPCs are for staff. An RPC marked "Staff only" returns PERMISSION_DENIED to a patient, whatever the test's status.

A collected sample stays with the location it was collected at: once a test has a collection location, staff change it only if they may manage laboratories at that location (they are assigned there and the permission is not excluded for them there); anyone else gets PERMISSION_DENIED. Reading it is not limited by location.

Each route has two forms. Staff use the one with a patient segment, since every RPC except ListLaboratories needs to know the patient. Patients may use either, as the patient is always themselves.

A test that does not exist and a test the caller is not allowed to see both return NOT_FOUND. An action the test's current status does not allow returns FAILED_PRECONDITION.

An RPC that needs a feature of the organization's plan (GENERATED_DOCUMENTS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.clinical.laboratory.v1.LaboratoryService Operations

nightingale.platform.clinical.observation.v1.ObservationService (Collapsed)

​

ObservationService records a patient's health measurements, such as weight, blood pressure or temperature, and returns them individually, grouped by the batch they were recorded in, or as the latest value per type.

Each measurement has a type, identified by a slug such as weight or systolic_bp. ListObservationTypes returns the available types with their units and accepted ranges.

Staff record measurements under their organization; a patient records their own. Staff see their own organization's measurements, plus those the patient recorded once the patient has fully accepted the organization, and only while the patient shares vital signs with the organization. A patient sees every measurement recorded about them.

Every call except ListObservationTypes concerns one patient. Staff must always pass patient_id; a call without it fails with INVALID_ARGUMENT, and a call for a patient the organization has not accepted fails with PERMISSION_DENIED. A patient may omit it; passing another patient's identifier fails with PERMISSION_DENIED.

nightingale.platform.clinical.observation.v1.ObservationService Operations

nightingale.platform.clinical.surgery_history.v1.SurgeryHistoryService (Collapsed)

​

SurgeryHistoryService records a patient's past surgeries.

Entries are either self-reported by the patient or professional, recorded by organization staff on behalf of their organization. Either kind can be confirmed by the other side, which creates a new entry linked to the original.

Patients can call every RPC in this service for their own record. They may omit patient_id; if they supply one that is not their own, the call fails with PERMISSION_DENIED. Entries they add are self-reported. They see all of their own entries, from every organization, without collapsing, and can change or delete only their self-reported entries.

Organization staff must supply patient_id. The call fails with INVALID_ARGUMENT if it is missing or malformed, and with PERMISSION_DENIED if the patient is not linked to the caller's organization. Entries they add are professional and attributed to them and their organization. They see their own organization's professional entries and, once the patient has fully accepted data sharing with the organization, the patient's self-reported entries. They cannot see other organizations' entries, and can change or delete only their own organization's entries.

Staff can work with a patient's surgery history only while the patient shares clinical records with the organization. If the patient does not, or the sharing has expired, ListSurgeryHistory returns no entries, AddSurgeryHistory fails with PERMISSION_DENIED, and the other RPCs fail with NOT_FOUND.

nightingale.platform.clinical.surgery_history.v1.SurgeryHistoryService Operations

nightingale.platform.clinical.symptom_log.v1.SymptomLogService (Collapsed)

​

SymptomLogService records the symptoms a patient experiences over time.

Symptoms are recorded in batches: every symptom submitted in one call shares a batch identifier (correlation_id) and can be listed or deleted together. Symptoms themselves come from the symptom catalog.

Both the patient and organization staff can record symptoms. Staff see the entries recorded by their own organization, plus the patient's own entries once the patient has accepted the organization, in both cases only while the patient shares vital signs with it. A patient sees every entry about them. Staff can delete any entry their organization recorded; a patient can delete only the entries they recorded themselves.

nightingale.platform.clinical.symptom_log.v1.SymptomLogService Operations

nightingale.platform.clinical.visit_diagnosis.v1.VisitDiagnosisService (Collapsed)

​

VisitDiagnosisService records the diagnoses made for a patient during a visit, and tracks when each one is resolved.

A visit diagnosis is a condition from the disease catalog, diagnosed on a given day during a given visit. Long-term conditions belong in the patient's chronic diagnoses instead.

Only organization staff record, resolve and delete visit diagnoses. Staff see the diagnoses made by their own organization, and only while the patient shares clinical information with it. A patient can list every diagnosis made for them, from every organization.

For organization staff, every RPC requires patient_id: a missing or malformed one fails with INVALID_ARGUMENT, and a patient who is not associated with the caller's organization fails with PERMISSION_DENIED.

nightingale.platform.clinical.visit_diagnosis.v1.VisitDiagnosisService Operations

nightingale.platform.clinical.visits.v1.VisitService (Collapsed)

​

VisitService manages medical visits: their lifecycle from request to close, clinician observations and after-care instructions. Live changes to a visit, and who else has it open, are streamed by RealtimeService.SubscribeVisitUpdates.

Every RPC is for staff unless its description says patients can call it too. ListVisits, GetVisit, GetFollowUpChain, ListVisitEvents, ListVisitObservations and the visit document RPCs take patient_id as optional for staff; if it is set and is not the visit's patient, they return NOT_FOUND. Every other RPC requires staff to supply patient_id, so its route without a patient in the path fails with INVALID_ARGUMENT for staff. Changes to a visit generally require it to be REQUESTED, SCHEDULED or IN_PROGRESS; a CLOSED or CANCELLED visit returns NOT_FOUND unless noted otherwise.

Reading a visit is not limited by location: with permission to view visits you see every visit of your organization. Changing one is, except for requesting and withdrawing a request: every other change needs its permission at the visit's location, which means your role grants it, you are assigned to the location, and it is not excluded for you there. Without that the call fails with PERMISSION_DENIED.

An RPC that needs a feature of the organization's plan (GENERATED_DOCUMENTS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan. ============================================================================ Medical Visit Lifecycle

nightingale.platform.clinical.visits.v1.VisitService Operations

nightingale.platform.document_templates.v1.DocumentTemplateService (Collapsed)

​

DocumentTemplateService manages the Typst templates your organization's visit reports, prescriptions and laboratory reports are printed with. A document uses the most specific active template for its kind: one for its location, then one for the location's country, then your organization's default.

Viewing templates needs permission to view document templates; changing them, permission to manage them. They only ever reach your own organization's templates. Every RPC needs a plan that includes document templates (Professional or Enterprise) and is for staff only.

An RPC that needs a feature of the organization's plan (DOCUMENT_TEMPLATES) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.document_templates.v1.DocumentTemplateService Operations

nightingale.platform.exports.v1.ExportService (Collapsed)

​

ExportService turns your organization's data into files: a staff list and a patient list, produced as background jobs that you can follow, download and cancel. Visit reports, prescriptions and laboratory reports are documents of their visit or laboratory order instead; see VisitService and LaboratoryService.

A file only ever contains what the person who asked for it could see when it was produced: the same staff, patients, locations and tags they could open in the app. Only the person who asked for an export can download its file, for 30 days; after that the file is deleted and the record kept. To get a file of someone else's export, request a new one.

Every RPC needs a plan that includes exports (Professional or Enterprise) and is for staff only.

An RPC that needs a feature of the organization's plan (EXPORTS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.exports.v1.ExportService Operations

nightingale.platform.imports.v1.ImportService (Collapsed)

​

ImportService loads records into your organization in bulk from a CSV or XLSX file: staff, patients, locations, and the links and clinical history between them.

An import runs in the background. Upload the file with StorageService.GetUploadURL, start the job with CreateImportJob, then follow it with GetImportJob or ListImportJobs until it completes. Each row is imported as the person who started the job, with their permissions: a row they could not create by hand fails, and its reason is listed in the job's row errors.

Import jobs belong to your organization, and everyone in it who may view imports sees all of them. The service is for staff only: viewing needs permission to view imports, and every change needs permission to manage them.

nightingale.platform.imports.v1.ImportService Operations

nightingale.platform.intake.v1.IntakeService (Collapsed)

​

IntakeService provides public (unauthenticated) endpoints for pre-visit patient intake. Access is controlled by a cryptographic token linked to a specific visit, not by user authentication. Send the token in the X-Public-Token header on every call; it is never part of the URL, so it stays out of access logs, proxies and Referer headers. The intake link staff share carries it in the URL fragment (after #), which browsers never send to a server.

Failures:

  • UNAUTHENTICATED: the token is missing or unknown, or was issued for something other than visit intake, or its visit is no longer requested or scheduled (it has started, been closed, cancelled or deleted).
  • PERMISSION_DENIED: the token has expired or has already been used. A token is also expired once a newer token has been issued for the visit.

Error messages are localized from the Accept-Language header.

nightingale.platform.intake.v1.IntakeService Operations

nightingale.platform.integrations.v1.IntegrationService (Collapsed)

​

IntegrationService manages the machine users and access tokens your own systems use to call the Nightingale API.

An integration authenticates as a machine user, with one of its personal access tokens, and acts on behalf of one of your users:

  • Authorization: Bearer
  • X-Client-Type: integration
  • X-Impersonate-User:

The request is then allowed exactly what that user is allowed. A machine user's permission mode limits which users it may name (see IntegrationPermissionMode).

Every RPC works on the caller's own organization and is for staff only. Integration access, and so this service, requires your organization to hold the INTEGRATIONS add-on; without it every RPC fails with PERMISSION_DENIED.

The two List RPCs need the View Integrations permission; every other RPC needs Manage Integrations. A caller without the permission an RPC needs gets PERMISSION_DENIED.

Only a person signed in directly can change integrations. An integration may list machine users and tokens, but every RPC that creates, changes or deletes them fails with PERMISSION_DENIED when called with a personal access token, whoever the integration acts as. This keeps a machine user from lifting its own restrictions.

An RPC that needs a feature of the organization's plan (INTEGRATIONS_API) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.integrations.v1.IntegrationService Operations

nightingale.platform.license.v1.LicenseService (Collapsed)

​

LicenseService shows which licences Nightingale offers and which ones the caller's organization holds.

A licence decides which features an organization can use. An organization normally holds one base plan (such as Essentials, Professional or Enterprise), where a higher plan includes everything in the plans below it, and may hold add-ons for extra features. Staff of an organization can only use a feature when one of the organization's licences in force includes it; otherwise the feature's calls fail with PERMISSION_DENIED with an ErrorInfo whose reason is FEATURE_NOT_LICENSED. A licence is in force from its start date until its end date, and applies from the moment it starts until the moment it ends. Calls made with an integration token also need the Integrations add-on. Licences apply to organization staff only, never to patients.

Licences are granted, changed and ended by Nightingale, not through this API. The license catalog is read-only. Organization licences are always those of the caller's own organization. The only change an organization can make itself is the quantity of one of its licences.

Only organization staff can call this service; patients get PERMISSION_DENIED.

nightingale.platform.license.v1.LicenseService Operations

nightingale.platform.lifestyle.exercise.v1.ExerciseService (Collapsed)

​

ExerciseService records a patient's exercise sessions and returns individual entries and averages over time.

Both patients and organization staff can record entries. A patient sees every entry about them, from every organization. Staff see the entries their own organization recorded, plus the entries the patient recorded themselves once the patient has also accepted the organization, in both cases only while the patient shares lifestyle data with the organization and the association has not expired.

An RPC that needs a feature of the organization's plan (LIFESTYLE_STATISTICS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.lifestyle.exercise.v1.ExerciseService Operations

nightingale.platform.lifestyle.nutrition.v1.NutritionService (Collapsed)

​

NutritionService records a patient's nutrition entries and returns individual entries and average scores over time.

Each entry is one meal, scored from 0 to 100. Both patients and organization staff can record entries. A patient sees every entry about them, from every organization. Staff see the entries their own organization recorded, plus the entries the patient recorded themselves once the patient has also accepted the organization, in both cases only while the patient shares lifestyle data with it. Entries cannot be edited: delete one and record it again.

An RPC that needs a feature of the organization's plan (LIFESTYLE_STATISTICS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.lifestyle.nutrition.v1.NutritionService Operations

nightingale.platform.lifestyle.sleep.v1.SleepService (Collapsed)

​

SleepService records a patient's sleep entries and returns individual entries and average scores over time.

Each entry is one night, described by hours slept and how rested the patient felt, and scored from 0 to 100. Both patients and organization staff can record entries. A patient sees every entry about them, from every organization. Staff see the entries their own organization recorded, plus the entries the patient recorded themselves once the patient has also accepted the organization, in both cases only while the patient shares lifestyle data with the organization and the association has not expired.

An RPC that needs a feature of the organization's plan (LIFESTYLE_STATISTICS) fails for staff of an organization without it with PERMISSION_DENIED and an ErrorInfo of reason FEATURE_NOT_LICENSED, whose feature metadata names the feature. Patients are never refused for their organization's plan.

nightingale.platform.lifestyle.sleep.v1.SleepService Operations

nightingale.platform.locations.v1.LocationService (Collapsed)

​

LocationService manages your organization's physical sites: their addresses, which one is primary, and the scheduling settings (slot length and time zone) that bookings use.

Only ListLocations accepts patients; every other RPC is for staff and works on the caller's own organization.

nightingale.platform.locations.v1.LocationService Operations

nightingale.platform.organizations.v1.OrganizationService (Collapsed)

​

OrganizationService looks up organizations, manages your organization's tags, and restricts which tagged patients a staff member can see.

Staff can only ever see their own organization. Patients see the organizations they are associated with.

nightingale.platform.organizations.v1.OrganizationService Operations

nightingale.platform.outbound_callbacks.v1.OutboundCallbackService (Collapsed)

​

OutboundCallbackService manages your organization's outbound webhooks and shows how each delivery went, so you can check that your endpoints are receiving events. It is for staff only, and needs the Integrations add-on: without it every call fails with PERMISSION_DENIED (reason FEATURE_NOT_LICENSED, feature OUTBOUND_CALLBACKS).

A subscription sends one event type to one HTTPS endpoint. Your organization can have at most one active subscription per event type. A subscription receives every patient's events, so staff whose access is limited to patients with certain tags cannot create or change one.

A visit_closed payload carries the visit's records only in the categories (vitals, lifestyle, clinical) the patient shares with your organization, and none once the patient's association with your organization has expired: the same records your staff can see in the app.

The platform team can disable a subscription, for example when its endpoint misbehaves (disabled_by_admin). Nothing is delivered to it then, and you cannot change, activate or delete it until they lift the disable: those calls fail with FAILED_PRECONDITION. Neither can you create or activate another subscription for the same event meanwhile. Deliveries that were waiting to be sent when it was disabled are cancelled (DEAD_LETTERED), and events that occur while it is disabled are not sent later.

Each delivery is an HTTPS POST of a JSON envelope with the fields version, event_type, organization_id, resource_id, occurred_at and data. It carries these headers:

  • X-Nightingale-Signature: t=,v1=<hex HMAC-SHA256 of "." keyed with the subscription's signing secret>
  • X-Nightingale-Delivery-Id
  • X-Nightingale-Event-Id
  • Content-Type: application/json
  • your own authentication header, if one was configured

Any 2xx response within 15 seconds counts as delivered. Redirects are not followed: a 3xx response counts as a failure. Failed deliveries are retried with a growing delay. Repeated failures pause the subscription for a few minutes. A delivery can arrive more than once, so use X-Nightingale-Delivery-Id to ignore duplicates.

The endpoint's host is resolved again for every attempt, and only public addresses are connected to: a host that has come to resolve to a private or otherwise internal address fails that attempt.

nightingale.platform.outbound_callbacks.v1.OutboundCallbackService Operations

nightingale.platform.patients.v1.PatientService (Collapsed)

​

PatientService manages patient records, the connection between a patient and an organization, the followers of that connection, and a patient's contacts.

A patient has one record across the platform. Each organization that cares for them has its own association with the patient, carrying its internal details and its own copy of the patient's identity. The organization can see the patient once it has accepted the association. Data the patient recorded themselves also needs the patient's acceptance, which the patient can withdraw at any time by declining or leaving the organization.

Staff always act within their own organization. Patients act on their own record: where a request takes a patient_id, a patient may leave it empty or send their own ID, and any other ID fails with PERMISSION_DENIED.

nightingale.platform.patients.v1.PatientService Operations

nightingale.platform.realtime.v1.RealtimeService (Collapsed)

​

RealtimeService pushes live change notifications to clients, so a screen can refresh the moment something it shows changes instead of polling for it.

Streams carry notifications, never data: an event says which kind of record changed and the client then re-reads it through the ordinary API, where the usual access rules apply.

This service is available over Connect, gRPC and gRPC-Web only. It has no REST routes, because server streaming does not map onto a plain HTTP request and response.

nightingale.platform.realtime.v1.RealtimeService Operations

nightingale.platform.risk.v1.RiskService (Collapsed)

​

RiskService returns the weekly risk scores computed for a patient, and lets a patient choose which risk scripts they subscribe to.

A risk script is a published assessment, such as a diabetes risk model, that is run once per ISO week against the patient's records and produces a score for that week. A script applies to a patient when it belongs to an organization that has accepted the patient, when such an organization has subscribed to it, or when the patient has subscribed to it directly. A week is scored once it has ended (weeks run Monday to Sunday, UTC). Scores are computed in the background, and on demand when they are read.

nightingale.platform.risk.v1.RiskService Operations

nightingale.platform.roles.v1.RoleService (Collapsed)

​

RoleService manages an organization's roles and the permissions each grants.

A user's permissions are the combined permissions of the roles assigned to them. Roles are assigned to users through the user APIs, not here. Every RPC works on the caller's own organization and is for staff only.

nightingale.platform.roles.v1.RoleService Operations

nightingale.platform.scheduling.v1.SchedulingService (Collapsed)

​

SchedulingService manages when staff can be booked: each staff member's weekly availability per location, date-specific exceptions to it, each location's opening hours, and the calendars and free slots resolved from them.

All times are wall-clock times at the location, between 00:00 and 23:59:59; 24:00 is not accepted, so a window that runs to midnight ends at 23:59. Responses that carry times also return the location's IANA time zone, which you need to turn them into instants. Every RPC works on the caller's own organization and is for staff only.

nightingale.platform.scheduling.v1.SchedulingService Operations

nightingale.platform.user_locations.v1.UserLocationService (Collapsed)

​

UserLocationService records which staff members work at which of your organization's locations, and which location-scoped permissions are switched off for each of them there. Roles apply organization-wide; an assignment can only take location-scoped permissions away, never add them. It is for staff only.

nightingale.platform.user_locations.v1.UserLocationService Operations

nightingale.platform.users.v1.UserService (Collapsed)

​

UserService manages your organization's staff accounts: creating, editing, deactivating and reactivating them, and assigning their roles. It also tells any signed-in caller who they are and what they may do.

Only GetCurrentUser and GetCurrentPermissions accept patients; every other RPC is for staff and works on the caller's own organization.

nightingale.platform.users.v1.UserService Operations

Models