CloudFit APIAPI referenceTechnical guideMCP guide

Technical guide

How the CloudFit API works: signing in, scopes, limits, revisions, retries, uploads and errors. It applies to both REST and MCP, which share the same services and rules. The API reference lists every REST route and model; the MCP guide covers connecting AI apps.

Beta. v1 may still change in small ways before general release.

Endpoints

WhatURL
RESThttps://api.cloudfit.tv/v1
OpenAPI 3.1 documenthttps://api.cloudfit.tv/v1/openapi.json
API referencehttps://api.cloudfit.tv/docs
MCP (streamable HTTP, stateless, JSON responses)https://api.cloudfit.tv/mcp

Concepts

Signing in

Personal tokens (REST and MCP)

Create a token in the CloudFit app under Settings → AI & API Access. Choose the locations and scopes; it lasts 30 or 90 days, and you can have 10 active at once. Send it on every request:

Authorization: Bearer cf_api_live_…

A token is shown once; CloudFit keeps only a hash. Delete it in the app to stop it at once.

Connected apps (MCP only)

Claude, Claude Code, ChatGPT and Codex sign in with OAuth 2.1 (authorization code with PKCE) following the MCP authorization spec, so people approve them on a CloudFit page instead of copying tokens. Discovery starts from the 401 on /mcp, whose WWW-Authenticate header points at /.well-known/oauth-protected-resource/mcp. Access tokens last 1 hour and work only on /mcp; refresh tokens rotate on every use and expire after 90 days without one. Only these four apps can register; other clients use a personal token.

Scopes

Scopes are granted per location, and every request is also checked against the person’s current CloudFit permissions, so a token or connection never outlasts a role change.

ScopeLets an appNeeds in CloudFit
locations:readSee the location, its displays and appearance, and what you can do thereAccess to the location
workouts:readRead workouts, folders and workout history, validate workout specsAccess to the location
exercises:readSearch exercises, list the exercise library, get exercise downloadsAccess to the location
media:readBrowse media librariesAccess to the location
schedule:readRead the class scheduleAccess to the location
workouts:writeCreate, duplicate, edit and delete workouts; publish them on a public web page and take them down (owners only); create folders (owners only)Permission to manage workouts (all, or your own)
media:writeUpload images and videos to the media libraryPermission to manage media
exercises:writeCreate, rename, update and delete custom exercises (deleting can’t be undone), upload their videos and images, and import many at oncePermission to manage exercises
schedule:writeAdd, change and remove classesPermission to manage the schedule

A location the token doesn’t cover is 404 not_found, as if it didn’t exist; a missing scope is 403 scope_missing.

Requests and responses

RESTMCP
locationId in the pathlocationId argument
/workouts/… or /hq-workouts/…source: "own" or "hq"
The body of a workout create (a workout spec)spec
If-Match headerexpectedRevision
Idempotency-Key headerrequestKey
Search q, comma-separated equipmentquery, an equipment array

The same create, both ways:

POST /v1/locations/{locationId}/workouts
Idempotency-Key: 7d1c-create-tuesday

{"name": "Tuesday burner", "modules": [{"id": "welcome", "type": "whiteboard", "settings": {"text": "Welcome!", "timing": {"mode": "simple", "durationSeconds": 60}}}]}
{"name": "create_workout", "arguments": {"locationId": "LOCATION_ID", "requestKey": "7d1c-create-tuesday", "spec": {"name": "Tuesday burner", "modules": [{"id": "welcome", "type": "whiteboard", "settings": {"text": "Welcome!", "timing": {"mode": "simple", "durationSeconds": 60}}}]}}}

Limits

Every request counts, including refused and malformed ones. A limit returns 429 rate_limited with Retry-After (seconds); MCP tool errors carry retryAfterSeconds. A daily budget names itself in details.scope.

LimitAllowance
Every request or tool call120 a minute per token or connected app, and 240 a minute per person across all of them
Validating and previewing, listing media, exercise downloads60 a minute per person
Changes (create, duplicate, apply edits, publish, schedule changes, uploads, folders, exercises)30 a minute per person and 30 a minute per location
Exercise searches200 a day per person
Workouts archived10 a day per location (unarchiving isn’t limited)
Workouts deleted10 a day per location
Workouts published, updated or unpublished30 a day per location
Exercises created50 a day per location
Exercises imported (bulk import)200 per location in any 7 days; CloudFit can raise it for a larger library
Exercises renamed50 a day per location
Exercises updated (equipment, categories)200 a day per location
Exercises deleted20 a day per location
Exercises given download links200 a day per location

Daily budgets are checked for the whole request and charged only for what happened, so a refused or repeated request costs nothing. A retry under the same idempotency key (below) doesn’t count against the change limits.

Revisions

Reads return a revision (REST also sends it as the ETag header). A change to something that exists names the revision it was based on, so nothing is overwritten by accident:

ChangeREST If-Match / MCP expectedRevisionWhere the revision comes from
Preview or apply workout editsRequiredReading the workout
Delete a workoutRequiredReading the workout
Publish a workoutRequiredReading the workout
Duplicate a workoutOptional; copying doesn’t change the sourceReading the workout
Change or remove one class (REST PATCH/DELETE)RequiredThe class’s revision in the schedule list
Schedule batch that changes or removes classesRequiredThe batch preview’s revision
Schedule batch that only addsNot needed

Edits are a batch of operations: updateMetadata, updateDisplays, addModule, moveModule, removeModule, replaceExercises and updateModuleSettings (details in the reference). Settings changes are patches: send only the settings to change. For example, renaming a workout:

  1. GET /v1/locations/{locationId}/workouts/{workoutId}. Note the ETag (the workout’s revision).
  2. POST …/workouts/{workoutId}/edits/preview with If-Match: <revision> and the operations. It returns the workout as it would be, and its warnings.
  3. POST …/workouts/{workoutId}/edits with the same If-Match, an Idempotency-Key and the same operations.
{"operations": [{"type": "updateMetadata", "patch": {"name": "Tuesday burner"}}]}

Retries and idempotency

Commits take an idempotency key so a retry after a lost response is safe. Sending the same key with the same body returns the first result instead of acting again; the same key with a different body is 409 idempotency_conflict. Keys are 1–128 characters of A-Z a-z 0-9 _ . : -, belong to the person, and are remembered for 7 days.

REST requires an Idempotency-Key header (idempotency_key_required) on:

In MCP, create_workout, duplicate_workout, apply_workout_edits and apply_schedule_changes require a requestKey, which works the same way.

These are safe to repeat without a key: creating a folder (by name), renaming exercises (a repeat reports already_renamed), updating them (unchanged), creating an exercise (a repeat returns it with created: false), deleting a workout (alreadyDeleted) or an exercise deleted through the API (alreadyDeleted), and publishing or unpublishing (the same result again).

A 503 on a keyed commit is safe to retry with the same key.

Uploads

Images and videos for the media library

  1. POST /v1/locations/{locationId}/media/uploads (MCP create_media_upload, needs media:write) with the file’s name, which sets the type, and, optionally, the name the library shows. It returns putUrl, uploadUrl and the limits.
  2. Upload. With a shell, PUT the whole file in one request to putUrl. Otherwise open uploadUrl in a browser and choose the file. The link is the credential, so no token is sent, and it works for 30 minutes.
  3. The file is saved to the media library on its own once it’s in. Check GET …/media/uploads/{uploadId} (get_media_upload) until it’s ready; checking only reports. States: waiting_for_file (not arrived yet), processing (arrived and being saved), ready (with the library file), failed (with a code) and expired (the link closed before the file arrived).
  4. Use the file’s mediaId as a whiteboard background (a video with loop, mute and the other video options). An image upload’s uploadId also works as a whiteboard canvasImage.

Images can be JPG, PNG or WebP, up to 20 MB and 50 megapixels, and are ready as soon as they arrive. Videos can be MP4, MOV or M4V, up to 268 MB and no longer than the maxSeconds the link returns (the location’s limit, 60 seconds unless CloudFit set another), portrait or landscape; they go through the same processing as the CloudFit app’s media library and are usually ready within a few minutes. The limits differ from exercise uploads (below) because these are backgrounds and longer clips, while exercise videos are short loops.

curl -X PUT --upload-file rain-loop.mp4 "$putUrl"

Exercise videos and images

  1. Create the exercise: POST /v1/locations/{locationId}/custom-exercises (create_exercise, needs exercises:write). It has no media yet, and workouts can’t use it until it does.
  2. Ask for an upload: POST …/custom-exercises/{exerciseId}/uploads with the file’s name (create_exercise_upload). Videos can be mp4, mov, m4v or webm; images jpg, png, webp, heic or avif.
  3. Upload. With a shell, PUT the whole file in one request to putUrl. Otherwise open uploadUrl in a browser and choose the file. Either works for 30 minutes.
  4. Processing starts on its own once the file is in. Check GET …/custom-exercises/{exerciseId}/uploads/{uploadId} (get_exercise_upload) until it’s ready; checking only reports. States: waiting_for_file (not arrived yet), processing (arrived and processing), ready, failed (with a code) and expired (the link closed before the file arrived).

Videos must be landscape, up to 268 MB, and no longer than the maxSeconds the link returns (the location’s limit, 20 seconds unless the location sets another in the app). Images can be up to 25 MB. Videos go through the same processing as in the CloudFit app and are usually ready within a minute or two.

curl -X PUT --upload-file sled-push.mp4 "$putUrl"

To change an exercise’s equipment or categories later, such as for exercises added through an import page (which get none), send up to 10 at a time to POST …/custom-exercises/updates (update_exercises). Each field sent replaces what the exercise has. The schema lists the values to choose from.

Schedule

Paused changes

CloudFit can pause changes through the API, everywhere or for one location, while it deals with a problem. Changes then return 503 writes_paused with Retry-After, and details.scope is all or location. Reads, validation and previews keep working, and a refused change doesn’t count against the change limits.

Errors

REST errors are application/problem+json (RFC 9457):

{
  "type": "about:blank",
  "title": "Precondition Failed",
  "status": 412,
  "code": "revision_stale",
  "detail": "The source workout has changed since it was read",
  "requestId": "6f1c…"
}

MCP tool errors are tool results with isError and the same code, the HTTP status it maps to, the message, details, retryAfterSeconds when rate limited and the request ID. Refusals before any tool runs (no token, not in the beta) are JSON-RPC errors with the code in error.data. Branch on code, never on the message.

CodeStatusMeaning
cursor_invalid400The cursor is from another listing or was changed
idempotency_key_invalid400The Idempotency-Key has characters or a length it can’t have
idempotency_key_required400Send an Idempotency-Key header
if_match_invalid400If-Match isn’t a revision this API gave out
request_invalid400The body or a query parameter doesn’t match the schema; details lists the issues
unauthenticated401No token, or one that is invalid, expired or revoked
permission_denied403Your role at this location doesn’t allow this
scope_missing403The token lacks the scope this route needs at this location (details.scope)
exercise_not_found404No exercise with that ID in this location’s own library
not_found404No such location, or no such workout, class or other item there, or one the token can’t see
route_not_found404No such route
upload_not_found404No such upload for this location and account
method_not_allowed405The route doesn’t take this method; see Allow
exercise_has_media409The exercise already has media; replacing it isn’t available through the API yet
exercise_name_taken409The library already has an exercise with that name
exercise_processing409The exercise’s media is still uploading or processing
idempotency_conflict409This Idempotency-Key was used for a different request
media_processing409The video is still being processed; try again soon
schedule_conflict409Some classes clash, so nothing was saved (details.conflicts lists them)
upload_not_ready409Nothing has been uploaded to the link yet; check again once it has
workout_name_unavailable409No unique name could be found for the workout
workout_scheduled409The workout has upcoming classes, here or at a location using it; remove them first (details.classes lists up to 10, details.count says how many)
upload_expired410The upload expired; create a new upload link
revision_stale412It changed since you read it: read it again (a schedule batch: preview it again), then retry
body_too_large413The body is over 2 MiB
unsupported_media_type415Send JSON (application/json)
after_module_invalid422afterModuleId isn’t a module on the target track
assignment_id_invalid422An assignmentId isn’t from this workout’s current revision
canvas_needs_saved_module422Add the whiteboard first, then set its canvasImage in another edit
chatgpt_files_invalid422Send 1 to 10 attached files a call, and no more exercises entries than files (add_exercises_from_files)
demo_link_invalid422A demos module must link modules with exercises in this workout
demo_source_removed422A removed module is still linked by a demos module; change the demos too
exercise_details_invalid422Equipment or categories outside those built-in exercises use (details lists the choices)
exercise_download_invalid422Send 1 to 25 exercise IDs
exercise_import_closed422The import closed after 24 hours
exercise_import_duplicate422An import file names an exercise another file in the same import already does
exercise_import_files_invalid422Send 1 to 50 files a call
exercise_import_limit_reached422The import allowance (200 exercises per 7 days, unless CloudFit raised it) has no room; details has the numbers
exercise_library_full422The location’s library is at its exercise limit
exercise_library_inherited422This location uses its HQ’s exercise library; use the HQ location
exercise_name_invalid422Exercise names are 3 to 100 letters, numbers, spaces and simple punctuation
exercise_reference_invalid422An exercise reference isn’t valid
exercise_rename_invalid422Some renames can’t be done, so nothing was changed (details.problems says which and why)
exercise_replaces_builtin422A built-in exercise’s name; send replaceBuiltIn: true to replace its video in this location
exercise_unavailable422An exercise isn’t available here; search for exercises this location can use
exercise_update_invalid422Some updates can’t be done, so nothing was changed (details.problems says which and why)
exercise_upload_type422The filename doesn’t end in a video or image type CloudFit takes
flexi_timing_get_ready422An exercises module with flexi timing has a get-ready; remove it in the app
flexi_timing_governs422Flexi timing decides this module’s timing; switch to simple timing to change it
folder_name_invalid422Folder names are 3 to 60 characters
folder_unknown422A folder the location doesn’t have; list or create folders first (details.folders)
history_range_invalid422since or before isn’t an ISO 8601 date and time, or since isn’t earlier than before
image_invalid422A whiteboard image belongs to another workout
main_track_missing422A workout needs at least one module on track 1, the main track
main_track_untimed422The main track has no module with a timing
media_not_found422The media isn’t in a library this location can use; list media for a valid ID
media_upload_type422The filename doesn’t end in an image type (jpg, jpeg, png, webp) or a video type (mp4, mov, m4v)
module_format_outdated422Open and save the module in the app once before changing it here
module_has_no_exercises422This module type has no exercises
module_id_duplicate422Two modules in the request share an ID
module_not_found422No module with that ID in this workout or request
module_type_mismatch422The settings are for another module type; types can’t change
module_type_unsupported422The API can’t edit modules of this type
operation_conflict422Two edits in the batch conflict (the same module removed and changed, say)
publish_duration_invalid422A published workout’s main track must play 5 to 60 minutes (details.seconds is how long it plays, null when it can’t be timed)
publish_expiry_invalid422expiresAt must be a date and time in the future, within about 5 years
schedule_copy_invalid422Each destination must be a different week, a whole number of weeks away
schedule_nothing_to_copy422Every copied class would be in the past or about to start
schedule_operation_invalid422An update has nothing to change
schedule_range_invalid422The dates are out of order, or further ahead or wider than allowed
schedule_time_invalid422Classes start on five-minute marks, such as 10:00 or 10:05
schedule_too_large422The request covers too many classes; split it by date
schedule_week_empty422The week to copy has no classes
schedule_workout_unavailable422A workout was deleted, or this location can’t use it
setting_not_representable422The module has a setting the API can’t show or change; change it in the app
setting_unsupported422A setting this module type doesn’t take
settings_invalid422The module’s settings with this change aren’t valid; details.issues says why
time_zone_invalid422Not an IANA time zone
time_zone_required422The request has no timeZone and the location’s displays don’t report one; send an IANA time zone
timing_invalid422A timing value isn’t a whole number of seconds in range
timing_override_unsupported422Per-exercise timingsSeconds work only in flow modules
too_many_media422The request names more different media files than one request can use
track_invalid422A track must be 1 to 5
whiteboard_canvas_text422The whiteboard uses the app’s canvas editor; change its text in the app
workout_locked422The workout has a module of a type the API can’t time or edit, so only its details can change
workout_too_complex422The workout is too complex to time; simplify its repeats or timings
workout_too_large422Too many modules, exercises or timings
workout_too_long422A track would play for more than 24 hours
precondition_required428Send If-Match with the revision you read (see Revisions)
schedule_revision_required428This batch can remove or change classes; preview it and send the preview’s revision
rate_limited429Too many requests; retry after Retry-After seconds
internal500Something went wrong on our side
image_copy_failed503Copying the workout’s whiteboard images didn’t finish; retry with the same Idempotency-Key
service_unavailable503CloudFit is briefly unavailable; retry shortly
writes_paused503CloudFit has paused changes through the API, everywhere or for this location (details.scope: all or location); reads still work

Warnings

A successful response can carry warnings, each with a code and a message. Nothing was refused; they point out something worth checking.

CodeMeaning
demo_link_droppedA demos module linked a module that was left out, so that link was removed
demos_without_linked_modulesThe demos module links no modules
display_on_empty_trackDisplays (displays) are set to a track (track) with no modules, so they show nothing during this workout. Add modules to that track, or set the displays to another track
display_without_exercisesIn manual display mode a display has no exercises
exercise_display_ignoredExercises name displays (overrides.display, listed in displays) the module won’t use: displays are used only in manual display mode, and only once every exercise names one
exercise_overrides_unsupportedSome of an exercise’s settings (label, display, timings, …) can’t be shown; send the exercise back with its assignmentId to keep them
exercise_reference_invalidOne of these exercises can’t be read, so the module’s exercises can’t be edited here; change them in the app
exercise_unavailableAn exercise is no longer available here (deleted, or from a library this location can’t use)
exercises_on_missing_displayIn manual display mode, exercises are on displays (displays) that aren’t paired, or are off or on another track for this module, so they show nowhere. Use the location’s display numbers
fewer_exercises_than_displaysFewer exercises than displays showing this module (displays), so some displays have none
manual_display_with_snake_orderingSnake ordering can’t be used with manual display mode; the displays ignore it
module_omittedA module of a type the API doesn’t support was left out of the copy
module_too_longThe module plays for more than 24 hours
module_type_unsupportedA module of a type the API doesn’t cover; it has no timing
module_without_trackA module plays on no track; fix it in the app
more_zones_than_exercisesThe module has more zones than exercises
no_exercises_addedThe module has no exercises
no_workout_selectedThese classes have no workout yet and won’t start until one is chosen
publish_display_exercises_hiddenThese modules put exercises on display 2 or later by hand; those exercises don’t show in the published workout
publish_empty_modulesThese modules have no exercises, so they show only a timer
publish_extra_tracksOnly track 1 plays in the published workout; modules on other tracks are left out
publish_grid_exercises_hiddenThese modules have more than 8 exercises; the published workout’s grid shows only 8
publish_grid_layoutThese modules show exercises in a grid, which doesn’t suit one screen; a flow module shows them one at a time
schedule_timezone_differsMost classes nearby use a different time zone; check the time zone is the location’s
snake_ordering_with_mixed_orientationsSnake ordering can’t run across portrait and landscape displays (displays) in automatic display mode; the app refuses it
times_skippedThese dates and times have passed or are about to start, so they were left alone
timing_not_computedTiming wasn’t computed (reason says why); the rest of the read is complete
too_many_exercises_per_android_displayA Google TV, Chromecast or other Android display shows this module, and a display (displays) would have more than 8 exercises (limit): the app won’t start the workout like this. Keep each display to 8, or split the module
too_many_exercises_per_displayMore than 12 exercises (limit) would be on one display (displays): tiles get too small to follow, and mirror mode shows only the first 12. Use fewer exercises, more displays (manual display mode), or split the module
track_without_displayNo display plays this track (track, where 1 is the main track), so its modules show nowhere. Set displays to it with the workout’s displays (an updateDisplays edit for a saved workout), using the location’s display numbers
uneven_zonesEach zone should have the same number of exercises
video_ends_moduleThe background video is shorter than the module, so the module ends when the video does

Per-item results

Exercise renames and updates report each item on its own: a result’s code (or reason), or one entry of details.problems when a refusal changed nothing.

CodeMeaning
chatgpt_file_hostThe download link isn’t one of ChatGPT’s file links; only files attached in ChatGPT can be added this way
chatgpt_file_invalidThe file isn’t one ChatGPT attached (its file_id is missing or malformed)
chatgpt_file_name_missingChatGPT didn’t send the file’s name; give its exercise a name in exercises
exercise_details_builtinIt replaces a built-in exercise’s video, so it keeps that exercise’s equipment and categories
exercise_details_missingAn update needs equipment, categories or both
exercise_media_not_in_libraryThe exercise’s media belongs to another library, so it can’t be renamed here
exercise_name_duplicateTwo renames in the request give the same name
exercise_name_invalidExercise names are 3 to 100 letters, numbers, spaces and simple punctuation
exercise_name_takenThe library already has an exercise with that name
exercise_name_unchangedThe new name gives the same exercise ID
exercise_needs_mediaThe exercise has no video or image yet; add one before renaming it
exercise_not_foundNo exercise with that ID in this location’s library
exercise_processingIts media is still uploading or processing; try again once it’s ready
exercise_rename_failedThe rename didn’t finish; try it again
exercise_replaces_builtinThat is a built-in exercise’s name; send replaceBuiltIn: true to replace the built-in video in this location
exercise_update_duplicateThe request changes the same exercise more than once
media_not_in_libraryThe exercise’s media belongs to another library
media_unavailableThe exercise’s media can’t be found

Upload failures

The code of an upload whose status is failed (GET …/media/uploads/{uploadId}, GET …/custom-exercises/{exerciseId}/uploads/{uploadId}, an import’s files). The file was not used; upload it again with a new link.

CodeMeaning
chatgpt_file_fetch_failedCloudFit couldn’t fetch the file from ChatGPT; send it again
chatgpt_file_unavailableChatGPT’s download link had expired or was refused; send the file again for a fresh one
exercise_media_failedProcessing the video didn’t work; upload it again with a new link
exercise_upload_failedProcessing didn’t work; upload it again with a new link
exercise_upload_invalidThe file was over the size limit or not the right type, so it was deleted
exercise_upload_limitedToo many videos were processed recently; try again later
exercise_upload_refusedThe account can no longer manage this library, or the exercise is gone
exercise_upload_rejectedCloudFit couldn’t use the file (the message says why, such as a portrait or too-long video)
media_save_failedThe file arrived but couldn’t be saved to the library; upload it again
media_upload_limitedToo many videos were processed recently; try again later
media_upload_refusedThe account can no longer add to this media library
media_video_failedProcessing didn’t work; upload it again with a new link
media_video_invalidThe file was over the size limit or not a video, so it was deleted
media_video_rejectedCloudFit couldn’t use the video (the message says why, such as one too long or of an unknown type)

This page as Markdown