> ## Documentation Index
> Fetch the complete documentation index at: https://help.apnealytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A read-only REST API for your own Apnealytics therapy data, authenticated with a personal API key.

The Apnealytics API is a **read-only** REST API for **your own** CPAP therapy data.
Every response is JSON and is scoped to your account only — a key can never read
another account's data.

> [!NOTE]
>
> The API is a **Pro** feature. Create keys in the app under **Account → API**.
> If your plan is not Pro, a key will not authenticate.

## Base URL

```
https://my.apnealytics.com
```

All endpoints live under `/api/v1/me`.

## Authentication

Authenticate with a **personal API key** sent as a **Bearer token**:

1. Open the app and go to **Account → API**.
2. Create a key and give it a name (e.g. *Home Assistant*). The plaintext key is
   shown **once** — copy it then. Afterwards only a short prefix is visible.
3. Send it on every request in the `Authorization` header:

```
Authorization: Bearer apn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Keys are revocable at any time from the same page; a revoked key stops working
immediately. Because keys are Pro-gated, a key also stops working if the account
is no longer Pro.

## Quickstart

```bash curl theme={null}
curl -H "Authorization: Bearer $APN_KEY" \
  https://my.apnealytics.com/api/v1/me/summary
```

```js JavaScript theme={null}
const res = await fetch("https://my.apnealytics.com/api/v1/me/summary", {
  headers: { Authorization: `Bearer ${process.env.APN_KEY}` },
});
const { summary, nights } = await res.json();
console.log(`${nights} nights, avg AHI ${summary.avgAhi}`);
```

## Endpoints

> [card] [GET /api/v1/me](https://help.apnealytics.com/api-reference/endpoint/get-me)
>
> Account profile and high-level night counts.

> [card] [GET /api/v1/me/summary](https://help.apnealytics.com/api-reference/endpoint/get-summary)
>
> Aggregate therapy summary — adherence, AHI, composition.

> [card] [GET /api/v1/me/nights](https://help.apnealytics.com/api-reference/endpoint/get-nights)
>
> Nightly rows, with optional `from` / `to` / `limit`.

> [card] [GET /api/v1/me/vitals](https://help.apnealytics.com/api-reference/endpoint/get-vitals)
>
> Wearable / Apple Health daily metrics.

## Rate limits

There is currently **no rate limiting** on the read-only API. Please be a good
citizen: cache responses and avoid tight polling loops. Keys may be revoked if
usage puts the service at risk.

## Errors

Errors use a uniform JSON envelope with a stable, machine-readable `error` code:

```json theme={null}
{ "error": "unauthorized" }
```

| Status | `error` | Meaning |
| - | - | - |
| 400 | `invalid_request` | A query parameter failed validation (e.g. a malformed `from` / `to`). |
| 401 | `unauthorized` | Missing, malformed, revoked, expired, or non-Pro key. (No case oracle.) |
| 500 | `server_error` | Unexpected server error. No internal detail is returned. |

## Units and conventions

* Dates are `YYYY-MM-DD`; nightly data is keyed by the calendar day of therapy.
* **AHI** and its sub-indices (OAI, CAI, HI, UAI) are events/hour.
* **Leak** is reported in **L/min**; **pressures** in cmH₂O; **usage** in minutes.
* Nightly rows are returned oldest-first. On `/api/v1/me/nights`, `limit` returns
  the most recent matching rows (default 100, max 1000).
* Non-ResMed machines (DreamStation, F\&P SleepStyle, DeVilbiss, BMC) currently
  fill usage and pressure settings only — clinical fields such as AHI sub-indices
  and leak are `null` for those nights.

> [!WARNING]
>
> Apnealytics is a tracking and coaching tool, **not a medical device**.
> Machine-estimated AHI and the values returned by this API are not a clinical
> diagnosis. Discuss your therapy with a qualified clinician.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.