API 總覽
NexRex REST API 完整參考文件 — 認證、核心端點、錯誤處理。
簡介
NexRex API 是一個 RESTful API，提供跑步訓練平台的所有後端功能。
Base URL
| 環境 | Base URL |
|---|---|
| Production | `https://api.nexrex.ai/api/v1` |
| Staging | `https://api-stg.nexrex.ai/api/v1` |
認證
所有 API 請求需要在 header 中傳送 API Key：
Request Header
x-api-key: your_api_key_here
取得 API Key
聯繫 NexRex 團隊取得你的 API Key。每個 API Key 綁定一個組織。
API Key 認證即將上線。目前部分端點使用 Firebase JWT Token（`Authorization: Bearer <token>`），未來將統一為 API Key。
核心 API
NexRex API 的六大核心端點：
| API | 說明 | 端點前綴 |
|---|---|---|
| Activities | 跑步活動 CRUD、留言、互動 | `/activities` |
| User Profiles | 使用者資料、區間、目標 | `/users` |
| Training Plans | 訓練計畫模板 CRUD | `/training/training_plans` |
| Plan Instances | 選手報名的計畫實例 | `/training/plan_instances` |
| Group Plans | 群組訓練計畫 | `/training/group_plan_instances` |
| Groups | 跑團群組管理 | `/groups` |
請求格式
- Content-Type:
application/json - Accept:
application/json - 所有時間戳使用 epoch milliseconds（Unix timestamp × 1000）
- 所有 ID 為 string 類型
回應格式
成功回應
HTTP 200（成功）或 201（已建立），回傳 JSON 物件。
錯誤回應
{"error": "Error message description"}
HTTP Status Codes
| Code | 說明 |
|---|---|
| `200` | 成功 |
| `201` | 已建立 |
| `400` | 請求無效（參數錯誤） |
| `401` | 未認證（缺少或無效的 API Key） |
| `403` | 權限不足 |
| `404` | 資源不存在 |
| `409` | 衝突（例如重複建立） |
| `500` | 伺服器內部錯誤 |
分頁
列表端點支援分頁：
page_size：每頁數量（預設 20）page：頁碼（部分端點）last_created_at：cursor-based 分頁時間戳（epoch ms）
資料慣例
時間戳
所有時間欄位使用 epoch milliseconds（毫秒級 Unix 時間戳）。
例如：1712000000000 = 2024-04-02 00:00:00 UTC
距離
所有距離欄位使用 公尺。
例如：21097 = 21.097 km（半馬）
配速
配速使用 秒/公里。
例如：300 = 5:00/km
時間長度
活動時間使用 秒。
例如：3600 = 1 小時