Skip to Content
API ReferenceUsers API

Users API

Endpoints for managing users in the system.

Get Users List

Get the complete list of users.

Request

GET /api/users

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Query Parameters

NameTypeDescription
pageintegerOptional. Page number (default: 1)
per_pageintegerOptional. Records per page (default: 20)

Response

{ "users": [ { "id": 1, "username": "admin", "email": "[email protected]", "created_at": "2023-01-01T00:00:00Z", "status": "active" }, { "id": 2, "username": "user1", "email": "[email protected]", "created_at": "2023-01-02T00:00:00Z", "status": "active" } ] }

Response Fields

FieldTypeDescription
usersarrayArray of users
idintegerUser ID
usernamestringUsername
emailstringUser email
created_atstringCreation date
statusstringUser status

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request

Get User Data

Get detailed information about a specific user.

Request

GET /api/users/{id}

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "user": { "id": 1, "username": "admin", "email": "[email protected]", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-10T00:00:00Z", "status": "active", "roles": [ { "id": 1, "name": "admin", "description": "Administrator" } ] } }

Response Fields

FieldTypeDescription
userobjectUser object
idintegerUser ID
usernamestringUsername
emailstringUser email
created_atstringCreation date
updated_atstringUpdate date
statusstringUser status
rolesarrayArray of user roles

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found

Create User

Create a new user in the system.

Request

POST /api/users

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "username": "newuser", "email": "[email protected]", "password": "securepassword", "role_ids": [2] }

Request Body Parameters

NameTypeDescription
usernamestringRequired. Username
emailstringRequired. User email
passwordstringRequired. User password
role_idsarrayOptional. User role IDs

Response

{ "message": "User created successfully", "user": { "id": 3, "username": "newuser", "email": "[email protected]", "created_at": "2023-03-15T12:00:00Z", "status": "active" } }

Response Codes

CodeDescription
201User successfully created
401Invalid or missing API key
403Insufficient permissions to perform request
422Invalid request parameters

Update User

Update data of an existing user.

Request

PUT /api/users/{id}

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "username": "updateduser", "email": "[email protected]", "password": "newsecurepassword", "status": "active" }

Request Body Parameters

NameTypeDescription
usernamestringOptional. Username
emailstringOptional. User email
passwordstringOptional. User password
statusstringOptional. User status

Response

{ "message": "User updated successfully", "user": { "id": 3, "username": "updateduser", "email": "[email protected]", "created_at": "2023-03-15T12:00:00Z", "updated_at": "2023-03-16T14:30:00Z", "status": "active" } }

Response Codes

CodeDescription
200User successfully updated
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found
422Invalid request parameters

Block User

Block a user in the system.

Request

POST /api/users/{id}/block

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "reason": "Site rules violation", "until": "2023-04-15T00:00:00Z" }

Request Body Parameters

NameTypeDescription
reasonstringOptional. Block reason
untilstringOptional. Block end date (ISO 8601)

Response

{ "message": "User blocked successfully" }

Response Codes

CodeDescription
200User successfully blocked
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found
422Invalid request parameters

Unblock User

Unblock a previously blocked user.

Request

POST /api/users/{id}/unblock

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "message": "User unblocked successfully" }

Response Codes

CodeDescription
200User successfully unblocked
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found

Manage User Roles

Change user roles.

Request

PUT /api/users/{id}/roles

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "role_ids": [1, 2, 3] }

Request Body Parameters

NameTypeDescription
role_idsarrayRequired. Array of role IDs

Response

{ "message": "User roles updated successfully", "user": { "id": 3, "username": "user3", "email": "[email protected]", "roles": [ { "id": 1, "name": "admin", "description": "Administrator" }, { "id": 2, "name": "moderator", "description": "Moderator" }, { "id": 3, "name": "user", "description": "User" } ] } }

Response Codes

CodeDescription
200User roles successfully updated
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found
422Invalid request parameters

Get User Social Networks

Get the list of linked social networks for a user.

Request

GET /api/users/{id}/social-networks

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "social_networks": [ { "id": 1, "network": "vk", "profile_url": "https://vk.com/username" }, { "id": 2, "network": "telegram", "profile_url": "@username" } ] }

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found

Add Social Network to User

Add a new social network link to a user.

Request

POST /api/users/{id}/social-networks

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key
Content-TypestringRequired. application/json

Request Body

{ "network_id": 1, "profile_url": "https://vk.com/new_username" }

Request Body Parameters

NameTypeDescription
network_idintegerRequired. Social network ID
profile_urlstringRequired. Profile URL or username

Response

{ "message": "Social network added successfully", "social_network": { "id": 3, "network": "vk", "profile_url": "https://vk.com/new_username" } }

Response Codes

CodeDescription
201Social network successfully added
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found
422Invalid request parameters

Remove User Social Network

Remove a social network link from a user.

Request

DELETE /api/users/{userId}/social-networks/{networkId}

Path Parameters

NameTypeDescription
userIdintegerUser ID
networkIdintegerSocial network link ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "message": "Social network removed successfully" }

Response Codes

CodeDescription
200Social network successfully removed
401Invalid or missing API key
403Insufficient permissions to perform request
404User or network link not found

Get User Devices

Get the list of user devices.

Request

GET /api/users/{id}/devices

Path Parameters

NameTypeDescription
idintegerUser ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "devices": [ { "id": 1, "name": "Chrome on Windows", "last_active": "2023-03-15T12:00:00Z", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36" }, { "id": 2, "name": "Firefox on MacOS", "last_active": "2023-03-10T14:30:00Z", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/111.0" } ] }

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request
404User not found

Remove User Device

Remove a device and its associated session from a user.

Request

DELETE /api/users/{userId}/devices/{deviceId}

Path Parameters

NameTypeDescription
userIdintegerUser ID
deviceIdintegerDevice ID

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Response

{ "message": "Device removed successfully" }

Response Codes

CodeDescription
200Device successfully removed
401Invalid or missing API key
403Insufficient permissions to perform request
404User or device not found

Search Users

Search users by name or email.

Request

GET /api/users/search

Headers

NameTypeDescription
X-API-KeystringRequired. API key

Query Parameters

NameTypeDescription
qstringRequired. Search query (min. 3 characters)

Response

{ "users": [ { "id": 1, "username": "admin", "email": "[email protected]", "created_at": "2023-01-01T00:00:00Z", "status": "active" }, { "id": 5, "username": "administrator", "email": "[email protected]", "created_at": "2023-01-05T00:00:00Z", "status": "active" } ] }

Response Codes

CodeDescription
200Successful request
401Invalid or missing API key
403Insufficient permissions to perform request
422Invalid request parameters (query too short)