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

# Search or filter workout template plans

> Searches active-company template plans within the authenticated access scope. Results include permitted Everyone, Fitsociety and Company visibility values. Category, difficulty and goal filters apply to both text searches and listings. Deleted, WOD and assigned plans are excluded. Client visibility restrictions also apply.

Read collections default to 10 records. limit accepts 1 through 100; larger values use 100. Continue with page using the returned pagination metadata. Owned collections have no page ceiling.

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



## OpenAPI

````yaml /openapi/public-v1.json get /public/v1/workout/plans
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/plans:
    get:
      tags:
        - Workout
      summary: Search or filter workout template plans
      description: >-
        Searches active-company template plans within the authenticated access
        scope. Results include permitted Everyone, Fitsociety and Company
        visibility values. Category, difficulty and goal filters apply to both
        text searches and listings. Deleted, WOD and assigned plans are
        excluded. Client visibility restrictions also apply.


        Read collections default to 10 records. limit accepts 1 through 100;
        larger values use 100. Continue with page using the returned pagination
        metadata. Owned collections have no page ceiling.


        Requires the `workout_plans:read` scope and the corresponding Workout
        features and permissions.
      operationId: publicWorkoutgetPublicV1WorkoutPlans
      parameters:
        - in: query
          name: query
          schema:
            type: string
            maxLength: 100
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: difficulty
          schema:
            type: string
            enum:
              - Beginner
              - Intermediate
              - Advanced
        - in: query
          name: goal
          schema:
            type: string
            enum:
              - Weight Loss
              - Hypertrophy
              - Endurance
              - Flexibility
              - General Fitness
              - Strength
        - in: query
          name: category
          schema:
            type: string
            enum:
              - Agility & Speed
              - Strength
              - Hypertrophy
              - Strength - Dynamic
              - Strength - Explosive
              - Strength - Static
              - Cardio
              - Cardio - Duration
              - Cardio - Interval
              - HIIT
              - Crossfit
              - Mobility
              - Stretching
              - Core
              - Coordination & Balance
              - Movement Prep
              - Functional Training
              - Recovery
              - Sports
              - Martial Arts
              - Yoga
              - Other
              - GROUP_WORKOUT_TEMPLATE
              - Plyometric
              - Cycling
              - Cardio - interval
              - Mobilisation
              - Stabilisation
              - Daily Living
              - Target zone
              - Respiration
              - Breathing
              - Massage
              - Outdoor sports
              - Indoor sports
              - Dance
              - Group Lessons
              - Martial arts
              - Material Arts
              - Fight skills
              - Mind and body
              - ''
              - default
        - in: query
          name: visibility
          schema:
            type: string
            enum:
              - Everyone
              - Company
              - Fitsociety
        - in: query
          name: visibilityScope
          schema:
            type: string
            enum:
              - company
              - everyone
              - fitsociety
      responses:
        '200':
          description: Template-plan search results.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PublicApiSuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: >-
                          #/components/schemas/PublicWorkoutSourceGETAppV1WorkoutPlansResponse200
              examples:
                success:
                  summary: Successful response
                  value:
                    data:
                      items:
                        - _id: 67f1234567890abcdef1234
                          name: 4-Day Strength Block
                          description: Progressive upper/lower split.
                          category: Strength
                          goal: Strength
                          periodizationType: Linear
                          difficulty: Intermediate
                          intensity: High
                          duration:
                            startDate: '2026-04-15'
                            endDate: '2026-06-15'
                            hasEndDate: true
                          images:
                            - url: https://cdn.example.com/workouts/plan-cover.jpg
                              width: 1280
                              height: 720
                          videos:
                            - url: https://cdn.example.com/workouts/demo.mp4
                              platform: s3
                              videoId: ''
                              thumbnail: https://cdn.example.com/workouts/demo-thumb.jpg
                              duration: 84
                              width: 1920
                              height: 1080
                          status: Active
                          templateType: Assigned
                          popularity: 64
                          visibility: Company
                          useDefaultExerciseSettings: true
                          defaultExerciseValues:
                            sets: 3
                            reps: 10-12
                            rest: 90
                            weight: 0
                            repTempo: '3010'
                            duration: 0
                          createdAt: '2026-04-12T10:00:00.000Z'
                          updatedAt: '2026-04-12T10:00:00.000Z'
                      pagination:
                        page: 1
                        limit: 25
                        totalPages: 5
                        totalItems: 100
                        hasNextPage: true
                        hasPreviousPage: false
                        nextPage: 2
                        previousPage: null
                        totalAvailableItems: 1
                      query: strength
                      filters: {}
                    meta:
                      requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83
                      rateLimit:
                        limit: 10
                        remaining: 9
                        resetSeconds: 1
        '400':
          description: >-
            Invalid pagination or search query. `SEARCH_QUERY_TOO_LONG` is
            returned when the query exceeds 100 characters.
          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
        '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_plans: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'
        '422':
          $ref: '#/components/schemas/ErrorResponse'
        '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 GET "https://api.fitsociety.io/public/v1/workout/plans" \
              -H "Authorization: Bearer <access_token>"
components:
  schemas:
    PublicApiSuccessResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          type: object
        meta:
          $ref: '#/components/schemas/PublicApiMeta'
    PublicWorkoutSourceGETAppV1WorkoutPlansResponse200:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                example: 67f1234567890abcdef1234
              name:
                type: string
                example: 4-Day Strength Block
              description:
                type: string
                example: Progressive upper/lower split.
              category:
                type: string
                enum:
                  - Agility & Speed
                  - Strength
                  - Hypertrophy
                  - Strength - Dynamic
                  - Strength - Explosive
                  - Strength - Static
                  - Cardio
                  - Cardio - Duration
                  - Cardio - Interval
                  - HIIT
                  - Crossfit
                  - Mobility
                  - Stretching
                  - Core
                  - Coordination & Balance
                  - Movement Prep
                  - Functional Training
                  - Recovery
                  - Sports
                  - Martial Arts
                  - Yoga
                  - Other
                  - GROUP_WORKOUT_TEMPLATE
                  - Plyometric
                  - Cycling
                  - Cardio - interval
                  - Mobilisation
                  - Stabilisation
                  - Daily Living
                  - Target zone
                  - Respiration
                  - Breathing
                  - Massage
                  - Outdoor sports
                  - Indoor sports
                  - Dance
                  - Group Lessons
                  - Martial arts
                  - Material Arts
                  - Fight skills
                  - Mind and body
                  - ''
                  - default
                example: Strength
              goal:
                type: string
                enum:
                  - Weight Loss
                  - Hypertrophy
                  - Endurance
                  - Flexibility
                  - General Fitness
                  - Strength
                example: Strength
              periodizationType:
                type: string
                enum:
                  - Linear
                  - Non-Linear
                  - Block
                  - Undulating
                  - None
                example: Linear
              difficulty:
                type: string
                enum:
                  - Beginner
                  - Intermediate
                  - Advanced
                example: Intermediate
              intensity:
                type: string
                enum:
                  - Low
                  - Medium
                  - High
                example: High
              duration:
                type: object
                properties:
                  startDate:
                    type: string
                    example: '2026-04-15'
                  endDate:
                    type: string
                    example: '2026-06-15'
                  hasEndDate:
                    type: boolean
                    example: true
              images:
                type: array
                items:
                  type: object
                  required:
                    - url
                  properties:
                    url:
                      type: string
                      format: uri
                      example: https://cdn.example.com/workouts/plan-cover.jpg
                    width:
                      type:
                        - number
                        - 'null'
                      example: 1280
                    height:
                      type:
                        - number
                        - 'null'
                      example: 720
              videos:
                type: array
                items:
                  type: object
                  required:
                    - url
                    - platform
                  properties:
                    url:
                      type: string
                      format: uri
                      example: https://cdn.example.com/workouts/demo.mp4
                    platform:
                      type: string
                      enum:
                        - s3
                        - youtube
                        - tiktok
                      example: s3
                    videoId:
                      type: string
                      example: ''
                    thumbnail:
                      type: string
                      format: uri
                      example: https://cdn.example.com/workouts/demo-thumb.jpg
                    duration:
                      type:
                        - number
                        - 'null'
                      example: 84
                    width:
                      type:
                        - number
                        - 'null'
                      example: 1920
                    height:
                      type:
                        - number
                        - 'null'
                      example: 1080
              status:
                type: string
                enum:
                  - Active
                  - Inactive
                  - Draft
                example: Active
              templateType:
                type: string
                enum:
                  - Template
                  - Assigned
                example: Assigned
              popularity:
                type: number
                example: 64
              visibility:
                type: string
                enum:
                  - Everyone
                  - Company
                  - Fitsociety
                example: Company
              useDefaultExerciseSettings:
                type: boolean
                example: true
              defaultExerciseValues:
                oneOf:
                  - type: object
                    required:
                      - sets
                      - reps
                      - rest
                      - repTempo
                    properties:
                      sets:
                        type: number
                        minimum: 1
                        example: 3
                      reps:
                        oneOf:
                          - type: string
                            pattern: ^\d+(-\d+)?$
                          - type: number
                            minimum: 1
                        example: 10-12
                      rest:
                        type: number
                        minimum: 0
                        example: 90
                      weight:
                        type: number
                        example: 0
                      repTempo:
                        type: string
                        example: '3010'
                      duration:
                        type: number
                        example: 0
                  - type: 'null'
              createdAt:
                type: string
                format: date-time
                example: '2026-04-12T10:00:00.000Z'
              updatedAt:
                type: string
                format: date-time
                example: '2026-04-12T10:00:00.000Z'
        pagination:
          type: object
          properties:
            page:
              type: integer
              example: 1
            limit:
              type: integer
              example: 25
            totalPages:
              type: integer
              example: 5
            totalItems:
              type: integer
              example: 100
            hasNextPage:
              type: boolean
              example: true
            hasPreviousPage:
              type: boolean
              example: false
            nextPage:
              type: integer
              nullable: true
              example: 2
            previousPage:
              type: integer
              nullable: true
              example: null
            totalAvailableItems:
              type: integer
              minimum: 0
              description: >-
                Total matching records before the shared catalogue browse
                boundary.
        query:
          type: string
          example: strength
        filters:
          type: object
          additionalProperties: true
    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
    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.