API Docs

Acme API - Users Management

API Users Endpoints Overview: Manage user accounts, profiles, and permissions through these endpoints.

Endpoint: GET /api/v1/users

Description: List all users in the organization with pagination.
Parameters:
  - 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:
  - users (array): List of user objects
  - total (integer): Total number of matching users
  - page (integer): Current page
  - per_page (integer): Results per page

Endpoint: GET /api/v1/users/{user_id}

Description: Get detailed profile for a specific user.
Parameters:
  - user_id (string, required): The unique user identifier
Response:
  - id (string): User ID
  - email (string): User email address
  - name (string): Full name
  - role (string): User role
  - created_at (string): ISO 8601 timestamp
  - last_login (string): ISO 8601 timestamp of last login

Endpoint: POST /api/v1/users

Description: Create a new user account.
Parameters:
  - email (string, required): Email address for the new user
  - name (string, required): Full name
  - role (string, optional): Role assignment, default "member"
Response:
  - id (string): New user ID
  - email (string): Confirmed email
  - status (string): "pending" until email verified

Endpoint: PATCH /api/v1/users/{user_id}

Description: Update user profile fields.
Parameters:
  - user_id (string, required): User to update
  - name (string, optional): Updated name
  - role (string, optional): Updated role
Response:
  - id (string): User ID
  - updated_fields (array): List of fields that were changed

Endpoint: DELETE /api/v1/users/{user_id}

Description: Deactivate a user account. Does not permanently delete data.
Parameters:
  - user_id (string, required): User to deactivate
Response:
  - status (string): "deactivated"