Skip to main content

AI Training API

AI Training provides plan-based routine APIs for end users and authenticated admin APIs for assignment, reporting, and template management.

AI Training uses AI Move as the exercise execution surface. AI Training owns the user plan, routine queue, and routine run summary. AI Move continues to own the per-exercise session record.

Authentication​

Use a Firebase user token in the Authorization: Bearer <firebase_jwt> header for end-user routes.

Use an authenticated admin token for admin routes.

note

The AI Training module must be enabled for the requesting client.

External App Integration (Custom Token)​

Third-party or kiosk apps that already have a valid Firebase session can obtain a customToken via the POST /api/auth/exchange-token endpoint and append it as a query parameter when navigating to the AI Training play page:

https://{client}.gofa.app/ai-training/routine-run/{routineRunId}/play?customToken={token}&locale=zh-Hant

The GOFA web app automatically signs the user in from the custom token and establishes a full session, so all subsequent API calls during the routine play work with normal authentication.

End User Runtime​

GET /api/ai-training/my-plan​

Returns the latest AI Training plan for the authenticated user.

Response
{
  "plan": {
    "planId": "plan_001",
    "clientId": "gofa",
    "userId": "user_001",
    "status": "active",
    "goal": "balance",
    "intensity": "moderate",
    "frequency": 3,
    "preferredSessionDurationMinutes": 20,
    "generationSource": "rules",
    "assessmentSnapshot": {
      "latestRiskTier": "moderate",
      "availableInputs": ["fallRisk", "preferences"],
      "missingInputs": ["mskAssessment", "cognitiveAssessment"]
    }
  }
}

POST /api/ai-training/my-plan/generate​

Generates a starter plan for the authenticated user from the routine templates currently visible to the client.

All request body fields are optional.

  • goal (string): Preferred training goal
  • intensity (string): Preferred training intensity
  • frequency (number): Desired sessions per cycle
  • preferredSessionDurationMinutes (number): Preferred session duration
  • equipmentAvailability (string[]): Available equipment labels
  • allowDuplicateRoutineTemplates (boolean): Optional opt-in. Defaults to false, so repeated routine templates are deduplicated before routine instances are created.
Request
{
  "goal": "balance",
  "intensity": "moderate",
  "frequency": 3
}
Response (201)
{
  "plan": {
    "planId": "plan_001",
    "status": "active"
  },
  "routineInstances": [
    {
      "routineInstanceId": "instance_001",
      "routineTemplateId": "template_001",
      "routineTemplateName": "Balance Builder A",
      "queueIndex": 0,
      "status": "queued"
    }
  ]
}

GET /api/ai-training/my-routine-queue​

Returns the queued or in-progress routine instances for the authenticated user.

Optional query parameters:

  • allowDuplicateRoutineTemplates (boolean): Optional opt-in. Defaults to false, so the queue response hides duplicate routine instances that point to the same routine template.

POST /api/ai-training/routine-runs​

Creates a routine run for a queued routine instance.

  • routineInstanceId (string, required): The queued routine instance to start
  • startedFrom (string, required): Entry point label for analytics or UI context
Request
{
  "routineInstanceId": "instance_001",
  "startedFrom": "dashboard"
}
Response (201)
{
  "routineRun": {
    "routineRunId": "run_001",
    "routineInstanceId": "instance_001",
    "status": "created",
    "startedFrom": "dashboard",
    "summary": {
      "completedExercises": 0,
      "totalExercises": 4,
      "completionRate": 0,
      "totalDurationSeconds": 0,
      "totalCaloriesBurned": 0
    },
    "exerciseSteps": [
      {
        "sequenceIndex": 0,
        "stepId": "step_001",
        "exerciseId": "march-basic",
        "status": "pending"
      }
    ]
  }
}

GET /api/ai-training/routine-runs​

Lists routine runs for the authenticated user.

GET /api/ai-training/routine-runs/[routineRunId]​

Returns a specific routine run for the authenticated user.

Response
{
  "routineRun": {
    "routineRunId": "run_001",
    "status": "in-progress"
  }
}

PATCH /api/ai-training/routine-runs/[routineRunId]​

Updates a specific routine run.

POST /api/ai-training/routine-runs/[routineRunId]/sync​

Synchronizes a routine run summary from the latest AI Move child session result.

  • aiMoveSessionId (string): Optional child session ID to sync
  • sequenceIndex (number): Optional step index to sync
  • guidedComplete (boolean): Optional flag to mark a guided step as completed
  • skipped (boolean): Optional flag to mark a step as skipped
Response
{
  "success": true,
  "routineRun": {
    "routineRunId": "run_001",
    "status": "in-progress"
  }
}

POST /api/ai-training/routine-instances/[routineInstanceId]/defer​

Defers a queued routine instance for the authenticated user, subject to the configured defer limit.

GET /api/ai-training/progress-report​

Returns a lightweight adherence summary for the authenticated user.

Response
{
  "adherence": 0.67,
  "totalRuns": 6,
  "completedRuns": 4,
  "completionRate": 0.67,
  "series": [
    {
      "label": "Mar 27",
      "completedRuns": 1,
      "totalRuns": 2,
      "completionRate": 0.5
    }
  ]
}

Admin Reporting And Assignment​

GET /api/ai-training/records​

Admin-only endpoint that returns AI Training routine run records for a client.

Optional query parameters:

  • clientId (string): Override client when the requester has cross-client admin access
  • limit (number): Max number of records to return

GET /api/client/[clientId]/users/[userId]/ai-training/plan​

Admin-only endpoint that returns the latest plan for a specific user.

POST /api/client/[clientId]/users/[userId]/ai-training/assign-starter-plan​

Admin-only endpoint that generates and assigns a starter plan to a user.

This endpoint accepts the same optional request body fields as POST /api/ai-training/my-plan/generate, including allowDuplicateRoutineTemplates.

POST /api/client/[clientId]/users/[userId]/ai-training/assign-routine-template​

Admin-only endpoint that assigns a specific routine template to a user.

GET /api/client/[clientId]/users/[userId]/ai-training/routine-runs​

Admin-only endpoint that lists AI Training routine runs for a specific user.

B2B Template Authoring​

GET /api/b2b/ai-training/routine-templates​

Lists the routine templates visible in the current admin workspace, including client-owned templates and selectable GOFA library templates.

POST /api/b2b/ai-training/routine-templates​

Creates a client-owned routine template.

GET /api/b2b/ai-training/routine-templates/[routineTemplateId]​

Returns one routine template for editing or preview.

PATCH /api/b2b/ai-training/routine-templates/[routineTemplateId]​

Updates a client-owned routine template.

POST /api/b2b/ai-training/routine-templates/[routineTemplateId]/publish​

Publishes a client-owned routine template.

GET /api/b2b/ai-training/catalog​

Returns the client's current AI Training catalog state.

PATCH /api/b2b/ai-training/catalog​

Updates which GOFA library routine templates are visible to the client.

Relationship With AI Move​

AI Training launches AI Move for each exercise step and can provide contextual metadata such as plan ID, routine instance ID, routine run ID, and step sequence index.

That metadata lets AI Training summarize each child AI Move session into the parent routine run while keeping the documented contract focused on the public request and response shapes.