Users API

Users API v1 Comprehensive user and team member management system.

This API provides complete control over team membership, user roles, permissions, and team administration.

Key capabilities:

• Team member management (list, invite, update, remove)

• Role-based access control (admin, editor, viewer, deactivated)

• User profile management and updates

• Team invitation system with email notifications

• Subscription and billing integration for user limits

• User activity tracking and audit logs Security features:

• All operations require proper authentication

• Team-based isolation ensures data privacy

• Role validation prevents unauthorized access

• Audit trails for all user management actions

Endpoints

List users

List team members

Retrieve a paginated list of team members for the authenticated team. Returns user profiles with their roles.

Endpoint: GET /api/v1/users

Examples:

curl -X GET "https://simplistica.co/api/v1/users?limit=20&page=1" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Query Parameters:

• limit (integer) Optional (default: 20) - Number of items to return
• page (integer) Optional (default: 1) - Page number for pagination (starts from 1)

Response Schema:

Example Response:

{
  "path": "/api/v1/users",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "example_title",
        "type": "document",
        "reviewStatus": "draft",
        "createdAt": "2025-01-27T10:30:00.000Z",
        "updatedAt": "2025-01-27T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasNextPage": true,
      "prevPage": null,
      "nextPage": "https://simplistica.co/api/v1/documents?limit=20&page=2"
    }
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Get user by ID

Get user details

Retrieve detailed information about a specific team member by their ID.

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

Examples:

curl -X GET "https://simplistica.co/api/v1/users/{id}?limit=20&page=1" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Parameters:

Path Parameters:

• id (string) Required - The id of the resource

Query Parameters:

• limit (integer) Optional (default: 20) - Number of items to return
• page (integer) Optional (default: 1) - Page number for pagination (starts from 1)

Response Schema:

Example Response:

{
  "path": "/api/v1/users/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z",
    "owner": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example_name",
      "email": "user@example.com"
    },
    "ownerTeam": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example_name"
    }
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 500: Internal Server Error

Create user

Create a new team member

Create a new team member or add an existing user to the team. If the user already exists, they will be added to the team with the specified role. For new users, an authentication account will be created first. The API will automatically handle subscription limits and auto-scaling based on the team’s tier.

Endpoint: POST /api/v1/users

Examples:

curl -X POST "https://simplistica.co/api/v1/users" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{}'

Request Body Schema:

{
  "$ref": "#/components/schemas/CreateUserSchema"
}

Response Schema:

Example Response:

{
  "path": "/api/v1/users",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Invite user to team

POST operation for users

Endpoint: POST /api/v1/users/invite

Examples:

curl -X POST "https://simplistica.co/api/v1/users/invite" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "example_email",
       "role": "admin"
     }'

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/users/invite",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Update user

Update user

Update user profile information (name, email) or team role. Only fields provided will be updated.

Endpoint: PUT /api/v1/users/{id}

Examples:

curl -X PUT "https://simplistica.co/api/v1/users/{id}" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "example_name",
       "email": "example_email",
       "username": "example_username",
       "role": "admin",
       "force": false
     }'

Path Parameters:

• id (string) Required - The id of the resource

Request Body Schema:

Response Schema:

Example Response:

{
  "path": "/api/v1/users/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "example_title",
    "content": "example_content",
    "type": "document",
    "reviewStatus": "draft",
    "createdAt": "2025-01-27T10:30:00.000Z",
    "updatedAt": "2025-01-27T10:30:00.000Z"
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Delete user

Remove user from team

Remove a user from the team. This does not delete the user’s profile, only their team membership.

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

Examples:

curl -X DELETE "https://simplistica.co/api/v1/users/{id}" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

Path Parameters:

• id (string) Required - The id of the resource

Response Schema:

Example Response:

{
  "path": "/api/v1/users/{id}",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": {
    "message": "example_message",
    "success": true
  }
}

Responses:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 500: Internal Server Error

Response Examples

Success Response

{
  "path": "/api/v1/users",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "data": null,
  "message": "Operation completed successfully"
}

Error Response

{
  "path": "/api/v1/users",
  "version": "v1",
  "timestamp": "2025-01-27T10:30:00.000Z",
  "error": "Validation Error",
  "message": "Required field 'email' is missing"
}

Common HTTP Status Codes

• 200: Success
• 201: Created
• 400: Bad Request (validation error)
• 401: Unauthorized (invalid or missing token)
• 404: Not Found (resource doesn’t exist)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error