Getting Started

Atlas is a weightlifting coaching product. Its Coach API is a versioned REST API for AI agents, custom GPT actions, automation tools, and direct integrations. Everything a token can do is scoped to one club and to the coach who created it.

What Atlas Exposes

The Coach API publishes 138 operations. Each one is listed in the Coach API Reference, generated from the same OpenAPI document the API serves. With the right permissions a token can:

List the roster, create or adopt stable roster entries, and read, update, or archive athlete profiles by athlete ID.
Create, read, replace, and delete programs, or change one week, day, or exercise at a time, including coach notes and atomic session completion.
Create and organize reusable templates in folders, and assign them to athletes.
Browse and search the Atlas and club exercise libraries, and add or update club exercises.
Read and write personal records, upcoming meets, meet results, meet-day worksheets, annual plans, and weekly coach notes.
Read session check-ins, completed days, session activity, weekly analytics, and performance by time of day.
Fetch live Oura and FatSecret data for athletes who connected them. Atlas does not store those measurements.
Read and send club messages, including photos, voice messages, files, and form-review videos.
Read athletes' workout and exercise comments, mark them read, and reply to them as a direct message.

Call the API directly, script it with the Atlas CLI, or give an AI agent the Agent Skill.

Create A Token

Sign in to the coach console and open Integrations.
Name the token, choose only the permissions the integration needs, and pick a lifetime of 30, 90, or 180 days, or no expiry.
Copy the token. It is shown once; Atlas stores only a SHA-256 hash of it.

A token is bound to the club selected when it is created. Switching clubs in the Atlas app does not retarget it or any script that uses it, so create one token per club. A token stops working as soon as its coach leaves that club, and any token can be revoked from Integrations.

Older tokens created without a club by a coach who is not the platform administrator are rejected and must be replaced. Legacy platform-administrator tokens keep platform access, with the same limits on private health and message data as the platform account.

Base URL

Every path in these docs is relative to the API base URL:

https://graceful-tortoise-95.convex.site/api/v1

The OpenAPI 3.1 document is public and needs no token:

https://graceful-tortoise-95.convex.site/api/v1/openapi.json

An agent that supports OpenAPI actions can import that URL and use the token as an HTTP bearer credential. The stable operationId values tell it which action to call.

Authentication

Send the token on every request except the health check and the OpenAPI document:

Authorization: Bearer YOUR_ATLAS_API_TOKEN

Start with GET /account. It confirms which token is in use, the permissions it carries, and the published rate limit.

curl "https://graceful-tortoise-95.convex.site/api/v1/account" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN"

Permissions

Each endpoint needs one permission, shown beside it in the reference. Messaging permissions are separate from program and roster permissions.

Permission	Integrations Label	Allows	Endpoints
`read`	Read Athletes And Programs	Roster, programs, templates, exercises, check-ins, and meet results.	46
`wearables_read`	Read Health Data	Oura and nutrition logs. Needs `read`.	8
`write`	Create And Edit	Programs, templates, exercises, athletes, meet results, PRs, meet plans, and settings. Also deletes exercises and template folders. Needs `read`.	44
`workout_delete`	Delete Workouts And Weeks	Remove workouts or whole weeks from a program. Needs `write`.	3
`program_delete`	Delete Programs And Templates	Remove whole programs and templates. Needs `write`.	2
`athlete_data_delete`	Delete Athlete Data	Remove an athlete's records. This cannot be undone. Needs `write`.	17
`messaging_read`	Read Messages	Conversations and attachments this token can see.	5
`messaging_write`	Send Messages	Send, edit, react, and mark conversations read. Needs `messaging_read`.	12

The recommended Programming preset can correct a program by removing exercises, days, or weeks, but cannot delete whole programs or templates or erase personal records, meets, or all athlete data. Legacy tokens that carry delete keep every deletion permission. A platform Super Admin token cannot read club messages unless its user also coaches in the token's club.

Errors

Every failure returns the same envelope:

{ "error": { "code": "NOT_FOUND", "message": "Program not found" } }

A 4xx status means the request can be fixed; a 5xx status means it cannot.

Code	Status	Meaning
`VALIDATION_ERROR`	400, or 422 with issues	The request or program body is invalid. A program or template body returns 422 with the offending path in issues.
`UNAUTHENTICATED`	401	The token is missing, unknown, expired, or revoked.
`FORBIDDEN`	403	The token lacks the permission, or the coach cannot reach that athlete or library entry.
`NOT_FOUND`	404	The resource does not exist or is not visible to this token.
`CONFLICT`	409	The write conflicts with stored data, such as a completed session or a duplicate program.
`PRECONDITION_FAILED`	412	The If-Match revision is stale. Read the resource again and merge.
`PAYLOAD_TOO_LARGE`	413	The request body is over the 1 MB limit.
`PRECONDITION_REQUIRED`	428	The write needs an If-Match revision.
`RATE_LIMITED`	429	The token passed its per-minute limit. Wait for Retry-After seconds.
`RESULT_SET_TOO_LARGE`	400	The query would return too much data. Narrow the date range or filters.
`UPSTREAM_ERROR`	502	Oura or FatSecret failed to answer.
`INTERNAL_ERROR`	500	A failure on the Atlas side. The message is always "Internal server error"; the cause is logged on the deployment.

Rate Limits

Each token may make 120 requests per minute. A 429 response carries Retry-After in seconds. Rate accounting is sharded, so responses do not report an exact remaining count and there is no X-RateLimit-Remaining header.

Pagination

List endpoints that take a cursor return a page with continueCursor and isDone. Pass continueCursor back as cursor until isDone is true.

GET /roster?limit=100 is the authoritative, complete roster. GET /athletes is a compatibility view that also surfaces legacy name-only records.
Program and template pages hold at most 10 items, because each item carries its complete nested workout.

Idempotency

These operations accept an Idempotency-Key header of up to 128 characters. A retry with the same key returns the original result instead of creating a duplicate, so send a stable key whenever a request might be repeated.

POST /messages/conversations/{conversationId} (required)
PATCH /messages/scheduled/{messageId} (optional)
POST /comments/{commentKey}/replies (required)
POST /programs (optional)
POST /templates/{templateId}/assign (optional)

curl -X POST "https://graceful-tortoise-95.convex.site/api/v1/programs" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-09-01-alex" \
  -d @program.json

Revisions And If-Match

Programs use optimistic concurrency. Creating a program returns revision: 1 and an ETag. Every later program, week, day, or exercise write must send that revision in If-Match, and a successful write returns the next revision.

A stale revision returns 412: read the program again, merge, and retry instead of overwriting a coach's changes.
A write without If-Match returns 428.
Each nested write reads the latest stored program and changes only the requested day or exercise inside one transaction.

curl -X PATCH \
  "https://graceful-tortoise-95.convex.site/api/v1/programs/<program-id>/weeks/1/days/2" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2" \
  -d '{"coachNotes":"Stay patient off the floor"}'

Quick Start

These examples use YOUR_ATLAS_API_TOKEN in place of a token. Replace it with your own, ideally from an environment variable so it stays out of shell history.

curl "https://graceful-tortoise-95.convex.site/api/v1/roster?limit=100" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN"

curl "https://graceful-tortoise-95.convex.site/api/v1/exercises?search=snatch&limit=20" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN"

curl -X POST "https://graceful-tortoise-95.convex.site/api/v1/athletes" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex Smith"}'

curl -X POST "https://graceful-tortoise-95.convex.site/api/v1/programs/validate" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"athleteName":"Alex","programName":"Prep","startDate":"2026-09-01","weeks":[{"days":[{"exercises":[{"exerciseName":"Snatch","reps":"3"}]}]}]}'

curl -X PATCH \
  "https://graceful-tortoise-95.convex.site/api/v1/programs/<program-id>/weeks/1/days/2/exercises/3" \
  -H "Authorization: Bearer YOUR_ATLAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 1" \
  -d '{"reps":["3","2","1"],"setWeights":[80,85,90],"exerciseNotes":"Fast turnover"}'

Create or adopt a roster entry before writing a new program, and use the athleteId it returns rather than an editable name. The Coach API Reference covers program bodies, prescriptions, intensity, and every other endpoint.