Users API Documentation

GET /api/v1/users

List all users in the organization with pagination.

Parameters

Name	Type	Required	Description
`page`	integer	Optional	Page number, default 1
`per_page`	integer	Optional	Results per page, default 20, max 100
`role`	string	Optional	Filter by role (admin, member, viewer)
`status`	string	Optional	Filter by status (active, suspended, pending)

Response Fields

Name	Type	Required	Description
`users`	array	Optional	List of user objects
`total`	integer	Optional	Total number of matching users
`page`	integer	Optional	Current page
`per_page`	integer	Optional	Results per page

Example Response

{
  "users": [],
  "total": 42,
  "page": 42,
  "per_page": 42
}

GET /api/v1/users/{user_id}

Get detailed profile for a specific user.

Parameters

Name	Type	Required	Description
`user_id`	string	Required	The unique user identifier

Response Fields

Name	Type	Required	Description
`id`	string	Optional	User ID
`email`	string	Optional	User email address
`name`	string	Optional	Full name
`role`	string	Optional	User role
`created_at`	string	Optional	ISO 8601 timestamp
`last_login`	string	Optional	ISO 8601 timestamp of last login

Example Response

{
  "id": "id_123",
  "email": "user@example.com",
  "name": "name value",
  "role": "role value",
  "created_at": "created at value",
  "last_login": "last login value"
}

POST /api/v1/users

Create a new user account.

Parameters

Name	Type	Required	Description
`email`	string	Required	Email address for the new user
`name`	string	Required	Full name
`role`	string	Optional	Role assignment, default "member"

Response Fields

Name	Type	Required	Description
`id`	string	Optional	New user ID
`email`	string	Optional	Confirmed email
`status`	string	Optional	"pending" until email verified

Example Response

{
  "id": "id_123",
  "email": "user@example.com",
  "status": "pending"
}

PATCH /api/v1/users/{user_id}

Update user profile fields.

Parameters

Name	Type	Required	Description
`user_id`	string	Required	User to update
`name`	string	Optional	Updated name
`role`	string	Optional	Updated role

Response Fields

Name	Type	Required	Description
`id`	string	Optional	User ID
`updated_fields`	array	Optional	List of fields that were changed

Example Response

{
  "id": "id_123",
  "updated_fields": []
}

DELETE /api/v1/users/{user_id}

Deactivate a user account. Does not permanently delete data.

Parameters

Name	Type	Required	Description
`user_id`	string	Required	User to deactivate

Response Fields

Name	Type	Required	Description
`status`	string	Optional	"deactivated"

Example Response

{
  "status": "deactivated"
}