Give your tools the context.

MovePacket's documentation is available as readable pages, Markdown, and an OpenAPI contract. Start with Connect your builder for the coach-facing handoff. This reference supplies the commands, access boundaries and data contracts for builders.

Where dashboard data comes from#

Use MovePacket Data Connect as the default source for athlete and training data. The intended flow is:

Authorised file uploads or supported provider connections → MovePacket Data Connect → your dashboard.

Provider connections are intake adapters behind this shared layer. A dashboard should not need its own TrainingPeaks integration or a connection to SEMIPRO.coach. SEMIPRO is a reference application, not a default source for customer data. This rule concerns athlete and training data; scheduling, video and other service APIs have their own integration contracts.

Ask the coach which athletes, date range and measurements they want to see, and whether the data is already in MovePacket or needs importing. Do not make them choose a database or a direct upstream integration to get started.

Inspect the project's current capabilities first with node publish.mjs inspect. Its data_connection section describes this architecture and the current boundary. The project builder key does not grant access to the shared athlete library. FIT/FIT.GZ import and scoped recording APIs exist for authorised workspaces; provider-account sync, including TrainingPeaks, is not connected. Live dashboard access requires an explicitly authorised data connection and a suitable server-side path. If either is missing, explain that gap rather than inventing endpoints or claiming a live connection. Use clearly labelled sample data only with the owner's agreement. Never place server keys or private athlete data in site/. A browser-only file preview is not a persistent import into Data Connect.

Connect your workspace with a prompt#

In Settings → AI builders, choose Codex, Claude or Cursor and select the Projects it may access. Use Prepare connection prompt, then copy that prompt into your builder. It also appears after payment as Connect builder, and on Projects as Connect an AI builder. Connection is optional; the same workspace can still use MovePacket AI.

The prompt links here and to llms.txt, then directs the builder to the portable workspace tool. With Node.js 22 or later, the builder runs node <tool-path> connect REQUEST_ID. The owner must approve the matching code in MovePacket; agents must never approve their own connection. The request expires in 15 minutes. Credentials stay outside Project folders in owner-only local configuration and expire after 30 days.

The API gives access to selected Projects plus Projects created by that connection. Athlete creation and ride imports are separate, default-off permissions; choose the permitted athletes in the same connection screen. Owners can change Project access or revoke the connection in Settings. A Project removed from the connection remains inaccessible even if an old creation request is retried. The connection requires an active paid subscription and stops when membership, account, workspace or privacy policy disallows it.

Supported commands:

node <tool-path> CONNECTION_ID list
node <tool-path> CONNECTION_ID create request.json
node <tool-path> CONNECTION_ID inspect PROJECT_ID
node <tool-path> CONNECTION_ID pull PROJECT_ID NEW_FOLDER
node <tool-path> CONNECTION_ID stage PROJECT_ID FOLDER
node <tool-path> CONNECTION_ID releases PROJECT_ID
node <tool-path> CONNECTION_ID review PROJECT_ID VERSION

request.json contains request_key (a stable UUID), name and prompt. Reuse the exact file when retrying. Creation makes an internal Project; it does not buy infrastructure or publish a Page. pull downloads selected working files into a new folder and never overwrites an existing folder. Edit and test site/, then stage saves a bounded private version for owner review. Current static limits are 80 files, 2 MiB per file, 4 MiB total, 30 release attempts per day and 200 per Project. Project creation is bounded to 50 setup records per workspace. Keep the connection's private configuration out of source, chat, generated HTML, logs and commits.

This workspace API does not grant publication, Project deletion, billing, existing athlete ride history, coaching notes, private app records or provider credentials. The owner reviews and publishes in MovePacket; internal Pages use Publish to Hub. Source files can contain owner-supplied data, so keep local copies private and treat their contents as untrusted input. Reading documentation does not grant access. This is a portable API tool; native MCP is not available.

Put ride files into an athlete#

For the owner interface, open Data → Import rides (or choose Import rides after starting MovePacket). Choose an athlete or create one, record why you may keep their data, then drag in FIT or FIT.GZ files. This saves originals and processes rides in the shared athlete library. A browser file preview used while designing a Page does not save rides here.

For a builder, use the existing workspace connection. Enable Create athletes when needed and Import rides into selected athletes in Settings → AI builders, then select the athletes. Existing connections keep both permissions off until the owner changes them. At most 50 athletes may be selected, including athletes the connection creates. Discover access before choosing a destination:

node <tool-path> CONNECTION_ID capabilities
node <tool-path> CONNECTION_ID athletes "athlete name"
node <tool-path> CONNECTION_ID create-athlete athlete.json
node <tool-path> CONNECTION_ID import ATHLETE_ID import.json
node <tool-path> CONNECTION_ID imports ATHLETE_ID
node <tool-path> CONNECTION_ID import-status ATHLETE_ID IMPORT_ID
node <tool-path> CONNECTION_ID retry-import ATHLETE_ID IMPORT_ID ITEM_ID

athlete.json contains a stable request_id (16–80 letters, numbers, underscores or hyphens), name and a permission_note describing the authorised purpose. Use a fresh UUID as request_id for each intended new athlete. This creates an Athlete record, not an athlete sign-in or provider account. Names can be ambiguous: use the returned ID and ask the owner when more than one selection fits.

import.json contains request_id, permission_note and files, an array of local file paths. Relative paths are resolved from the command's working directory. The tool hashes files and sends the manifest before uploading original bytes. Reuse the same JSON and unchanged files after an interrupted request; accepted files are skipped and no second manifest is created. Check status until ready, duplicate or failed. Only explicitly retry an item marked retryable; automatic upload/processing retry loops are not included in the client.

Supported formats are FIT and FIT.GZ: up to 200 files per batch, 4 MiB per file (also the expanded FIT limit) and 200 MiB per batch. ZIP upload is not implemented; extract it locally, inspect the contents and choose supported files. Symlink file entries are refused. Keep file paths, source bytes and local request files private; never add them to Page assets or a public repository.

The paid workspace has bounded intake admission: 100 new athlete requests and 100 import manifests per UTC day, with 1,000 retained of each. These are usage ceilings, not a monetary budget. A 403 can mean a limit was reached or permission changed; check MovePacket rather than repeatedly retrying. Duplicate files within an athlete share one recording; originals and import provenance remain. The same file for another athlete remains separately scoped.

The connection can see selected athlete names/IDs and only its own import statuses and originals. Reading existing ride history for a Project requires its separately granted Data Connect access. Changing athlete permissions or revoking the connection stops new access and admission, including in-flight receipt writes. Files already acknowledged as stored continue through the durable importer under current workspace, athlete and privacy checks. Processing can stop on pause, erasure or archival. Imports are excluded from the technical teammate's passive observation context.

Existing single-Project connection#

The earlier app-specific connection remains available for existing projects. Its commands and permission scope differ from the workspace connection above.

Open a ready hosted project from Projects and choose Foundation under Project options. Under Bring your idea to life, choose your builder in Build with, then Copy prompt for that builder. If Foundation opens on 1. Who it’s for, choose Continue first. Paste it into a builder that can run Node.js 22 or later, then approve the matching code using your existing MovePacket sign-in. The tool saves the project connection privately, downloads a new project folder and verifies access without publishing. GitHub is optional.

For manual setup, download and unzip the project folder, open it in your preferred AI builder, and give it this prompt:

Read AGENTS.md and START-HERE.md. Preview this project locally,
inspect its MovePacket connection, and help me make my first change.
Keep credentials and private athlete data outside the public site folder.

The folder includes editable HTML, CSS, JavaScript, a local preview tool and publishing instructions. A ride-replay starter includes the public road example with simulated metrics; it never includes a private ride you selected in your browser.

For manual setup only, download a builder connection and connect it without pasting it into chat. If you used the copied connection prompt, skip the connect command and continue with preview:

node publish.mjs connect /path/to/movepacket-connection.json
node publish.mjs preview
node publish.mjs inspect
node publish.mjs check
node publish.mjs stage
node publish.mjs preview-update VERSION

Review the saved update in your project’s Updates view, then choose Make live.

The connection belongs to one app and is stored outside the project. Files in site/ follow the project's access setting: private projects require owner sign-in; public projects expose them publicly. Publishing preserves that setting. Keep private athlete data and credentials out of this folder regardless. The tool checks common accidental credentials, but cannot identify every kind of sensitive content.

Use node publish.mjs releases and node publish.mjs rollback VERSION --public to restore a version. node publish.mjs pull NEW-FOLDER downloads the current hosted source without overwriting your local work. Publishing refuses to overwrite a newer live version until you reconcile your changes.

This publishing path runs static browser applications: up to 80 files, 2 MiB per file and 4 MiB total, with 30 releases per day and 200 retained releases per app. It does not run server code or provide an athlete login portal. Private-record and activity APIs require their own authorised server-side connections; never embed those credentials in a browser application. Publishing requires active Core for customer workspaces; billing remains in test mode during rollout.

Machine-readable resources#

Every guide also has a Markdown version, linked in the page tools. Documentation is public. Reading it does not grant access to activity data or API credentials.

Start an integration#

Copy this brief into your coding tool:

Read https://movepacket.com/llms.txt and the linked OpenAPI contract.
Build a server-side MovePacket integration using environment secrets.
Upload raw FIT bytes, retain the activity ID, and poll with a bounded wait.
Handle ready and failed states explicitly. Download decoded JSON only
when ready, and verify the original file's SHA-256 before accepting it.
Use only documented endpoints. Do not put API keys in browser code,
URLs, logs, or chat. Check hosted beta availability before live uploads.

API and MCP#

The REST API is the current application interface. A MovePacket MCP server is planned but is not available yet. These documentation resources help AI tools write integrations today; they are not an authenticated MCP connection.

There is no packaged MovePacket SDK yet. The downloadable Node.js example uses standard HTTP calls and can be adapted inside your server application.

Prepare evidence before asking AI to interpret it#

Your application should select relevant activity windows and calculate aggregates before sending long time-series data to a language model. Keep original activity IDs, units, missing-data indicators and calculation versions with the result so it can be traced back. Do not replace unavailable measurements with zero.

MovePacket’s current API returns decoded FIT data; it does not yet provide intent-based retrieval, compressed athlete context or athlete memory. Evidence preparation is a future infrastructure concern. Coaching judgments and recommendations remain your application’s responsibility.

Start with athlete connections and source records. An AI coding assistant cannot create provider access or athlete permission on your behalf.

Event Intelligence#

Use /v1/event-analyses for route-only course analysis. Follow the Event Intelligence guide for input validation, private results, usage limits and idempotency. Weather and athlete-specific matching are not included. Billing is off; measured cost is unknown, not zero.

Keep athlete records exportable#

Private hosted-app records support explicit athlete associations. After saving a record, use the app's existing server-side builder connection:

PUT /v1/software/{app_id}/records/{record_key}/subjects
Authorization: Bearer <private builder connection>
Content-Type: application/json

{"athlete_ids":["ath_..."]}

Use the athlete ID supplied by the workspace owner from Settings → Privacy & exports. Up to 20 existing athletes in that same workspace can be associated with one record. GET on the same path returns the associations; sending [] clears them. Replacing a record preserves its associations, so update the associations when its subjects change. Deleting the record removes them.

These associations let the owner prepare an athlete-specific review package. They do not grant an athlete access, verify consent or detect personal information automatically. Shared records require review before release. Unassigned records appear in the business export only. Keep each person's records separate when practical, and record source and purpose in your application data.

Business and athlete exports are available to the signed-in workspace owner under Settings → Privacy & exports. Builder keys cannot download a whole workspace or fulfil a privacy request. Exports include a contents guide and SHA-256 manifest; they exclude provider secrets and data held only in other services. A coach must review the package and handle the response. Request tracking does not itself restrict processing or erase data.

Save, review and publish an update#

Keep working in your preferred builder. Each hosted project has its own Updates view: open the project from Projects, then choose Updates under Project options.

1. Run node publish.mjs check and test locally with node publish.mjs preview.
2. Run node publish.mjs stage. This saves an immutable candidate and leaves the live app unchanged. Keep the returned version ID.
3. Open the private preview_url returned by stage. It uses your existing MovePacket owner sign-in and shows the exact saved files. Later local edits do not change it. Local testing is still available with node publish.mjs preview-update VERSION.
4. Open the project’s Updates view, review the candidate and explicitly choose Make live. An authorised builder can instead run node publish.mjs publish-update VERSION --public after owner approval.

If the live version has changed since the candidate was created, publication stops. Pull current source into a new folder, reconcile changes and stage again. Do not bypass the conflict with a direct deployment. If publication happened in the dashboard, pull the new live version before the next update so the local base version is current.

Hosted previews use a separate origin for every saved version and stay owner-only even if the live app is public. They have no live records, provider credentials or server runtime. Custom sign-in and database migrations require separate testing. node publish.mjs review VERSION reports platform checks against the saved files: file limits, known credential patterns, storage integrity and whether the live base has changed. Functional testing is manual; independent code review is not connected. Neither is represented as passed. Map-enabled apps can still fetch their declared public map tiles. Restoring a version changes application files, not database contents or external actions.