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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK –
success
provide a valid auth token
signature expired, please log in again
invalid token, please log in again
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 clientExample 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 OK –
success
provide a valid auth token
signature expired, please log in again
invalid token, please log in again
you do not have permissions, your account is suspended
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:
200 OK –
success
user does not exist
No picture.
- 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK –
success
invalid payload
invalid role
valid email must be provided
new email must be different than current email
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
user does not exist
500 Internal Server Error –
error, 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
204 No Content – user account deleted
provide a valid auth token
signature expired, please log in again
invalid token, please log in again
you do not have permissions
you can not delete your account, no other user has admin rights
user does not exist
500 Internal Server Error –
error, please try again or contact the administrator
- 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
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
user does not exist
500 Internal Server Error –
error, 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
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
user does not exist
500 Internal Server Error –
error, please try again or contact the administrator
- 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
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
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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
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
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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
invalid payload
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
user not found
- 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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
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
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:
Authorization – OAuth 2.0 Bearer Token
- Status Codes:
200 OK – success
provide a valid auth token
signature expired, please log in again
invalid token, please log in again
you do not have permissions
user not found
- 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:
200 OK – success
provide a valid auth token
signature expired, please log in again
invalid token, please log in again
you do not have permissions
user not found