Client Management

API endpoints for managing client accounts, including retrieving client information, listing clients, and updating client details.

BASE API ENDPOINT

/api/v1/client

Client Entity

Entity Schema

interface ClientEntity {
  clientId: string; // UUID - Client identifier
  email: string; // Client email address (unique)
  name: string; // Client display name
  roles: string[]; // User roles (array, typically ['client'])
  emailConfirmed: boolean; // Email confirmation status
  createdAt: string; // ISO 8601 timestamp - Account creation
  updatedAt: string; // ISO 8601 timestamp - Last update
  lastLogin?: string; // ISO 8601 timestamp - Last login (optional)
  totalRequests: number; // Total number of requests created
  activeRequests: number; // Number of requests currently in progress
  completedRequests: number; // Number of successfully completed requests
}

Field Descriptions:

clientId: Unique identifier (UUID) for the client
email: Client's email address (unique, used for login)
name: Display name of the client
roles: User roles array (typically ['client'] for client accounts, can include ['admin', 'client'])
emailConfirmed: Whether the client has confirmed their email address
createdAt: Timestamp when the client account was created
updatedAt: Timestamp when the client account was last updated
lastLogin: Timestamp of the client's last login (optional, null if never logged in)
totalRequests: Total count of all requests created by the client
activeRequests: Count of requests currently being processed
completedRequests: Count of successfully completed requests

Client Endpoints

Get Client by ID

Endpoint: GET /api/v1/client/:id

Headers:

Authorization: Bearer ACCESS_TOKEN

Path Parameters:

id (string, required) - Client UUID

Response: 200 OK

{
  "success": true,
  "data": {
    "clientId": "uuid-here",
    "email": "client@example.com",
    "name": "John Doe",
    "emailConfirmed": true,
    "createdAt": "2024-01-22T14:30:00Z",
    "updatedAt": "2024-01-23T10:15:00Z",
    "lastLogin": "2024-01-23T10:15:00Z",
    "totalRequests": 5,
    "activeRequests": 2
  }
}

Error Response: 404 Not Found

{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "Client not found with ID: uuid-here"
  }
}

List Clients

Endpoint: GET /api/v1/client

Headers:

Authorization: Bearer ACCESS_TOKEN

Query Parameters:

page (int, optional, default: 1) - Page number
limit (int, optional, default: 10, max: 100) - Items per page
search (string, optional) - Search by email or name

Epic 3 - Advanced Filtering

The following filters will be available in Epic 3:

emailConfirmed (boolean) - Filter by email confirmation status
sortBy (string) - Sort field (createdAt, lastLogin, name, email)
sortOrder (string) - Sort order (asc, desc)

Response: 200 OK

{
  "success": true,
  "data": {
    "clients": [
      {
        "clientId": "uuid-1",
        "email": "client1@example.com",
        "name": "John Doe",
        "emailConfirmed": true,
        "createdAt": "2024-01-22T14:30:00Z",
        "lastLogin": "2024-01-23T10:15:00Z",
        "totalRequests": 5,
        "activeRequests": 2
      },
      {
        "clientId": "uuid-2",
        "email": "client2@example.com",
        "name": "Jane Smith",
        "emailConfirmed": false,
        "createdAt": "2024-01-20T09:00:00Z",
        "lastLogin": null,
        "totalRequests": 0,
        "activeRequests": 0
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalClients": 47,
      "limit": 10,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

Update Client

Endpoint: PATCH /api/v1/client/:id

Headers:

Authorization: Bearer ACCESS_TOKEN

Path Parameters:

id (string, required) - Client UUID

Request Body:

{
  "name": "John Doe Updated"
}

Response: 200 OK

{
  "success": true,
  "data": {
    "clientId": "uuid-here",
    "email": "client@example.com",
    "name": "John Doe Updated",
    "emailConfirmed": true,
    "updatedAt": "2024-01-24T12:00:00Z"
  },
  "message": "Client updated successfully."
}

Error Response: 404 Not Found

{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "Client not found with ID: uuid-here"
  }
}

Delete Client

Endpoint: DELETE /api/v1/client/:id

Headers:

Authorization: Bearer ADMIN_ACCESS_TOKEN

Admin Only

This endpoint requires admin authentication. Regular clients cannot delete accounts.

Path Parameters:

id (string, required) - Client UUID

Response: 200 OK

{
  "success": true,
  "message": "Client deleted successfully."
}

Error Response: 404 Not Found

{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "Client not found with ID: uuid-here"
  }
}

Error Response: 403 Forbidden (If client has active requests)

{
  "success": false,
  "error": {
    "code": "CLIENT_HAS_ACTIVE_REQUESTS",
    "message": "Cannot delete client with active requests. Please complete or cancel all requests first."
  }
}

Client Requests

Get Client Requests

Endpoint: GET /api/v1/client/:id/requests

Headers:

Authorization: Bearer ACCESS_TOKEN

Path Parameters:

id (string, required) - Client UUID

Query Parameters:

page (int, optional, default: 1) - Page number
limit (int, optional, default: 10, max: 50) - Items per page
status (string, optional) - Filter by status (pending, processing, completed)

Response: 200 OK

{
  "success": true,
  "data": {
    "requests": [
      {
        "requestId": "REQ-001234",
        "text": "Welcome to MicDots! Scan the QR code...",
        "voiceId": "voice-001",
        "voiceName": "Rachel",
        "status": "completed",
        "audioUrl": "https://s3.amazonaws.com/micdots-audio/REQ-001234.mp3",
        "slug": "welcome-message-123456",
        "playbackUrl": "https://micdots.com/play/welcome-message-123456",
        "createdAt": "2024-01-22T14:30:00Z",
        "completedAt": "2024-01-22T16:45:00Z"
      },
      {
        "requestId": "REQ-001235",
        "text": "Today's special is pan-seared salmon...",
        "voiceId": "voice-002",
        "voiceName": "Adam",
        "status": "processing",
        "audioUrl": null,
        "slug": "todays-special-salmon-123457",
        "playbackUrl": null,
        "createdAt": "2024-01-23T10:00:00Z",
        "completedAt": null
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 3,
      "totalRequests": 25,
      "limit": 10
    }
  }
}

Testing Endpoints

Using cURL

Get Client by ID:

curl -X GET http://localhost:5000/api/v1/client/CLIENT_ID_HERE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Clients:

curl -X GET "http://localhost:5000/api/v1/client?page=1&limit=10&search=john" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Client:

curl -X PATCH http://localhost:5000/api/v1/client/CLIENT_ID_HERE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Updated Name"
  }'

Delete Client:

curl -X DELETE http://localhost:5000/api/v1/client/CLIENT_ID_HERE \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

Get Client Requests:

curl -X GET "http://localhost:5000/api/v1/client/CLIENT_ID_HERE/requests?page=1&limit=10&status=completed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Access Control

Who Can Access These Endpoints?

GET /api/v1/client/:id:

Client can view their own profile
Admins can view any client profile

GET /api/v1/client (List):

Admin only

PATCH /api/v1/client/:id:

Client can update their own profile
Admins can update any client profile

DELETE /api/v1/client/:id:

Admin only

GET /api/v1/client/:id/requests:

Client can view their own requests
Admins can view any client's requests

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token."
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource."
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "Client not found with ID: uuid-here"
  }
}

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "name": ["Name must be between 2 and 100 characters."]
    }
  }
}

Authentication - Client registration and login
Request Management - Managing text-to-audio requests
Epic 1 Overview - Complete feature overview

Client Entity​

Entity Schema​

Client Endpoints​

Get Client by ID​

List Clients​

Update Client​

Delete Client​

Client Requests​

Get Client Requests​

Testing Endpoints​

Using cURL​

Access Control​

Who Can Access These Endpoints?​

Error Responses​

401 Unauthorized​

403 Forbidden​

404 Not Found​

400 Bad Request​

Related Documentation​

Client Entity

Entity Schema

Client Endpoints

Get Client by ID

List Clients

Update Client

Delete Client

Client Requests

Get Client Requests

Testing Endpoints

Using cURL

Access Control

Who Can Access These Endpoints?

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

400 Bad Request

Related Documentation