API Referencev1.0
Users API
API endpoints for managing user accounts and authentication.
Base URL:
https://api.example.com/v1GET
/usersRetrieve a paginated list of all users in the system.
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number for pagination (default: 1) |
limit | integer | Number of results per page (default: 20, max: 100) |
sort | string | Sort field (name, email, created_at) |
order | string | Sort order (asc, desc) |
Response
| Name | Type | Description |
|---|---|---|
data | User[] | Array of user objects |
meta.total | integer | Total number of users |
meta.page | integer | Current page number |
meta.pages | integer | Total number of pages |
Example
Request
GET /users?page=1&limit=10Response
{
"data": [
{
"id": "usr_123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2025-01-15T10:30:00Z"
}
],
"meta": {
"total": 150,
"page": 1,
"pages": 15
}
}POST
/usersCreate a new user account.
Request Body
| Name | Type | Description |
|---|---|---|
namerequired | string | Full name of the user |
emailrequired | string | Unique email address |
passwordrequired | string | Password (min 8 characters) |
role | string | User role (user, admin). Defaults to user |
Response
| Name | Type | Description |
|---|---|---|
id | string | Unique user identifier |
name | string | User's full name |
email | string | User's email address |
created_at | string | ISO 8601 timestamp |
Example
Request
POST /users
Content-Type: application/json
{
"name": "Jane Smith",
"email": "jane@example.com",
"password": "securePassword123"
}Response
{
"id": "usr_456",
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2025-01-20T14:22:00Z"
}DELETE
/users/:idPermanently delete a user account. This action cannot be undone.
Query Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | The unique identifier of the user to delete |
Example
Request
DELETE /users/usr_123Response
{
"success": true,
"message": "User deleted successfully"
}