User Management

Manage users through the API.

The User Object

{
  "id": "usr_123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "status": "active",
  "avatar": "https://example.com/avatars/usr_123.jpg",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Attributes

Attribute	Type	Description
id	string	Unique identifier for the user
name	string	User's full name
email	string	User's email address
role	string	User role: admin, user, viewer
status	string	Account status: active, inactive, suspended
avatar	string	URL to user's avatar image
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update

List All Users

Retrieve a paginated list of users.

GET /v1/users

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max: 100)
role	string	-	Filter by role
status	string	-	Filter by status
search	string	-	Search by name or email

Example Request

curl -X GET "https://api.example.com/v1/users?page=1&limit=20&role=admin" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "usr_123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin",
      "status": "active",
      "avatar": "https://example.com/avatars/usr_123.jpg",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

Get a User

Retrieve details of a specific user.

GET /v1/users/{user_id}

Example Request

curl -X GET https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin",
    "status": "active",
    "avatar": "https://example.com/avatars/usr_123.jpg",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Create a User

Create a new user.

POST /v1/users

Request Body

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "role": "user",
  "password": "secure_password_123"
}

Example Request

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "user",
    "password": "secure_password_123"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "usr_456",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "user",
    "status": "active",
    "created_at": "2025-01-20T15:00:00Z",
    "updated_at": "2025-01-20T15:00:00Z"
  },
  "message": "User created successfully"
}

Update a User

Update an existing user's information.

PATCH /v1/users/{user_id}

Request Body

{
  "name": "John Smith",
  "role": "admin"
}

Example Request

curl -X PATCH https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "role": "admin"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "usr_123",
    "name": "John Smith",
    "email": "john@example.com",
    "role": "admin",
    "status": "active",
    "updated_at": "2025-01-20T16:00:00Z"
  },
  "message": "User updated successfully"
}

Delete a User

Delete a user permanently.

DELETE /v1/users/{user_id}

Example Request

curl -X DELETE https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "User deleted successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid email format",
    "field": "email"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "User not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "duplicate_email",
    "message": "A user with this email already exists"
  }
}