# Hyperhuman Content API

> One API for delivery, personalization, and insights across your entire product.

> Last updated: 2026-04-30. Spec version: see `info.version` in `/openapi.json`.

Hyperhuman is the fitness content infrastructure behind modern health, wellness, and fitness products. The Content API is the developer-facing surface for the publish + personalize + insights layer.

- Base URL: `https://content.api.hyperhuman.cc`
- Authentication: send `X-Api-Key: <your_key>` on every request
- All non-2xx responses use a single envelope: `{ "error": { "code": "<StableCode>", "message": "...", "target?": "...", "details?": [...] } }`
- Pagination: `offset` and `limit` (no `page`). **Max `50`** on most list endpoints; **`100`** for `GET /v1/orgs/{organizationId}/endusers`. Organization **workout and plan** library lists and **`GET /v1/orgs/{organizationId}/video-assets`** use **`limit` 10 in the service** when `limit` is **omitted** (pass it explicitly for 20/50) — see [AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md) section 4.
- Localization: pass `locale` (BCP-47, e.g. `en-US`, `fr-FR`); falls back to English when unsupported
- AI / heavy-video endpoints (recommend, generate, adapt, insights, chat, video generation, full video export) count as **10x** rate-limit weight
- **Strict parameters:** Do not send query or body keys that are not in the public OpenAPI operation; unknown keys often return **400** (`ValidationError`). **`/openapi.json` is the curated, productized surface** — not every in-process route may be listed. See [AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md) sections 11–12.
- **Ids:** Opaque **24-character hex** strings (DB ids); do not document or depend on a specific storage engine name.

## Five capabilities

The API stacks five layers on the same library. Most teams ship steps 1-2 in week one and add the AI layers as their audience signals demand it.

1. **Publish Content** - list and play workouts and plans (`GET /v1/orgs/{organizationId}/workouts`, `GET /v1/orgs/{organizationId}/plans`), and browse workspace exercise videos (`GET /v1/orgs/{organizationId}/video-assets`).
2. **AI Recommend** - rank library content for the user (`POST /v1/orgs/{organizationId}/workouts/recommend`, `POST /v1/orgs/{organizationId}/plans/recommend`).
3. **AI Generate** - create new content on the fly (`POST /v1/orgs/{organizationId}/workouts/generate`, `POST /v1/orgs/{organizationId}/plans/generate`).
4. **AI Adapt** - evolve existing content as the user progresses (`POST /v1/orgs/{organizationId}/workouts/{workoutId}/adapt`, `POST /v1/orgs/{organizationId}/plans/{planId}/adapt`).
5. **AI Insights** - daily digest + per-pillar drill-downs (`GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest`).

In `.../endusers/{endUserId}/...` routes, the `{endUserId}` path segment is **resolved** by the server: it can be a **24-character hex** user id, an **external** id, or a **user email** (see [AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md) section 6). Responses still use opaque ids; prefer the hex id in new integrations.

## Machine-readable specs

- [OpenAPI 3 (JSON)](https://content.api.hyperhuman.cc/openapi.json) - source of truth for SDK and tool/function-calling generation
- [LLM bundle](https://content.api.hyperhuman.cc/llms-full.txt) - auth, errors, pagination, locales, and a per-endpoint summary in one markdown file
- [Agent integration guide](https://content.api.hyperhuman.cc/AGENTS.md) - conventions a coding agent must follow when generating client code
- [Custom player guide](https://content.api.hyperhuman.cc/docs/guides/custom-player.md) - reference implementation for building your own interactive workout player
- [Swagger UI](https://content.api.hyperhuman.cc/docs/api-explorer) - try-it-out browser explorer

## Embedded library pages (member web)

Hosted **workout** and **program** catalog grids on the member web app (production base `https://member.hyperhuman.cc`), not on `https://content.api.hyperhuman.cc`. Paths: `/workouts?orgId=...` and `/plans?orgId=...`. Optional query flags: `showSearch`, `showFilters`, `gridCols` (2-4, default 3), `playbackMode` (`overlay` default vs `dedicated-page` for new-tab playback), `showDuration`, `showDifficulty` — see the **Branded library embed** section in the API overview (Scalar / Swagger intro). Teams copy snippets from **Share → Embed page**. API parity: `GET /v1/orgs/{organizationId}/workouts` and `GET /v1/orgs/{organizationId}/plans`.

## Top endpoints (read-mostly)

- `GET /v1/workouts/metadata` - categories, equipment, muscle groups, supported locales
- `GET /v1/orgs/{organizationId}/workouts` - paginated workout library for an org
- `GET /v1/workouts/{workoutId}` - full workout document
- `GET /v1/workouts/{workoutId}/playlist?locale=en-US` - segments with HLS streams (drives the player)
- `GET /v1/workouts/{workoutId}/music` - pre-signed background music tracks
- `GET /v1/workouts/{workoutId}/export/video/stream_url?locale=en-US` - `text/plain` presigned URL to full video export (404 if locale not rendered)
- `GET /v1/workouts/{workoutId}/export/audio/stream_url?locale=en-US` - `text/plain` presigned URL to full narrative audio export
- `GET /v1/orgs/{organizationId}/plans` - paginated training plan library
- `GET /v1/plans/{planId}` - full plan document
- `GET /v1/orgs/{organizationId}/metadata` - org branding (logo, colors, watermark) and module flags
- `GET /v1/orgs/{organizationId}/video-assets` - **workspace-only** exercise videos for catalogs/builders (no stock / pay-as-you-go; no `visibility` filter; `single-exercise` rows expose `audioInstructions[]` per locale, each with `assetUri` + optional `scriptText` (verbatim narrator transcript for captions / accessibility / search) - see OpenAPI). DB-level filters: `q` (locale-aware substring), `equipmentIds`, `muscleGroupIds`, `kinds`, `skillLevels`, `executionSides`, `coach`, `collectionNames`. Sort: `date` (alias of `createdAt`), `name`, `kind` with `+`/`-` prefix; default `-date`.
- `GET /v1/orgs/{organizationId}/groups` - exercise collections (circuits / sets)
- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest?date=YYYY-MM-DD` - daily AI insights digest
- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}` - drill-down for a specific pillar

## Top endpoints (mutating)

- `POST /v1/orgs/{organizationId}/workouts/recommend` - rank existing workouts for a user
- `POST /v1/orgs/{organizationId}/plans/recommend` - rank existing plans for a user
- `POST /v1/orgs/{organizationId}/workouts/generate` - create an AI-generated workout
- `POST /v1/orgs/{organizationId}/plans/generate` - create an AI-generated multi-week plan
- `POST /v1/orgs/{organizationId}/workouts/{workoutId}/adapt` - personalize an existing team workout
- `POST /v1/orgs/{organizationId}/plans/{planId}/adapt` - personalize an existing team plan
- `POST /v1/workouts/{workoutId}/sessions/start` - begin tracking a session
- `PATCH /v1/workouts/{workoutId}/sessions/{sessionId}` - update session progress
- `POST /v1/workouts/{workoutId}/sessions/end` - close out a session
- `POST /v1/workouts/{workoutId}/feedback` - submit session feedback

## Per-endpoint catalog

A complete catalog (with method, path, summary, tags, and stable `operationId`s) is appended live to `/llms-full.txt` from the current `/openapi.json`. Use that file as the single context drop for an LLM.

## Operations by tag (live)

### workouts

- `GET /v1/workouts/metadata` `WorkoutsApi_getWorkoutMetadata` — Get available workout categories and difficulties
- `GET /v1/workouts/equipment/metadata` `WorkoutsApi_getEquipmentMetadata` — Get available equipment categories and equipment items
- `GET /v1/workouts/{workoutId}` `WorkoutsApi_getWorkout` — Get workout details
- `GET /v1/workouts/{workoutId}/export/video/stream_url` `WorkoutsApi_getExportVideoStream` — Get complete workout video export URL
- `GET /v1/workouts/{workoutId}/export/audio/stream_url` `WorkoutsApi_getExportAudioStream` — Get audio-only workout export URL
- `GET /v1/workouts/exercises/metadata` `WorkoutsApi_getExercisesMetadata` — Get available muscle groups and exercise collections
- `GET /v1/orgs/{organizationId}/workouts` `OrganizationWorkoutsApi_getOrganizationWorkouts` — List organization-specific workouts
- `GET /v1/workouts/{workoutId}/playlist` `WorkoutContentApi_getWorkoutPlaylist` — Retrieve Detailed Workout Playlist Structure
- `GET /v1/workouts/{workoutId}/music` `WorkoutContentApi_getWorkoutMusic` — Get workout music playlist
- `POST /v1/workouts/{workoutId}/sessions/start` `WorkoutsSessionsApi_startWorkoutSession` — Start workout session
- `PATCH /v1/workouts/{workoutId}/sessions/{sessionId}` `WorkoutsSessionsApi_patchWorkoutSession` — Update a workout session
- `GET /v1/workouts/{workoutId}/sessions/{sessionId}` `WorkoutsSessionsApi_getWorkoutSession` — Get specific workout session details
- `POST /v1/workouts/{workoutId}/sessions/end` `WorkoutsSessionsApi_endWorkoutSession` — End a workout session
- `POST /v1/workouts/{workoutId}/sessions/complete` `WorkoutsSessionsApi_completeWorkoutSession` — Complete workout session with 100% progress
- `GET /v1/workouts/{workoutId}/sessions/recent` `WorkoutsSessionsApi_getRecentWorkoutSession` — Get most recent workout session
- `GET /v1/workouts/feedback/options` `WorkoutsFeedbackApi_getWorkoutFeedbackOptions` — Get workout feedback options
- `POST /v1/workouts/{workoutId}/feedback` `WorkoutsFeedbackApi_submitWorkoutFeedback` — Submit workout feedback

### plans

- `GET /v1/plans/metadata` `PlansApi_getPlanMetadata` — Get available plan goals and difficulties
- `GET /v1/plans/{planId}` `PlansApi_getPlan` — Get training plan details
- `GET /v1/plans/{planId}/workouts` `PlansApi_getPlanWorkouts` — Get workouts in training plan
- `GET /v1/orgs/{organizationId}/plans` `OrganizationPlansApi_getOrganizationPlans` — List organization-specific training plans

### library-exercises

- `GET /v1/orgs/{organizationId}/video-assets` `OrganizationExercisesApi_getOrganizationExercises` — List workspace exercise videos for an organization

### exercise-groups

- `GET /v1/orgs/{organizationId}/groups` `OrganizationExerciseGroupsApi_getOrganizationExerciseGroups` — List organization micro workouts (exercise groups)
- `GET /v1/orgs/{organizationId}/groups/{groupId}` `OrganizationExerciseGroupsApi_getOrganizationExerciseGroupById` — Get micro workout (exercise group) by ID
- `GET /v1/orgs/{organizationId}/groups/{groupId}/exercises` `OrganizationExerciseGroupsApi_getOrganizationGroupExercises` — Get exercises in micro workout

### ai-generation

- `POST /v1/orgs/{organizationId}/workouts/generate` `OrganizationWorkoutGeneration_generateWorkout` — Generate personalized on-the-fly workouts based on user profile details, duration preferences, and exercise sources.
- `POST /v1/orgs/{organizationId}/plans/generate` `OrganizationPlanGeneration_generatePlan` — Generate personalized training programs based on user profile details, duration preferences, and workout collection sources.

### ai-recommendation

- `POST /v1/orgs/{organizationId}/workouts/recommend` `OrganizationWorkoutRecommendation_getWorkoutRecommendations` — Get workout recommendations from existing library
- `POST /v1/orgs/{organizationId}/plans/recommend` `OrganizationPlanRecommendation_getPlanRecommendations` — Get training plan recommendations from existing library

### ai-adaptation

- `POST /v1/orgs/{organizationId}/workouts/{workoutId}/adapt` `OrganizationWorkoutAdaptation_adaptWorkout` — Adapt an existing team workout based on user profile and data
- `POST /v1/orgs/{organizationId}/plans/{planId}/adapt` `OrganizationPlanAdaptation_adaptPlan` — Adapt an existing program based on user profile and data

### organization

- `GET /v1/orgs/{organizationId}/metadata` `OrganizationMetadataApi_getOrganizationMetadata` — Get organization metadata
- `GET /v1/orgs/{organizationId}/join-options` `OrganizationJoinOptionsApi_getOrganizationJoinOptions` — Get organization join options
- `GET /v1/orgs/{organizationId}/stats` `OrganizationStatsApi_getOrganizationStats` — Get organization API usage statistics

### social

- `GET /v1/orgs/{organizationId}/drops` `OrganizationDropsApi_getOrganizationDrops` — List organization social drops
- `GET /v1/orgs/{organizationId}/drops/{dropId}` `OrganizationDropsApi_getOrganizationDropById` — Get drop by ID
- `POST /v1/orgs/{organizationId}/drops/{dropId}/export` `OrganizationDropsApi_exportDrop` — Export drop for channel bundle

### content-autopilot

- `GET /v1/orgs/{organizationId}/content-autopilot` `OrganizationContentAutopilotApi_listTasks` — List content autopilot tasks
- `POST /v1/orgs/{organizationId}/content-autopilot` `OrganizationContentAutopilotApi_createTask` — Create content autopilot task
- `GET /v1/orgs/{organizationId}/content-autopilot/events` `OrganizationContentAutopilotApi_listTeamEvents` — List execution events across all tasks
- `GET /v1/orgs/{organizationId}/content-autopilot/{taskId}` `OrganizationContentAutopilotApi_getTask` — Get autopilot task by ID
- `PATCH /v1/orgs/{organizationId}/content-autopilot/{taskId}` `OrganizationContentAutopilotApi_updateTask` — Update autopilot task configuration
- `DELETE /v1/orgs/{organizationId}/content-autopilot/{taskId}` `OrganizationContentAutopilotApi_deleteTask` — Delete autopilot task (soft delete)
- `POST /v1/orgs/{organizationId}/content-autopilot/{taskId}/activate` `OrganizationContentAutopilotApi_activateTask` — Activate autopilot task
- `POST /v1/orgs/{organizationId}/content-autopilot/{taskId}/deactivate` `OrganizationContentAutopilotApi_deactivateTask` — Deactivate autopilot task
- `POST /v1/orgs/{organizationId}/content-autopilot/{taskId}/run-now` `OrganizationContentAutopilotApi_runNow` — Manually trigger task execution
- `GET /v1/orgs/{organizationId}/content-autopilot/{taskId}/events` `OrganizationContentAutopilotApi_listTaskEvents` — List execution events for a task

### social-publish

- `GET /v1/orgs/{organizationId}/social-publish/connected-platforms` `OrganizationSocialPublishApi_getConnectedPlatforms` — List connected social platforms
- `GET /v1/orgs/{organizationId}/social-publish` `OrganizationSocialPublishApi_listTasks` — List scheduled social publish automations
- `POST /v1/orgs/{organizationId}/social-publish` `OrganizationSocialPublishApi_createTask` — Create a social publish automation (draft)
- `GET /v1/orgs/{organizationId}/social-publish/{taskId}` `OrganizationSocialPublishApi_getTask` — Get one social publish automation
- `PATCH /v1/orgs/{organizationId}/social-publish/{taskId}` `OrganizationSocialPublishApi_patchTask` — Update a social publish automation
- `DELETE /v1/orgs/{organizationId}/social-publish/{taskId}` `OrganizationSocialPublishApi_deleteTask` — Delete a social publish automation (soft delete)

### endusers-ai-insights

- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest` `UserInsightsApi_getUserDailyDigest` — Get daily AI-powered user insights digest
- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}` `UserInsightsApi_getPillarDetail` — Get detailed view of a specific insight pillar

### endusers-ai-chat

- `POST /v1/chat/conversations` `ChatApi_startConversation` — Start a new chat conversation
- `GET /v1/chat/conversations` `ChatApi_getConversations` — Get user conversations
- `GET /v1/chat/conversations/{conversationId}/messages` `ChatApi_getConversationMessages` — Get conversation messages
- `POST /v1/chat/conversations/{conversationId}/messages` `ChatApi_sendMessage` — Send message to conversation
- `POST /v1/chat/conversations/{conversationId}/actions/confirm` `ChatApi_confirmAction` — Confirm a pending AI action
- `DELETE /v1/chat/conversations/{conversationId}` `ChatApi_archiveConversation` — Archive conversation

### endusers-plans

- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/plans/active/progress` `OrganizationEndUserPlansApi_getActivePlanProgress` — Get plan progress for an end user
- `GET /v1/orgs/{organizationId}/endusers/{endUserId}/plans/active` `OrganizationEndUserPlansApi_getActivePlan` — Get active plan for an end user
- `POST /v1/orgs/{organizationId}/endusers/{endUserId}/plans/start` `OrganizationEndUserPlansApi_startPlan` — Start a plan for an end user
- `POST /v1/orgs/{organizationId}/endusers/{endUserId}/plans/{planId}/end` `OrganizationEndUserPlansApi_endPlan` — End an active plan for an end user

### endusers-management

- `GET /v1/orgs/{organizationId}/endusers` `OrganizationEndUsersApi_getOrganizationEndUsers` — Get organization end users
- `DELETE /v1/orgs/{organizationId}/endusers` `OrganizationEndUsersApi_removeEndUser` — Remove end user from organization
- `POST /v1/orgs/{organizationId}/endusers/invite` `OrganizationEndUsersApi_inviteEndUsers` — Invite end users to organization
- `PUT /v1/orgs/{organizationId}/endusers/suspend` `OrganizationEndUsersApi_suspendEndUser` — Suspend end user in organization
- `PUT /v1/orgs/{organizationId}/endusers/reactivate` `OrganizationEndUsersApi_reactivateEndUser` — Reactivate end user in organization
- `GET /v1/orgs/{organizationId}/endusers/find` `OrganizationEndUsersApi_getEndUserById` — Find end user by email or external UUID