https://api-chatbot-ai-aip568.dev.aperogroup.ai

Copy

sk-y6o8xn6GuEpqUXlQ9wfOxCmotXPmwdZlXfrhgaGIhXKoulsFwT

Copy

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvwFBgEPkjGpXZLrOSAj+
31+8jpQMuMnjvyZMSvCjlNPo9MPc6CsIcbJXpVc+LojM/mpysqpwJFk46ao61j3l
UgZIGOEJyDGKEF7KOKmKJOnfnzcrx0bewnJwco5k64Iw7JRcj3x92iKOjy3Dwib2
ncCQy5emukM63p8e7Ahl0KFoziERQYzGaRSzV+bhcSDkohZeh4GO1wtItgsLPNaA
Ix1vD4y/3S7RVwcEfZ2hiLmR2WBs7vEfFOpWhBcMH3abRjH8eajfM6NaKtuxUrFc
XTnGAm9qpeBeqzxCitiqTrmodTQjX5Y+myexa2HIRWGoSAOxE0TYE2aHk82iq7Gm
nQIDAQAB
-----END PUBLIC KEY-----

Copy

# 1. Get available AI models
GET /api/ai-provider/models

# 2. Create an Assistant
POST /api/assistants

# 3. Create a Conversation with that Assistant
POST /api/conversations

# 4. Send Messages and get AI responses
POST /api/conversations/{conversationId}/messages

Copy

// JavaScript Example
const deviceId = 'user-device-123';
const { signature, timestamp } = generateSignature(API_KEY, PUBLIC_KEY);

const response = await fetch('{{BASE_URL}}/api/assistants', {
  method: 'GET',
  headers: {
    'x-api-signature': signature, // ← Required: API signature
    'x-api-timestamp': timestamp.toString(), // ← Required: Timestamp
    'x-device-id': deviceId,
  },
});

Copy

# cURL Example
curl -X GET "{{BASE_URL}}/api/assistants" \
  -H "x-device-id: user-device-123"

Copy

sequenceDiagram
    participant Client
    participant API

    Note over Client: Generate or retrieve Device ID
    Client->>Client: Store deviceId in localStorage

    Client->>API: Any API Request with x-device-id header
    API->>API: Validate deviceId

    alt Valid Device ID
        API-->>Client: 200 OK + Response Data
    else Invalid/Missing Device ID
        API-->>Client: 401 Unauthorized
        Client->>Client: Redirect to login
    end

// Recommended: Create a wrapper function for all API calls
const API_BASE_URL = '{{BASE_URL}}';

function authenticatedFetch(path, options = {}) {
  const deviceId = localStorage.getItem('deviceId');

  if (!deviceId) {
    throw new Error('Device ID not found. Please login first.');
  }

  // Generate fresh signature for each request
  const { signature, timestamp } = generateSignature(API_KEY, PUBLIC_KEY);

  return fetch(`${API_BASE_URL}${path}`, {
    ...options,
    headers: {
      ...options.headers,
      'x-api-signature': signature, // ← Required: API signature
      'x-api-timestamp': timestamp.toString(), // ← Required: Timestamp
      'x-device-id': deviceId,
    },
  });
}

// Usage
const response = await authenticatedFetch('/api/assistants');
const data = await response.json();

Copy

sequenceDiagram
    participant Client
    participant API
    participant AI Provider

    Note over Client,API: Authentication: x-device-id header

    Note over Client,AI Provider: Step 1: Get Available Models
    Client->>API: GET /api/ai-provider/models
    API-->>Client: ["gpt-4o-mini", "inhouse"]

    Note over Client,AI Provider: Step 2: Create Assistant (One-time)
    Client->>API: POST /api/assistants
    API-->>Client: Assistant created (assistantId)

    Note over Client,AI Provider: Step 3: Start Conversation
    Client->>API: POST /api/conversations (with assistantId + model)
    API->>AI Provider: Create thread
    AI Provider-->>API: threadId
    API-->>Client: Conversation created (conversationId)

    Note over Client,AI Provider: Step 4: Chat Loop
    loop Each Message
        Client->>API: POST /api/conversations/{id}/messages
        Note right of Client: Accept: text/event-stream
        API->>AI Provider: Send message to AI
        AI Provider-->>API: SSE: token stream
        API-->>Client: SSE: stream_start {threadId, runId}
        API-->>Client: SSE: stream_chunk {"Hello..."}
        API-->>Client: SSE: stream_chunk {"How can I..."}
        API-->>Client: SSE: stream_end {"Full message"}
    end

    Note over Client,AI Provider: Optional: Stop Generation
    Client->>API: POST /api/conversations/{id}/stop
    Note right of Client: Body: {threadId, runId}
    API->>AI Provider: Cancel run
    API-->>Client: Generation stopped

sequenceDiagram
    participant Client
    participant API
    participant S3

    Note over Client,API: x-device-id header required

    Client->>API: POST /api/upload/generate-url
    API-->>Client: { uploadUrl, fileUrl, expiresIn }
    Client->>S3: PUT uploadUrl (file binary data)
    Note right of Client: Content-Type must match requested type
    S3-->>Client: 200 OK
    Note over Client: Use fileUrl in messages

GET /api/ai-provider/models

Copy

{
  "data": ["gpt-4o-mini", "inhouse"]
}

Copy

POST /api/ai-provider/tts

Copy

{
  "input": "Hello, how can I help you today?",
  "model": "tts-1",
  "speed": 1.0,
  "language": "en",
  "refAudio": "https://cdn.example.com/voice-ref.wav"
}

Copy

{
  "data": {
    "runId": "run_abc123xyz",
    "status": "queued"
  },
  "timestamp": "2026-05-19T09:00:00.000Z",
  "path": "/api/ai-provider/tts"
}

Copy

GET /api/ai-provider/tts/:runId

Copy

{
  "data": {
    "runId": "run_abc123xyz",
    "status": "success",
    "output": {
      "path": "tts/2026/05/19/run_abc123xyz.wav",
      "resultFile": "https://cdn.example.com/tts/2026/05/19/run_abc123xyz.wav",
      "resultStatus": "completed"
    },
    "error": null
  },
  "timestamp": "2026-05-19T09:00:05.000Z",
  "path": "/api/ai-provider/tts/run_abc123xyz"
}

Copy

POST /api/assistants

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "name": "Math Tutor",
  "description": "Helps students with math problems",
  "instructions": "You are a helpful math tutor. Explain concepts step by step.",
  "temperature": 0.7,
  "topP": 1.0,
  "maxTokens": 2048
}

Copy

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "providerAssistantId": "asst_abc123",
    "name": "Math Tutor",
    "description": "Helps students with math problems",
    "instructions": "You are a helpful math tutor...",
    "temperature": 0.7,
    "topP": 1.0,
    "maxTokens": 2048,
    "createdAt": "2026-01-20T10:00:00.000Z",
    "updatedAt": "2026-01-20T10:00:00.000Z"
  }
}

Copy

GET /api/assistants?skip=0&take=10&search=tutor

Copy

x-device-id: your-device-id

Copy

{
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Math Tutor",
        "description": "Helps students with math problems",
        "createdAt": "2026-01-20T10:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Copy

GET /api/assistants/{id}

Copy

x-device-id: your-device-id

Copy

PATCH /api/assistants/{id}

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "name": "Advanced Math Tutor",
  "temperature": 0.5
}

Copy

DELETE /api/assistants/{id}

Copy

x-device-id: your-device-id

Copy

POST /api/conversations

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "assistantId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Help with Algebra",
  "model": "gpt-4o-mini",
  "instructions": "Focus on quadratic equations",
  "temperature": 0.5,
  "topP": 0.9,
  "maxTokens": 4096
}

Copy

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "title": "Help with Algebra",
    "assistantId": "550e8400-e29b-41d4-a716-446655440000",
    "model": "gpt-4o-mini",
    "providerThreadId": "thread_abc123",
    "createdAt": "2026-01-20T10:30:00.000Z",
    "updatedAt": "2026-01-20T10:30:00.000Z"
  }
}

Copy

GET /api/conversations?skip=0&take=10&search=algebra&assistantId=xxx

Copy

x-device-id: your-device-id

Copy

{
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "title": "Help with Algebra",
        "assistantId": "550e8400-e29b-41d4-a716-446655440000",
        "updatedAt": "2026-01-20T10:30:00.000Z"
      }
    ],
    "total": 1
  }
}

Copy

GET /api/conversations/{id}

Copy

x-device-id: your-device-id

Copy

PATCH /api/conversations/{id}

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "title": "Algebra and Calculus"
}

Copy

DELETE /api/conversations/{id}

Copy

x-device-id: your-device-id

Copy

POST /api/conversations/{conversationId}/messages

Copy

x-device-id: your-device-id
Content-Type: application/json
Accept: text/event-stream

Copy

{
  "content": "What is the quadratic formula?",
  "model": "gpt-4o-mini"
}

Copy

data: {"type": "<event-type>", "data": {...}}

Copy

data: {"type":"stream_start","data":{"threadId":"thread_abc","runId":"run_123"}}

data: {"type":"stream_chunk","data":{"content":"The"}}

data: {"type":"stream_chunk","data":{"content":" quadratic"}}

data: {"type":"stream_chunk","data":{"content":" formula"}}

data: {"type":"stream_end","data":{"content":"The quadratic formula is x = (-b ± √(b²-4ac)) / 2a...","ttsAudioUrl":"https://cdn.example.com/tts/2026/05/19/run_abc123.wav"}}

Copy

const sendMessage = async (conversationId, content, model) => {
  const deviceId = localStorage.getItem('deviceId');
  const { signature, timestamp } = generateSignature(API_KEY, PUBLIC_KEY);

  const response = await fetch(
    `/api/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'x-api-signature': signature, // ← Required: API signature
        'x-api-timestamp': timestamp.toString(), // ← Required: Timestamp
        'x-device-id': deviceId,
        'Content-Type': 'application/json',
        Accept: 'text/event-stream',
      },
      body: JSON.stringify({ content, model }),
    },
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let assistantMessage = '';
  let ttsAudioUrl = '';
  let threadId = '';
  let runId = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        try {
          const jsonStr = line.substring(6).trim();
          if (jsonStr === '[DONE]') continue;

          const eventData = JSON.parse(jsonStr);
          const type = eventData.type;
          const data = eventData.data;

          if (type === 'stream_start') {
            // Save these for stop functionality
            threadId = data.threadId;
            runId = data.runId;
          } else if (type === 'stream_chunk') {
            assistantMessage += data.content;
            // Update UI with partial message
          } else if (type === 'stream_end') {
            assistantMessage = data.content;
            ttsAudioUrl = data.ttsAudioUrl; // Full CDN URL, may be undefined
            // Final message received
          }
        } catch (e) {
          console.warn('Failed to parse SSE data', e);
        }
      }
    }
  }

  return { assistantMessage, ttsAudioUrl, threadId, runId };
};

Copy

POST /api/conversations/{conversationId}/stop

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "threadId": "thread_abc123",
  "runId": "run_xyz789"
}

Copy

GET /api/conversations/{conversationId}/messages?page=1&limit=20

Copy

x-device-id: your-device-id

Copy

{
  "data": {
    "items": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "What is the quadratic formula?",
        "createdAt": "2026-05-19T10:31:00.000Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "The quadratic formula is x = (-b ± √(b²-4ac)) / 2a...",
        "ttsAudioUrl": "https://cdn.example.com/tts/2026/05/19/run_abc123.wav",
        "createdAt": "2026-05-19T10:31:05.000Z"
      }
    ],
    "total": 2
  }
}

Copy

DELETE /api/conversations/{conversationId}/messages/{messageId}

Copy

x-device-id: your-device-id

Copy

POST /api/upload/generate-url

Copy

x-device-id: your-device-id
Content-Type: application/json

Copy

{
  "filename": "document.pdf",
  "contentType": "application/pdf",
  "fileSize": 1024000,
  "folder": "documents"
}

Copy

{
  "data": {
    "uploadUrl": "https://bucket.s3.amazonaws.com/path?signature...",
    "fileKey": "app-name/uploads/2026/01/20/abc-123/document.pdf",
    "fileUrl": "https://cdn.example.com/uploads/.../document.pdf",
    "expiresIn": 3600,
    "contentType": "application/pdf"
  }
}

Copy

// Step 1: Get the presigned URL
const { signature, timestamp } = generateSignature(API_KEY, PUBLIC_KEY);

const response = await fetch('/api/upload/generate-url', {
  method: 'POST',
  headers: {
    'x-api-signature': signature, // ← Required: API signature
    'x-api-timestamp': timestamp.toString(), // ← Required: Timestamp
    'x-device-id': deviceId,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: file.name,
    contentType: file.type,
    fileSize: file.size,
  }),
});
const { data } = await response.json();

// Step 2: Upload the file directly to S3 using PUT
// Note: S3 upload does NOT need signature - it uses presigned URL
await fetch(data.uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': data.contentType,
  },
  body: file, // The actual file binary
});

// Step 3: Use fileUrl in your messages
console.log('File available at:', data.fileUrl);

Copy

Step 1 — Load home screen layout
GET /api/cms/screens/{key}
  → topicListSection.topics: topic cards with documentId, slug, type, difficulty, cardPreview
  → bannerSection.lessonDocumentId: featured lesson documentId to deep-link into

Step 2 — User taps a topic → get lessons for that topic
GET /api/cms/lessons?topicDocumentId={topic.documentId}
  ⚠️  Use topic.documentId as the query param — NOT as the path segment
  → Returns paginated lessons belonging to that topic (without content body)

Step 3 — User taps a lesson → get full lesson detail
GET /api/cms/lessons/{lesson.documentId}
  ⚠️  Use lesson.documentId from the lessons list (Step 2) or bannerSection.lessonDocumentId
  → Full detail: content (roleplay-config or sentence-list), persona, goal, scenario, tasks

Supporting endpoints (load once at app start):
GET /api/cms/countries     → Language options
GET /api/cms/personas      → AI character roster
GET /api/cms/milestones    → Achievement definitions

Copy

GET /api/cms/countries

Copy

{
  "data": [
    {
      "id": 2,
      "documentId": "j4mrfkhde73ra3umedhjbnwh",
      "code": "VI",
      "name": "Vietnamese",
      "isActive": true
    },
    {
      "id": 1,
      "documentId": "z5q41lv7eatn80dt0bax212n",
      "code": "EN",
      "name": "English",
      "isActive": true,
      "cardPreview": {
        "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
        "role": "DEFAULT"
      }
    }
  ],
  "timestamp": "19/05/2026 17:15:27",
  "path": "/api/cms/countries"
}

Copy

GET /api/cms/personas?page=1&pageSize=25

Copy

{
  "data": {
    "items": [
      {
        "id": 5,
        "documentId": "gmv3l8khsr5cni2n8epagwph",
        "name": "Alex",
        "slug": null,
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        },
        "voice": "en-US-GuyNeural",
        "role": "Pronunciation Coach",
        "description": "A professional pronunciation coach focused on clear, natural English speech.",
        "personality": "Precise, supportive, and detail-oriented.",
        "systemPromptTemplate": "You are Alex, a pronunciation coach. Help the user improve their English pronunciation."
      },
      {
        "id": 6,
        "documentId": "xxfr6ej3xz5rqawd2bl4o5no",
        "name": "Emma",
        "slug": null,
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        },
        "voice": "en-US-JennyNeural",
        "role": "English Tutor",
        "description": "A friendly and patient English tutor who helps learners build confidence.",
        "personality": "Warm, encouraging, and clear in explanations.",
        "systemPromptTemplate": "You are Emma, a friendly English tutor. Help the user practice English conversation."
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 2,
      "pageCount": 1,
      "total": 2
    }
  },
  "timestamp": "19/05/2026 18:00:45",
  "path": "/api/cms/personas?page=1&pageSize=2"
}

Copy

GET /api/cms/milestones?page=1&pageSize=25

Copy

{
  "data": {
    "items": [
      {
        "id": 5,
        "documentId": "bc4phn6qy5qdaz8i6v0yx95r",
        "type": "lessons_completed",
        "triggerValue": 10,
        "isActive": true,
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        },
        "title": "10 Lessons Completed!",
        "description": "Complete your first 10 lessons.",
        "reward": {
          "type": "badge",
          "amount": 1,
          "label": "First Steps Badge",
          "cardPreview": {
            "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
            "role": "DEFAULT"
          }
        }
      },
      {
        "id": 6,
        "documentId": "vygcrls60bin39w1vf4nttig",
        "type": "streak",
        "triggerValue": 7,
        "isActive": true,
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        },
        "title": "7-Day Streak!",
        "description": "Practice every day for 7 consecutive days.",
        "reward": {
          "type": "energy",
          "amount": 50,
          "label": "50 Energy Points",
          "cardPreview": {
            "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
            "role": "DEFAULT"
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 2,
      "pageCount": 1,
      "total": 2
    }
  },
  "timestamp": "19/05/2026 18:01:42",
  "path": "/api/cms/milestones?page=1&pageSize=2"
}

Copy

GET /api/cms/lessons?page=1&pageSize=25&topicDocumentId=dv1kyej7onlk06zhc54ohi4i

Copy

{
  "data": {
    "items": [
      {
        "id": 5,
        "documentId": "pd5dkfzjljijxu3kkn39f3hf",
        "slug": "ordering-coffee",
        "difficulty": "basic",
        "estimatedSeconds": 240,
        "energyCost": 5,
        "isActive": true,
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        },
        "topics": [
          {
            "id": 5,
            "documentId": "dv1kyej7onlk06zhc54ohi4i",
            "slug": "cafe-ordering"
          }
        ],
        "content": null
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  },
  "timestamp": "19/05/2026 18:12:09",
  "path": "/api/cms/lessons?topicDocumentId=dv1kyej7onlk06zhc54ohi4i"
}

Copy

GET /api/cms/lessons/:documentId

Copy

{
  "data": {
    "id": 6,
    "documentId": "v398c9npek6tuu3inf932apr",
    "slug": "introducing-yourself",
    "difficulty": "beginner",
    "estimatedSeconds": 300,
    "energyCost": 5,
    "isActive": true,
    "cardPreview": {
      "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
      "role": "DEFAULT"
    },
    "topics": [
      {
        "id": 6,
        "documentId": "j2vjzslcwoewzwt3em2agpfd",
        "slug": "daily-conversation"
      }
    ],
    "content": {
      "__component": "aip568-speaking.roleplay-config",
      "id": 6,
      "systemPromptOverride": null,
      "persona": {
        "id": 6,
        "documentId": "xxfr6ej3xz5rqawd2bl4o5no",
        "name": "Emma",
        "slug": null,
        "voice": "en-US-JennyNeural",
        "cardPreview": {
          "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
          "role": "DEFAULT"
        }
      },
      "goal": [
        {
          "id": 160,
          "value": "Practice introducing yourself naturally in English.",
          "language": { "code": "EN", "name": "English" }
        },
        {
          "id": 161,
          "value": "Luyện tập tự giới thiệu bản thân một cách tự nhiên bằng tiếng Anh.",
          "language": { "code": "VI", "name": "Vietnamese" }
        }
      ],
      "scenario": [
        {
          "id": 162,
          "value": "You just joined a new company and are meeting your team for the first time.",
          "language": { "code": "EN", "name": "English" }
        },
        {
          "id": 163,
          "value": "Bạn vừa gia nhập một công ty mới và đang gặp gỡ nhóm lần đầu.",
          "language": { "code": "VI", "name": "Vietnamese" }
        }
      ],
      "inspireExamples": [
        {
          "id": 170,
          "value": "Hi, I'm Sarah. I'm the new marketing manager. I'm originally from New York but I've been living in Hanoi for 3 years.",
          "language": { "code": "EN", "name": "English" }
        }
      ],
      "tasks": [
        {
          "id": 11,
          "requiredPhrases": ["my name is", "i'm from"],
          "description": [
            {
              "id": 164,
              "value": "Tell Emma your name and where you are from.",
              "language": { "code": "EN", "name": "English" }
            },
            {
              "id": 165,
              "value": "Nói với Emma tên và quê quán của bạn.",
              "language": { "code": "VI", "name": "Vietnamese" }
            }
          ],
          "hint": [
            {
              "id": 168,
              "value": "Try: My name is [name] and I'm from [place].",
              "language": { "code": "EN", "name": "English" }
            }
          ]
        },
        {
          "id": 12,
          "requiredPhrases": ["working as", "my role"],
          "description": [
            {
              "id": 166,
              "value": "Share what your role is in the new company.",
              "language": { "code": "EN", "name": "English" }
            },
            {
              "id": 167,
              "value": "Chia sẻ vai trò của bạn trong công ty mới.",
              "language": { "code": "VI", "name": "Vietnamese" }
            }
          ],
          "hint": [
            {
              "id": 169,
              "value": "Try: I'll be working as a [job title].",
              "language": { "code": "EN", "name": "English" }
            }
          ]
        }
      ]
    }
  },
  "timestamp": "19/05/2026 18:01:53",
  "path": "/api/cms/lessons/v398c9npek6tuu3inf932apr"
}

Copy

GET /api/cms/screens/:key

Copy

{
  "data": {
    "id": 3,
    "documentId": "yp6zx56344z4j6cw6s3p06tv",
    "key": "home",
    "isActive": true,
    "topicListSection": {
      "topicType": "speaking",
      "displayMode": "grid",
      "topics": [
        {
          "documentId": "j2vjzslcwoewzwt3em2agpfd",
          "slug": "daily-conversation",
          "type": "speaking",
          "difficulty": "beginner",
          "isActive": true,
          "cardPreview": {
            "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
            "role": "DEFAULT"
          }
        },
        {
          "documentId": "dv1kyej7onlk06zhc54ohi4i",
          "slug": "cafe-ordering",
          "type": "speaking",
          "difficulty": "basic",
          "isActive": true,
          "cardPreview": {
            "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
            "role": "DEFAULT"
          }
        }
      ]
    },
    "bannerSection": {
      "cardPreview": {
        "mediaUrl": "https://dev-static.apero.vn/content/uploads/mo_rong_anh_202604011831_3923a402b1.jpeg",
        "role": "DEFAULT"
      },
      "lessonDocumentId": "v398c9npek6tuu3inf932apr"
    }
  },
  "timestamp": "19/05/2026 18:01:48",
  "path": "/api/cms/screens/home"
}

Copy

interface Assistant {
  id: string; // UUID - Unique identifier
  providerAssistantId: string; // Provider's assistant ID
  name: string; // Display name
  description?: string; // Optional description
  instructions: string; // System prompt
  temperature?: number; // Creativity (0-2), default: 0.7
  topP?: number; // Nucleus sampling (0-1), default: 1.0
  maxTokens?: number; // Max response tokens, default: 2048
  createdAt: Date; // Creation timestamp
  updatedAt: Date; // Last update timestamp
}

Copy

interface Conversation {
  id: string; // UUID - Unique identifier
  title: string; // Conversation title
  assistantId: string; // Linked assistant ID
  providerThreadId?: string; // Provider's thread ID
  model?: string; // AI model being used
  instructions?: string; // Instructions override
  temperature?: number; // Temperature override
  topP?: number; // TopP override
  maxTokens?: number; // MaxTokens override
  userId?: string; // Owner user ID (from device)
  createdAt: Date; // Creation timestamp
  updatedAt: Date; // Last update timestamp
  messages?: Message[]; // Messages in conversation
}

Copy

interface Message {
  id: string; // UUID - Unique identifier
  role: 'user' | 'assistant'; // Who sent the message
  content: string; // Message text
  ttsAudioUrl?: string; // Full CDN URL of the TTS audio (assistant messages only)
  providerMessageId?: string; // Provider's message ID
  createdAt: Date; // Timestamp
}

Copy

interface UploadResponse {
  uploadUrl: string; // Presigned PUT URL (expires)
  fileKey: string; // S3 object key/path
  fileUrl: string; // Public access URL
  expiresIn: number; // URL expiration in seconds
  contentType: string; // File MIME type
}

Copy

interface CardPreviewDto {
  mediaUrl?: string; // Strapi media URL (absent when no media attached)
  role?: string; // DEFAULT | FEATURED | COMPACT | AVATAR | BANNER
}

interface CmsCountryDto {
  id: number;
  documentId: string;
  code: string; // e.g. "EN", "VI"
  name: string;
  isActive: boolean;
  cardPreview?: CardPreviewDto;
}

Copy

interface CmsPersonaDto {
  id: number;
  documentId: string;
  name: string;
  slug: string;
  voice?: string; // TTS voice ID (e.g. "en-US-JennyNeural")
  cardPreview?: CardPreviewDto;
  role?: string; // Localized
  description?: string; // Localized
  personality?: string; // Localized
  systemPromptTemplate?: string; // Localized — base system prompt for AI conversations
}

Copy

interface CmsRewardDto {
  type: string; // energy | badge | premium_day | custom
  amount?: number;
  label?: string; // Localized
  cardPreview?: CardPreviewDto;
}

interface CmsMilestoneDto {
  id: number;
  documentId: string;
  type: string; // streak | lessons_completed | score_achieved | custom
  triggerValue: number; // Threshold to unlock (e.g. 7 for 7-day streak)
  isActive: boolean;
  cardPreview?: CardPreviewDto;
  title?: string; // Localized
  description?: string; // Localized
  reward?: CmsRewardDto;
}

Copy

interface CmsTopicDto {
  id: number;
  documentId: string;
  slug: string;
  type: string; // speaking | pronunciation | reading | writing | grammar | custom
  difficulty: string; // beginner | basic | intermediate | advanced
  isActive: boolean;
  cardPreview?: CardPreviewDto;
  title?: string; // Localized
  description?: string; // Localized
  shortDescription?: string; // Localized
}

Copy

interface CmsTopicRefDto {
  id: number;
  documentId: string;
  slug: string;
  title?: string; // Localized — only resolved when x-country-code is set
}

interface CmsLessonDto {
  id: number;
  documentId: string;
  slug: string;
  difficulty: string; // beginner | basic | intermediate | advanced
  estimatedSeconds: number;
  energyCost: number;
  isActive: boolean;
  cardPreview?: CardPreviewDto;
  title?: string; // Localized
  topics?: CmsTopicRefDto[];
  content?: RoleplayConfig | SentenceList | null; // Dynamic zone — first item only
}

// Content: Speaking lesson
interface RoleplayConfig {
  __component: 'aip568-speaking.roleplay-config';
  persona?: PersonaRef;
  goal?: string; // Localized
  scenario?: string; // Localized
  inspireExamples?: string[]; // Localized examples
  systemPromptOverride?: string;
  tasks?: RoleplayTask[];
}

interface RoleplayTask {
  description?: string; // Localized
  hint?: string; // Localized
  requiredPhrases?: string[];
}

// Content: Pronunciation lesson
interface SentenceList {
  __component: 'aip568-pronunciation.sentence-list';
  sentences: Sentence[];
}

interface Sentence {
  text: string;
  phonetic?: string;
  difficulty?: string; // easy | medium | hard
  cardPreview?: CardPreviewDto; // Audio file via cardPreview.mediaUrl
  translations?: string[]; // Localized
  hints?: string[]; // Localized
}

Copy

interface CmsTopicSummaryDto {
  documentId: string;
  slug: string;
  type: string;
  difficulty: string;
  isActive: boolean;
  cardPreview?: CardPreviewDto;
  title?: string; // Localized
}

interface CmsTopicListSectionDto {
  title?: string; // Localized section heading
  topicType?: string; // Pre-filter hint for the list
  displayMode?: string; // grid | list | carousel
  topics?: CmsTopicSummaryDto[];
}

interface CmsBannerSectionDto {
  title?: string; // Localized
  cardPreview?: CardPreviewDto;
  topicDocumentId?: string; // Deep-link to a topic
  lessonDocumentId?: string; // Deep-link to a lesson
}

interface CmsScreenDto {
  id: number;
  documentId: string;
  key: string; // home | roleplay | pronunciation | discover | profile | custom
  isActive: boolean;
  title?: string; // Localized
  topicListSection?: CmsTopicListSectionDto;
  bannerSection?: CmsBannerSectionDto;
}

Copy

interface SSEEvent {
  type: 'stream_start' | 'stream_chunk' | 'stream_end' | 'error';
  data: StreamStartData | StreamChunkData | StreamEndData | ErrorData;
}

interface StreamStartData {
  threadId: string; // Thread ID for stop functionality
  runId: string; // Run ID for stop functionality
}

interface StreamChunkData {
  content: string; // Partial message token
}

interface StreamEndData {
  content: string; // Full complete message
  ttsAudioUrl?: string; // Full CDN URL of the TTS audio (undefined if TTS failed/disabled)
}

interface ErrorData {
  message: string; // Error description
}

Copy

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Copy

{
  "statusCode": 400,
  "message": ["name must be a string", "instructions should not be empty"],
  "error": "Bad Request"
}

Copy

if (response.status === 401) {
  localStorage.removeItem('deviceId');
  window.location.href = '/login';
}

Copy

class AIClient {
  constructor(baseUrl, apiKey, publicKey) {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
    this.publicKey = publicKey;
    this.deviceId = localStorage.getItem('deviceId');
  }

  async request(path, options = {}) {
    if (!this.deviceId) {
      throw new Error('Not authenticated');
    }

    // Generate fresh signature for each request
    const { signature, timestamp } = generateSignature(
      this.apiKey,
      this.publicKey,
    );

    const response = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        ...options.headers,
        'x-api-signature': signature,
        'x-api-timestamp': timestamp.toString(),
        'x-device-id': this.deviceId,
      },
    });

    if (response.status === 401) {
      localStorage.removeItem('deviceId');
      this.deviceId = null;
      throw new Error('Session expired');
    }

    return response;
  }

  // Assistants
  async getAssistants(params = {}) {
    const query = new URLSearchParams(params).toString();
    const res = await this.request(`/api/assistants?${query}`);
    return res.json();
  }

  async createAssistant(data) {
    const res = await this.request('/api/assistants', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    return res.json();
  }

  // Conversations
  async createConversation(assistantId, title, model) {
    const res = await this.request('/api/conversations', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ assistantId, title, model }),
    });
    return res.json();
  }

  // Messages (Streaming)
  async sendMessage(conversationId, content, model, onChunk, onComplete) {
    const res = await this.request(
      `/api/conversations/${conversationId}/messages`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Accept: 'text/event-stream',
        },
        body: JSON.stringify({ content, model }),
      },
    );

    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let threadId, runId;

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value, { stream: true });
      for (const line of chunk.split('\n')) {
        if (line.startsWith('data: ')) {
          try {
            const event = JSON.parse(line.substring(6));
            if (event.type === 'stream_start') {
              threadId = event.data.threadId;
              runId = event.data.runId;
            } else if (event.type === 'stream_chunk') {
              onChunk?.(event.data.content);
            } else if (event.type === 'stream_end') {
              onComplete?.(event.data.content, event.data.ttsAudioUrl, {
                threadId,
                runId,
              });
            }
          } catch (e) {}
        }
      }
    }
  }

  async stopGeneration(conversationId, threadId, runId) {
    return this.request(`/api/conversations/${conversationId}/stop`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ threadId, runId }),
    });
  }
}

// Usage
const client = new AIClient(
  '{{BASE_URL}}',
  process.env.API_KEY,
  process.env.PUBLIC_KEY,
);

Copy

sequenceDiagram
    participant You as Your App
    participant Server as API Server

    You->>You: 1. Get current time
    You->>You: 2. Combine: time + API key
    You->>You: 3. Encrypt with public key
    You->>You: 4. Convert to base64 text

    You->>Server: 5. Send request with signature

    alt ✅ Signature is valid
        Server-->>You: 200 OK - Here's your data
    else ❌ Signature is wrong
        Server-->>You: 400 Error - Invalid signature
    end

const crypto = require('crypto');

// --- Helper: Generate Signature ---
function generateSignature(apiKey, publicKeyPem) {
  const timestamp = Date.now();
  const payload = timestamp + '@@@' + apiKey;

  const buffer = Buffer.from(payload, 'utf8');
  const encrypted = crypto.publicEncrypt(
    {
      key: publicKeyPem,
      padding: crypto.constants.RSA_PKCS1_PADDING,
    },
    buffer,
  );

  const signature = encrypted.toString('base64');
  return { signature, timestamp };
}

Copy

// Your credentials (get these from your backend team)
const API_KEY = 'your-api-key-here';
const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

// Generate signature
const { signature, timestamp } = generateSignature(API_KEY, PUBLIC_KEY);

// Make request
const response = await fetch('https://api.example.com/api/assistants', {
  method: 'GET',
  headers: {
    'x-api-signature': signature, // ← Add this
    'x-api-timestamp': timestamp.toString(), // ← Add this
    'x-device-id': 'your-device-id',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Copy

const crypto = require('crypto');
const fetch = require('node-fetch');

class APIClient {
  constructor(apiKey, publicKey, baseUrl) {
    this.apiKey = apiKey;
    this.publicKey = publicKey;
    this.baseUrl = baseUrl;
  }

  // Generate signature automatically
  generateSignature() {
    const timestamp = Date.now();
    const payload = `${timestamp}@@@${this.apiKey}`;
    const buffer = Buffer.from(payload, 'utf8');

    const encrypted = crypto.publicEncrypt(
      {
        key: this.publicKey,
        padding: crypto.constants.RSA_PKCS1_PADDING,
      },
      buffer,
    );

    return {
      signature: encrypted.toString('base64'),
      timestamp,
    };
  }

  // Make any API request
  async request(endpoint, options = {}) {
    // Generate fresh signature for this request
    const { signature, timestamp } = this.generateSignature();

    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        ...options.headers,
        'x-api-signature': signature,
        'x-api-timestamp': timestamp.toString(),
        'x-device-id': options.deviceId || 'default-device',
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }

    return response.json();
  }

  // Example: Get assistants
  async getAssistants(deviceId) {
    return this.request('/api/assistants', { deviceId });
  }

  // Example: Create conversation
  async createConversation(deviceId, data) {
    return this.request('/api/conversations', {
      method: 'POST',
      deviceId,
      body: JSON.stringify(data),
    });
  }
}

// --- How to use it ---
const client = new APIClient(
  process.env.API_KEY, // Your API key
  process.env.PUBLIC_KEY, // Your public key
  'https://api.example.com', // API base URL
);

// Now just use it!
const assistants = await client.getAssistants('device-123');
const conversation = await client.createConversation('device-123', {
  assistantId: 'xxx',
  title: 'My Chat',
});

Copy

{
  "statusCode": 400,
  "message": "Signature expired",
  "error": "Bad Request"
}

Copy

const crypto = require('crypto');

// Put your real keys here
const TEST_API_KEY = 'your-api-key';
const TEST_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
... your public key ...
-----END PUBLIC KEY-----`;

function testSignature() {
  console.log('🧪 Testing signature generation...\n');

  const timestamp = Date.now();
  const payload = `${timestamp}@@@${TEST_API_KEY}`;
  console.log('📦 Payload:', payload);

  const buffer = Buffer.from(payload, 'utf8');
  const encrypted = crypto.publicEncrypt(
    {
      key: TEST_PUBLIC_KEY,
      padding: crypto.constants.RSA_PKCS1_PADDING,
    },
    buffer,
  );

  const signature = encrypted.toString('base64');
  console.log('✅ Signature created!');
  console.log('📝 First 50 chars:', signature.substring(0, 50) + '...');

  console.log('\n📤 Headers to send:');
  console.log({
    'x-api-signature': signature,
    'x-api-timestamp': timestamp.toString(),
  });
}

testSignature();

Copy