> ## Documentation Index > Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt > Use this file to discover all available pages before exploring further. # List exercises for client with filters > Returns a paginated list of exercises visible to the client (global, company, and own exercises). All filters are optional and sent in the request body. `exerciseType` in each item is `coach` (added by a coach), `personal` (added by the client), or `global` (Everyone/Fitsociety visibility). `availableFilters.coaches` is populated dynamically from exercises visible in this company. Pass `skipExercise=` (query or body) to exclude one exercise from the list — e.g. the exercise currently being replaced. An invalid/missing id is ignored. Pass `excludeExerciseIds` (the multi-value version of `skipExercise`) to exclude one or more exercises — e.g. movements already selected/prescribed. Both exclude exercises from the results and pagination totals. Pass `clientOwn: true` to return ONLY the client's own exercises (same set as `/my-exercises`). Pass `exerciseToTop=` to pin one exercise at page 1 / index 0 — but only if it also satisfies the active filters/visibility; otherwise it is not pinned and does not appear. The pinned item is de-duplicated from the rest of the list. Each item also returns a `media` array (images + videos, same shape as getExerciseHistory) and `targetedMuscles` (primary + secondary, de-duplicated). Requires the workout_client_plans:write scope. This operation maps to /app/v1/workout/client/exercises and retains its Workout V2 permission, feature-flag, and resource-scope checks. The clientId path parameter identifies the client represented by the request context. ## OpenAPI ````yaml /openapi/public-v1.json post /public/v1/workout/clients/{clientId}/exercises/search openapi: 3.1.0 info: title: FITsociety Public API v1 version: 1.0.0 description: >- Developer Public API endpoints under `/public/v1`. This reference is filtered to OAuth/Bearer Public API resources and excludes provider callback receivers, storefront routes, public widgets, wishlist routes, and access-device validation endpoints. contact: name: FITsociety Engineering servers: - url: https://api.fitsociety.io description: Production security: [] tags: - name: Workout description: >- Workout V2 libraries, programmes, client plans, calendars, sessions, groups, settings and progress. AI operations are excluded. - name: OAuth description: Public API OAuth endpoints for server-to-server client credentials. - name: Health description: Public API token health checks. - name: Platform description: >- Inspect Public API client context, capabilities, scopes, and redacted audit logs. - name: Company Catalog description: Read and manage company profile metadata and locations. - name: Clients description: >- Create and manage clients through the Public API using Bearer access tokens. - name: Coaches description: Retrieve coaches for the authenticated company via integrations. - name: Calendar Events description: Read Public API calendar events. - name: Calendar Templates description: >- Read and manage event types and event templates used by calendar availability and bookings. - name: Calendar Extensions description: >- Read recurring bookings, booking requests, calendar tasks, and availability closure metadata. - name: Availability description: Read bookable availability slots and signed availability tokens. - name: Availability Management description: >- Manage coach and location availability templates used to derive bookable slots. - name: Bookings description: Read and manage Public API bookings. - name: Finance description: >- Read invoices, transactions, products, subscriptions, and memberships with guarded finance writes. - name: Credits description: >- Read company-wide and client-scoped credit allocations, mutations, and guarded credit adjustments. - name: Exports description: >- Create and monitor asynchronous company exports through Public API Bearer endpoints. - name: Webhooks description: >- Manage outbound webhook subscriptions and inspect delivery attempts through Public API Bearer endpoints. - name: Measurements description: Read and write client measurement entries. - name: Progress Photos description: Read client progress photo metadata and short-lived signed media URLs. - name: Forms description: Read, create, update, and archive company form templates. - name: Intakes description: Assign intake forms and read client intake assignments and submissions. - name: Check-ups description: >- Schedule and cancel client check-ups and read their status and submissions. - name: Documents description: >- Read client document and folder metadata, register external document links, update metadata, and archive documents from Public API listings. Binary upload, permanent deletion, and company-wide document management are not exposed. - name: Habits description: Read habits and habit entries. - name: Goals description: Read client goal summaries. - name: Conversations description: >- Read and manage direct and group chat conversations through the Public API. - name: Reports description: Read aggregate attendance, revenue, and retention summaries. paths: /public/v1/workout/clients/{clientId}/exercises/search: post: tags: - Workout summary: List exercises for client with filters description: >- Returns a paginated list of exercises visible to the client (global, company, and own exercises). All filters are optional and sent in the request body. `exerciseType` in each item is `coach` (added by a coach), `personal` (added by the client), or `global` (Everyone/Fitsociety visibility). `availableFilters.coaches` is populated dynamically from exercises visible in this company. Pass `skipExercise=` (query or body) to exclude one exercise from the list — e.g. the exercise currently being replaced. An invalid/missing id is ignored. Pass `excludeExerciseIds` (the multi-value version of `skipExercise`) to exclude one or more exercises — e.g. movements already selected/prescribed. Both exclude exercises from the results and pagination totals. Pass `clientOwn: true` to return ONLY the client's own exercises (same set as `/my-exercises`). Pass `exerciseToTop=` to pin one exercise at page 1 / index 0 — but only if it also satisfies the active filters/visibility; otherwise it is not pinned and does not appear. The pinned item is de-duplicated from the rest of the list. Each item also returns a `media` array (images + videos, same shape as getExerciseHistory) and `targetedMuscles` (primary + secondary, de-duplicated). Requires the workout_client_plans:write scope. This operation maps to /app/v1/workout/client/exercises and retains its Workout V2 permission, feature-flag, and resource-scope checks. The clientId path parameter identifies the client represented by the request context. operationId: publicWorkoutpostPublicV1WorkoutClientsClientIdExercisesSearch parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 example: booking-create-20260714-001 description: >- Required for Public API write requests. Reusing the same key with the same method, path, and body replays the stored successful response; reusing it with a different request returns `409 idempotency.conflict`. - in: query name: skipExercise required: false schema: type: string example: 67f1234567890abcdef1234 description: >- Exclude this exercise id from the results (and from pagination totals). Typically the exercise being replaced. May also be sent in the request body. Invalid or missing ids are ignored. - name: clientId in: path required: true schema: type: string pattern: ^[a-fA-F0-9]{24}$ description: Client in the company bound to the Public API token. requestBody: required: false content: application/json: schema: $ref: >- #/components/schemas/PublicWorkoutSourcePOSTAppV1WorkoutClientExercisesRequest example: page: 1 limit: 20 search: '' favourites: false levels: - Beginner muscleGroups: - Chest equipments: - barbell categories: - Strength coaches: [] clientOwn: false responses: '200': description: Paginated exercise list with available and selected filters. content: application/json: schema: allOf: - $ref: '#/components/schemas/PublicApiWriteSuccessResponse' - type: object properties: data: $ref: >- #/components/schemas/PublicWorkoutSourcePOSTAppV1WorkoutClientExercisesResponse200 examples: success: summary: Successful response value: data: exercises: - _id: 67f1234567890abcdef1234 name: Barbell Bench Press thumbnail: https://cdn.example.com/exercises/bench.jpg type: s3 media: - type: image url: https://cdn.example.com/exercises/bench.jpg platform: null videoId: null thumbnail: null duration: null width: 1080 height: 1920 primaryMuscle: Chest secondaryMuscles: - Shoulders - Triceps targetedMuscles: - Chest - Shoulders - Triceps difficulty: Intermediate category: Strength equipment: - Barbell - Bench exerciseType: coach isFavourite: false availableFilters: favourites: - true - false clientOwn: - true - false muscleGroups: - Chest - Back - Lats equipments: - value: barbell label: Barbell categories: - Agility & Speed - Strength - Hypertrophy levels: - Beginner - Intermediate - Advance coaches: - id: 67f1234567890abcdef1234 name: Jane Smith image: https://cdn.example.com/coaches/jane.jpg exerciseToTop: null selectedFilters: favourites: false muscleGroups: [] equipments: [] categories: [] levels: [] coaches: [] search: '' clientOwn: false excludeExerciseIds: [] exerciseToTop: null pagination: page: 1 limit: 20 totalItems: 48 totalPages: 3 meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotency: replayed: false '400': description: >- Company context missing (`COMPANY_ID_REQUIRED`), invalid level value (`INVALID_LEVELS_OF_DIFFICULTIES`), or invalid coach id (`INVALID_COACH_ID`). content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: invalidRequest: summary: Invalid request value: error: code: 400 key: request.invalid message: The request is invalid. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyRequired: summary: Missing Idempotency-Key value: error: code: 400 key: idempotency.required message: >- Idempotency-Key header is required for Public API write requests. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyInvalid: summary: Invalid Idempotency-Key value: error: code: 400 key: idempotency.invalid message: Idempotency-Key header must be 200 characters or fewer. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '401': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: missingBearer: summary: Missing Bearer token value: error: code: 401 key: auth.missing_bearer message: Authorization Bearer token is required. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidToken: summary: Invalid or expired token value: error: code: 401 key: auth.invalid_token message: The access token is invalid or expired. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidClient: summary: Inactive or revoked client value: error: code: 401 key: auth.invalid_client message: The Public API client is inactive or revoked. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '403': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: insufficientScopes: summary: Missing required scope value: error: code: 403 key: scopes.insufficient message: The access token does not include the required scope. details: requiredScopes: - required:scope meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '404': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: notFound: summary: Resource not found value: error: code: 404 key: resource.not_found message: The requested Public API resource was not found. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '409': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: idempotencyConflict: summary: Idempotency-Key conflict value: error: code: 409 key: idempotency.conflict message: >- Idempotency-Key was already used with a different request. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyInProgress: summary: Idempotency-Key in progress value: error: code: 409 key: idempotency.in_progress message: >- Idempotency-Key is already processing for this Public API client. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '422': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: emptyBody: summary: Empty or invalid JSON object body value: error: code: 422 key: EMPTY_BODY message: Request body must be a non-empty JSON object. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '429': $ref: '#/components/schemas/ErrorResponse' content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: rateLimitExceeded: summary: Rate limit exceeded value: error: code: 429 key: rate_limit.exceeded message: Too many Public API requests. Retry later. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 0 resetSeconds: 1 retryAfterSeconds: 1 '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: serverInternalError: summary: Unexpected server error value: error: code: 500 key: server.internal_error message: An unexpected Public API server error occurred. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 security: - PublicBearerAuth: [] x-codeSamples: - lang: cURL label: cURL source: >- curl -X POST "https://api.fitsociety.io/public/v1/workout/clients/{clientId}/exercises/search" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: " \ -H "Content-Type: application/json" \ -d '{}' components: schemas: PublicWorkoutSourcePOSTAppV1WorkoutClientExercisesRequest: type: object properties: page: type: integer minimum: 1 example: 1 limit: type: integer minimum: 1 maximum: 100 example: 20 search: type: string example: bench press favourites: type: boolean example: false levels: oneOf: - type: string example: Beginner,Intermediate - type: array items: type: string enum: - Beginner - Intermediate - Advance example: - Beginner - Intermediate description: 'Filter by difficulty. Values: `Beginner`, `Intermediate`, `Advance`.' muscleGroups: oneOf: - type: string example: Chest,Shoulders - type: array items: type: string example: - Chest - Shoulders description: >- Matches on primaryMuscle OR secondaryMuscles. Allowed values: Chest, Back, Lats, Traps, Shoulders … equipments: oneOf: - type: string example: barbell,dumbbell - type: array items: type: string example: - barbell - dumbbell description: Equipment key values from `availableFilters.equipments`. categories: oneOf: - type: string example: Strength,Cardio - type: array items: type: string example: - Strength - Cardio description: >- Filters on primaryCategory. Allowed values: Agility & Speed, Strength, Hypertrophy, Strength - Dynamic, Strength - Explosive … coaches: type: array items: type: string example: - 67f1234567890abcdef1111 description: >- Filter to exercises added by specific coaches. Restricts to `addedByRole: Coach`. skipExercise: type: string example: 67f1234567890abcdef1234 description: >- Exclude this exercise id from the results (and pagination totals). Typically the exercise being replaced. May also be passed as the `skipExercise` query param. Invalid/missing ids are ignored. excludeExerciseIds: oneOf: - type: string example: 6925d2764ac340a53e012927,6925d2764ac340a53e012928 - type: array items: type: string example: 67f1234567890abcdef1234 description: >- Exclude one or more exercises from the results (movements already selected/prescribed). Comma-separated string or array of exercise ObjectIds. Aliases also accepted: excludeExerciseId / exerciseIds / exerciseId; also readable from the query string. Invalid id → 400 WORKOUTEXERCISE_EXERCISEID_INVALID. Echoed back in selectedFilters.excludeExerciseIds. clientOwn: type: boolean example: false description: >- When `true`, return ONLY the client's own exercises (`addedByRole: Client`, `addedBy` = client) — the 'My Exercises' subset. Overrides the `coaches` filter. exerciseToTop: type: string example: 67f1234567890abcdef1234 description: >- Pin a single exercise to page 1 / index 0. Only pinned if it also satisfies the active filters + visibility (else omitted entirely). De-duplicated from the rest of the list. May also be passed as the `exerciseToTop` query param. Invalid id → 400 WORKOUTEXERCISE_EXERCISEID_INVALID. PublicApiWriteSuccessResponse: type: object additionalProperties: false required: - data - meta properties: data: type: object meta: $ref: '#/components/schemas/PublicApiWriteMeta' PublicWorkoutSourcePOSTAppV1WorkoutClientExercisesResponse200: type: object properties: exercises: type: array items: type: object properties: _id: type: string example: 67f1234567890abcdef1234 name: type: string example: Barbell Bench Press thumbnail: type: string example: https://cdn.example.com/exercises/bench.jpg type: type: string enum: - s3 - link example: s3 description: >- Source of the `thumbnail`: `s3` (hosted image/video thumbnail) or `link` (external video url). media: type: array description: >- Full ordered media list (images first, then videos). Same shape as getExerciseHistory / searchExercises. items: type: object properties: type: type: string enum: - image - video - link example: image description: >- `image` (photo), `video` (s3-hosted video), or `link` (external-platform video, e.g. youtube/tiktok). url: type: string example: https://cdn.example.com/exercises/bench.jpg platform: type: string nullable: true example: null description: >- `null` for images; `s3` / `youtube` / `tiktok` … for videos. videoId: type: string nullable: true example: null description: >- External video id for `link` videos; `""` for s3 videos; `null` for images. thumbnail: type: string nullable: true example: null description: Video poster/thumbnail URL; `null` for images. duration: type: number nullable: true example: null description: Video duration in seconds when known. width: type: integer nullable: true example: 1080 height: type: integer nullable: true example: 1920 primaryMuscle: type: string example: Chest secondaryMuscles: type: array items: type: string example: - Shoulders - Triceps targetedMuscles: type: array items: type: string example: - Chest - Shoulders - Triceps description: >- Primary + secondary muscles, de-duplicated (a muscle listed as both appears once), order preserved. difficulty: type: string example: Intermediate category: type: string example: Strength equipment: type: array items: type: string example: - Barbell - Bench exerciseType: type: string enum: - coach - personal - global example: coach description: >- `coach` = added by a coach; `personal` = added by the client; `global` = Everyone/Fitsociety visibility. isFavourite: type: boolean example: false availableFilters: type: object properties: favourites: type: array items: type: boolean example: - true - false clientOwn: type: array items: type: boolean example: - true - false muscleGroups: type: array items: type: string example: - Chest - Back - Lats equipments: type: array items: type: object properties: value: type: string example: barbell label: type: string example: Barbell categories: type: array items: type: string example: - Agility & Speed - Strength - Hypertrophy levels: type: array items: type: string enum: - Beginner - Intermediate - Advance example: - Beginner - Intermediate - Advance coaches: type: array description: Coaches who have created exercises visible in this company. items: type: object properties: id: type: string example: 67f1234567890abcdef1234 name: type: string example: Jane Smith description: Coach full name (`firstName lastName`, trimmed). image: type: string example: https://cdn.example.com/coaches/jane.jpg exerciseToTop: type: string nullable: true example: null description: >- Free-form single exercise id (no preset options), so always `null` here. selectedFilters: type: object properties: favourites: type: boolean example: false muscleGroups: type: array items: type: string example: [] equipments: type: array items: type: string example: [] categories: type: array items: type: string example: [] levels: type: array items: type: string example: [] coaches: type: array items: type: string example: [] search: type: string example: '' clientOwn: type: boolean example: false excludeExerciseIds: type: array items: type: string example: [] exerciseToTop: type: string example: null nullable: true pagination: type: object properties: page: type: integer example: 1 limit: type: integer example: 20 totalItems: type: integer example: 48 totalPages: type: integer example: 3 PublicApiError: type: object additionalProperties: false required: - error - meta properties: error: type: object additionalProperties: false required: - code - key - message properties: code: type: integer example: 401 key: type: string example: auth.invalid_token message: type: string example: The access token is invalid. details: type: object additionalProperties: true meta: $ref: '#/components/schemas/PublicApiMeta' ErrorResponse: allOf: - $ref: '#/components/schemas/StandardResponse' - example: status: 401 error: true message: MISSING_AUTH PublicApiWriteMeta: type: object additionalProperties: false required: - requestId properties: requestId: type: string description: Stable request correlation id. Mirrors `X-Request-Id` when supplied. example: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: $ref: '#/components/schemas/PublicApiRateLimitMeta' idempotency: type: object additionalProperties: false properties: replayed: type: boolean description: >- True when the response was replayed from a previous request with the same `Idempotency-Key`. example: true PublicApiMeta: type: object additionalProperties: false required: - requestId properties: requestId: type: string description: Stable request correlation id. Mirrors `X-Request-Id` when supplied. example: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: $ref: '#/components/schemas/PublicApiRateLimitMeta' StandardResponse: type: object properties: status: type: integer example: 200 error: type: boolean example: false message: type: string example: SUCCESS required: - status - error - message PublicApiRateLimitMeta: type: object additionalProperties: false properties: limit: type: integer example: 10 remaining: type: integer example: 9 resetSeconds: type: integer description: Seconds until the current rate limit window resets. example: 1 retryAfterSeconds: type: integer description: Present when the request was rate limited. example: 1 securitySchemes: PublicBearerAuth: type: http scheme: bearer bearerFormat: Opaque description: >- Public API access token issued by `/public/v1/oauth/token`. Example: `Authorization: Bearer fspt_...`. Each resource request rechecks the token company's current provider access. Disabling access blocks existing tokens with `403 auth.provider_unavailable`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.