OneRep API: REST and Model Context Protocol Overview

OneRep exposes your entire training and nutrition log through a REST API and a Model Context Protocol (MCP) endpoint. You can use either surface to read your history, post new entries, or connect an AI assistant — all with the same API key, the same scopes, and the same rate limits.

Base URL

Your deployment has a unique base URL printed under Settings → API & MCP in the app. Copy it from there rather than assembling it by hand.

https://<your-convex-deployment>.convex.site/v1

All REST routes are relative to that base URL. The MCP endpoint lives at the same host under /mcp.

Format

Every request and response uses JSON. Send Content-Type: application/json on any request that carries a body; responses always return Content-Type: application/json. Nothing else is parsed.

Two surfaces, one credential

Authentication

Create API keys, understand scopes, and learn the authorization header format.

Read Endpoints

Retrieve days, workouts, measurements, goals, and computed insights.

Write Endpoints

Log food, water, weight, workouts, and rest days programmatically.

MCP Endpoint

Connect AI assistants using the Model Context Protocol — same keys, same data.

Rate limits

Rate limits are per key, not per account, so a runaway script cannot lock you out of your own app.

Scope	Limit
Reads	600 per hour
Writes	60 per hour

Limits run in a fixed window. When you exceed a limit the API responds with 429 and a Retry-After header telling you how many seconds to wait before retrying. Retry on 429 and 5xx responses; do not retry on 4xx errors.

Verifying your key

To confirm a key is valid without touching any logged data, call GET /v1/me:

curl -s https://<deployment>.convex.site/v1/me \
  -H "Authorization: Bearer onerep_sk_…" | jq

A healthy response echoes the key’s scopes and its remaining hourly budget:

{
  "scopes": ["read"],
  "limits": {
    "readPerHour": 600,
    "writePerHour": 60
  }
}

GET /v1 returns the full route list filtered to only the routes your key is allowed to call — useful when you are writing a new integration and want a quick reference without leaving your terminal.

Error shape

Every error, regardless of status code, uses the same JSON structure:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key has read access, and POST /v1/water needs write."
  }
}

Branch your error handling on code; the human-readable message may be reworded between releases. The API never returns a stack trace.

​Base URL

​Format

​Two surfaces, one credential