Add, manage, and organize athletes in Astral

Your organization is the central roster for every athlete you coach. From here you can invite new athletes, add existing Astral users, update profiles, and assign training plans — all from the dashboard at app.nexrex.ai or directly through the API.

Inviting athletes

Invitations let athletes join your organization through a personalized link. You can send single-use invitations to a specific email address, or create a reusable multi-use link to share with a group.

Dashboard
API

Open your organization roster

Navigate to Athletes in the left sidebar.

Click Invite athlete

Select Invite athlete in the top-right corner of the roster page.

Fill in the invitation details

Enter the athlete’s first name, email address, and optionally assign a group and training plan that will be applied automatically when they accept.

Send the invitation

Click Send invitation. The athlete receives an email with a unique link to join your organization.

Use a multi-use link when onboarding a batch of athletes at once. Set a maximum number of uses, or leave it unlimited with no expiry date.

POST /api/v1/organizations/{org_id}/invitations

{
  "email": "athlete@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "role": "member",
  "expires_in_days": 7,
  "group_id": "grp_abc123",
  "training_plan_id": "plan_xyz789",
  "plan_start_date": "2026-05-01"
}

For a reusable link, set is_multi_use: true and optionally max_uses:

{
  "is_multi_use": true,
  "max_uses": 20,
  "expires_in_days": 0,
  "name": "Spring cohort link"
}

Valid roles are member, coach, and assistant_coach. Omitting expires_in_days defaults to 7 days; set it to 0 for no expiry.

Adding an existing Astral user

If an athlete already has an Astral account, you can add them directly without sending an invitation.

Dashboard
API

On the Athletes page, choose Add existing user and search by the athlete’s email address. Once found, optionally assign them to a group and training plan, then confirm.

First, verify the user exists and is eligible to join:

GET /api/v1/organizations/{org_id}/members/verify?email=athlete@example.com

If the response shows "available": true, add them:

POST /api/v1/organizations/{org_id}/members/add-existing

{
  "user_id": "usr_abc123",
  "group_id": "grp_abc123",
  "training_plan_id": "plan_xyz789",
  "plan_start_date": "2026-05-01"
}

Viewing athlete profiles

The athlete profile aggregates a runner’s training history, current goals, active plans, connected devices, and fitness metrics into a single view.

Dashboard
API

Click any athlete’s name in the Athletes list to open their profile. The profile page shows:

Current and upcoming training plans
Goal race and target pace
Connected integrations (Strava, Garmin, Apple Health)
Recent activity feed and weekly distance trend
AI-generated insights and attention signals

GET /api/v1/analytics/athlete_profile?user_id={athlete_user_id}

Add refresh=true to bypass the cache and fetch the latest data:

GET /api/v1/analytics/athlete_profile?user_id={athlete_user_id}&refresh=true

Updating athlete information

You can update organization-specific attributes for any athlete without changing their Astral account settings.

Dashboard
API

Open an athlete’s profile and click Edit to update their:

Display name — a nickname shown only within your organization
Member level — custom tier (e.g., beginner, intermediate, advanced)
Labels — tags for filtering and grouping (e.g., @marathon, @injury-watch)
Private notes — coach-only notes not visible to the athlete
Status — active, inactive, or suspended

PUT /api/v1/organizations/{org_id}/members/{member_user_id}

{
  "display_name": "Jane (Elite)",
  "member_level": "advanced",
  "labels": ["@marathon", "@track"],
  "notes": "Recovering from IT band issue — reduce mileage by 20%",
  "status": "active"
}

To reset a display name back to the athlete’s default, send "display_name": null.

Assigning training plans

You can attach a training plan to an athlete when inviting them, when adding an existing user, or at any time from their profile.

Dashboard
API

From an athlete’s profile page, navigate to the Plans tab and click Assign plan. Select the plan from your library, set the start date, and save.

Include training_plan_id and plan_start_date in the body when calling the add-existing-user or invitation endpoints (see above). To assign a plan to an athlete already in your organization, use the training plan assignment endpoint with the athlete’s user_id.

Removing an athlete

Dashboard
API

Open the athlete’s profile, click the … menu in the top-right corner, and select Remove from organization. This removes the athlete from your roster but does not delete their Astral account.

DELETE /api/v1/organizations/{org_id}/members/{member_user_id}

Only the head coach can assign athletes to specific coaches within the organization. Regular coaches see all athletes in the roster but can only view athletes assigned to them when using the filtered view.

Filtering and searching the roster

Use the roster filters to narrow down your athlete list by status, member level, label, or assigned coach. The search bar matches on name and email.

GET /api/v1/organizations/{org_id}/members?status=active&label=@marathon&assigned_to_coach_id={coach_user_id}

To include each athlete’s profile status (integrations, zones, race goals, training plans), add include_profile_status=true:

GET /api/v1/organizations/{org_id}/members?include_profile_status=true

​Inviting athletes

​Adding an existing Astral user

​Viewing athlete profiles

​Updating athlete information

​Assigning training plans

​Removing an athlete

​Filtering and searching the roster

Inviting athletes

Adding an existing Astral user

Viewing athlete profiles

Updating athlete information

Assigning training plans

Removing an athlete

Filtering and searching the roster