# Rune Labs Stream API

The V1 stream API is now longer supported aside from the `/v1/session` endpoint (see below).

## [section/Overview](https://docs.runelabs.io/stream/v1/#section/Overview) Overview

## [section/Overview/Key-Concepts](https://docs.runelabs.io/stream/v1/#section/Overview/Key-Concepts) Key Concepts

Throughout this document, the following terminology is used:

- **Patient** refers to the user of a patient-facing app.
- **Client** refers to the patient-facing app itself. A client accesses data programmatically, on behalf of a patient.
- **Device** refers to the sensor serving as the datasource, such as a patient implant, phone, or wearable.

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.

## [section/Overview/Authentication](https://docs.runelabs.io/stream/v1/#section/Overview/Authentication) Authentication

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

- Access tokens (recommended)
- Client keys

Both the access tokens and the client keys are comprised of two parts: a _key ID_ and an _access key_. These are analagous to a username and password. Usage is described in detail below.

### Access Tokens

Access tokens provide read access to all the patients in your organization. This is the recommended authentication method for the Stream API.

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

- `X-Rune-User-Access-Token-Id` \- access token ID
- `X-Rune-User-Access-Token-Secret` \- access token secret

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.

#### Create a New Access Token

1. Log in to the [Rune web app](https://app.runelabs.io/)
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.

### 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](https://app.runelabs.io/) 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](https://app.runelabs.io/). 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).

## [tag/v1session](https://docs.runelabs.io/stream/v1/#tag/v1session) Session

Fetch raw data that was uploaded to the Rune Platform.

To use this endpoint, you will need a **dataset ID**, which is generated by the [Rune Data API](https://docs.runelabs.io/data) on upload. Rune’s GraphQL API can be used to find dataset IDs for a given patient.

A dataset may be composed of several **streams** (files). Each request to this endpoint returns _one_ stream: you may need to make multiple requests to download an entire dataset.

Note that unlike other Stream API endpoints, this endpoint returns the **raw binary** of the original data. It does not have a standard JSON or CSV structure.

The typical use for this endpoint is to download a raw dataset into local storage. **This is not the optimal way to download entire archives.** If for any reason you need to export all data for all your patients, please contact [support@runelabs.io](mailto:support@runelabs.io), and our team will provide you with a copy of the raw data in a more efficient way.

## [tag/v1session/paths/~1v1~1session/get](https://docs.runelabs.io/stream/v1/#tag/v1session/paths/~1v1~1session/get) Session

##### query Parameters

|     |     |
| --- | --- |
| session_id<br>required | string<br>Example: session_id=dataset-37a2a3dc70c825d9ed1dc5bfcc3137b7c63c84f42c89b075975fb99bfb81c105<br>The dataset ID to download.<br>Confusingly, this is _NOT_ the `session_id` that is provided in the client request to the Data Upload API. |
| stream_name<br>required | string<br>Example: stream_name=metadata<br>The name of the specific stream to download from the dataset.<br>Stream names vary, according to the schema of the dataset. |

### Responses

**200** Successful request

**400** Bad request

**401** Not authorized to perform the request

**404** Not found

**429** Client IP throttled

**500** Internal server error

**503** Service unavailable

get/v1/session

https://stream.runelabs.io/v1/session

### Response samples

- 400
- 401
- 404
- 500

Content type

application/json

```json
{"success": false,

"error": {"message": "string",

"type": "string"
},

"result": null
}
```