---
title: "Developers & agents — Meso"
description: "Meso developer portal: OpenAPI spec, MCP server, agent authentication, sandbox, and quickstart."
canonical: "https://meso.fitness/developers.html"
last-updated: "2026-09-10"
---

# 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 is the entry point for developers and AI agents.

**API status: in development — not yet publicly available.** 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 authoritative. Public read-only operations (pricing, methodology) need no auth; member-scoped operations use an OAuth 2.1 bearer token.

## Machine-readable descriptions

- OpenAPI 3.1: https://meso.fitness/openapi.json
- MCP server (live): https://meso.fitness/mcp (docs: https://meso.fitness/docs/mcp) — card: https://meso.fitness/.well-known/mcp/server-card.json
- MCP registry (Smithery): https://smithery.ai/servers/davicd/meso-fitness
- A2A agent card: https://meso.fitness/.well-known/agent-card.json
- Agent skills index (v0.2.0): https://meso.fitness/.well-known/agent-skills/index.json
- Resource discovery (ARD): https://meso.fitness/.well-known/ard.json
- API catalog (RFC 9727): https://meso.fitness/.well-known/api-catalog

## Authentication

OAuth 2.1 (authorization code + PKCE) with dynamic client registration. Start at the walkthrough and follow the links:

- Walkthrough: https://meso.fitness/auth.md
- Protected-resource metadata (RFC 9728): https://meso.fitness/.well-known/oauth-protected-resource
- Authorization-server metadata (RFC 8414): https://meso.fitness/.well-known/oauth-authorization-server

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

## Quickstart

```
# Public — no auth
curl https://api.meso.fitness/v1/pricing

# Authenticated
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

`https://sandbox.api.meso.fitness` mirrors the API against seeded test data — no real member data. No "contact sales" gate: three free program generations (no time limit) and self-serve OAuth client registration via the `registration_endpoint` mean an agent can onboard end to end on its own.

## Errors

All errors are JSON with a stable `error.code`, a message, and a resolution hint:

```json
{ "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

| Operation | Method & path | Auth |
| --- | --- | --- |
| `getPricing` | GET /v1/pricing | none |
| `getMethodology` | GET /v1/methodology | none |
| `getProgram` | GET /v1/program | program:read |
| `regenerateProgram` | POST /v1/program/regenerate → 202 + job | program:write |
| `getJob` | GET /v1/jobs/{jobId} | program:read |
| `swapExercise` | POST /v1/exercises/swap | program:write |
| `setEquipmentMode` | PUT /v1/equipment-mode | program:write |
| `listSets` | GET /v1/sets (cursor paginated) | program:read |
| `logSet` | POST /v1/sets | logs:write |
| `batchLogSets` | POST /v1/sets/batch | logs:write |

## 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 `next_cursor` back 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`.
- **Errors:** always JSON with a stable `error.code`, a message, and a hint.

## Versioning & deprecation

The API is versioned in the URL path (`/v1/…`); breaking changes ship under a new version (`/v2`). Deprecated operations/versions carry `Deprecation: true` and a `Sunset: <date>` header (RFC 8594) with the earliest removal date, announced at https://meso.fitness/developers.html at least 6 months ahead. Non-breaking additions can happen within a version without notice.

## Scoped context for agents

- Site-wide index: https://meso.fitness/llms.txt
- API context: https://meso.fitness/api/llms.txt
- Developer-portal context: https://meso.fitness/developers/llms.txt
- Product docs context: https://meso.fitness/docs/llms.txt
- Full context: https://meso.fitness/llms-full.txt