Patient

The person about whom data was measured. This may include a StrivePD user, a person with a neural implant, etc. Each patient has a unique identifier ("patient ID"). Patient IDs are generated by Rune and cannot be changed.

Device

The sensor serving as the data source (e.g. a DBS implant, iOS application, wearable device, etc.). A patient may have multiple devices: each one has a unique identifier ("device ID"). Device IDs are generated by Rune and cannot be changed. They do not correspond to any identifier or information from the device itself.

Client

Refers to the patient-facing app itself. A client accesses data programmatically, on behalf of a patient.

A client is associated with exactly one patient. Patients may have multiple clients, depending on how many apps are sending or accessing data. Patients and clients are resources in the Rune platform with unique identifiers, and they are used to control access to patient data.

Dataset

A dataset is a collection of files containing data recorded by a patient's device, over some period of time.

Each dataset has a schema that broadly identifies its contents. The schema_id serves as a typing system for datasets. Supported schema IDs include:

• medtronic-percept-1
• medtronic-rcs-1
• strivestudy-applewatch-1
• strivestudy-applewatch-md-1
• strivestudy-healthkit-1
• strivestudy-healthkit-2
• strivestudy-spiraltest-1

Schemas specify the number of files that each dataset of a particular type contains, as well as the semantics of each of those files (i.e. what the file is expected to contain). This is used to parse and ingest data after upload.

For example, the strivestudy-applewatch-md-1 dataset schema is used for data collected by the StrivePD app, from the Apple Watch Movement Disorder Kit. Per the schema definition, 3 files must be uploaded for each dataset:

• tremor - Tremor data
• dyskinetic -- Dyskinesia data
• metadata -- Assorted metadata

Authentication is required for all API requests. There are several authentication methods:

Client Keys

Client keys provide read and write access to one patient.

To use a client key pair for authentication, the HTTP request must include two headers:

• X-Rune-Client-Key-Id - client key ID
• X-Rune-Client-Access-Key - client access key (secret)

Note that each client may only fetch data for its associated patient.

Register a New Client

1. Log in to the Rune web app as an admin user.
2. Find the patient you want to access data for, and open Patient Settings.
3. Open the Clients section.
4. Create a new client. You can name it anything, though typically it is named after your app.
5. A default client key pair will be created with the new client. Copy the key ID and the access key before closing the page. The access key will never be shown again.

Create New Client Keys

You can create any number of client keys for a given client, through the Rune web app. If you forget a key, you can always create a new key pair and disable the old.

It is highly recommended that you "rotate" keys for a patient every 3-6 months, by creating a new client key, configuring it in the client (e.g. the patient's app), then disabling the old key. You should do this immediately if you believe the key may have been compromised (e.g. stolen from the device, posted over any insecure/public communication channel, etc).

User Access Tokens

Access tokens are long-lived tokens that belong to a single user of the Rune platform, granting access to any patient in that user's active organization. Only admin users have access to the Data API.

To use an access token for authentication, the HTTP request must include the following headers:

• X-Rune-User-Access-Token-Id - access token ID
• X-Rune-User-Access-Token-Secret - access token secret
• X-Rune-Patient-Id - patient ID for the data being accessed

Create a New Access Token

1. Log in to the Rune web app
2. Click on the profile icon in the top right corner.
3. Click on User Settings.
4. On the left sidebar, click on Access Tokens.
5. Click CREATE ACCESS TOKEN.
6. Copy the token ID and the token secret before closing the page. The secret will never be shown again.

It is highly recommended that you "rotate" user access tokens every 3-6 months, by creating a new token and deactivating the old one. Store your access tokens securely, and do not share them.

JWT

JWTs are generated by the Rune web app upon login. This is not a recommended authentication method for API users.

To use a JWT for authentication, the HTTP request must include two headers:

• X-Rune-User-Access-Token - JWT
• X-Rune-Patient-Id - patient ID for the data being accessed

All endpoints return JSON-formatted data.

Standard HTTP status codes are used to indicate success or failure. In the event of most errors, the response body is JSON that includes additional information, with the following format:

{
  "success": false,
  "error": {
    "code": "EnumeratedErrorKind"
    "message": "Human-readable error description",
    "should_retry": false
  }
}

Endpoints to initiate a dataset upload or check on the status of an existing dataset.

Create an event or span, which can later be queried via the Stream API.

These endpoints only accept Client Key authentication.

Events and spans cannot be deleted. However, they will be overwritten, if the following values are identical:

• Patient ID (determined via authentication credentials)
• Device ID
• All timestamps (1 for events; 4 for spans)
• Classification

Query patient upload statistics per schema_id which include:

• Total bytes of raw data uploaded
• Number datasets uploaded
• Creation time of the latest dataset
• Creation time of the earliest dataset