Skip to content

REST API

Cadence exposes a JSON REST API at /api/v1/ for building custom clients.

Authentication

All API endpoints (except login and signup) require a bearer token:

Authorization: Bearer <token>

Get a token by calling the login endpoint.

Auth Endpoints

POST /api/v1/auth/login

Authenticate and receive a bearer token.

// Request
{
  "email": "user@example.com",
  "password": "your-password"
}

// Response
{
  "token": "eyJ...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "display_name": "User"
  }
}

POST /api/v1/auth/signup

Create an account and receive a bearer token.

// Request
{
  "email": "user@example.com",
  "password": "SecureP@ss1",
  "display_name": "User"
}

// Response
{
  "token": "eyJ...",
  "user": { ... }
}

GET /api/v1/auth/me

Get the current authenticated user's profile.

Dashboard

GET /api/v1/dashboard

Returns the full dashboard payload: connected devices, daily health metrics, recent activities, and weekly stats.

Settings

PUT /api/v1/settings/profile

Update display name or email.

{ "display_name": "New Name" }

PUT /api/v1/settings/password

Change password.

{
  "current_password": "old-password",
  "new_password": "NewP@ss1"
}

GET /api/v1/settings/coaching-profile

Get the user's coaching profile text.

PUT /api/v1/settings/coaching-profile

Update the coaching profile.

{ "coaching_profile": "I'm training for a marathon in June..." }

Workouts

GET /api/v1/workouts

List workouts (paginated).

Query params: page, per_page

POST /api/v1/workouts

Create a workout.

{
  "date": "2025-01-15",
  "workout_name": "Upper Body",
  "notes": "Felt strong today",
  "exercises": [
    {
      "name": "Bench Press",
      "sets": 4,
      "reps": "8",
      "weight_kg": 80
    }
  ]
}

GET /api/v1/workouts/{id}

Get a single workout with exercises.

PUT /api/v1/workouts/{id}

Update a workout.

DELETE /api/v1/workouts/{id}

Delete a workout.

GET /api/v1/exercises/library

List the user's exercise library (all exercises ever logged).

Chat

POST /api/v1/chat

Send a chat message. Returns a streaming SSE response.

{
  "message": "How did I sleep last night?",
  "conversation_id": null,
  "model_id": "anthropic/claude-sonnet-4-5-20250929"
}

SSE Events: token, tool_start, tool_end, chart, usage, done, error

GET /api/v1/conversations

List conversations (most recent first).

GET /api/v1/conversations/{id}/messages

Get messages for a conversation.

DELETE /api/v1/conversations/{id}

Delete a conversation and its messages.

Devices

GET /api/v1/devices

List connected devices with their status.

// Response
{
  "devices": [
    {
      "provider": "garmin",
      "connected": true,
      "status": "ok"
    },
    {
      "provider": "whoop",
      "connected": true,
      "status": "ok"
    }
  ]
}