Workouts

GET /api/workouts

Get workouts for the authenticated user.

Scope: workouts:read

Example requests:

• without parameters:

GET /api/workouts/ HTTP/1.1

• with some query parameters:

GET /api/workouts?from=2019-07-02&to=2019-07-31&sport_id=1  HTTP/1.1

Example responses:

• returning at least one workout:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "id": "kjxavSTUrJvoAh2wvCeGEF",
          "liked": false,
          "likes_count": 0,
          "map": null,
          "map_visibility": "private",
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 13,
              "record_type": "HA",
              "sport_id": 1,
              "user": "Sam",
              "value": 43.97,
              "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
              "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            }
          ],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "suspended_at": null,
          "title": null,
          "user": {
            "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }

• returning no workouts

HTTP/1.1 200 OK
Content-Type: application/json

  {
      "data": {
          "workouts": []
      },
      "status": "success"
  }

Query Parameters:

• page (integer) – page if using pagination (default: 1)

• per_page (integer) – number of workouts per page (default: 5, max: 100)

• sport_id (integer) – sport id

• title (string) – any part (or all) of the workout title; title matching is case-insensitive

• from (string) – start date (format: %Y-%m-%d)

• to (string) – end date (format: %Y-%m-%d)

• distance_from (float) – minimal distance

• distance_to (float) – maximal distance

• duration_from (string) – minimal duration (format: %H:%M)

• duration_to (string) – maximal distance (format: %H:%M)

• ave_speed_from (float) – minimal average speed

• ave_speed_to (float) – maximal average speed

• max_speed_from (float) – minimal max. speed

• max_speed_to (float) – maximal max. speed

• order (string) – sorting order: asc, desc (default: desc)

• order_by (string) – sorting criteria: ave_speed, distance, duration, workout_date (default: workout_date)

• equipment_id (string) – equipment id (if none, only workouts without equipments will be returned)

• notes (string) – any part (or all) of the workout notes, notes matching is case-insensitive

• description (string) – any part of the workout description; description matching is case-insensitive

• return_equipments (string) – return workouts with equipment (by default, equipment is not returned). Note: It’s not a filter. Warning: Needed for 3rd-party applications updating equipments.

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)

Get a workout.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF HTTP/1.1

Example responses:

• success:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": null,
          "ave_speed": 16,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 18:57:14 GMT",
          "descent": null,
          "description": null,
          "distance": 12,
          "duration": "0:45:00",
          "equipments": [],
          "id": "kjxavSTUrJvoAh2wvCeGEF",
          "liked": false,
          "likes_count": 0,
          "map": null,
          "map_visibility": "private",
          "max_alt": null,
          "max_speed": 16,
          "min_alt": null,
          "modification_date": "Sun, 14 Jul 2019 18:57:22 GMT",
          "moving": "0:45:00",
          "next_workout": 4,
          "notes": "workout without gpx",
          "pauses": null,
          "previous_workout": 3,
          "records": [],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "suspended_at": null,
          "title": "biking on sunday morning",
          "user": {
            "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Sun, 07 Jul 2019 07:00:00 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }

• workout not found:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

  {
    "data": {
      "workouts": []
    },
    "status": "not found"
  }

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only visibility

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

GET /api/workouts/(string: workout_short_id)/gpx

Get gpx file for a workout displayed on map with Leaflet.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "gpx": "gpx file content"
  },
  "message": "",
  "status": "success"
}

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only map visibility

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found –

  • workout not found

  • no gpx file for this workout

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/chart_data

Get chart data from a workout gpx file, to display it with Chart.js.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/chart HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "chart_data": [
      {
        "distance": 0,
        "duration": 0,
        "elevation": 279.4,
        "latitude": 51.5078118,
        "longitude": -0.1232004,
        "speed": 8.63,
        "time": "Fri, 14 Jul 2017 13:44:03 GMT"
      },
      {
        "distance": 7.5,
        "duration": 7380,
        "elevation": 280,
        "latitude": 51.5079733,
        "longitude": -0.1234538,
        "speed": 6.39,
        "time": "Fri, 14 Jul 2017 15:47:03 GMT"
      }
    ]
  },
  "message": "",
  "status": "success"
}

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only map visibility

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found –

  • workout not found

  • no gpx file for this workout

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/chart_data/segment/(int: segment_id)

Get chart data from a workout gpx file, to display it with Chart.js.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/chart/segment/1 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "chart_data": [
      {
        "distance": 0,
        "duration": 0,
        "elevation": 279.4,
        "latitude": 51.5078118,
        "longitude": -0.1232004,
        "speed": 8.63,
        "time": "Fri, 14 Jul 2017 13:44:03 GMT"
      },
      {
        "distance": 7.5,
        "duration": 7380,
        "elevation": 280,
        "latitude": 51.5079733,
        "longitude": -0.1234538,
        "speed": 6.39,
        "time": "Fri, 14 Jul 2017 15:47:03 GMT"
      }
    ]
  },
  "message": "",
  "status": "success"
}

Parameters:

• workout_short_id (string) – workout short id

• segment_id (integer) – segment id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only map visibility

Status Codes:

• 200 OK – success

• 400 Bad Request – no gpx file for this workout

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/(string: workout_short_id)/gpx/segment/(int: segment_id)

Get gpx file for a workout segment displayed on map with Leaflet.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx/segment/1 HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "gpx": "gpx file content"
  },
  "message": "",
  "status": "success"
}

Parameters:

• workout_short_id (string) – workout short id

• segment_id (integer) – segment id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only map visibility

Status Codes:

• 200 OK – success

• 400 Bad Request – no gpx file for this workout

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/map/(map_id)

Get map image for workouts with gpx.

Example request:

GET /api/workouts/map/fa33f4d996844a5c73ecd1ae24456ab8?1563529507772
  HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

Parameters:

• map_id (string) – workout map id

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 404 Not Found – map does not exist

• 500 Internal Server Error – error, please try again or contact the administrator

GET /api/workouts/map_tile/(s)/(z)/(x)/(y).png

Get map tile from tile server.

Example request:

GET /api/workouts/map_tile/c/13/4109/2930.png HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: image/png

Parameters:

• s (string) – subdomain

• z (string) – zoom

• x (string) – index of the tile along the map’s x axis

• y (string) – index of the tile along the map’s y axis

Status codes are status codes returned by tile server

GET /api/workouts/(string: workout_short_id)/gpx/download

Download gpx file.

Scope: workouts:read

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/gpx/download HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/gpx+xml

Parameters:

• workout_short_id (string) – workout short id

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 404 Not Found –

  • workout not found

  • no gpx file for workout

POST /api/workouts

Post a workout with a gpx file.

Scope: workouts:write

Example request:

POST /api/workouts/ HTTP/1.1
Content-Type: multipart/form-data

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": 435.621,
          "ave_speed": 13.14,
          "bounds": [
            43.93706,
            4.517587,
            43.981933,
            4.560627
          ],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": 427.499,
          "description": null,
          "distance": 23.478,
          "duration": "2:08:35",
          "equipments": [],
          "id": "PsjeeXbJZ2JJNQcTCPxVvF",
          "liked": false,
          "likes_count": 0,
          "map": "ac075ec36dc25dcc20c270d2005f0398",
          "map_visibility": "private",
          "max_alt": 158.41,
          "max_speed": 25.59,
          "min_alt": 55.03,
          "modification_date": null,
          "moving": "1:47:11",
          "next_workout": "Kd5wyhwLtVozw6o3AU5M4J",
          "notes": "",
          "pauses": "0:20:32",
          "previous_workout": "HgzYFXgvWKCEpdq3vYk67q",
          "records": [
            {
              "id": 6,
              "record_type": "AS",
              "sport_id": 4,
              "user": "Sam",
              "value": 13.14,
              "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            },
            {
              "id": 7,
              "record_type": "FD",
              "sport_id": 4,
              "user": "Sam",
              "value": 23.478,
              "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            },
            {
              "id": 9,
              "record_type": "LD",
              "sport_id": 4,
              "user": "Sam",
              "value": "1:47:11",
              "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            },
            {
              "id": 10,
              "record_type": "MS",
              "sport_id": 4,
              "user": "Sam",
              "value": 25.59,
              "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            },
            {
              "id": 8,
              "record_type": "HA",
              "sport_id": 4,
              "user": "Sam",
              "value": 435.621,
              "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            }
          ],
          "segments": [
            {
              "ascent": 435.621,
              "ave_speed": 13.14,
              "descent": 427.499,
              "distance": 23.478,
              "duration": "2:08:35",
              "max_alt": 158.41,
              "max_speed": 25.59,
              "min_alt": 55.03,
              "moving": "1:47:11",
              "pauses": "0:20:32",
              "segment_id": 0,
              "workout_id": "PsjeeXbJZ2JJNQcTCPxVvF"
            }
          ],
          "sport_id": 4,
          "suspended": false,
          "suspended_at": null,
          "title": "VTT dans le Gard",
          "user": {
            "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 3,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": true,
          "workout_date": "Tue, 26 Apr 2016 14:42:30 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }

Form Parameters:

• file – gpx file (allowed extensions: .gpx, .zip)

• data –

  sport id, equipment id, description, title, notes, visibility for workout, analysis and map for example: {"sport_id": 1, "notes": "", "title": "", "description": "", "analysis_visibility": "private", "map_visibility": "private", "workout_visibility": "private", "equipment_ids": []}. Double quotes in notes, description and title must be escaped.

  The maximum length is 500 characters for notes, 10000 characters for description and 255 for title. Otherwise, they will be truncated. When description and title are provided, they replace the description and title from gpx file.

  For equipment_ids, the id of the equipment to associate with this workout. Note: for now only one equipment can be associated. If not provided and default equipment exists for sport, default equipment will be associated.

  Notes, description, title, equipment ids and visibility for workout, analysis and map are not mandatory. Visibility levels default to user preferences.

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 201 Created – workout created

• 400 Bad Request –

  • invalid payload

  • no file part

  • no selected file

  • file extension not allowed

  • equipment_ids must be an array of strings

  • only one equipment can be added

  • equipment with id <equipment_id> does not exist

  • invalid equipment id <equipment_id> for sport

  • equipment with id <equipment_id> is inactive

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 413 Request Entity Too Large – error during picture update: file size exceeds 1.0MB

• 500 Internal Server Error – error, please try again or contact the administrator

POST /api/workouts/no_gpx

Post a workout without gpx file.

Scope: workouts:write

Example request:

POST /api/workouts/no_gpx HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

 {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "id": "Kd5wyhwLtVozw6o3AU5M4J",
          "liked": false,
          "likes_count": 0,
          "equipments": [],
          "map": null,
          "map_visibility": "private",
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            }
          ],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "suspended_at": null,
          "title": null,
          "user": {
            "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "uuid": "kjxavSTUrJvoAh2wvCeGEF"
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }

Request JSON Object:

• analysis_visibility (string) – analysis visibility (private, followers_only or public). Not mandatory, defaults to user preferences.

• ascent (float) – workout ascent (not mandatory, must be provided with descent)

• descent (float) – workout descent (not mandatory, must be provided with ascent)

• description (string) – workout description (not mandatory, max length: 10000 characters, otherwise it will be truncated)

• distance (float) – workout distance in km

• duration (integer) – workout duration in seconds

• equipment_ids (array of strings) – the id of the equipment to associate with this workout. Note: for now only one equipment can be associated. If not provided and default equipment exists for sport, default equipment will be associated.

• map_visibility (string) – map visibility (private, followers_only or public). Not mandatory, defaults to user preferences.

• notes (string) – notes (not mandatory, max length: 500 characters, otherwise they will be truncated)

• sport_id (integer) – workout sport id

• title (string) – workout title (not mandatory, max length: 255 characters, otherwise it will be truncated)

• workout_date (string) – workout date, in user timezone (format: %Y-%m-%d %H:%M)

• workout_visibility (string) – workout visibility (private, followers_only or public). Not mandatory, defaults to user preferences.

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 201 Created – workout created

• 400 Bad Request –

  • invalid payload

  • equipment_ids must be an array of strings

  • only one equipment can be added

  • equipment with id <equipment_id> does not exist

  • invalid equipment id <equipment_id> for sport

  • equipment with id <equipment_id> is inactive

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 500 Internal Server Error – error, please try again or contact the administrator

PATCH /api/workouts/(string: workout_short_id)

Update a workout.

Scope: workouts:write

Example request:

PATCH /api/workouts/2oRDfncv6vpRkfp3yrCYHt HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": null,
          "ave_speed": 10.0,
          "bounds": [],
          "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT",
          "descent": null,
          "description": null,
          "distance": 10.0,
          "duration": "0:17:04",
          "equipments": [],
          "id": "2oRDfncv6vpRkfp3yrCYHt",
          "liked": false,
          "likes_count": 0,
          "map": null,
          "map_visibility": "private",
          "max_alt": null,
          "max_speed": 10.0,
          "min_alt": null,
          "modification_date": null,
          "moving": "0:17:04",
          "next_workout": 3,
          "notes": null,
          "pauses": null,
          "previous_workout": null,
          "records": [
            {
              "id": 4,
              "record_type": "MS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 3,
              "record_type": "LD",
              "sport_id": 1,
              "user": "admin",
              "value": "0:17:04",
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF"
            },
            {
              "id": 2,
              "record_type": "FD",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF",
            },
            {
              "id": 1,
              "record_type": "AS",
              "sport_id": 1,
              "user": "admin",
              "value": 10.0,
              "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
              "workout_id": "kjxavSTUrJvoAh2wvCeGEF",
            }
          ],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "suspended_at": null,
          "title": null,
          "user": {
            "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "uuid": "kjxavSTUrJvoAh2wvCeGEF"
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }

Parameters:

• workout_short_id (string) – workout short id

Request JSON Object:

• analysis_visibility (string) – analysis visibility (private, followers_only or public)

• ascent (float) – workout ascent (only for workout without gpx, must be provided with descent)

• descent (float) – workout descent (only for workout without gpx, must be provided with ascent)

• description (string) – workout description (max length: 10000 characters, otherwise it will be truncated)

• distance (float) – workout distance in km (only for workout without gpx)

• duration (integer) – workout duration in seconds (only for workout without gpx)

• equipment_ids (array of strings) – the id of the equipment to associate with this workout (any existing equipment for this workout will be replaced). Note: for now only one equipment can be associated. If an empty array, equipment for this workout will be removed.

• map_visibility (string) – map visibility (private, followers_only or public)

• notes (string) – notes (max length: 500 characters, otherwise they will be truncated)

• sport_id (integer) – workout sport id

• title (string) – workout title (max length: 255 characters, otherwise it will be truncated)

• workout_date (string) – workout date in user timezone (format: %Y-%m-%d %H:%M) (only for workout without gpx)

• workout_visibility (string) – workout visibility (private, followers_only or public)

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – workout updated

• 400 Bad Request –

  • invalid payload

  • equipment_ids must be an array of strings

  • only one equipment can be added

  • equipment with id <equipment_id> does not exist

  • invalid equipment id <equipment_id> for sport

  • equipment with id <equipment_id> is inactive

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

• 500 Internal Server Error – error, please try again or contact the administrator

DELETE /api/workouts/(string: workout_short_id)

Delete a workout.

Scope: workouts:write

Example request:

DELETE /api/workouts/kjxavSTUrJvoAh2wvCeGEF HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 204 No Content – workout deleted

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

• 500 Internal Server Error – error, please try again or contact the administrator

POST /api/workouts/(string: workout_short_id)/like

Add a “like” to a workout.

Scope: workouts:write

Example request:

POST /api/workouts/HgzYFXgvWKCEpdq3vYk67q/like HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": 231.208,
          "ave_speed": 13.12,
          "bounds": [],
          "creation_date": "Wed, 04 Dec 2024 09:18:26 GMT",
          "descent": 234.208,
          "description": null,
          "distance": 23.41,
          "duration": "3:32:27",
          "equipments": [],
          "id": "HgzYFXgvWKCEpdq3vYk67q",
          "liked": true,
          "likes_count": 1,
          "map": null,
          "map_visibility": "private",
          "max_alt": 104.44,
          "max_speed": 25.59,
          "min_alt": 19.0,
          "modification_date": "Wed, 04 Dec 2024 16:45:14 GMT",
          "moving": "1:47:04",
          "next_workout": null,
          "notes": null,
          "pauses": "1:23:51",
          "previous_workout": null,
          "records": [],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "title": "Cycling (Sport) - 2016-04-26 16:42:27",
          "user": {
            "created_at": "Sun, 24 Nov 2024 16:52:14 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Tue, 26 Apr 2016 14:42:27 GMT",
          "workout_visibility": "public"
        }
      ]
    },
    "status": "success"
  }

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – comment not found

POST /api/workouts/(string: workout_short_id)/like/undo

Remove workout “like”.

Scope: workouts:write

Example request:

POST /api/workouts/HgzYFXgvWKCEpdq3vYk67q/like/undo HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "workouts": [
        {
          "analysis_visibility": "private",
          "ascent": 231.208,
          "ave_speed": 13.12,
          "bounds": [],
          "creation_date": "Wed, 04 Dec 2024 09:18:26 GMT",
          "descent": 234.208,
          "description": null,
          "distance": 23.41,
          "duration": "3:32:27",
          "equipments": [],
          "id": "HgzYFXgvWKCEpdq3vYk67q",
          "liked": false,
          "likes_count": 0,
          "map": null,
          "map_visibility": "private",
          "max_alt": 104.44,
          "max_speed": 25.59,
          "min_alt": 19.0,
          "modification_date": "Wed, 04 Dec 2024 16:45:14 GMT",
          "moving": "1:47:04",
          "next_workout": null,
          "notes": null,
          "pauses": "1:23:51",
          "previous_workout": null,
          "records": [],
          "segments": [],
          "sport_id": 1,
          "suspended": false,
          "title": "Cycling (Sport) - 2016-04-26 16:42:27",
          "user": {
            "created_at": "Sun, 24 Nov 2024 16:52:14 GMT",
            "followers": 0,
            "following": 0,
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          },
          "weather_end": null,
          "weather_start": null,
          "with_analysis": false,
          "with_gpx": false,
          "workout_date": "Tue, 26 Apr 2016 14:42:27 GMT",
          "workout_visibility": "public"
        }
      ]
    },
    "status": "success"
  }

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – comment not found

GET /api/workouts/(string: workout_short_id)/likes

Get users who like the workout.

Example request:

GET /api/workouts/kjxavSTUrJvoAh2wvCeGEF/likes HTTP/1.1

Example responses:

• success:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "likes": [
        {
          "created_at": "Sun, 31 Dec 2017 09:00:00 GMT",
          "followers": 0,
          "following": 0,
          "nb_workouts": 1,
          "picture": false,
          "role": "user",
          "suspended_at": null,
          "username": "Sam"
        }
      ]
    },
    "status": "success"
  }

• workout not found:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

  {
    "data": {
      "likes": []
    },
    "status": "not found"
  }

Parameters:

• workout_short_id (string) – workout short id

Query Parameters:

• page (integer) – page if using pagination (default: 1)

Request Headers:

• Authorization – OAuth 2.0 Bearer Token for workout with private or followers_only visibility

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 404 Not Found – workout not found

POST /api/workouts/(string: workout_short_id)/suspension/appeal

Appeal workout suspension.

Only workout author can appeal the suspension.

Scope: workouts:write

Example request:

POST /api/workouts/2oRDfncv6vpRkfp3yrCYHt/suspension/appeal HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

  {
    "status": "success"
  }

Parameters:

• workout_short_id (string) – workout short id

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 201 Created – appeal created

• 400 Bad Request –

  • no text provided

  • you can appeal only once

  • workout is not suspended

  • workout has no suspension

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden – you do not have permissions

• 404 Not Found – workout not found

• 500 Internal Server Error – error, please try again or contact the administrator