# API Documentation

## Database Schema

```mermaid
erDiagram
    Vitrine {
        string hostname PK
        boolean used
    }

    VPS {
        string id PK
        string size
        string ip
        string version
        string plan
        string state
        string hostname FK
    }

    Workspace {
        string id PK
        string name
        string plan
        timestamp created_at
    }

    User {
        string id PK
        string username
        string email
        string password_hash
        boolean is_active
        timestamp created_at
    }

    Profile {
        string id PK
        string profile_name
        string workspace_id FK
        timestamp created_at
    }

    Account {
        string id PK
        string type
        string identifier
        string profile_id FK
        timestamp last_sync
    }

    AccountTrend {
        string id PK
        string account_id FK
        string trend_name
        float engagement_rate
        int followers_growth
        timestamp detected_at
        timestamp expires_at
    }

    Suggestion {
        string id PK
        string profile_id FK
        string type
        string title
        string description
        float relevance_score
        string status
        timestamp created_at
        timestamp updated_at
    }

    GeneratedImage {
        string id PK
        string suggestion_id FK
        string image_url
        string prompt_used
        timestamp generated_at
        boolean is_selected
    }

    WorkspaceUser {
        string workspace_id FK
        string user_id FK
        string role
        timestamp joined_at
    }

    VitrineUsers {
        string hostname FK
        string user_id FK
    }

    Vitrine ||--o{ VitrineUsers : "has"
    Vitrine ||--o{ VPS : "hosts"
    Workspace ||--o{ WorkspaceUser : "has"
    User ||--o{ WorkspaceUser : "belongs_to"
    Workspace ||--o{ Profile : "contains"
    Profile ||--o{ Account : "has"
    Account ||--o{ AccountTrend : "trends"
    Profile ||--o{ Suggestion : "receives"
    Suggestion ||--o{ GeneratedImage : "has"
```

## Authentication
All protected routes require a Bearer token in the Authorization header:
```
Authorization: Bearer <token>
```

## Base URLs
- Main platform: `https://localhost:8443/`
- Workspace specific: `https://{workspace-name}.yourdomain.com/api`

## Routes

### Create Workspace Owner
Creates the first user (owner) for a new workspace.

```http
POST /workspace/owner
```

**Request Body:**
```json
{
    "email": "string",
    "name": "string",
    "password": "string",
    "phone_number": "string"
}
```

**Response:** `201 Created`
```json
{
    "id": "uuid",
    "email": "string",
    "name": "string",
    "phone_number": "string",
    "role": "owner",
    "status": "active"
}
```

### Accept Invitation
Creates a new user account from an invitation.

```http
POST /workspace/invite
```

**Request Body:**
```json
{
    "email": "string",
    "name": "string",
    "password": "string",
    "phone_number": "string",
    "token": "string"
}
```

**Response:** `201 Created`
```json
{
    "id": "uuid",
    "email": "string",
    "name": "string",
    "phone_number": "string",
    "role": "string",
    "status": "active"
}
```

### Invite User
Protected route to invite a new user to the workspace.

```http
POST /users/invite
```

**Request Body:**
```json
{
    "email": "string",
    "role": "string"
}
```

**Response:** `201 Created`
```json
{
    "id": "uuid",
    "email": "string",
    "role": "string",
    "token": "string",
    "expires_at": "timestamp"
}
```

### List Invitations
Protected route to get all pending invitations.

```http
GET /users/invitations
```

**Response:** `200 OK`
```json
{
    "invitations": [
        {
            "id": "uuid",
            "email": "string",
            "role": "string",
            "status": "string",
            "expires_at": "timestamp",
            "created_at": "timestamp"
        }
    ]
}
```

### Cancel Invitation
Protected route to cancel a pending invitation.

```http
DELETE /users/invitations/:id
```

**Response:** `200 OK`
```json
{
    "success": true
}
```

### Get Current User Profile
Protected route to get the current user's profile.

```http
GET /users/me
```

**Response:** `200 OK`
```json
{
    "id": "uuid",
    "email": "string",
    "name": "string",
    "phone_number": "string",
    "role": "string",
    "status": "string"
}
```

### Update Current User Profile
Protected route to update the current user's profile.

```http
PUT /users/me
```

**Request Body:**
```json
{
    "name": "string",
    "phone_number": "string"
}
```

**Response:** `200 OK`
```json
{
    "id": "uuid",
    "email": "string",
    "name": "string",
    "phone_number": "string",
    "role": "string",
    "status": "string"
}
```

## Data Types

### Role Values
- `owner`: Workspace owner with full permissions
- `admin`: Administrative user with elevated permissions
- `member`: Regular workspace member

### Status Values
- `active`: User account is active
- `inactive`: User account is temporarily inactive
- `suspended`: User account has been suspended

### Invitation Status Values
- `pending`: Invitation is waiting to be accepted
- `accepted`: Invitation has been accepted
- `expired`: Invitation has expired
- `cancelled`: Invitation was cancelled

### Notes
- All timestamps are in ISO 8601 format
- All IDs are UUIDs
- Workspace is identified by subdomain
- Password requirements:
  - Minimum 8 characters
  - Must contain at least one number
  - Must contain at least one uppercase letter
  - Must contain at least one special character

## Error Responses
All error responses follow this format:
```json
{
    "error": "string"
}
```

Common HTTP status codes:
- `400`: Bad Request - Invalid input data
- `401`: Unauthorized - Missing or invalid authentication
- `403`: Forbidden - Insufficient permissions
- `404`: Not Found - Resource doesn't exist
- `500`: Internal Server Error - Server-side error