openapi: 3.1.0
info:
  title: Ordentus API — health & fitness (opt-in)
  description: 'Sleep, bedtime, cognitive forecast, and workouts/training plans. These endpoints require an API token with the HEALTH permission (Account Settings, API Access); without it they return 403. Add as a third Action only if your token has health access. Reference: https://ordent.us/llms-api.txt'
  version: '1.0.0'
servers:
- url: https://ordent.us
paths:
  /api/auth/me:
    get:
      operationId: whoami
      summary: Who the token belongs to, and what it can do. CALL THIS FIRST.
      description: 'Returns an auth object. For health endpoints check auth.can_access_health — if false, this token lacks the health permission and every /api/health call returns 403; tell the user to create a token with health enabled.'
      responses:
        '200':
          description: The current user record, including an auth object with can_access_health.
  /api/health/dashboard:
    get:
      operationId: getHealthDashboard
      summary: Today's health dashboard — sleep, recovery, readiness, key stats.
      responses:
        '200':
          description: The dashboard payload.
  /api/health/recommendations:
    get:
      operationId: getHealthRecommendations
      summary: Tonight's recommended bedtime and other readiness recommendations.
      description: Computed from tomorrow's first event, target sleep hours, and current sleep debt.
      responses:
        '200':
          description: The recommendations payload.
  /api/health/cognitive:
    get:
      operationId: getCognitiveForecast
      summary: Today's cognitive-performance forecast across five domains.
      responses:
        '200':
          description: The cognitive assessment.
  /api/health/sleep/history:
    get:
      operationId: getSleepHistory
      summary: Recent sleep records.
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          maximum: 365
      responses:
        '200':
          description: Sleep history for the window.
  /api/health/profile:
    get:
      operationId: getHealthProfile
      summary: The user's health profile (sleep targets, buffers, enabled features).
      responses:
        '200':
          description: The health profile.
    patch:
      operationId: updateHealthProfile
      summary: Update health-profile fields (e.g. ideal_sleep_hours, wake_buffer_minutes).
      description: Requires a write-scoped token with health access. Send only the fields you want to change.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Partial profile — only the fields you want to change.
              properties:
                ideal_sleep_hours:
                  type: number
                wake_buffer_minutes:
                  type: integer
                bedtime_reminder_enabled:
                  type: boolean
                bedtime_reminder_minutes:
                  type: integer
                smart_bedtime_enabled:
                  type: boolean
              additionalProperties: true
      responses:
        '200':
          description: The updated profile.
  /api/health/workouts:
    get:
      operationId: listWorkouts
      summary: List workouts (planned and/or completed), with optional filters.
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Date (YYYY-MM-DD) lower bound.
      - name: end
        in: query
        required: false
        schema:
          type: string
        description: Date (YYYY-MM-DD) upper bound.
      - name: workout_type
        in: query
        required: false
        schema:
          type: string
        description: e.g. running, strength.
      - name: planned_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: completed_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 100
          maximum: 500
      responses:
        '200':
          description: A list of workouts.
    post:
      operationId: createWorkout
      summary: Log or schedule a workout.
      description: Requires a write-scoped token with health access. Set planned=true with scheduled_for to schedule; omit it and give started_at to log a completed session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkoutInput'
      responses:
        '200':
          description: The created workout.
  /api/health/workouts/{workout_id}:
    get:
      operationId: getWorkout
      summary: Fetch one workout by id.
      parameters:
      - name: workout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The workout.
    patch:
      operationId: updateWorkout
      summary: Update a workout.
      description: Requires a write-scoped token with health access.
      parameters:
      - name: workout_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkoutInput'
      responses:
        '200':
          description: The updated workout.
    delete:
      operationId: deleteWorkout
      summary: Delete a workout.
      description: Requires a write-scoped token with health access.
      parameters:
      - name: workout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted.
  /api/health/workouts/{workout_id}/complete:
    post:
      operationId: completeWorkout
      summary: Mark a planned workout as completed.
      description: Requires a write-scoped token with health access.
      parameters:
      - name: workout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The completed workout.
  /api/health/training-plans:
    get:
      operationId: listTrainingPlans
      summary: List the user's training plans.
      responses:
        '200':
          description: A list of training plans.
    post:
      operationId: createTrainingPlan
      summary: Create a training plan (a weekly template that materialises workouts).
      description: Requires a write-scoped token with health access.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainingPlanInput'
      responses:
        '200':
          description: The created plan.
  /api/health/training-plans/{plan_id}:
    patch:
      operationId: updateTrainingPlan
      summary: Update a training plan.
      description: Requires a write-scoped token with health access.
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainingPlanInput'
      responses:
        '200':
          description: The updated plan.
    delete:
      operationId: deleteTrainingPlan
      summary: Delete a training plan (and its not-yet-completed planned workouts).
      description: Requires a write-scoped token with health access.
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted.
  /api/health/training-plans/{plan_id}/activate:
    post:
      operationId: activateTrainingPlan
      summary: Materialise the next few weeks of planned workouts from a plan.
      description: Requires a write-scoped token with health access.
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Activation result.
components:
  schemas:
    PlannedWorkout:
      type: object
      description: One planned workout within a weekday of a training plan's template.
      properties:
        workout_type:
          type: string
          description: e.g. running, strength, cycling.
        title:
          type: string
        duration_min:
          type: number
        notes:
          type: string
      additionalProperties: true
    WorkoutInput:
      type: object
      required:
      - workout_type
      description: A workout to log (completed) or schedule (planned).
      properties:
        workout_type:
          type: string
          description: e.g. running, strength, cycling.
        title:
          type: string
        started_at:
          type: string
          description: ISO datetime the session started.
        ended_at:
          type: string
          description: ISO datetime it ended.
        duration_min:
          type: number
        active_energy_kcal:
          type: number
        distance_km:
          type: number
        avg_heart_rate:
          type: number
        max_heart_rate:
          type: number
        scheduled_for:
          type: string
          description: Date (YYYY-MM-DD) for a planned workout.
        planned:
          type: boolean
          default: false
          description: true = a scheduled plan; false = a logged session.
        notes:
          type: string
        exercises:
          type: array
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
              sets:
                type: integer
              reps:
                type: integer
              weight_kg:
                type: number
              notes:
                type: string
    TrainingPlanInput:
      type: object
      required:
      - name
      - week_template
      description: A weekly template that materialises planned workouts when activated.
      properties:
        name:
          type: string
        week_template:
          type: object
          description: Map of weekday to a list of planned workouts for that day.
          properties:
            monday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            tuesday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            wednesday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            thursday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            friday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            saturday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
            sunday:
              type: array
              items:
                $ref: '#/components/schemas/PlannedWorkout'
          additionalProperties: true
        active:
          type: boolean
          default: false
        start_date:
          type: string
          description: Date (YYYY-MM-DD) to start materialising from.
        weeks_ahead:
          type: integer
          default: 4
        calendar_feed_id:
          type: string
          description: Manual calendar to write generated workouts into.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your personal API token with the health permission, sent as Authorization: Bearer <token>.'
security:
- bearerAuth: []
