Skip to main content
Organizations are the top-level container for coaches and athletes in Astral. Each organization has a head coach, optional co-coaches, and a roster of athlete members. All organization endpoints (except GET /{org_id}) require either a valid app key or an authenticated user token.

​
Create an organization

​
name
string
required
Display name of the organization.
​
description
string
Short description of the organization.
​
head_coach_user_id
string
required
User ID of the head coach who will own and administrate the organization.
​
settings
object
Arbitrary settings object stored on the organization (e.g. training_principle, logo_url).
POST /api/v1/organizations
Authentication: App key (X-API-Key header) 
curl -X POST https://api.astral.run/api/v1/organizations \
  -H "X-API-Key: <your_app_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summit Running Club",
    "description": "Elite distance running program",
    "head_coach_user_id": "usr_abc123"
  }'
Response 201 Created 
{
  "message": "Organization created successfully",
  "organization": {
    "org_id": "org_xyz789",
    "org_name": "Summit Running Club",
    "description": "Elite distance running program",
    "head_coach_user_id": "usr_abc123",
    "coaches": [],
    "created_at": "2025-04-23T10:00:00Z"
  }
}

​
Get an organization

Returns full organization details including head coach, coaches list, and settings. 
GET /api/v1/organizations/{org_id}
Path parameters
​
org_id
string
required
The unique organization identifier.
curl https://api.astral.run/api/v1/organizations/org_xyz789 \
  -H "Authorization: Bearer <token>"
Response 200 OK 
{
  "org_id": "org_xyz789",
  "org_name": "Summit Running Club",
  "description": "Elite distance running program",
  "head_coach_user_id": "usr_abc123",
  "coaches": [
    {
      "user_id": "usr_coach2",
      "name": "Jane Smith",
      "role": "assistant_coach"
    }
  ],
  "settings": {
    "training_principle": "High-volume aerobic base with periodic intensity blocks.",
    "logo_url": "https://cdn.astral.run/logos/summit.png"
  },
  "created_at": "2025-04-23T10:00:00Z"
}

​
Update an organization

Updates organization metadata and settings. Requires the authenticated user to be the head coach or a platform admin. 
PUT /api/v1/organizations/{org_id}
Authentication: Bearer token (require_user_auth)
​
org_id
string
required
The unique organization identifier.
​
name
string
New display name.
​
description
string
Updated description.
​
settings
object
Partial settings to merge. Supports any key, including training_principle and logo_url.
curl -X PUT https://api.astral.run/api/v1/organizations/org_xyz789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "training_principle": "Polarized training with 80/20 easy-hard split."
    }
  }'
Response 200 OK 
{
  "message": "Organization updated successfully",
  "organization": {
    "org_id": "org_xyz789",
    "org_name": "Summit Running Club",
    "settings": {
      "training_principle": "Polarized training with 80/20 easy-hard split."
    }
  }
}

​
Add a member

Adds an athlete to the organization’s roster. Requires the member_management feature on the organization’s plan. 
POST /api/v1/organizations/{org_id}/members
Authentication: Bearer token (require_user_auth)
​
org_id
string
required
The unique organization identifier.
​
user_id
string
required
The Astral user ID of the athlete to add.
​
display_name
string
Coach-assigned nickname. Overrides the athlete’s own display name in coach views.
​
member_level
string
Training level label (e.g. "beginner", "intermediate", "advanced").
​
labels
array
Array of string labels for filtering and categorization.
curl -X POST https://api.astral.run/api/v1/organizations/org_xyz789/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_athlete1",
    "display_name": "Alex",
    "member_level": "intermediate",
    "labels": ["5k-focus", "morning-group"]
  }'
Response 201 Created 
{
  "message": "Member added successfully",
  "member": {
    "user_id": "usr_athlete1",
    "display_name": "Alex",
    "member_level": "intermediate",
    "labels": ["5k-focus", "morning-group"],
    "status": "active",
    "joined_at": "2025-04-23T11:00:00Z"
  }
}

​
Remove a member

Removes an athlete from the organization roster. Requires the member_management feature. 
DELETE /api/v1/organizations/{org_id}/members/{user_id}
Authentication: Bearer token
​
org_id
string
required
The unique organization identifier.
​
user_id
string
required
The user ID of the athlete to remove.
curl -X DELETE \
  https://api.astral.run/api/v1/organizations/org_xyz789/members/usr_athlete1 \
  -H "Authorization: Bearer <token>"
Response 200 OK 
{ "message": "Member removed successfully" }

​
List members

Returns all members in an organization. Accessible to coaches and admins only. Supports filtering and optional profile status enrichment. 
GET /api/v1/organizations/{org_id}/members
Authentication: Bearer token (coach or admin role required)
​
status
string
Filter by member status: active, inactive, or suspended.
​
member_level
string
Filter by training level.
​
label
string
Filter members by a specific label.
​
include_profile_status
boolean
When true, each member object is enriched with profile_status flags: has_strava, has_garmin, has_pace_zones, has_hr_zones, has_next_race, has_training_plan, has_mbti.
​
assigned_to_coach_id
string
Filter to only members assigned to this coach.
curl "https://api.astral.run/api/v1/organizations/org_xyz789/members?status=active&include_profile_status=true" \
  -H "Authorization: Bearer <token>"
Response 200 OK 
{
  "members": [
    {
      "user_id": "usr_athlete1",
      "display_name": "Alex",
      "member_level": "intermediate",
      "labels": ["5k-focus"],
      "status": "active",
      "profile_status": {
        "has_strava": true,
        "has_garmin": false,
        "has_pace_zones": true,
        "has_hr_zones": false,
        "has_next_race": true,
        "has_training_plan": true,
        "has_mbti": false,
        "profile_image_url": "https://cdn.astral.run/images/alex.jpg",
        "gender": "male"
      }
    }
  ],
  "count": 1
}

​
Get audit logs

Returns the audit event log for the organization, including member joins/removals and group changes. 
GET /api/v1/organizations/{org_id}/audit-logs
Authentication: Bearer token (coach or admin)
​
org_id
string
required
The unique organization identifier.
curl https://api.astral.run/api/v1/organizations/org_xyz789/audit-logs \
  -H "Authorization: Bearer <token>"
Response 200 OK 
{
  "logs": [
    {
      "event_type": "member_added",
      "actor_id": "usr_abc123",
      "target_id": "usr_athlete1",
      "target_name": "Alex",
      "org_id": "org_xyz789",
      "created_at": "2025-04-23T11:00:00Z"
    }
  ],
  "count": 1
}

​
Response fields

​
org_id
string
Unique identifier for the organization.
​
org_name
string
Display name of the organization.
​
description
string
Organization description.
​
head_coach_user_id
string
User ID of the head coach.
​
coaches
array
Array of coach objects. Each has user_id, name, and role.
​
settings
object
Key-value settings including training_principle and logo_url.
​
created_at
string
ISO 8601 creation timestamp.

​
Error codes

StatusMeaning
400Validation error — missing or invalid fields
401Invalid or missing authentication credentials
403Insufficient permissions (not a coach or admin)
404Organization or member not found
409Conflict — organization name already exists
500Internal server error