User Management API Documentation

Endpoints

GET
/kb/api/v1/users
Retrieves a list of all users.

Query Parameters

Name Type Description Required
limit integer Maximum number of users to return. No
offset integer Number of users to skip before returning results. No
sortBy string Field to sort users by (e.g., 'username', 'createdAt'). No
sortOrder string Order of sorting ('asc' or 'desc'). No

Responses

Status Code Content Type Description
200 OK application/json Success An array of user objects.
401 Unauthorized application/json Unauthorized Authentication credentials are required or invalid.
500 Internal Server Error application/json Error An unexpected error occurred on the server.

Example Response (200 OK):

[
  {
    "id": "user-123",
    "username": "alice_wonder",
    "email": "alice@example.com",
    "role": "admin",
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  },
  {
    "id": "user-456",
    "username": "bob_the_builder",
    "email": "bob@example.com",
    "role": "editor",
    "createdAt": "2023-10-26T15:30:00Z",
    "updatedAt": "2023-10-26T15:30:00Z"
  }
]
POST
/kb/api/v1/users
Creates a new user.

Request Body

Name Type Description Required
username string The desired username for the new user. Yes
email string The email address of the new user. Must be unique. Yes
password string The password for the new user. Yes
role string The role assigned to the user (e.g., 'user', 'editor', 'admin'). No (defaults to 'user')

Responses

Status Code Content Type Description
201 Created application/json Success The newly created user object.
400 Bad Request application/json Invalid Input The request body is missing required fields or contains invalid data.
409 Conflict application/json Conflict A user with the provided email or username already exists.
401 Unauthorized application/json Unauthorized Authentication credentials are required or invalid.

Example Response (201 Created):

{
  "id": "user-789",
  "username": "charlie_chaplin",
  "email": "charlie@example.com",
  "role": "user",
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:00:00Z"
}
Authentication: This API requires authentication. Requests must include a valid API key in the Authorization header as a Bearer token (e.g., Authorization: Bearer YOUR_API_KEY).