Build on Meso

Meso is a periodized strength-training program that designs and rebuilds block-periodized programs from a user's goals, equipment, injury history, and recovery. This page is the entry point for developers and AI agents: the API description, the MCP server, authentication, and a sandbox.

The Meso web app is available now. This HTTP API and its OAuth server are still being built; the machine-readable descriptions below are published now and are the authoritative source for the surface. Public read-only operations (pricing, methodology) need no authentication; member-scoped operations use an OAuth 2.1 bearer token.

Machine-readable descriptions

Authentication

Meso uses OAuth 2.1 (authorization code + PKCE) with dynamic client registration, and supports the emerging agent-auth discovery flow. Start at the auth walkthrough and follow the links to the authorization-server and protected-resource metadata:

• /auth.md — agent authentication walkthrough (start here)
• /.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata
• /.well-known/oauth-authorization-server — RFC 8414 authorization-server metadata

Scopes: program:read, program:write, logs:write, profile:read. On a missing or invalid token, protected endpoints return 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource".

Quickstart

Read pricing — a public endpoint, no auth:

curl https://api.meso.fitness/v1/pricing

Read the authenticated member's current program:

curl https://api.meso.fitness/v1/program \
  -H "Authorization: Bearer $MESO_TOKEN"

Log a set:

curl -X POST https://api.meso.fitness/v1/sets \
  -H "Authorization: Bearer $MESO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"exerciseId":"ex_squat","weight":100,"reps":5,"rpe":8}'

Sandbox & self-serve access

A sandbox host — https://sandbox.api.meso.fitness — mirrors the API against seeded test data so agents can exercise every operation without touching a real member's program. There is no "contact sales" gate: three free program generations (no time limit) and self-serve OAuth client registration via the registration_endpoint in the authorization-server metadata mean an agent can onboard end to end on its own.

Errors

All errors are JSON with a stable machine-readable error.code plus a message and a resolution hint:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid bearer token.",
    "hint": "Obtain a token via the OAuth flow described at /auth.md.",
    "docs": "https://meso.fitness/auth.md"
  }
}

Endpoints

Conventions for agents

• Idempotency: send an Idempotency-Key header (a UUID) on any POST/PUT — retrying with the same key returns the original result instead of acting twice.
• Pagination: list endpoints are cursor-based — pass the next_cursor from a response as cursor; limit is 1–100 (default 20).
• Long-running work: regenerateProgram returns 202 Accepted with a job; poll getJob until status is succeeded/failed.
• Bulk: batchLogSets accepts an array of set-log operations in one request.
• Rate limits: every response carries RateLimit-Limit/-Remaining/-Reset; a 429 includes Retry-After. Self-throttle accordingly.
• Errors: always JSON with a stable error.code, a message, and a hint (see above).

Versioning & deprecation

The API is versioned in the URL path (/v1/…); breaking changes ship under a new version (/v2). When an operation or version is deprecated, responses carry Deprecation: true and a Sunset: <date> header (RFC 8594) with the earliest removal date, announced here at least 6 months in advance. Non-breaking additions can happen within a version without notice.

Scoped context for agents

Fetch just the slice you need instead of the whole manual:

• /llms.txt — site-wide index and when-to-use guidance
• /api/llms.txt — API & integration context
• /developers/llms.txt — developer-portal context
• /docs/llms.txt — product documentation context
• /llms-full.txt — full context in one file