Skip to main content
The Astral API lets you build integrations on top of the Astral AI-powered running coaching platform. You can read and write user profiles, log activities, manage training plans, and more. All endpoints follow a consistent pattern: JSON request bodies, Bearer token authentication, and predictable error responses.

​
Base URL

All API endpoints are served under: 
https://app.nexrex.ai/api/v1/
For example, to retrieve the authenticated user’s profile: 
GET https://app.nexrex.ai/api/v1/auth/me

​
Authentication

Every request to a protected endpoint must include a Bearer token in the Authorization header: 
Authorization: Bearer <your_access_token>
Organization integrations can also authenticate using an API key in the X-API-Key header. See Authentication for details on obtaining tokens and keys.

​
Request format

All request bodies must be JSON. Set the Content-Type header on every request that has a body: 
Content-Type: application/json

​
Response format

Successful responses return JSON. Most endpoints wrap their payload in a data key: 
{
  "status": "ok",
  "data": { ... }
}
Auth endpoints return their fields at the top level of the response object.

​
Error responses

Errors return a JSON object with an error string and an optional details object: 
{
  "error": "Human-readable error message",
  "details": {
    "code": "MACHINE_READABLE_CODE",
    "field": "additional context"
  }
}

​
HTTP status codes

CodeMeaning
200OK — request succeeded
201Created — resource created successfully
400Bad Request — validation error or missing required field
401Unauthorized — missing or invalid token
403Forbidden — authenticated but not authorized for this resource
404Not Found — resource does not exist
409Conflict — duplicate resource (e.g. username already taken)
500Internal Server Error — unexpected server-side failure

​
Rate limiting

Verification email requests are limited to 3 per email address per hour. Other endpoints do not currently enforce rate limits, but you should avoid sending more than a few hundred requests per minute per credential.

​
Resource types

ResourceDescription
UsersAthlete and coach profiles, preferences, privacy settings, training zones
ActivitiesRuns and workouts logged by athletes, including GPS data and metrics
Training plansAI-generated and coach-assigned training schedules
OrganizationsClubs, teams, and coaching organizations with member management

​
Versioning

The current API version is v1. The version is part of every endpoint path (/api/v1/...). Breaking changes will be introduced under a new version prefix.