Activity Library API

The Open Activity Library exposes a public REST API for browsing and searching exercises. Read endpoints require no authentication. Write endpoints require a user ID or admin credentials.

Base URL

https://your-domain.com

All endpoints are relative to the application root. Replace with your deployment URL.

Public Endpoints

GET/api/library/activities

List and search exercises in the library. Public — no authentication required.

Query Parameters

qstringSearch query (name, description, muscles)

musclestringFilter by primary muscle group

equipmentstringFilter by equipment type

tagstringFilter by tag

sourcestringFilter by source: "user", "ai", or "migration"

limitnumberMax results (default 50, max 200)

offsetnumberPagination offset

Response

{
  "activities": [
    {
      "id": "lib-1710500000-abc123",
      "name": "Barbell Back Squat",
      "description": "...",
      "primaryMuscles": ["quadriceps", "glutes"],
      "equipment": ["barbell", "squat rack"],
      "source": "user",
      "provenance": {
        "confidence": 0.85,
        "reviewCount": 3,
        "contributors": [...]
      },
      "validationStatus": "validated"
    }
  ],
  "total": 1247
}

GET/api/library/activities/:id

Get a single exercise by ID with full details including provenance and feedback summary.

Response

{
  "id": "lib-1710500000-abc123",
  "name": "Barbell Back Squat",
  "description": "...",
  "primaryMuscles": ["quadriceps", "glutes"],
  "secondaryMuscles": ["hamstrings", "core"],
  "equipment": ["barbell", "squat rack"],
  "trackableMetrics": [...],
  "defaults": { "sets": 3, "reps": 8 },
  "provenance": {
    "confidence": 0.85,
    "contributors": [...],
    "citations": [...],
    "reviewCount": 3
  },
  "feedbackSummary": {
    "thumbsUp": 12,
    "thumbsDown": 1,
    "totalFeedback": 13
  },
  "validationStatus": "validated"
}

GET/api/library/stats

Library-wide statistics: total exercises, breakdown by source/status, average confidence.

Response

{
  "total": 1247,
  "bySource": { "user": 340, "ai": 780, "migration": 127 },
  "byStatus": { "active": 1100, "pending_review": 47, "archived": 100 },
  "averageConfidence": 0.72,
  "validatedCount": 980,
  "pendingValidation": 167,
  "staleCount": 100
}

GET/api/library/schema

Returns the YAML schema definition for exercises. Useful for building tools or validators.

Response

{
  "schema": "# Open Activity Library Exercise Schema\n..."
}

POST/api/library/activities/:id/feedback

Submit feedback (thumbs up/down) on an exercise. Used for Tier 3 crowdsourced validation.

Request Body

userIdstringUser ID

rating"up" | "down"Thumbs up or down

feedbackTypestringCurrently always "validation"

Response

{ "success": true }

GET/api/library/activities/:id/feedback

Get user feedback for an exercise. Check if user already submitted.

Query Parameters

userIdstringUser ID to check

Response

{
  "feedback": {
    "rating": "up",
    "feedbackType": "validation",
    "createdAt": "2026-03-15T..."
  }
}

Authenticated Endpoints

POST/api/library/activities/proposeRequires x-user-id header

Propose a new exercise. Goes through Tier 2 AI review (expert model with research).

Request Body

exerciseobjectFull exercise object (name, description, primaryMuscles, etc.)

submittedBystringUser ID of the proposer

citationsstring[]Optional source URLs or references

Response

{
  "decision": "approve",
  "reasoning": "Well-structured exercise with accurate anatomy...",
  "exerciseId": "lib-1710500000-xyz789",
  "validationStatus": "pending_validation"
}

POST/api/library/activities/:id/suggestRequires userId in body

Suggest an edit to an existing exercise. Tier 1 for minor edits (descriptions, tags), Tier 2 for structural changes (muscles, equipment).

Request Body

proposedChangesobjectObject with changed field values

changedFieldsstring[]List of changed field names

submittedBystringUser ID

contextstringOptional context for the change

Response

{
  "decision": "approve",
  "reasoning": "Tag additions are accurate and follow conventions.",
  "tier": 1
}

Admin Endpoints

POST/api/library/reviewRequires x-admin-uid header (admin only)

Admin endpoint. Manually trigger AI review on an exercise.

Request Body

exerciseIdstringExercise to review

changedFieldsstring[]Fields that changed

proposedChangesobjectNew field values

tiernumberForce tier 1 or 2

Response

{
  "decision": "approve",
  "reasoning": "...",
  "tier": 2
}

POST/api/library/syncRequires x-admin-uid header (admin only)

Admin endpoint. Sync library to GitHub repository as YAML files.

Request Body

dryRunbooleanIf true, returns file list without pushing

Response

{
  "fileCount": 1247,
  "commitSha": "abc123...",
  "dryRun": false
}

POST/api/library/recalculateRequires x-admin-uid header (admin only)

Admin endpoint. Recalculate confidence scores for all exercises, flag stale ones.

Request Body

dryRunbooleanDefaults to true. Set false to apply changes.

staleThresholdDaysnumberDays before marking stale (default 180)

Response

{
  "dryRun": true,
  "total": 1247,
  "recalculated": 45,
  "flaggedStale": 12,
  "flaggedArchive": 3,
  "changes": [...]
}