Activities API — Log and Manage Workouts

The Activities API lets you log completed workouts, retrieve historical training data, and manage activity records on behalf of your athletes. All endpoints require a valid Bearer token. Activities with a distance of 3 km or more automatically receive an AI-generated summary from Rex, Astral’s coaching agent.

List activities

GET /api/v1/activities

Returns activities for the authenticated user, or for another user if the caller has coach access. Supports filtering by date range, type, and status.

Query parameters

user_id

string

Return activities for this user ID. Defaults to the authenticated user. Callers requesting another user’s activities must have coach access.

start_date

string

ISO 8601 start date. Only activities on or after this datetime are returned. Example: 2025-01-01T00:00:00Z.

end_date

string

ISO 8601 end date. Only activities on or before this datetime are returned.

activity_type

string

Filter by activity type. Must be one of: run, bike, swim, walk, hike, workout.

status

string

Filter by status. Accepts completed, scheduled, or skipped. Can be specified multiple times or as a comma-separated list. Defaults to all three.

plan_instance_id

string

Filter to activities belonging to a specific training plan instance.

limit

integer

Maximum number of activities to return.

offset

integer

Number of activities to skip for pagination.

format

string

Set to raw to return the original Firestore document structure instead of the standardized format.

detail

string

Set to true to include activity stream data (heart rate, pace, elevation). Adds latency; use only when displaying individual activity details.

image_urls

string

Set to true to include image_urls in each activity.

Example request

curl https://app.nexrex.ai/api/v1/activities \
  -H "Authorization: Bearer <token>" \
  -G \
  --data-urlencode "user_id=usr_abc123" \
  --data-urlencode "status=completed" \
  --data-urlencode "limit=20"

Response

Returns an array of activity objects.

activity_id

string

Unique identifier for the activity.

user_id

string

ID of the athlete who performed the activity.

status

string

Activity status: completed, scheduled, or skipped.

ai_summary

string

AI-generated coaching summary from Rex. Present for completed activities with distance ≥ 3 km.

ai_summary_title

string

Short headline for the AI summary.

Create an activity

POST /api/v1/activities

Logs a new activity for the authenticated user. The activity is always created for the authenticated user regardless of any user_id supplied in the body.

Request body

string

required

Email address of the athlete.

username

string

required

Display name of the athlete.

summary

object

required

Object containing the core performance data for the activity.

summary.activity_name

string

required

Title of the activity.

summary.activity_type

string

required

Type of activity. Must be one of: RUNNING, CYCLING, SWIMMING.

summary.duration_in_seconds

integer

Total duration of the activity in seconds. Maximum value: 86400 (24 hours).

summary.distance_in_meters

integer

Total distance covered in meters.

summary.start_time_in_seconds

integer

Unix timestamp for when the activity started.

status

string

Activity status. One of: completed, scheduled, cancelled. Defaults to completed.

data_source

string

Origin of the activity data. One of: garmin, strava, apple_watch, manual. Defaults to manual.

complete_date

integer

Unix timestamp (milliseconds) for when the activity was completed.

complete_date_str

string

ISO 8601 date string for the completion date.

zones

object

Heart rate and pace zone distribution data.

splits

object

Per-kilometre or per-mile split analysis data.

map

object

Encoded polyline and bounding box for the route map.

Example request

curl -X POST https://app.nexrex.ai/api/v1/activities \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "athlete@example.com",
    "username": "Jane Runner",
    "summary": {
      "activity_name": "Morning 10K",
      "activity_type": "RUNNING",
      "distance_in_meters": 10000,
      "duration_in_seconds": 3120
    },
    "status": "completed",
    "data_source": "manual"
  }'

Response

Returns 201 Created with the new activity object.

status

string

ok on success.

data

object

The created activity in standardized format.

data.activity_id

string

Unique identifier assigned to the new activity.

Get an activity

GET /api/v1/activities/{activity_id}

Returns a single activity by ID.

Path parameters

activity_id

string

required

The unique identifier of the activity to retrieve.

Query parameters

format

string

Set to raw to return the original Firestore document.

detail

string

Set to true to include stream data (heart rate, pace, elevation charts).

include_streams

string

Set to true alongside detail=true to include the full raw data stream.

Example request

curl https://app.nexrex.ai/api/v1/activities/act_xyz789 \
  -H "Authorization: Bearer <token>"

Response

status

string

ok on success.

data

object

Full activity object including AI summary fields when applicable.

data.activity_id

string

Unique identifier of the activity.

data.user_id

string

ID of the athlete who owns the activity.

data.status

string

Activity status: completed, scheduled, or skipped.

data.ai_summary

string

AI coaching summary. Present for completed activities ≥ 3 km.

data.ai_summary_title

string

Short headline for the AI coaching summary.

data.agent_name

string

Name of the AI coach who generated the summary (e.g. Rex).

Update an activity

PUT /api/v1/activities/{activity_id}

Replaces the activity fields with the values supplied in the request body. Partial updates are supported — only the fields provided are changed.

Path parameters

activity_id

string

required

The unique identifier of the activity to update.

Request body

Send the same fields as the create endpoint. All fields are optional for updates.

Example request

curl -X PUT https://app.nexrex.ai/api/v1/activities/act_xyz789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": {
      "activity_name": "Morning 10K — updated title"
    }
  }'

Response

status

string

ok on success.

data

object

The updated activity object.

Delete an activity

DELETE /api/v1/activities/{activity_id}

Permanently deletes an activity. If the activity belongs to a training plan instance, it is also removed from the plan.

Path parameters

activity_id

string

required

The unique identifier of the activity to delete.

Example request

curl -X DELETE https://app.nexrex.ai/api/v1/activities/act_xyz789 \
  -H "Authorization: Bearer <token>"

Response

status

string

ok on success.

message

string

Human-readable confirmation, e.g. Activity deleted successfully.

​List activities

​Query parameters

​Example request

​Response

​Create an activity

​Request body

​Example request

​Response

​Get an activity

​Path parameters

​Query parameters

​Example request

​Response

​Update an activity

​Path parameters

​Request body

​Example request

​Response

​Delete an activity

​Path parameters

​Example request

​Response

List activities

Query parameters

Example request

Response

Create an activity

Request body

Example request

Response

Get an activity

Path parameters

Query parameters

Example request

Response

Update an activity

Path parameters

Request body

Example request

Response

Delete an activity

Path parameters

Example request

Response