Partner API

The AI Endurance Partner API lets authorized third party applications access data in AI Endurance. For instance, this could be the workouts of a user's AI Endurance training plan who has authorized the third party application to access their AI Endurance data. We plan to expand the offerings of the Partner API in the near future. For additional information, please also visit our GitHub API documentation.

Register an application

To register an application contact us and briefly describe your application. After we review your application, we'll get back to you with a client_id and client_secret and ask you to provide at least one redirect_uri for the authentication flow.

Authentication

AI Endurance uses Oauth2 to authorize requests to its Partner API. To implement the authentication flow simply follow these steps.

  1. Open 
    https://aiendurance.com/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>
  2. User comes back toredirect_uri?code=<code> with code present if the user authorized the request. If the user did not authorize the request, code is absent. code is valid for 15 minutes.
  3. Exchange code for access_token and refresh_token: 
    curl -X POST -d "grant_type=authorization_code&code=<code>&client_id=<client_id>&client_secret=<client_secret>" https://aiendurance.xyz/o/token/
    access_token expires after 36000 seconds.
  4. Once access_token is expired, use refresh_token to obtain a new access_token and refresh_token:
    curl -X POST -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>" https://aiendurance.xyz/o/token/
  5. To deauthorize a user, revoke token via
    curl -X POST -d "token=<token>&client_id=<client_id>&client_secret=<client_secret>" https://aiendurance.xyz/o/revoke_token/
    where token is either an access_token or refresh_token.

Endpoints

Check AI Endurance's Redoc API documentation. The machine readable part of running and cycling workouts is stored in Future_Workout_Static.steps.

Receive workouts of the user as a GET request via:

curl -H "Authorization: Bearer <access_token>" https://aiendurance.xyz/o/future_workout_static/

To only receive workouts with date after startDate call:

curl -H "Authorization: Bearer <access_token>" https://aiendurance.xyz/o/future_workout_static/?startDate=<startDate>

with formatting startDate as YYYY-MM-DD e.g.

curl -H "Authorization: Bearer <access_token>" https://aiendurance.xyz/o/future_workout_static/?startDate=2023-01-01

and the request will only include Future_Workout_Static results after 2023-01-01.

Examples

The purpose of this section is to further elaborate on the structure of the steps field of the Future_Workout_Static model. A cycling or running workout can either be an

  • Endurance workout: characterized mainly by duration and target_high intensity upper bound.
    {
  "act_type": "Run",
  "type": "Endurance",
  "duration": 1800,
  "stress": 26,
  "is_long": false,
  "target_high": 3.45
}
  • Interval workout: characterized by an interval type (Tempo, Threshold, VO2Max or Anaerobic); number of interval repeats; durations of warmup, cooldown, on, off (interval recovery) and additional time in endurance zone (duration_add_endurance); as well as targets for each respective duration.
    {
  "act_type": "Run",
  "type": "Tempo",
  "stress": 38,
  "is_long": false,
  "repeats": 2,
  "duration_warmup": 600,
  "duration_cooldown": 720,
  "duration_on": 540,
  "duration_off": 300,
  "duration_add_endurance": 0,
  "target_off_low": null,
  "target_off_high": 3.1050000000000004,
  "target_warmup_low": null,
  "target_warmup_high": 3.45,
  "target_cooldown_low": null,
  "target_cooldown_high": 3.1050000000000004,
  "target_add_endurance_low": null,
  "target_add_endurance_high": 3.45,
  "target_on_low": 3.45,
  "target_on_high": 3.6656250000000004
}

All durations are in seconds. Targets are either in m/s (running pace) or Watts (running power or cycling power). Stress is in units of external stress score (ESS). 100 ESS is equivalent to 1 hour at Threshold intensity.

Fit file Endpoints

api/fit_partner_ping/ POST

Send ping for a list of Fit files. The partner makes the fit files available via either of the following options:

  • The partner is making each Fit file available at the URL callback_url to be downloaded by AI Endurance.
  • The partner sends each Fit file as a base64 encoded string via json in the callback_url field.

The partner can specify different priorities depending on how fast the Fit file should be downloaded: if a user is already connected to the partner service and finishes an individual activity that should show in AI Endurance as soon as possible, use priority 1. If the user is connecting to the partner and many Fit files are being sent to AI Endurance, use priority 0. If priority 0 is used, the download is not triggered automatically. Instead, AI Endurance waits until a bulk import task is received that notifies us that the partner has now sent all Fit file pings and the bulk download/import shall begin.

Call via

curl -H "Authorization: Bearer <access_token>" -H 'Content-Type: application/json' -d '<data_partner_ping>' https://aiendurance.xyz/o/fit_partner_ping/

where


<data_partner_ping> = {
  'client_id': <client_id>,
  'activity_files': [
    {
      'file_type': 'FIT',
      'activity_name': 'string' (or null),
      'priority': 0, 1 (0 is lowest priority, i.e. bulk import; if not bulk import use 1),
      'source': 'string' (e.g. 'garmin'),
      'overwrite_mode': false (true gives option to overwrite what is in db already),
      'start_time_in_seconds': 'string' (unix time stamp),
      'callback_url': 'string' (URL where Fit file can be downloaded),
      'summary_id': 'string' (file name),
    }, ...
  ]
}

All fields in <data_partner_ping> are required to be present.

AI Endurance Logo
175 Longwood Rd S, Hamilton, ON L8P 0A1
instagram logofacebook logotwitter logoyoutube logo