Users API
Endpoints for managing users in the system.
Get Users List
Get the complete list of users.
Request
GET /api/users
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Query Parameters
Name | Type | Description |
---|---|---|
page | integer | Optional. Page number (default: 1) |
per_page | integer | Optional. 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
Field | Type | Description |
---|---|---|
users | array | Array of users |
id | integer | User ID |
username | string | Username |
string | User email | |
created_at | string | Creation date |
status | string | User status |
Response Codes
Code | Description |
---|---|
200 | Successful request |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
Get User Data
Get detailed information about a specific user.
Request
GET /api/users/{id}
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. 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
Field | Type | Description |
---|---|---|
user | object | User object |
id | integer | User ID |
username | string | Username |
string | User email | |
created_at | string | Creation date |
updated_at | string | Update date |
status | string | User status |
roles | array | Array of user roles |
Response Codes
Code | Description |
---|---|
200 | Successful request |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
Create User
Create a new user in the system.
Request
POST /api/users
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Content-Type | string | Required. application/json |
Request Body
{
"username": "newuser",
"email": "[email protected]",
"password": "securepassword",
"role_ids": [2]
}
Request Body Parameters
Name | Type | Description |
---|---|---|
username | string | Required. Username |
string | Required. User email | |
password | string | Required. User password |
role_ids | array | Optional. 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
Code | Description |
---|---|
201 | User successfully created |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
422 | Invalid request parameters |
Update User
Update data of an existing user.
Request
PUT /api/users/{id}
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Content-Type | string | Required. application/json |
Request Body
{
"username": "updateduser",
"email": "[email protected]",
"password": "newsecurepassword",
"status": "active"
}
Request Body Parameters
Name | Type | Description |
---|---|---|
username | string | Optional. Username |
string | Optional. User email | |
password | string | Optional. User password |
status | string | Optional. 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
Code | Description |
---|---|
200 | User successfully updated |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
422 | Invalid request parameters |
Block User
Block a user in the system.
Request
POST /api/users/{id}/block
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Content-Type | string | Required. application/json |
Request Body
{
"reason": "Site rules violation",
"until": "2023-04-15T00:00:00Z"
}
Request Body Parameters
Name | Type | Description |
---|---|---|
reason | string | Optional. Block reason |
until | string | Optional. Block end date (ISO 8601) |
Response
{
"message": "User blocked successfully"
}
Response Codes
Code | Description |
---|---|
200 | User successfully blocked |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
422 | Invalid request parameters |
Unblock User
Unblock a previously blocked user.
Request
POST /api/users/{id}/unblock
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Response
{
"message": "User unblocked successfully"
}
Response Codes
Code | Description |
---|---|
200 | User successfully unblocked |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
Manage User Roles
Change user roles.
Request
PUT /api/users/{id}/roles
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Content-Type | string | Required. application/json |
Request Body
{
"role_ids": [1, 2, 3]
}
Request Body Parameters
Name | Type | Description |
---|---|---|
role_ids | array | Required. 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
Code | Description |
---|---|
200 | User roles successfully updated |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
422 | Invalid 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
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Response
{
"social_networks": [
{
"id": 1,
"network": "vk",
"profile_url": "https://vk.com/username"
},
{
"id": 2,
"network": "telegram",
"profile_url": "@username"
}
]
}
Response Codes
Code | Description |
---|---|
200 | Successful request |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User 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
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Content-Type | string | Required. application/json |
Request Body
{
"network_id": 1,
"profile_url": "https://vk.com/new_username"
}
Request Body Parameters
Name | Type | Description |
---|---|---|
network_id | integer | Required. Social network ID |
profile_url | string | Required. 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
Code | Description |
---|---|
201 | Social network successfully added |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
422 | Invalid request parameters |
Remove User Social Network
Remove a social network link from a user.
Request
DELETE /api/users/{userId}/social-networks/{networkId}
Path Parameters
Name | Type | Description |
---|---|---|
userId | integer | User ID |
networkId | integer | Social network link ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Response
{
"message": "Social network removed successfully"
}
Response Codes
Code | Description |
---|---|
200 | Social network successfully removed |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User or network link not found |
Get User Devices
Get the list of user devices.
Request
GET /api/users/{id}/devices
Path Parameters
Name | Type | Description |
---|---|---|
id | integer | User ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. 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
Code | Description |
---|---|
200 | Successful request |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User not found |
Remove User Device
Remove a device and its associated session from a user.
Request
DELETE /api/users/{userId}/devices/{deviceId}
Path Parameters
Name | Type | Description |
---|---|---|
userId | integer | User ID |
deviceId | integer | Device ID |
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Response
{
"message": "Device removed successfully"
}
Response Codes
Code | Description |
---|---|
200 | Device successfully removed |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
404 | User or device not found |
Search Users
Search users by name or email.
Request
GET /api/users/search
Headers
Name | Type | Description |
---|---|---|
X-API-Key | string | Required. API key |
Query Parameters
Name | Type | Description |
---|---|---|
q | string | Required. 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
Code | Description |
---|---|
200 | Successful request |
401 | Invalid or missing API key |
403 | Insufficient permissions to perform request |
422 | Invalid request parameters (query too short) |