Skip to main content
POST
Log a workout from a description

Authorizations

__Secure-better-auth.session_token
string
cookie
required

Better Auth session. Signing in (Google or email magic link) sets an HttpOnly session cookie that scopes every request to that account. The web app and CLI use this; agents use the OAuth 2.1 flow of the MCP server.

Body

application/json

The workout description and optional local day.

Body for logging a workout from a freeform text description.

text
string
required

The workout in the user's own words.

Maximum string length: 4000
Example:

"ran 5k easy in 28 minutes, then 3x10 pullups"

date
string<date>

Local day to log against (YYYY-MM-DD); defaults to now.

Example:

"2026-07-02"

tz
integer

Timezone offset in minutes, as from getTimezoneOffset.

Example:

420

Response

The workout was parsed and logged.

A logged workout, normalized to the standard fields of Apple Health, Garmin, and Strava; metric fields are null when the user didn't state them.

id
string<uuid>
required

Workout identifier.

Example:

"9c2d1e4f-7a8b-4c5d-9e0f-1a2b3c4d5e6f"

source
enum<string>
required

Where the workout came from; manual for described/photographed logs.

Available options:
manual,
apple_health,
garmin,
strava
Example:

"manual"

activityType
string
required

Normalized activity type (run, ride, swim, walk, hike, strength_training, yoga, rowing, elliptical, crossfit, other).

Example:

"run"

summary
string
required

Short AI-generated title.

Example:

"5k run + pullups"

description
string
required

The user's original words (or the summary for photo-only logs).

Example:

"ran 5k easy, then 3x10 pullups"

startedAt
integer
required

Start time as Unix milliseconds.

Example:

1783100000000

durationS
integer | null
required

Elapsed duration in seconds.

Example:

1680

movingDurationS
integer | null
required

Moving time in seconds, when distinct from elapsed.

Example:

null

distanceM
number | null
required

Distance in meters.

Example:

5000

elevationGainM
number | null
required

Elevation gain in meters.

Example:

null

energyKcal
number | null
required

Active energy in kilocalories.

Example:

320

avgHr
integer | null
required

Average heart rate in bpm.

Example:

148

maxHr
integer | null
required

Max heart rate in bpm.

Example:

null

avgPowerW
number | null
required

Average power in watts.

Example:

null

avgCadence
number | null
required

Average cadence (spm or rpm as reported).

Example:

null

exercises
object[]
required

Strength breakdown; empty for pure cardio.

Example:
createdAt
integer
required

Row creation time as Unix milliseconds.

Example:

1783100001000