> ## 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.

# Coach exercise picker (Library / My / Last Used tabs)

> Returns company-visible exercises selected by tab. library returns the visible library, my returns exercises created by the attributed coach, and lastUsed returns exercises from that coach's plans in most recently used order with lastUsedAt. library and my are sorted by popularity, then newest. search, muscleGroups, and categories apply to every tab.

Read collections default to 10 records. limit accepts 1 through 100; larger values use 100. Continue with page using the returned pagination metadata. Shared or mixed catalogue browsing supports pages 1 through 10. Own-record and explicit company-only scopes have no page ceiling. pagination.totalItems describes the accessible browse window; pagination.totalAvailableItems gives the full matching count for bounded catalogues.

Requires the `workout_library:read` scope and the corresponding Workout features and permissions.



## OpenAPI

````yaml /openapi/public-v1.json post /public/v1/workout/exercises/company-coach
openapi: 3.1.0
info:
  title: FITsociety Public API v1
  version: 1.0.0
  description: >-
    Integrate with FITsociety through `/public/v1`. Use OAuth client credentials
    to obtain a Bearer access token, then call the endpoints available to the
    authenticated company and granted scopes.
  contact:
    name: FITsociety Engineering
servers:
  - url: https://api.fitsociety.io
    description: Production
security: []
tags:
  - name: Health
    description: Public API token health checks.
  - name: OAuth
    description: Public API OAuth endpoints for server-to-server client credentials.
  - name: Platform
    description: Inspect Public API client context, capabilities, scopes, and 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, and
      manage finance actions.
  - name: Credits
    description: >-
      Read company-wide and client-scoped credit allocations and mutations, and
      adjust credits.
  - 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.
  - name: Workout
    description: >-
      Workout libraries, programmes, client plans, calendars, sessions, groups,
      settings and progress. AI operations are excluded.
paths:
  /public/v1/workout/exercises/company-coach:
    post:
      tags:
        - Workout
      summary: Coach exercise picker (Library / My / Last Used tabs)
      description: >-
        Returns company-visible exercises selected by tab. library returns the
        visible library, my returns exercises created by the attributed coach,
        and lastUsed returns exercises from that coach's plans in most recently
        used order with lastUsedAt. library and my are sorted by popularity,
        then newest. search, muscleGroups, and categories apply to every tab.


        Read collections default to 10 records. limit accepts 1 through 100;
        larger values use 100. Continue with page using the returned pagination
        metadata. Shared or mixed catalogue browsing supports pages 1 through
        10. Own-record and explicit company-only scopes have no page ceiling.
        pagination.totalItems describes the accessible browse window;
        pagination.totalAvailableItems gives the full matching count for bounded
        catalogues.


        Requires the `workout_library:read` scope and the corresponding Workout
        features and permissions.
      operationId: publicWorkoutpostPublicV1WorkoutExercisesCompanyCoach
      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`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PublicWorkoutSourcePOSTAppV1WorkoutExercisesCompanyCoachRequest
            example:
              tab: library
              page: 1
              limit: 20
              search: ''
              muscleGroups:
                - Chest
              categories:
                - Strength
      responses:
        '200':
          description: >-
            Coach exercises for the requested tab with available and selected
            filters.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PublicApiWriteSuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: >-
                          #/components/schemas/PublicWorkoutSourcePOSTAppV1WorkoutExercisesCompanyCoachResponse200
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      tab: library
                      exercises:
                        - _id: 67f1234567890abcdef1234
                          name: Barbell Hip Thrusts
                          thumbnail: https://cdn.example.com/exercises/hip-thrust.jpg
                          primaryMuscle: Legs/Glutes
                          secondaryMuscles:
                            - Hamstrings
                          difficulty: Intermediate
                          category: Strength
                          equipment:
                            - Barbell
                          exerciseType: coach
                          lastUsedAt: '2026-04-12T10:00:00.000Z'
                      availableFilters:
                        muscleGroups:
                          - Chest
                          - Back
                          - Lats
                        categories:
                          - Agility & Speed
                          - Strength
                          - Hypertrophy
                      selectedFilters:
                        search: ''
                        muscleGroups: []
                        categories: []
                        excludeExerciseIds: []
                      pagination:
                        page: 1
                        limit: 1
                        totalItems: 1
                        totalAvailableItems: 1
                        totalPages: 1
                        hasNextPage: true
                        hasPreviousPage: true
                        nextPage: 1
                        previousPage: 1
                    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 coach id
            (`INVALID_USER`), or invalid pagination.
          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:
                          - workout_library:read
                    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/exercises/company-coach"
            \
              -H "Authorization: Bearer <access_token>" \
              -H "Idempotency-Key: <stable_request_key>" \
              -H "Content-Type: application/json" \
              -d '{}'
components:
  schemas:
    PublicWorkoutSourcePOSTAppV1WorkoutExercisesCompanyCoachRequest:
      type: object
      properties:
        tab:
          type: string
          enum:
            - library
            - my
            - lastUsed
          default: library
          description: >-
            Which tab to compute. Defaults to `library`. Unknown values fall
            back to `library`.
        page:
          type: integer
          minimum: 1
          default: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        search:
          type: string
          example: bench press
          description: Case-insensitive name search. Applies to every tab.
        muscleGroups:
          oneOf:
            - type: string
              example: Chest,Shoulders
            - type: array
              items:
                type: string
              example:
                - Chest
                - Shoulders
          description: >-
            Matches primaryMuscle OR secondaryMuscles. Allowed values: Chest,
            Back, Lats, Traps, Shoulders …
        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 …
        excludeExerciseIds:
          oneOf:
            - type: string
              example: 6925d2764ac340a53e012927,6925d2764ac340a53e012928
            - type: array
              items:
                type: string
                example: 67f1234567890abcdef1234
          description: >-
            Exclude one or more exercises from results (comma-separated string
            or array of exercise ObjectIds). Aliases accepted: excludeExerciseId
            / exerciseIds / exerciseId. Also readable from query
            `excludeExerciseIds` / `excludeExerciseId`. Invalid id → 400
            WORKOUTEXERCISE_EXERCISEID_INVALID. Echoed in
            selectedFilters.excludeExerciseIds.
    PublicApiWriteSuccessResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          type: object
        meta:
          $ref: '#/components/schemas/PublicApiWriteMeta'
    PublicWorkoutSourcePOSTAppV1WorkoutExercisesCompanyCoachResponse200:
      type: object
      properties:
        tab:
          type: string
          enum:
            - library
            - my
            - lastUsed
          example: library
        exercises:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                example: 67f1234567890abcdef1234
              name:
                type: string
                example: Barbell Hip Thrusts
              thumbnail:
                type: string
                example: https://cdn.example.com/exercises/hip-thrust.jpg
              primaryMuscle:
                type: string
                example: Legs/Glutes
              secondaryMuscles:
                type: array
                items:
                  type: string
                example:
                  - Hamstrings
              difficulty:
                type: string
                example: Intermediate
              category:
                type: string
                example: Strength
                description: Exercise `primaryCategory`.
              equipment:
                type: array
                items:
                  type: string
                example:
                  - Barbell
              exerciseType:
                type: string
                enum:
                  - coach
                  - personal
                  - global
                example: coach
                description: >-
                  `coach` = added by a coach; `personal` = added by a client;
                  `global` = Everyone/Fitsociety visibility.
              lastUsedAt:
                type: string
                format: date-time
                example: '2026-04-12T10:00:00.000Z'
                nullable: true
                description: >-
                  Only present on the `lastUsed` tab — when the coach last used
                  this exercise in a plan.
        availableFilters:
          type: object
          properties:
            muscleGroups:
              type: array
              items:
                type: string
              example:
                - Chest
                - Back
                - Lats
            categories:
              type: array
              items:
                type: string
              example:
                - Agility & Speed
                - Strength
                - Hypertrophy
        selectedFilters:
          type: object
          properties:
            search:
              type: string
              example: ''
            muscleGroups:
              type: array
              items:
                type: string
              example: []
            categories:
              type: array
              items:
                type: string
              example: []
            excludeExerciseIds:
              type: array
              items:
                type: string
                example: 67f1234567890abcdef1234
              example: []
        pagination:
          type: object
          properties:
            page:
              type: integer
              minimum: 1
            limit:
              type: integer
              minimum: 1
              maximum: 100
            totalItems:
              type: integer
              minimum: 0
            totalAvailableItems:
              type: integer
              minimum: 0
            totalPages:
              type: integer
              minimum: 1
            hasNextPage:
              type: boolean
            hasPreviousPage:
              type: boolean
            nextPage:
              type:
                - integer
                - boolean
            previousPage:
              type:
                - integer
                - boolean
          additionalProperties: false
    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.