> ## 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. # Create or run groups performance sessions :session Id exercises :exercise Id To Replace replace > Requires the workout_groups:write scope. This operation maps to /app/v1/coach/workout/group/performance/sessions/:sessionId/exercises/:exerciseIdToReplace/replace and retains its Workout V2 permission, feature-flag, and resource-scope checks. The clientId path parameter is resolved inside the company bound to the Public API token when present. ## OpenAPI ````yaml /openapi/public-v1.json post /public/v1/workout/groups/performance/sessions/{sessionId}/exercises/{exerciseIdToReplace}/replace 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/groups/performance/sessions/{sessionId}/exercises/{exerciseIdToReplace}/replace: post: tags: - Workout summary: >- Create or run groups performance sessions :session Id exercises :exercise Id To Replace replace description: >- Requires the workout_groups:write scope. This operation maps to /app/v1/coach/workout/group/performance/sessions/:sessionId/exercises/:exerciseIdToReplace/replace and retains its Workout V2 permission, feature-flag, and resource-scope checks. The clientId path parameter is resolved inside the company bound to the Public API token when present. operationId: >- publicWorkoutpostPublicV1WorkoutGroupsPerformanceSessionsSessionIdExercisesExerciseIdToReplaceReplace 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`. - name: sessionId in: path required: true schema: type: string pattern: ^[a-fA-F0-9]{24}$ description: sessionId from the source Workout V2 endpoint. - name: exerciseIdToReplace in: path required: true schema: type: string pattern: ^[a-fA-F0-9]{24}$ description: exerciseIdToReplace from the source Workout V2 endpoint. requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/PublicWorkoutSourcePOSTAppV1CoachWorkoutGroupPerformanceSessionsSessionIdExercisesExerciseIdToReplaceReplaceRequest responses: '200': description: Successful Workout V2 response. content: application/json: schema: allOf: - $ref: '#/components/schemas/PublicApiWriteSuccessResponse' - type: object properties: data: $ref: >- #/components/schemas/PublicWorkoutSourcePOSTAppV1CoachWorkoutGroupPerformanceSessionsSessionIdExercisesExerciseIdToReplaceReplaceResponse200 examples: success: summary: Successful response value: data: id: 66f7b8b1e13c8d25f4d3d90a exerciseId: 66f7b8b1e13c8d25f4d3d90a planExerciseId: 66f7b8b1e13c8d25f4d3d90a order: 1 isCompleted: true date: '2026-07-14T10:00:00.000Z' startedAt: '2026-07-14T10:00:00.000Z' endedAt: '2026-07-14T10:00:00.000Z' totals: totalReps: 1 totalTimeSeconds: 1 totalDistanceMeters: 1 totalVolume: 1 maxWeight: 1 estimated1RM: 1 averageRPE: 1 sets: - setNumber: 1 setType: 'N' displayNumber: 1 displayLabel: '1' targetReps: 8-12 targetWeight: 60 targetTimeSeconds: null targetDistanceMeters: null targetRestSeconds: 90 weight: 70 reps: 8 timeSeconds: null distanceMeters: null restSeconds: 120 rpe: 8 completed: true notes: Felt strong. isPersonalBest: false repsPlaceholder: 22 weightPlaceholder: 30 timeSecondsPlaceholder: 55 distanceMetersPlaceholder: 40 rpePlaceholder: 3 restSecondsPlaceholder: 60 repsActual: 30 weightActual: 42 timeSecondsActual: null distanceMetersActual: null rpeActual: 8 restSecondsActual: 90 notes: string nextSessionTarget: reps: 1 weight: 1 timeSeconds: 1 distanceMeters: 1 targetSnapshot: reps: 1 weight: 1 timeSeconds: 1 distanceMeters: 1 setupFields: - key: seat label: Seat type: text unit: '' options: - '1' - '2' - '3' - '4' order: 1 required: false enabled: true defaultValue: 3 setupValues: {} nextSetupValues: {} hasMachineSettings: true setupSettingsEnabled: true isMachineSetting: true provenance: recordedByActorType: string recordedByClientId: 66f7b8b1e13c8d25f4d3d90a recordedByCoachId: 66f7b8b1e13c8d25f4d3d90a lastUpdatedByActorType: string lastUpdatedByClientId: 66f7b8b1e13c8d25f4d3d90a lastUpdatedByCoachId: 66f7b8b1e13c8d25f4d3d90a meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotency: replayed: false '400': $ref: '#/components/schemas/ErrorResponse' 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': $ref: '#/components/schemas/ErrorResponse' 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/groups/performance/sessions/{sessionId}/exercises/{exerciseIdToReplace}/replace" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: " \ -H "Content-Type: application/json" \ -d '{}' components: schemas: PublicWorkoutSourcePOSTAppV1CoachWorkoutGroupPerformanceSessionsSessionIdExercisesExerciseIdToReplaceReplaceRequest: type: object required: - newExerciseId properties: newExerciseId: type: string pattern: ^[a-fA-F0-9]{24}$ additionalProperties: false PublicApiWriteSuccessResponse: type: object additionalProperties: false required: - data - meta properties: data: type: object meta: $ref: '#/components/schemas/PublicApiWriteMeta' PublicWorkoutSourcePOSTAppV1CoachWorkoutGroupPerformanceSessionsSessionIdExercisesExerciseIdToReplaceReplaceResponse200: type: object required: - id - exerciseId - order - isCompleted - date - startedAt - endedAt - totals - sets - notes - setupFields - setupValues - nextSetupValues - hasMachineSettings - setupSettingsEnabled - isMachineSetting - provenance properties: id: type: string exerciseId: type: string planExerciseId: type: - string - 'null' order: type: integer isCompleted: type: boolean date: type: string format: date-time startedAt: type: - string - 'null' format: date-time endedAt: type: - string - 'null' format: date-time totals: type: object required: - totalReps - totalTimeSeconds - totalDistanceMeters - totalVolume - maxWeight - estimated1RM - averageRPE properties: totalReps: type: number totalTimeSeconds: type: number totalDistanceMeters: type: number totalVolume: type: number maxWeight: type: number estimated1RM: type: number averageRPE: type: number additionalProperties: false sets: type: array items: $ref: '#/components/schemas/PublicWorkoutSourceWorkoutPerformanceSet' notes: type: string nextSessionTarget: type: object properties: reps: type: - number - 'null' weight: type: - number - 'null' timeSeconds: type: - number - 'null' distanceMeters: type: - number - 'null' additionalProperties: false targetSnapshot: type: - object - 'null' properties: reps: type: - number - 'null' weight: type: - number - 'null' timeSeconds: type: - number - 'null' distanceMeters: type: - number - 'null' additionalProperties: false setupFields: type: array items: $ref: '#/components/schemas/PublicWorkoutSourceWorkoutExerciseSetupField' setupValues: type: object additionalProperties: type: - string - number - boolean - 'null' nextSetupValues: type: object additionalProperties: type: - string - number - boolean - 'null' hasMachineSettings: type: boolean setupSettingsEnabled: type: boolean isMachineSetting: type: boolean provenance: type: object required: - recordedByActorType - recordedByClientId - recordedByCoachId - lastUpdatedByActorType - lastUpdatedByClientId - lastUpdatedByCoachId properties: recordedByActorType: type: string recordedByClientId: type: - string - 'null' recordedByCoachId: type: - string - 'null' lastUpdatedByActorType: type: string lastUpdatedByClientId: type: - string - 'null' lastUpdatedByCoachId: type: - string - 'null' additionalProperties: false additionalProperties: false ErrorResponse: allOf: - $ref: '#/components/schemas/StandardResponse' - example: status: 401 error: true message: MISSING_AUTH 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' 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 PublicWorkoutSourceWorkoutPerformanceSet: type: object required: - setNumber properties: setNumber: type: integer minimum: 1 example: 1 setType: type: string enum: - 'N' - W - D - F example: 'N' description: >- Planned or performed set type: N normal, W warm-up, D drop set, F to failure. displayNumber: type: - integer - 'null' example: 1 description: >- Sequential number for normal sets only. Warm-up, drop set, and failure sets return null. displayLabel: type: string example: '1' description: >- Backend-ready display string: normal sets use their sequential number, other set types use W, D, or F. targetReps: type: string example: 8-12 targetWeight: type: - number - 'null' minimum: 0 example: 60 targetTimeSeconds: type: - integer - 'null' minimum: 0 example: null targetDistanceMeters: type: - integer - 'null' minimum: 0 example: null targetRestSeconds: type: - integer - 'null' minimum: 0 example: 90 weight: type: - number - 'null' minimum: 0 example: 70 reps: type: - integer - 'null' minimum: 0 example: 8 timeSeconds: type: - integer - 'null' minimum: 0 example: null distanceMeters: type: - integer - 'null' minimum: 0 example: null restSeconds: type: - integer - 'null' minimum: 0 example: 120 rpe: type: - number - 'null' minimum: 0 maximum: 10 example: 8 completed: type: boolean example: true notes: type: string example: Felt strong. isPersonalBest: type: boolean example: false repsPlaceholder: type: - number - string - 'null' example: 22 description: >- The client's OWN greyed hint for an empty reps input on this set — accepted on upsert and stored as sent. A range string (`"8-12"`) is allowed. It is a FALLBACK, not an override: the coach's `repsPlaceholderCoach` wins wherever it exists, so this value is only used for sets the coach never prescribed (per-set tracking off, extra sets, metrics left blank). Sending it for a prescribed set is accepted but has no effect. **Never logged work**: placeholders are excluded from every total, volume, PR and completion check, so leaving a hint after clearing a value does not make the set count. To COMMIT a hint the athlete accepted, send it as the real `reps` value with `completed: true` — but never submit a RANGE on a completed set, which is stored as its minimum (`"12-24"` → 12) and under-credits the athlete. weightPlaceholder: type: - number - 'null' minimum: 0 example: 30 description: >- The client's own hint for an empty weight input. See `repsPlaceholder`. timeSecondsPlaceholder: type: - integer - 'null' minimum: 0 example: 55 description: >- The client's own hint for an empty time input. See `repsPlaceholder`. distanceMetersPlaceholder: type: - integer - 'null' minimum: 0 example: 40 description: >- The client's own hint for an empty distance input. See `repsPlaceholder`. rpePlaceholder: type: - number - 'null' minimum: 0 maximum: 10 example: 3 description: The client's own hint for an empty RPE input. See `repsPlaceholder`. restSecondsPlaceholder: type: - integer - 'null' minimum: 0 example: 60 description: >- The client's own hint for an empty rest input. See `repsPlaceholder`. repsActual: type: - number - string - 'null' example: 30 description: >- The athlete's ACTUALLY-logged reps for this set (mirrors `reps`), or `null` when they have not logged it — the visible `reps` may be a coach-prescription prefill. Additive: `reps` is unchanged. weightActual: type: - number - 'null' minimum: 0 example: 42 description: >- Actually-logged weight (mirrors `weight`), or `null` if not logged. See `repsActual`. timeSecondsActual: type: - integer - 'null' minimum: 0 example: null description: >- Actually-logged time (mirrors `timeSeconds`), or `null` if not logged. See `repsActual`. distanceMetersActual: type: - integer - 'null' minimum: 0 example: null description: >- Actually-logged distance (mirrors `distanceMeters`), or `null` if not logged. See `repsActual`. rpeActual: type: - number - 'null' minimum: 0 maximum: 10 example: 8 description: >- Actually-logged RPE (mirrors `rpe`), or `null` if not logged or RPE is hidden. See `repsActual`. restSecondsActual: type: - integer - 'null' minimum: 0 example: 90 description: >- Actually-logged rest in seconds (mirrors `restSeconds`), or `null` if not logged. See `repsActual`. PublicWorkoutSourceWorkoutExerciseSetupField: type: object required: - key - label properties: key: type: string example: seat label: type: string example: Seat type: type: string enum: - text - number - select example: text unit: type: string example: '' options: type: array items: type: string example: - '1' - '2' - '3' - '4' order: type: number example: 1 required: type: boolean example: false enabled: type: boolean example: true defaultValue: oneOf: - type: string - type: number example: 3 StandardResponse: type: object properties: status: type: integer example: 200 error: type: boolean example: false message: type: string example: SUCCESS required: - status - error - message 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' 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.