Главная Обзор Помощь
Вход
fszontagh
/
smartbotic-microbit
1
0
Ответвить 0
Файлы Задачи 1 Запросы на слияние 0 Вики
Ветка: main
Ветки Метки
smartbotic-micr...
/
docs
/
API.md

API.md 21 KB
Постоянная ссылка История Исходник

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

{
  "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:

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

Response: 201 Created

{
  "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:

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

Response: 200 OK

{
  "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:

{
  "refresh_token": "eyJhbGc..."
}

Response: 200 OK

{
  "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

{
  "message": "Logged out successfully"
}

Get Current User

Get information about the authenticated user.

Endpoint: GET /api/v1/auth/me

Authentication: Required

Response: 200 OK

{
  "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:

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

Response: 200 OK

{
  "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:

{
  "display_name": "Jane Doe"
}

Response: 200 OK

{
  "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

{
  "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:

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

Response: 201 Created

{
  "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

{
  "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:

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

Response: 200 OK

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

Delete Workspace

Delete a workspace permanently.

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

Authentication: Required

Authorization: Owner only

Response: 200 OK

{
  "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

{
  "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:

{
  "role": "admin"
}

Valid roles: owner, admin, member, guest

Response: 200 OK

{
  "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

{
  "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:

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

Response: 201 Created

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

{
  "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

{
  "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

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

Update Assistant

Update assistant configuration.

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

Authentication: Required

Authorization: Admin+

Request Body:

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

Response: 200 OK

{
  "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:

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

Response: 200 OK

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

Delete Assistant

Delete an assistant.

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

Authentication: Required

Authorization: Admin+

Response: 200 OK

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

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

Response: 201 Created

{
  "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

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

Update Calendar

Update calendar details.

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

Authentication: Required

Authorization: Admin+

Request Body:

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

Response: 200 OK

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

Delete Calendar

Delete a calendar.

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

Authentication: Required

Authorization: Admin+

Response: 200 OK

{
  "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

{
  "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:

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

Response: 201 Created

{
  "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:

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

Response: 200 OK

{
  "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

{
  "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

{
  "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

{
  "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:

{
  "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

{
  "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

{
  "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

{
  "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:

{
  "registration_enabled": false
}

Response: 200 OK

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

Test SMTP Configuration

Test SMTP email sending.

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

Authentication: Required

Request Body:

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

Response: 200 OK

{
  "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

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

Data Models

User Object

{
  "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

{
  "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:

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