byom-customer-api/docs/api.md

API Documentation

Database Schema

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.

POST /workspace/owner

Request Body:

{
    "email": "string",
    "name": "string",
    "password": "string",
    "phone_number": "string"
}

Response: 201 Created

{
    "id": "uuid",
    "email": "string",
    "name": "string",
    "phone_number": "string",
    "role": "owner",
    "status": "active"
}

Accept Invitation

Creates a new user account from an invitation.

POST /workspace/invite

Request Body:

{
    "email": "string",
    "name": "string",
    "password": "string",
    "phone_number": "string",
    "token": "string"
}

Response: 201 Created

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

POST /users/invite

Request Body:

{
    "email": "string",
    "role": "string"
}

Response: 201 Created

{
    "id": "uuid",
    "email": "string",
    "role": "string",
    "token": "string",
    "expires_at": "timestamp"
}

List Invitations

Protected route to get all pending invitations.

GET /users/invitations

Response: 200 OK

{
    "invitations": [
        {
            "id": "uuid",
            "email": "string",
            "role": "string",
            "status": "string",
            "expires_at": "timestamp",
            "created_at": "timestamp"
        }
    ]
}

Cancel Invitation

Protected route to cancel a pending invitation.

DELETE /users/invitations/:id

Response: 200 OK

{
    "success": true
}

Get Current User Profile

Protected route to get the current user's profile.

GET /users/me

Response: 200 OK

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

PUT /users/me

Request Body:

{
    "name": "string",
    "phone_number": "string"
}

Response: 200 OK

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

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