Skip to content

Commit 5c9d20d

Browse files
StuMasonclaude
StuMason
and
claude
committed
docs: Add comprehensive documentation for GitHub Pages
- Add API reference with all endpoints documented - Add architecture overview with system diagram - Simplify nav to only include existing pages - Fix broken links in index.md and quickstart.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent db2e4d4 commit 5c9d20d

File tree

5 files changed

+504
-28
lines changed

5 files changed

+504
-28
lines changed

‎docs/api/overview.md‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
# API Reference
2+
3+
REST API for accessing synced Polar health data.
4+
5+
Base URL: `http://localhost:8000/api/v1`
6+
7+
## Authentication
8+
9+
All data endpoints require a `user_id` in the URL path. For self-hosted deployments, this is your Polar user ID. For SaaS integrations, this is your application's user identifier.
10+
11+
Sync endpoints require a Polar API access token via the `X-Polar-Token` header.
12+
13+
## Endpoints
14+
15+
### Sleep
16+
17+
| Method | Endpoint | Description |
18+
|--------|----------|-------------|
19+
| GET | `/users/{user_id}/sleep` | List sleep data |
20+
| GET | `/users/{user_id}/sleep/{date}` | Get sleep by date |
21+
22+
**Query Parameters:**
23+
- `days` (int, default: 7) - Number of days to fetch (1-365)
24+
25+
**Example:**
26+
```bash
27+
curl http://localhost:8000/api/v1/users/12345/sleep?days=30
28+
```
29+
30+
**Response:**
31+
```json
32+
[
33+
{
34+
"date": "2026-01-11",
35+
"sleep_score": 85,
36+
"total_sleep_hours": 7.5,
37+
"deep_sleep_hours": 1.8,
38+
"rem_sleep_hours": 1.9,
39+
"light_sleep_hours": 3.8,
40+
"hrv_avg": 45.2,
41+
"heart_rate_avg": 52
42+
}
43+
]
44+
```
45+
46+
---
47+
48+
### Activity
49+
50+
| Method | Endpoint | Description |
51+
|--------|----------|-------------|
52+
| GET | `/users/{user_id}/activity` | List daily activity |
53+
| GET | `/users/{user_id}/activity/{date}` | Get activity by date |
54+
55+
**Query Parameters:**
56+
- `days` (int, default: 30) - Number of days to fetch (1-365)
57+
58+
**Example:**
59+
```bash
60+
curl http://localhost:8000/api/v1/users/12345/activity?days=7
61+
```
62+
63+
**Response:**
64+
```json
65+
[
66+
{
67+
"date": "2026-01-11",
68+
"steps": 8542,
69+
"calories_active": 450,
70+
"calories_total": 2150,
71+
"distance_km": 6.2,
72+
"active_minutes": 45.5,
73+
"activity_score": 78
74+
}
75+
]
76+
```
77+
78+
---
79+
80+
### Nightly Recharge (HRV)
81+
82+
| Method | Endpoint | Description |
83+
|--------|----------|-------------|
84+
| GET | `/users/{user_id}/recharge` | List nightly recharge data |
85+
86+
**Query Parameters:**
87+
- `days` (int, default: 30) - Number of days to fetch (1-365)
88+
89+
**Example:**
90+
```bash
91+
curl http://localhost:8000/api/v1/users/12345/recharge?days=14
92+
```
93+
94+
**Response:**
95+
```json
96+
[
97+
{
98+
"date": "2026-01-11",
99+
"hrv_avg": 48.5,
100+
"ans_charge": 4.2,
101+
"ans_charge_status": "WELL_RECOVERED",
102+
"breathing_rate_avg": 14.2,
103+
"heart_rate_avg": 51
104+
}
105+
]
106+
```
107+
108+
---
109+
110+
### Exercises
111+
112+
| Method | Endpoint | Description |
113+
|--------|----------|-------------|
114+
| GET | `/users/{user_id}/exercises` | List exercises |
115+
| GET | `/users/{user_id}/exercises/{id}` | Get exercise detail |
116+
117+
**Query Parameters:**
118+
- `days` (int, default: 30) - Number of days to fetch (1-365)
119+
120+
**Example:**
121+
```bash
122+
curl http://localhost:8000/api/v1/users/12345/exercises?days=30
123+
```
124+
125+
**Response:**
126+
```json
127+
[
128+
{
129+
"id": 1,
130+
"polar_exercise_id": "abc123",
131+
"start_time": "2026-01-11 07:30:00",
132+
"sport": "RUNNING",
133+
"duration_minutes": 45.5,
134+
"distance_km": 8.2,
135+
"calories": 520,
136+
"average_heart_rate": 145,
137+
"max_heart_rate": 172,
138+
"training_load": 85
139+
}
140+
]
141+
```
142+
143+
---
144+
145+
### Cardio Load
146+
147+
| Method | Endpoint | Description |
148+
|--------|----------|-------------|
149+
| GET | `/users/{user_id}/cardio-load` | List cardio load data |
150+
151+
**Query Parameters:**
152+
- `days` (int, default: 30) - Number of days to fetch (1-365)
153+
154+
**Response:**
155+
```json
156+
[
157+
{
158+
"date": "2026-01-11",
159+
"strain": 125.5,
160+
"tolerance": 180.2,
161+
"cardio_load": 85.3,
162+
"cardio_load_ratio": 0.70,
163+
"cardio_load_status": "PRODUCTIVE"
164+
}
165+
]
166+
```
167+
168+
---
169+
170+
### Heart Rate
171+
172+
| Method | Endpoint | Description |
173+
|--------|----------|-------------|
174+
| GET | `/users/{user_id}/heart-rate` | List daily HR summaries |
175+
176+
**Query Parameters:**
177+
- `days` (int, default: 30) - Number of days to fetch (1-365)
178+
179+
**Response:**
180+
```json
181+
[
182+
{
183+
"date": "2026-01-11",
184+
"hr_min": 48,
185+
"hr_avg": 62,
186+
"hr_max": 165,
187+
"sample_count": 1440
188+
}
189+
]
190+
```
191+
192+
---
193+
194+
### SleepWise
195+
196+
| Method | Endpoint | Description |
197+
|--------|----------|-------------|
198+
| GET | `/users/{user_id}/sleepwise/alertness` | Hourly alertness predictions |
199+
| GET | `/users/{user_id}/sleepwise/bedtime` | Optimal bedtime recommendations |
200+
201+
**Query Parameters:**
202+
- `days` (int, default: 7) - Number of days to fetch (1-30)
203+
204+
**Alertness Response:**
205+
```json
206+
[
207+
{
208+
"period_start_time": "2026-01-11 08:00:00",
209+
"period_end_time": "2026-01-11 09:00:00",
210+
"grade": 4.2,
211+
"grade_classification": "GOOD"
212+
}
213+
]
214+
```
215+
216+
**Bedtime Response:**
217+
```json
218+
[
219+
{
220+
"period_start_time": "2026-01-11 00:00:00",
221+
"period_end_time": "2026-01-12 00:00:00",
222+
"preferred_sleep_start": "22:30:00",
223+
"preferred_sleep_end": "06:30:00",
224+
"sleep_gate_start": "22:00:00",
225+
"sleep_gate_end": "23:00:00",
226+
"quality": "GOOD"
227+
}
228+
]
229+
```
230+
231+
---
232+
233+
### Biosensing (Vantage V3)
234+
235+
Requires compatible device with Elixir sensor platform.
236+
237+
| Method | Endpoint | Description |
238+
|--------|----------|-------------|
239+
| GET | `/users/{user_id}/spo2` | Blood oxygen measurements |
240+
| GET | `/users/{user_id}/ecg` | ECG recordings |
241+
| GET | `/users/{user_id}/temperature/body` | Body temperature |
242+
| GET | `/users/{user_id}/temperature/skin` | Skin temperature |
243+
244+
**Query Parameters:**
245+
- `days` (int, default: 30) - Number of days to fetch (1-365)
246+
247+
**SpO2 Response:**
248+
```json
249+
[
250+
{
251+
"test_time": "2026-01-11 22:30:00",
252+
"blood_oxygen_percent": 98,
253+
"spo2_class": "NORMAL",
254+
"avg_heart_rate": 62,
255+
"hrv_ms": 45.2,
256+
"altitude_meters": 150
257+
}
258+
]
259+
```
260+
261+
---
262+
263+
### Sync
264+
265+
| Method | Endpoint | Description |
266+
|--------|----------|-------------|
267+
| POST | `/users/{user_id}/sync/trigger` | Trigger data sync |
268+
269+
**Headers:**
270+
- `X-Polar-Token` (required) - Polar API access token
271+
272+
**Query Parameters:**
273+
- `days` (int, optional) - Days to sync (default from config)
274+
275+
**Example:**
276+
```bash
277+
curl -X POST \
278+
-H "X-Polar-Token: your_polar_token" \
279+
http://localhost:8000/api/v1/users/12345/sync/trigger?days=30
280+
```
281+
282+
**Response:**
283+
```json
284+
{
285+
"status": "success",
286+
"user_id": "12345",
287+
"results": {
288+
"sleep": 28,
289+
"recharge": 28,
290+
"activity": 28,
291+
"exercises": 15,
292+
"cardio_load": 28,
293+
"sleepwise_alertness": 168,
294+
"sleepwise_bedtime": 7,
295+
"spo2": 5,
296+
"ecg": 3,
297+
"body_temperature": 7,
298+
"skin_temperature": 7
299+
}
300+
}
301+
```
302+
303+
---
304+
305+
### Export
306+
307+
| Method | Endpoint | Description |
308+
|--------|----------|-------------|
309+
| GET | `/users/{user_id}/export/summary` | Export summary manifest |
310+
311+
**Query Parameters:**
312+
- `days` (int, default: 30) - Number of days to include (1-365)
313+
314+
**Response:**
315+
```json
316+
{
317+
"user_id": "12345",
318+
"days": 30,
319+
"from_date": "2025-12-12",
320+
"to_date": "2026-01-11",
321+
"record_counts": {
322+
"sleep": 30,
323+
"activity": 30,
324+
"recharge": 30,
325+
"cardio_load": 28,
326+
"heart_rate": 30,
327+
"exercises": 12
328+
},
329+
"total_records": 160
330+
}
331+
```
332+
333+
---
334+
335+
### Health
336+
337+
| Method | Endpoint | Description |
338+
|--------|----------|-------------|
339+
| GET | `/health` | Server health check |
340+
341+
**Response:**
342+
```json
343+
{
344+
"status": "healthy",
345+
"database": "connected"
346+
}
347+
```

0 commit comments

Comments
 (0)