OneRep REST API: Read Endpoints Reference

The read endpoints let you pull everything OneRep has logged (nutrition totals, workout sessions, body measurements, goals, and computed insights) using any key that carries the read scope. Every response is JSON and every date parameter follows the YYYY-MM-DD format.

Dates default to today in UTC. If you know the user’s timezone, always pass an explicit date when calling near midnight. Otherwise you may silently query the wrong calendar day.

Use GET /v1/days?start=&end= for weekly questions. One request covers the entire range and costs a single unit of your hourly budget, instead of seven separate calls.

GET /v1: Route list

Returns the full list of routes available to your key, filtered by its scopes. This is the fastest way to confirm which endpoints your key can actually reach without consulting this page. Example request

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

Example response

[
  { "method": "GET",  "path": "/v1" },
  { "method": "GET",  "path": "/v1/me" },
  { "method": "GET",  "path": "/v1/goals" },
  { "method": "GET",  "path": "/v1/insights" },
  { "method": "GET",  "path": "/v1/days/{date}" },
  { "method": "GET",  "path": "/v1/days" },
  { "method": "GET",  "path": "/v1/workouts" },
  { "method": "GET",  "path": "/v1/measurements" },
  { "method": "GET",  "path": "/v1/health/days" },
  { "method": "GET",  "path": "/v1/health/workouts" },
  { "method": "GET",  "path": "/v1/health/metrics" },
  { "method": "GET",  "path": "/v1/custom-metrics" }
]

GET /v1/me: Key scopes and budget

Returns the scopes attached to the current key and its hourly rate-limit budget. Use this to verify a key is alive and to check what it is allowed to do before making other calls. Example request

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

Example response

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

string[]

The permission scopes granted to this key. Values are "read" and/or "write".

number

Maximum read requests allowed per fixed hour window for this key.

number

Maximum write requests allowed per fixed hour window for this key.

GET /v1/goals: Calorie and macro targets

Returns your configured nutrition targets, daily water goal, preferred weight unit, and stated training goal. These values are set inside the app and are read-only through the API. Example request

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

Example response

{
  "calories": 2400,
  "protein": 180,
  "carbs": 240,
  "fat": 80,
  "waterMl": 3000,
  "weightUnit": "kg",
  "goal": "build_muscle"
}

number

Daily calorie target in kcal.

number

Daily protein target in grams.

number

Daily carbohydrate target in grams.

number

Daily fat target in grams.

number

Daily water target in millilitres.

string

Preferred unit for displaying body weight ("kg" or "lbs").

string

Your stated training goal as set in the app (for example "build_muscle" or "lose_weight").

GET /v1/insights: Progression verdicts and monthly summaries

Returns computed analysis across your log history: per-lift progression verdicts, recovery status compared to your baseline, and up to six monthly summaries. You can anchor all analysis windows to a specific date with the optional ?date= query parameter.

Query parameters

string

YYYY-MM-DD date to anchor the analysis windows. Defaults to today in UTC.

Example request

curl -s "https://<deployment>.convex.site/v1/insights?date=2026-04-15" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

{
  "progression": [
    { "exercise": "Squat", "verdict": "progressing", "trend": "+5 kg over 4 weeks" }
  ],
  "recovery": {
    "status": "recovered",
    "vsBaseline": "+2 days since last rest day"
  },
  "monthlySummaries": [
    {
      "month": "2026-03",
      "totalWorkouts": 14,
      "avgCalories": 2350,
      "avgWeightKg": 84.2
    }
  ]
}

object[]

Array of per-lift progression verdicts. Each entry contains the exercise name, a verdict string, and a human-readable trend description.

object

Your current recovery status compared to your personal baseline, including days since your last rest day.

object[]

Up to six months of historical summaries, each containing workout count, average daily calories, and average body weight.

GET /v1/days/: Everything logged on one date

Returns the complete nutrition log, water intake, workout sessions, and body measurements recorded on a single calendar day. The {date} path parameter must be in YYYY-MM-DD format and defaults to today in UTC when omitted.

Path parameters

string

The calendar date to retrieve in YYYY-MM-DD format. Defaults to today in UTC.

Example request

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

Example response

{
  "date": "2026-04-15",
  "nutrition": {
    "calories": 2100,
    "protein": 155,
    "carbs": 210,
    "fat": 72,
    "entries": [
      { "name": "Oats", "calories": 350, "meal": "breakfast" }
    ]
  },
  "waterMl": 2500,
  "workouts": [
    {
      "id": "w_abc123",
      "durationMinutes": 55,
      "exercises": [
        { "name": "Squat", "sets": [{ "reps": 5, "weightKg": 100 }] }
      ]
    }
  ],
  "measurements": {
    "weightKg": 84.5
  }
}

string

The calendar date this record covers, in YYYY-MM-DD format.

object

Aggregated macro totals for the day plus the individual food log entries.

number

Total water logged for the day in millilitres.

object[]

Workout sessions logged on this date, including exercises and sets.

object

Body measurements recorded on this date, including weightKg if a weigh-in was logged.

GET /v1/days: Per-day totals over a date range

Returns daily nutrition, water, and measurement totals for every calendar day between ?start= and ?end= (inclusive). Both parameters are required. This is more efficient than calling GET /v1/days/{date} repeatedly: the entire range counts as one budget unit.

Query parameters

string

required

Start date in YYYY-MM-DD format. Inclusive.

string

required

End date in YYYY-MM-DD format. Inclusive.

Example request

curl -s "https://<deployment>.convex.site/v1/days?start=2026-04-09&end=2026-04-15" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

[
  {
    "date": "2026-04-09",
    "calories": 2200,
    "protein": 160,
    "carbs": 220,
    "fat": 75,
    "waterMl": 3000,
    "weightKg": 84.8
  },
  {
    "date": "2026-04-10",
    "calories": 1950,
    "protein": 140,
    "carbs": 190,
    "fat": 68,
    "waterMl": 2800,
    "weightKg": null
  }
]

string

The calendar date for this summary row in YYYY-MM-DD format.

number

Total calories logged on this date.

number

Total protein logged on this date in grams.

number

Total carbohydrates logged on this date in grams.

number

Total fat logged on this date in grams.

number

Total water logged on this date in millilitres.

number | null

Body weight recorded on this date in kilograms, or null if no weigh-in was logged.

GET /v1/workouts: Recent workout sessions

Returns your most recent workout sessions, sorted newest first. Use the optional ?limit= parameter to control how many sessions are returned, up to a maximum of 50.

Query parameters

number

Maximum number of sessions to return. Accepts values from 1 to 50. Defaults to the server’s built-in default when omitted.

Example request

curl -s "https://<deployment>.convex.site/v1/workouts?limit=5" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

[
  {
    "id": "w_abc123",
    "date": "2026-04-15",
    "durationMinutes": 55,
    "exercises": [
      {
        "name": "Squat",
        "sets": [
          { "reps": 5, "weightKg": 100 },
          { "reps": 5, "weightKg": 105 }
        ]
      },
      {
        "name": "Bench Press",
        "sets": [
          { "reps": 8, "weightKg": 80 }
        ]
      }
    ]
  }
]

string

Unique identifier for the workout session.

string

Calendar date the session was logged on, in YYYY-MM-DD format.

number

Session duration in minutes, if recorded.

object[]

Array of exercises performed, each containing a name and an array of sets with reps and optional weightKg.

GET /v1/measurements: Recent weigh-ins and measurements

Returns your most recent body measurements and weigh-ins, sorted newest first. Use the optional ?limit= parameter to control how many records are returned, up to a maximum of 100.

Query parameters

number

Maximum number of measurement records to return. Accepts values from 1 to 100. Defaults to the server’s built-in default when omitted.

Example request

curl -s "https://<deployment>.convex.site/v1/measurements?limit=10" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

[
  {
    "id": "kx7…",
    "date": "2026-04-15",
    "source": "health",
    "weightKg": 84.5,
    "bodyFatPct": 18.4,
    "waistCm": null,
    "hipsCm": null,
    "chestCm": null,
    "armsCm": null,
    "thighsCm": null,
    "calvesCm": null,
    "neckCm": null,
    "leanBodyMassKg": 68.7,
    "boneMassKg": null,
    "basalMetabolicRateKcal": 1780,
    "notes": null
  }
]

Every field a check-in can hold is returned, not just the ones the charts plot. A field with no value comes back as null rather than being omitted, so a client can tell the difference between “nothing recorded” and “not supported”.

string

Identifier for this check-in. Pass it to DELETE /v1/measurements/{id} to remove the row.

string

The date the measurement was recorded, in YYYY-MM-DD format.

string

Where the row came from. "manual" for a check-in typed in the app or written through the API, "health" for one read from Apple Health or Health Connect.

number

Body weight recorded on this date in kilograms.

number

Body fat percentage recorded on this date.

number

Lean body mass in kilograms, typically from a smart scale.

number

Bone mass in kilograms. Android only; Apple Health has no bone mass type.

number

Basal metabolic rate in kcal per day.

number

Circumference measurements in centimetres.

string

The journal note attached to this check-in, if any.

GET /v1/health/days: Synced daily health readings

Returns the sleep, steps, resting heart rate, HRV, and active energy stored for each day between start and end (both required, both inclusive), as synced from Apple Health or Health Connect. Example request

curl -s "https://<deployment>.convex.site/v1/health/days?start=2026-04-08&end=2026-04-15" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

{
  "start": "2026-04-08",
  "end": "2026-04-15",
  "days": [
    {
      "date": "2026-04-15",
      "provider": "apple_health",
      "sleepMinutes": 420,
      "steps": 9184,
      "restingHeartRateBpm": 52,
      "hrvMs": 61,
      "activeEnergyKcal": 640,
      "manualFields": ["sleepMinutes"]
    }
  ]
}

string

Where the day came from: "apple_health", "health_connect", or "manual" for a day that only ever held a typed correction.

string[]

Fields on this day the user corrected by hand. Those values are pinned: the phone no longer overwrites them, and POST /v1/health/days/{date} with value: null is what releases one.

HRV is SDNN on Apple Health and RMSSD on Health Connect. The two are different statistics. Compare a person against their own baseline and never against a figure from the other platform.

GET /v1/custom-metrics: The user’s own tracked metrics

Returns the metrics the user defined for themselves, the ones the app has no built-in screen for, each with its definition and its recent daily values.

Query parameters

string

Only metrics on this tab. One of body, nutrition, or training.

number

How many recent values to return per metric. Accepts 7 to 90, defaulting to 30.

Example request

curl -s "https://<deployment>.convex.site/v1/custom-metrics?tab=body&days=14" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

[
  {
    "id": "m_9f2…",
    "title": "Blood glucose",
    "description": "Morning finger-prick",
    "tab": "body",
    "kind": "number",
    "unit": "mmol/L",
    "step": 0.1,
    "target": null,
    "accent": "progress",
    "healthMetricKey": "bloodGlucoseMmolL",
    "healthMetricLabel": "Blood glucose",
    "entries": [
      { "date": "2026-04-15", "value": 5.4, "source": "synced" },
      { "date": "2026-04-14", "value": 6.1, "source": "manual" }
    ]
  }
]

string

Identifier for the metric. Every other custom-metric route takes it in the path.

string

How the app draws it: counter for whole things tallied through the day, number for a figure typed once, toggle for did-it-or-not.

string | null

The catalogue signal this metric is bound to, or null when the user types it in. A bound metric is filed onto the Health dial matching its catalogue group; an unbound one files by its tab.

string

"manual" for a value someone typed, "synced" for one the health sync wrote.

GET /v1/health/metrics: The bindable catalogue

Returns the Apple Health and Health Connect signals a custom metric can be bound to, with each one’s key, label, unit, aggregation, HealthKit identifier, Health Connect record, plausible range, and a gap note where one platform cannot supply it. Read this before creating a metric with a healthMetricKey. A key the catalogue does not know is rejected on the way in, so guessing costs you a 400.

Query parameters

string

Narrow to one category: activity, vitals, body, nutrition, sleep, reproductive, or mindfulness.

boolean

Pass true to include the metrics OneRep already scores on and draws its own screens for. Those cannot be bound; by default they are left out.

Example request

curl -s "https://<deployment>.convex.site/v1/health/metrics?group=vitals" \
  -H "Authorization: Bearer onerep_sk_…" | jq

Example response

[
  {
    "key": "bloodGlucoseMmolL",
    "label": "Blood glucose",
    "detail": "Finger-prick or continuous monitor readings",
    "group": "vitals",
    "unit": "mmol/L",
    "aggregation": "average",
    "apple": "bloodGlucose",
    "google": "BloodGlucose",
    "gap": null,
    "min": 1,
    "max": 40,
    "bindable": true
  }
]

string | null

Why one platform cannot supply this metric, or null when both can.

boolean

false for the metrics OneRep scores on itself, which only appear when you pass all=true.

This route reads a constant, not your log. It is the same list documented on Health metrics by platform, and the same caveat applies: the 25 most recently catalogued signals are bindable but not yet readable from a phone.

Overview

REST API

MCP

OneRep REST API: Read Endpoints Reference

GET /v1: Route list

GET /v1/me: Key scopes and budget

GET /v1/goals: Calorie and macro targets

GET /v1/insights: Progression verdicts and monthly summaries

Query parameters

GET /v1/days/: Everything logged on one date

Path parameters

GET /v1/days: Per-day totals over a date range

Query parameters

GET /v1/workouts: Recent workout sessions

Query parameters

GET /v1/measurements: Recent weigh-ins and measurements

Query parameters

GET /v1/health/days: Synced daily health readings

GET /v1/custom-metrics: The user’s own tracked metrics

Query parameters

GET /v1/health/metrics: The bindable catalogue

Query parameters

​GET /v1: Route list

​GET /v1/me: Key scopes and budget

​GET /v1/goals: Calorie and macro targets

​GET /v1/insights: Progression verdicts and monthly summaries

​Query parameters

​GET /v1/days/: Everything logged on one date

​Path parameters

​GET /v1/days: Per-day totals over a date range

​Query parameters

​GET /v1/workouts: Recent workout sessions

​Query parameters

​GET /v1/measurements: Recent weigh-ins and measurements

​Query parameters

​GET /v1/health/days: Synced daily health readings

​GET /v1/custom-metrics: The user’s own tracked metrics

​Query parameters

​GET /v1/health/metrics: The bindable catalogue

​Query parameters

GET /v1: Route list

GET /v1/me: Key scopes and budget

GET /v1/goals: Calorie and macro targets

GET /v1/insights: Progression verdicts and monthly summaries

Query parameters

GET /v1/days/: Everything logged on one date

Path parameters

GET /v1/days: Per-day totals over a date range

Query parameters

GET /v1/workouts: Recent workout sessions

Query parameters

GET /v1/measurements: Recent weigh-ins and measurements

Query parameters

GET /v1/health/days: Synced daily health readings

GET /v1/custom-metrics: The user’s own tracked metrics

Query parameters

GET /v1/health/metrics: The bindable catalogue

Query parameters