Users

GET /api/users

Get all users. If authenticated user has admin rights, users email is returned.

It returns user preferences only for authenticated user.

Scope: users:read

Example request:

  • without parameters:

GET /api/users HTTP/1.1
Content-Type: application/json
  • with some query parameters:

GET /api/users?order_by=workouts_count&par_page=5  HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": {
    "users": [
      {
        "admin": true,
        "bio": null,
        "birth_date": null,
        "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
        "email": "admin@example.com",
        "first_name": null,
        "followers": 0,
        "following": 0,
        "follows": "false",
        "is_followed_by": "false",
        "last_name": null,
        "location": null,
        "map_visibility": "private",
        "nb_sports": 3,
        "nb_workouts": 6,
        "picture": false,
        "records": [
          {
            "id": 9,
            "record_type": "AS",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 10,
            "record_type": "FD",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "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": 11,
            "record_type": "LD",
            "sport_id": 1,
            "user": "admin",
            "value": "1:01:00",
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 12,
            "record_type": "MS",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          }
        ],
        "sports_list": [
            1,
            4,
            6
        ],
        "total_distance": 67.895,
        "total_duration": "6:50:27",
        "username": "admin",
        "workouts_visibility": "private"
      },
      {
        "admin": false,
        "bio": null,
        "birth_date": null,
        "created_at": "Sat, 20 Jul 2019 11:27:03 GMT",
        "email": "sam@example.com",
        "first_name": null,
        "followers": 0,
        "following": 0,
        "follows": "false",
        "is_followed_by": "false",
        "last_name": null,
        "location": null,
        "map_visibility": "private",
        "nb_sports": 0,
        "nb_workouts": 0,
        "picture": false,
        "records": [],
        "sports_list": [],
        "total_distance": 0,
        "total_duration": "0:00:00",
        "username": "sam",
        "workouts_visibility": "private"
      }
    ]
  },
  "status": "success"
}
Query Parameters:
  • page (integer) – page if using pagination (default: 1)

  • per_page (integer) – number of users per page (default: 10, max: 50)

  • q (string) – query on user name

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

  • order_by (string) – sorting criteria: username, created_at, workouts_count, role, is_active (default: username)

  • with_following (boolean) – returns hidden users followed by user if true

  • with_hidden_users (boolean) – returns hidden users if true (only if authenticated user has administration rights - for users administration)

  • with_inactive (boolean) – returns inactive users if true (only if authenticated user has administration rights - for users administration)

  • with_suspended (boolean) – returns suspended users if true (only if authenticated user has administration rights - for users administration)

Request Headers:
Status Codes:
  • 200 OKsuccess

  • 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

GET /api/users/(user_name)

Get single user details. If a user is authenticated, it returns relationships. If authenticated user has admin rights, user email is returned.

It returns user preferences only for authenticated user.

Scope: users:read for Oauth 2.0 client

Example request:

GET /api/users/admin HTTP/1.1
Content-Type: application/json

Example response:

  • when a user is authenticated:

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

{
  "data": [
    {
      "admin": true,
      "bio": null,
      "birth_date": null,
      "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
      "email": "admin@example.com",
      "first_name": null,
      "followers": 0,
      "following": 0,
      "follows": "false",
      "is_followed_by": "false",
      "last_name": null,
      "location": null,
      "map_visibility": "private",
      "nb_sports": 3,
      "nb_workouts": 6,
      "picture": false,
      "records": [
        {
          "id": 9,
          "record_type": "AS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 10,
          "record_type": "FD",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "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": 11,
          "record_type": "LD",
          "sport_id": 1,
          "user": "admin",
          "value": "1:01:00",
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 12,
          "record_type": "MS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        }
      ],
      "sports_list": [
          1,
          4,
          6
      ],
      "total_distance": 67.895,
      "total_duration": "6:50:27",
      "username": "admin",
      "workouts_visibility": "private"
    }
  ],
  "status": "success"
}
  • when no authentication:

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

{
  "data": [
    {
      "admin": true,
      "bio": null,
      "birth_date": null,
      "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
      "email": "admin@example.com",
      "first_name": null,
      "followers": 0,
      "following": 0,
      "follows": "false",
      "is_followed_by": "false",
      "last_name": null,
      "location": null,
      "map_visibility": "private",
      "nb_workouts": 6,
      "picture": false,
      "username": "admin",
      "workouts_visibility": "private"
    }
  ],
  "status": "success"
}
Parameters:
  • user_name (integer) – user name

Request Headers:
  • Authorization – OAuth 2.0 Bearer Token if user is authenticated

Status Codes:
  • 200 OKsuccess

  • 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

    • user does not exist

GET /api/users/(user_name)/picture

get user picture

Example request:

GET /api/users/admin/picture HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Parameters:
  • user_name (integer) – user name

Status Codes:
PATCH /api/users/(user_name)

Update user account.

  • add/remove admin rights (regardless user account status)

  • reset password (and send email to update user password, if sending enabled)

  • update user email (and send email to new user email, if sending enabled)

  • activate account for an inactive user

  • deactivate account after report.

Scope: users:write

Minimum role: Administrator

Example request:

PATCH /api/users/<user_name> HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": [
    {
      "admin": true,
      "bio": null,
      "birth_date": null,
      "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
      "email": "admin@example.com",
      "first_name": null,
      "followers": 0,
      "following": 0,
      "follows": "false",
      "is_followed_by": "false",
      "last_name": null,
      "location": null,
      "map_visibility": "private",
      "nb_workouts": 6,
      "nb_sports": 3,
      "picture": false,
      "records": [
        {
          "id": 9,
          "record_type": "AS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 10,
          "record_type": "FD",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "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": 11,
          "record_type": "LD",
          "sport_id": 1,
          "user": "admin",
          "value": "1:01:00",
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 12,
          "record_type": "MS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        }
      ],
      "sports_list": [
          1,
          4,
          6
      ],
      "total_distance": 67.895,
      "total_duration": "6:50:27",
      "username": "admin",
      "workouts_visibility": "private"
    }
  ],
  "status": "success"
}
Parameters:
  • user_name (string) – user name

Request JSON Object:
  • activate (boolean) – (de-)activate user account

  • role (boolean) – user role (user, admin, moderator). owner can only be set via CLI.

  • new_email (boolean) – new user email

  • reset_password (boolean) – reset user password

Request Headers:
Status Codes:
  • 200 OKsuccess

  • 400 Bad Request

    • invalid payload

    • invalid role

    • valid email must be provided

    • new email must be different than current email

  • 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

    • user does not exist

  • 500 Internal Server Errorerror, please try again or contact the administrator

DELETE /api/users/(user_name)

Delete a user account.

A user can only delete his own account.

A user with admin rights can delete all accounts except his account if he is the only user with admin rights. Only owner can delete his own account.

Suspended user can access this endpoint.

Scope: users:write

Example request:

DELETE /api/users/john_doe HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json
Parameters:
  • user_name (string) – user name

Request Headers:
Status Codes:
POST /api/users/(user_name)/follow

Send a follow request to a user.

Scope: follow:write

Example request:

POST /api/users/john_doe/follow HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "status": "success",
  "message": "Follow request to user 'john_doe' is sent.",
}
Parameters:
  • user_name (string) – user name

Request Headers:
Status Codes:
  • 200 OK – success

  • 401 Unauthorized

    • provide a valid auth token

    • signature expired, please log in again

    • invalid token, please log in again

    • you do not have permissions

    • you do not have permissions, your account is suspended

  • 404 Not Found

    • user does not exist

  • 500 Internal Server Errorerror, please try again or contact the administrator

POST /api/users/(user_name)/unfollow

Unfollow a user.

Scope: follow:write

Example request:

POST /api/users/john_doe/unfollow HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "status": "success",
  "message": "Undo for a follow request to user 'john_doe' is sent.",
}
Parameters:
  • user_name (string) – user name

Request Headers:
Status Codes:
GET /api/users/(user_name)/followers

Get user followers. If the authenticated user has admin rights, it returns following users with additional field ‘email’

Scope: follow:read

Example request:

  • without parameters

GET /api/users/sam/followers HTTP/1.1
Content-Type: application/json
  • with page parameter

GET /api/users/sam/followers?page=1 HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": {
    "followers": [
      {
        "admin": false,
        "bio": null,
        "birth_date": null,
        "created_at": "Thu, 02 Dec 2021 17:50:48 GMT",
        "first_name": null,
        "followers": 1,
        "following": 1,
        "follows": "true",
        "is_followed_by": "false",
        "last_name": null,
        "location": null,
        "map_visibility": "followers_only",
        "nb_sports": 0,
        "nb_workouts": 0,
        "picture": false,
        "records": [],
        "sports_list": [],
        "total_distance": 0.0,
        "total_duration": "0:00:00",
        "username": "JohnDoe",
        "workouts_visibility": "followers_only"
      }
    ]
  },
  "pagination": {
    "has_next": false,
    "has_prev": false,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "status": "success"
}
Parameters:
  • user_name (string) – user name

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

Request Headers:
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

    • user does not exist

GET /api/users/(user_name)/following

Get user following. If the authenticate user has admin rights, it returns following users with additional field ‘email’

Scope: follow:read

Example request:

  • without parameters

GET /api/users/sam/following HTTP/1.1
Content-Type: application/json
  • with page parameter

GET /api/users/sam/following?page=1 HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": {
    "following": [
      {
        "admin": false,
        "bio": null,
        "birth_date": null,
        "created_at": "Thu, 02 Dec 2021 17:50:48 GMT",
        "first_name": null,
        "followers": 1,
        "following": 1,
        "follows": "false",
        "is_followed_by": "true",
        "last_name": null,
        "location": null,
        "map_visibility": "followers_only",
        "nb_sports": 0,
        "nb_workouts": 0,
        "picture": false,
        "records": [],
        "sports_list": [],
        "total_distance": 0.0,
        "total_duration": "0:00:00",
        "username": "JohnDoe",
        "workouts_visibility": "followers_only"
      }
    ]
  },
  "pagination": {
    "has_next": false,
    "has_prev": false,
    "page": 1,
    "pages": 1,
    "total": 1
  },
  "status": "success"
}
Parameters:
  • user_name (string) – user name

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

Request Headers:
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

    • user does not exist

POST /api/users/(user_name)/block

Block a user

Scope: users:write

Example request:

GET /api/users/sam/block HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "status": "success"
}
Parameters:
  • user_name (string) – user name

Request Headers:
Status Codes:
POST /api/users/(user_name)/unblock

Unblock a user

Scope: users:write

Example request:

GET /api/users/sam/unblock HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "status": "success"
}
Parameters:
  • user_name (string) – user name

Request Headers:
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

    • user not found

GET /api/users/(user_name)/sanctions

Get user sanctions.

It returns sanctions only if: - user name is authenticated user username - user has moderation rights.

Suspended user can access this endpoint.

Scope: users:read

Example requests:

  • without parameters:

GET /api/users/Sam/sanctions HTTP/1.1
  • with parameters:

GET /api/users/Sam/sanctions?page=2 HTTP/1.1

Example responses:

  • if sanctions exist (response with moderation rights)

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

  {
    "data": {
      "sanctions": [
        {
          "action_type": "workout_suspension",
          "appeal": {
            "approved": null,
            "created_at": "Wed, 04 Dec 2024 11:00:04 GMT",
            "id": "2ULe2hWhSnYCS2VHbsikB9",
            "moderator": null,
            "reason": null,
            "text": "<APPEAL TEXT>",
            "updated_at": null,
            "user": {
              "blocked": false,
              "created_at": "Wed, 04 Dec 2024 09:07:06 GMT",
              "email": "sam@example.com",
              "followers": 0,
              "following": 0,
              "follows": false,
              "is_active": true,
              "is_followed_by": false,
              "nb_workouts": 1,
              "picture": false,
              "role": "user",
              "suspended_at": null,
              "username": "Sam"
            }
          },
          "created_at": "Wed, 04 Dec 2024 10:59:45 GMT",
          "id": "6dxczvMrhkAR72shUz9Pwd",
          "moderator": {
            "blocked": false,
            "created_at": "Wed, 01 Mar 2023 12:31:17 GMT",
            "email": "admin@example.com",
            "followers": 0,
            "following": 0,
            "follows": "false",
            "is_active": true,
            "is_followed_by": "false",
            "nb_workouts": 0,
            "picture": true,
            "role": "admin",
            "suspended_at": null,
            "username": "admin"
          },
          "reason": "<SUSPENSION REASON>",
          "report_id": 2,
          "user": {
            "blocked": false,
            "created_at": "Sun, 01 Dec 2024 17:27:49 GMT",
            "email": "sam@example.com",
            "followers": 0,
            "following": 0,
            "follows": "false",
            "is_active": true,
            "is_followed_by": "false",
            "nb_workouts": 1,
            "picture": false,
            "role": "user",
            "suspended_at": null,
            "username": "Sam"
          }
        }
      ]
    },
    "pagination": {
      "has_next": false,
      "has_prev": false,
      "page": 1,
      "pages": 1,
      "total": 1
    },
    "status": "success"
  }
  • if sanctions exist (response for authenticated user)

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

  {
    "data": {
      "sanctions": [
        {
          "action_type": "workout_suspension",
          "appeal": {
            "approved": null,
            "created_at": "Wed, 04 Dec 2024 16:50:55 GMT",
            "id": "kcj6hdGQqPKaaKQmfQj8Jv",
            "reason": null,
            "text": "<APPEAL TEXT>",
            "updated_at": null
          },
          "created_at": "Wed, 04 Dec 2024 16:50:44 GMT",
          "id": "6nvxvAyoh9Zkr8RMXhu54T",
          "reason": "<SUSPENSION REASON>"
        }
      ]
    },
    "pagination": {
      "has_next": false,
      "has_prev": false,
      "page": 1,
      "pages": 1,
      "total": 1
    },
    "status": "success"
  }
  • no sanctions

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

  {
    "data": {
      "sanctions": []
    },
    "pagination": {
      "has_next": false,
      "has_prev": false,
      "page": 1,
      "pages": 0,
      "total": 0
    },
    "status": "success"
  }
Parameters:
  • user_name (string) – user name

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

Request Headers:
Status Codes:
GET /api/users/(user_name)/workouts

Get user last 5 visible workouts.

Scope: workouts:read

Example request:

GET /api/users/Sam/workouts HTTP/1.1

Example response:

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

  {
    "data": {
      "workouts": [
        {
          "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_gpx": false,
          "workout_date": "Mon, 01 Jan 2018 00:00:00 GMT",
          "workout_visibility": "private"
        }
      ]
    },
    "status": "success"
  }
Parameters:
  • user_name (string) – user name

Request Headers:
  • Authorization – OAuth 2.0 Bearer Token if user is authenticated

Status Codes: