# API Reference

This document describes the Smartbotic Microbit REST API.

## Base URL

```
http://localhost:8090/api/v1
```

In production, use your configured domain with HTTPS.

## Authentication

Most endpoints require authentication using JWT (JSON Web Tokens).

### Authorization Header

Include the access token in the `Authorization` header:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Token Lifecycle

- **Access Token**: Short-lived (default: 15 minutes), used for API requests
- **Refresh Token**: Long-lived (default: 7 days), used to obtain new access tokens

## Common Response Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created successfully |
| 400 | Bad request (invalid input) |
| 401 | Unauthorized (missing or invalid token) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not found |
| 500 | Internal server error |

## Error Response Format

```json
{
  "error": "Error message describing the problem"
}
```

---

## Authentication Endpoints

### Register User

Create a new user account.

**Endpoint:** `POST /api/v1/auth/register`

**Authentication:** Not required

**Request Body:**

```json
{
  "email": "user@example.com",
  "password": "SecurePass123",
  "display_name": "John Doe",
  "invite_token": "optional-invite-token"
}
```

**Response:** `201 Created`

```json
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "display_name": "John Doe",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

**Notes:**
- Password must meet policy requirements (min 8 chars, contains number by default)
- If `invite_token` is provided, pending invitations for this email will be processed

### Login

Authenticate and receive access tokens.

**Endpoint:** `POST /api/v1/auth/login`

**Authentication:** Not required

**Request Body:**

```json
{
  "email": "user@example.com",
  "password": "SecurePass123"
}
```

**Response:** `200 OK`

```json
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "display_name": "John Doe",
    "status": "active"
  },
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

### Refresh Token

Obtain a new access token using a refresh token.

**Endpoint:** `POST /api/v1/auth/refresh`

**Authentication:** Not required

**Request Body:**

```json
{
  "refresh_token": "eyJhbGc..."
}
```

**Response:** `200 OK`

```json
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

### Logout

Invalidate the current session.

**Endpoint:** `POST /api/v1/auth/logout`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "message": "Logged out successfully"
}
```

### Get Current User

Get information about the authenticated user.

**Endpoint:** `GET /api/v1/auth/me`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "display_name": "John Doe",
    "status": "active"
  }
}
```

### Change Password

Change the current user's password.

**Endpoint:** `POST /api/v1/auth/change-password`

**Authentication:** Required

**Request Body:**

```json
{
  "old_password": "OldPass123",
  "new_password": "NewPass456"
}
```

**Response:** `200 OK`

```json
{
  "message": "Password changed successfully"
}
```

---

## User Endpoints

### Update Current User

Update the authenticated user's profile.

**Endpoint:** `PUT /api/v1/users/me`

**Authentication:** Required

**Request Body:**

```json
{
  "display_name": "Jane Doe"
}
```

**Response:** `200 OK`

```json
{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "display_name": "Jane Doe",
    "status": "active"
  }
}
```

---

## Workspace Endpoints

### List Workspaces

List all workspaces the user is a member of.

**Endpoint:** `GET /api/v1/workspaces`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "workspaces": [
    {
      "id": "ws_xyz789",
      "name": "My Company",
      "company_name": "Acme Corp",
      "address": "123 Main St",
      "phone": "+1-555-0100",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}
```

### Create Workspace

Create a new workspace.

**Endpoint:** `POST /api/v1/workspaces`

**Authentication:** Required

**Request Body:**

```json
{
  "name": "My Company",
  "company_name": "Acme Corp",
  "address": "123 Main St",
  "phone": "+1-555-0100"
}
```

**Response:** `201 Created`

```json
{
  "workspace": {
    "id": "ws_xyz789",
    "name": "My Company",
    "company_name": "Acme Corp",
    "address": "123 Main St",
    "phone": "+1-555-0100"
  }
}
```

**Notes:**
- The creator becomes the workspace owner automatically

### Get Workspace

Get details of a specific workspace.

**Endpoint:** `GET /api/v1/workspaces/:id`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "workspace": {
    "id": "ws_xyz789",
    "name": "My Company",
    "company_name": "Acme Corp",
    "address": "123 Main St",
    "phone": "+1-555-0100"
  }
}
```

### Update Workspace

Update workspace details.

**Endpoint:** `PUT /api/v1/workspaces/:id`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "name": "Updated Name",
  "company_name": "New Corp Name",
  "address": "456 Oak Ave",
  "phone": "+1-555-0200"
}
```

**Response:** `200 OK`

```json
{
  "workspace": { /* updated workspace */ }
}
```

### Delete Workspace

Delete a workspace permanently.

**Endpoint:** `DELETE /api/v1/workspaces/:id`

**Authentication:** Required

**Authorization:** Owner only

**Response:** `200 OK`

```json
{
  "message": "Workspace deleted"
}
```

### List Workspace Members

Get all members of a workspace.

**Endpoint:** `GET /api/v1/workspaces/:id/members`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "members": [
    {
      "id": "wm_mem123",
      "workspace_id": "ws_xyz789",
      "user_id": "usr_abc123",
      "role": "owner",
      "user": {
        "email": "owner@example.com",
        "display_name": "Owner Name"
      }
    }
  ]
}
```

### Update Member Role

Change a member's role in the workspace.

**Endpoint:** `PUT /api/v1/workspaces/:wsId/members/:memberId/role`

**Authentication:** Required

**Authorization:** Admin+ (cannot change owner role)

**Request Body:**

```json
{
  "role": "admin"
}
```

**Valid roles:** `owner`, `admin`, `member`, `guest`

**Response:** `200 OK`

```json
{
  "member": { /* updated member */ }
}
```

### Remove Member

Remove a member from the workspace.

**Endpoint:** `DELETE /api/v1/workspaces/:wsId/members/:memberId`

**Authentication:** Required

**Authorization:** Admin+ (cannot remove owner)

**Response:** `200 OK`

```json
{
  "message": "Member removed"
}
```

---

## Invitation Endpoints

### Create Invitation

Invite a user to join a workspace.

**Endpoint:** `POST /api/v1/workspaces/:id/invitations`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "email": "newuser@example.com",
  "role": "member"
}
```

**Response:** `201 Created`

```json
{
  "invitation": {
    "id": "inv_token123",
    "workspace_id": "ws_xyz789",
    "email": "newuser@example.com",
    "role": "member",
    "token": "secure-token-here",
    "status": "pending"
  }
}
```

**Notes:**
- If SMTP is configured, an invitation email will be sent

### List Workspace Invitations

Get all pending invitations for a workspace.

**Endpoint:** `GET /api/v1/workspaces/:id/invitations`

**Authentication:** Required

**Authorization:** Admin+

**Response:** `200 OK`

```json
{
  "invitations": [
    {
      "id": "inv_token123",
      "workspace_id": "ws_xyz789",
      "email": "newuser@example.com",
      "role": "member",
      "status": "pending"
    }
  ]
}
```

### Cancel Invitation

Cancel a pending invitation.

**Endpoint:** `DELETE /api/v1/workspaces/:wsId/invitations/:invId`

**Authentication:** Required

**Authorization:** Admin+

**Response:** `200 OK`

```json
{
  "message": "Invitation cancelled"
}
```

### List My Pending Invitations

Get all pending invitations for the authenticated user.

**Endpoint:** `GET /api/v1/invitations/pending`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "invitations": [
    {
      "id": "inv_token123",
      "workspace_id": "ws_xyz789",
      "email": "user@example.com",
      "role": "member",
      "status": "pending",
      "workspace": {
        "name": "Company Name"
      }
    }
  ]
}
```

### Accept Invitation

Accept a workspace invitation.

**Endpoint:** `POST /api/v1/invitations/:id/accept`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "message": "Invitation accepted",
  "workspace_id": "ws_xyz789"
}
```

### Decline Invitation

Decline a workspace invitation.

**Endpoint:** `POST /api/v1/invitations/:id/decline`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "message": "Invitation declined"
}
```

---

## Assistant Endpoints

AI voice assistant management.

### List Assistants

List all assistants in a workspace.

**Endpoint:** `GET /api/v1/workspaces/:id/assistants`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "assistants": [
    {
      "id": "ast_ai123",
      "workspace_id": "ws_xyz789",
      "name": "Support Bot",
      "phone_number": "+1-555-0300",
      "instructions": "You are a helpful assistant...",
      "callerai_id": "callerai_ext_id",
      "status": "active"
    }
  ]
}
```

### Create Assistant

Create a new AI assistant.

**Endpoint:** `POST /api/v1/workspaces/:id/assistants`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "name": "Support Bot",
  "phone_number": "+1-555-0300",
  "instructions": "You are a helpful customer support assistant for Acme Corp...",
  "voice": "en-US-Neural2-J",
  "provider": "twilio",
  "provider_config": {
    "account_sid": "AC...",
    "auth_token": "..."
  }
}
```

**Response:** `201 Created`

```json
{
  "assistant": {
    "id": "ast_ai123",
    "workspace_id": "ws_xyz789",
    "name": "Support Bot",
    "phone_number": "+1-555-0300",
    "callerai_id": "callerai_ext_id",
    "status": "active"
  }
}
```

### Get Assistant

Get details of a specific assistant.

**Endpoint:** `GET /api/v1/workspaces/:wsId/assistants/:id`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "assistant": { /* assistant object */ }
}
```

### Update Assistant

Update assistant configuration.

**Endpoint:** `PUT /api/v1/workspaces/:wsId/assistants/:id`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "name": "Updated Name",
  "instructions": "New instructions...",
  "status": "active"
}
```

**Response:** `200 OK`

```json
{
  "assistant": { /* updated assistant */ }
}
```

### Update Assistant Voice

Update assistant voice settings.

**Endpoint:** `PUT /api/v1/workspaces/:wsId/assistants/:id/voice`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "voice": "en-US-Neural2-C",
  "language": "en-US"
}
```

**Response:** `200 OK`

```json
{
  "assistant": { /* updated assistant */ }
}
```

### Delete Assistant

Delete an assistant.

**Endpoint:** `DELETE /api/v1/workspaces/:wsId/assistants/:id`

**Authentication:** Required

**Authorization:** Admin+

**Response:** `200 OK`

```json
{
  "message": "Assistant deleted"
}
```

### Get Available Phone Numbers

Get available phone numbers from CallerAI.

**Endpoint:** `GET /api/v1/callerai/phone-numbers`

**Authentication:** Required

**Query Parameters:**
- `country_code`: ISO country code (e.g., "US")

**Response:** `200 OK`

```json
{
  "phone_numbers": [
    {
      "number": "+1-555-0100",
      "friendly_name": "+1 (555) 010-0100",
      "capabilities": ["voice", "sms"]
    }
  ]
}
```

### Get Available Voices

Get available voices for a language.

**Endpoint:** `GET /api/v1/callerai/voices/:language`

**Authentication:** Required

**Path Parameters:**
- `language`: Language code (e.g., "en-US")

**Response:** `200 OK`

```json
{
  "voices": [
    {
      "id": "en-US-Neural2-J",
      "name": "English (US) - Neural2 J",
      "gender": "male"
    }
  ]
}
```

### Get Provider Configurations

Get available telephony provider configurations.

**Endpoint:** `GET /api/v1/callerai/provider-configs`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "providers": [
    {
      "id": "twilio",
      "name": "Twilio",
      "fields": [
        {"name": "account_sid", "type": "string", "required": true},
        {"name": "auth_token", "type": "password", "required": true}
      ]
    }
  ]
}
```

---

## Calendar Endpoints

### List Calendars

List all calendars in a workspace.

**Endpoint:** `GET /api/v1/workspaces/:id/calendars`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "calendars": [
    {
      "id": "cal_cal123",
      "workspace_id": "ws_xyz789",
      "name": "Support Calendar",
      "assistant_id": "ast_ai123"
    }
  ]
}
```

### Create Calendar

Create a new calendar.

**Endpoint:** `POST /api/v1/workspaces/:id/calendars`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "name": "Support Calendar",
  "assistant_id": "ast_ai123"
}
```

**Response:** `201 Created`

```json
{
  "calendar": {
    "id": "cal_cal123",
    "workspace_id": "ws_xyz789",
    "name": "Support Calendar",
    "assistant_id": "ast_ai123"
  }
}
```

### Get Calendar

Get calendar details.

**Endpoint:** `GET /api/v1/workspaces/:wsId/calendars/:id`

**Authentication:** Required

**Authorization:** Member+

**Response:** `200 OK`

```json
{
  "calendar": { /* calendar object */ }
}
```

### Update Calendar

Update calendar details.

**Endpoint:** `PUT /api/v1/workspaces/:wsId/calendars/:id`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "name": "Updated Calendar Name",
  "assistant_id": "ast_ai456"
}
```

**Response:** `200 OK`

```json
{
  "calendar": { /* updated calendar */ }
}
```

### Delete Calendar

Delete a calendar.

**Endpoint:** `DELETE /api/v1/workspaces/:wsId/calendars/:id`

**Authentication:** Required

**Authorization:** Admin+

**Response:** `200 OK`

```json
{
  "message": "Calendar deleted"
}
```

---

## Time Slot Endpoints

### List Time Slots

Get all time slots for a calendar.

**Endpoint:** `GET /api/v1/calendars/:id/time-slots`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "time_slots": [
    {
      "id": "ts_slot123",
      "calendar_id": "cal_cal123",
      "day_of_week": 1,
      "start_time": "09:00",
      "end_time": "17:00"
    }
  ]
}
```

**Note:** `day_of_week`: 0=Sunday, 1=Monday, ..., 6=Saturday

### Create Time Slot

Add a time slot to a calendar.

**Endpoint:** `POST /api/v1/calendars/:id/time-slots`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00"
}
```

**Response:** `201 Created`

```json
{
  "time_slot": {
    "id": "ts_slot123",
    "calendar_id": "cal_cal123",
    "day_of_week": 1,
    "start_time": "09:00",
    "end_time": "17:00"
  }
}
```

### Update Time Slot

Update a time slot.

**Endpoint:** `PUT /api/v1/calendars/:calId/time-slots/:id`

**Authentication:** Required

**Authorization:** Admin+

**Request Body:**

```json
{
  "day_of_week": 2,
  "start_time": "10:00",
  "end_time": "18:00"
}
```

**Response:** `200 OK`

```json
{
  "time_slot": { /* updated time slot */ }
}
```

### Delete Time Slot

Remove a time slot.

**Endpoint:** `DELETE /api/v1/calendars/:calId/time-slots/:id`

**Authentication:** Required

**Authorization:** Admin+

**Response:** `200 OK`

```json
{
  "message": "Time slot deleted"
}
```

### Get Available Slots

Get available appointment slots for a date range.

**Endpoint:** `GET /api/v1/calendars/:id/available-slots`

**Authentication:** Not required (public endpoint)

**Query Parameters:**
- `start_date`: Start date (YYYY-MM-DD)
- `end_date`: End date (YYYY-MM-DD)
- `duration_minutes`: Appointment duration (default: 30)

**Response:** `200 OK`

```json
{
  "available_slots": [
    {
      "date": "2024-01-20",
      "start_time": "09:00",
      "end_time": "09:30"
    }
  ]
}
```

---

## Appointment Endpoints

### List Workspace Appointments

List all appointments in a workspace.

**Endpoint:** `GET /api/v1/workspaces/:id/appointments`

**Authentication:** Required

**Authorization:** Member+

**Query Parameters:**
- `start_date`: Filter by start date (YYYY-MM-DD)
- `end_date`: Filter by end date (YYYY-MM-DD)
- `status`: Filter by status (pending, confirmed, cancelled)

**Response:** `200 OK`

```json
{
  "appointments": [
    {
      "id": "apt_appt123",
      "calendar_id": "cal_cal123",
      "start_time": "2024-01-20T09:00:00Z",
      "end_time": "2024-01-20T09:30:00Z",
      "customer_name": "John Smith",
      "customer_phone": "+1-555-1234",
      "customer_email": "john@example.com",
      "notes": "Consultation call",
      "status": "confirmed"
    }
  ]
}
```

### Create Appointment

Book a new appointment.

**Endpoint:** `POST /api/v1/calendars/:id/appointments`

**Authentication:** Not required (public endpoint for customer booking)

**Request Body:**

```json
{
  "start_time": "2024-01-20T09:00:00Z",
  "end_time": "2024-01-20T09:30:00Z",
  "customer_name": "John Smith",
  "customer_phone": "+1-555-1234",
  "customer_email": "john@example.com",
  "notes": "Need help with product setup"
}
```

**Response:** `201 Created`

```json
{
  "appointment": {
    "id": "apt_appt123",
    "calendar_id": "cal_cal123",
    "start_time": "2024-01-20T09:00:00Z",
    "end_time": "2024-01-20T09:30:00Z",
    "customer_name": "John Smith",
    "status": "pending"
  }
}
```

### Cancel Appointment

Cancel an existing appointment.

**Endpoint:** `PUT /api/v1/appointments/:id/cancel`

**Authentication:** Not required (public endpoint)

**Response:** `200 OK`

```json
{
  "appointment": {
    "id": "apt_appt123",
    "status": "cancelled"
  }
}
```

---

## Settings Endpoints

### Get Global Settings

Get global platform settings.

**Endpoint:** `GET /api/v1/settings`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "settings": {
    "smtp_configured": true,
    "callerai_configured": true,
    "registration_enabled": true
  }
}
```

### Update Global Settings

Update platform settings.

**Endpoint:** `PUT /api/v1/settings`

**Authentication:** Required

**Authorization:** System admin (future feature)

**Request Body:**

```json
{
  "registration_enabled": false
}
```

**Response:** `200 OK`

```json
{
  "settings": { /* updated settings */ }
}
```

### Test SMTP Configuration

Test SMTP email sending.

**Endpoint:** `POST /api/v1/settings/test-smtp`

**Authentication:** Required

**Request Body:**

```json
{
  "to_email": "test@example.com"
}
```

**Response:** `200 OK`

```json
{
  "success": true,
  "message": "Test email sent successfully"
}
```

### Test CallerAI Configuration

Test CallerAI API connection.

**Endpoint:** `POST /api/v1/settings/test-callerai`

**Authentication:** Required

**Response:** `200 OK`

```json
{
  "success": true,
  "message": "CallerAI connection successful"
}
```

---

## Data Models

### User Object

```json
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "display_name": "John Doe",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### Workspace Object

```json
{
  "id": "ws_xyz789",
  "name": "My Company",
  "company_name": "Acme Corp",
  "address": "123 Main St",
  "phone": "+1-555-0100",
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-10T08:00:00Z"
}
```

### Role Hierarchy

From highest to lowest permission:

1. **Owner**: Full control, can delete workspace, manage all members
2. **Admin**: Manage members (except owner), assistants, calendars, settings
3. **Member**: View and use workspace resources, book appointments
4. **Guest**: Read-only access

---

## Rate Limiting

Rate limiting is configurable and applies per IP address:

- Default: 200 requests per minute
- Configuration: `rate_limit.requests_per_minute` in config

When rate limited, the API returns:

```
HTTP 429 Too Many Requests
{
  "error": "Rate limit exceeded"
}
```

---

## WebSocket Support

WebSocket support is planned for future releases to enable:
- Real-time appointment notifications
- Assistant status updates
- Live call monitoring

---

## Versioning

The API version is included in the URL path (`/api/v1/`). Future versions will maintain backward compatibility or introduce new version paths (e.g., `/api/v2/`).

---

## Additional Notes

### Date/Time Format

All timestamps use ISO 8601 format in UTC:
- `2024-01-20T09:00:00Z`

### Phone Number Format

Phone numbers should be in E.164 format:
- `+1-555-0100` (recommended)
- `+15550100` (also accepted)

### ID Prefixes

Entity IDs use prefixes for easy identification:
- `usr_`: User
- `ws_`: Workspace
- `wm_`: Workspace Member
- `ast_`: Assistant
- `cal_`: Calendar
- `ts_`: Time Slot
- `apt_`: Appointment
- `inv_`: Invitation
- `ses_`: Session

### CORS

CORS is configurable in `config/microbit.json`:

```json
{
  "cors": {
    "enabled": true,
    "origins": ["*"],
    "methods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
    "headers": ["Authorization", "Content-Type"]
  }
}
```