API Reference

Endpoint inti untuk melatih business brain dan mengelola pembelajaran karyawan.

Pengenalan

Emplobo menyediakan API REST untuk mengelola business brain, training AI, guide, dan progress karyawan. Semua request (kecuali webhook Clerk dan health check) wajib membawa token sesi Clerk pada header Authorization: Bearer <token> dan ter-isolasi per organisasi (orgId diambil dari token, bukan dari body request).

Base URL: https://api.emplobo.com

Training & Role

12 ENDPOINT

POST/api/rolesRESPONSE 201 · JSON

Membuat role training baru berstatus DRAFT.

PARAM	TIPE	STATUS	DESKRIPSI
name	string	Required	Nama role (max 100)
description	string	Opsional	Deskripsi (max 500)

LIHAT CONTOH CURL

curl -X POST "$API/roles" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Barista","description":"Menangani espresso & milk"}'

POST/api/roles/:id/training/messagesRESPONSE 201 · JSON

Mengirim pesan training admin → AI. Di latar belakang, AI menilai ulang completeness (0-100) dan meng-sync Celah Pengetahuan secara berkala.

PARAM	TIPE	STATUS	DESKRIPSI
content	string	Required	Teks SOP / know-how (max 4000)

LIHAT CONTOH CURL

curl -X POST "$API/roles/$ROLE_ID/training/messages" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Prosedur closing: backflush 5x dengan cafiza…"}'

POST/api/roles/:id/guide/generateRESPONSE 201 · JSON

Menghasilkan draf panduan (bab + kuis) dari transkrip training, tetapi TIDAK langsung menerbitkan. Hanya saat status READY atau PUBLISHED.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X POST "$API/roles/$ROLE_ID/guide/generate" \
  -H "Authorization: Bearer $CLERK_TOKEN"

POST/api/roles/:id/guide/draft/publishRESPONSE 200 · JSON

Menerbitkan draf terbaru secara atomik: progres karyawan dipertahankan (bab dengan judul sama dipetakan ulang), versi baru tercatat + riwayat.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X POST "$API/roles/$ROLE_ID/guide/draft/publish" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/api/roles/:id/guide/versionsRESPONSE 200 · JSON

Riwayat versi panduan (snapshot + changelog) untuk audit dan rollback.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/roles/$ROLE_ID/guide/versions" \
  -H "Authorization: Bearer $CLERK_TOKEN"

POST/api/roles/:id/assignmentsRESPONSE 201 · JSON

Menugaskan karyawan ke role (idempotent). Hanya untuk status PUBLISHED.

PARAM	TIPE	STATUS	DESKRIPSI
userIds	string[]	Required	Clerk user ids

LIHAT CONTOH CURL

curl -X POST "$API/roles/$ROLE_ID/assignments" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds":["user_abc","user_def"]}'

POST/api/roles/:id/training/lockRESPONSE 200 · JSON

Mengunci Training Room untuk satu admin (atomik). 423 jika dipegang admin lain.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X POST "$API/roles/$ROLE_ID/training/lock" \
  -H "Authorization: Bearer $CLERK_TOKEN"

PATCH/api/roles/:id/training/heartbeatRESPONSE 200 · JSON

Denyut jantung dari admin pemegang lock (setiap 60 detik). Lock dianggap basi setelah 30 menit tanpa denyut.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X PATCH "$API/roles/$ROLE_ID/training/heartbeat" \
  -H "Authorization: Bearer $CLERK_TOKEN"

DELETE/api/roles/:id/training/lockRESPONSE 200 · JSON

Melepas kunci Training Room secara eksplisit (saat menutup panel).

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X DELETE "$API/roles/$ROLE_ID/training/lock" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/roles/:id/training/messagesRESPONSE 200 · JSON

Transkrip percakapan training + status role.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/roles/$ROLE_ID/training/messages" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/roles/:id/guideRESPONSE 200 · JSON

Guide terpublikasi role (chapter + pertanyaan kuis, tanpa kunci jawaban).

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/roles/$ROLE_ID/guide" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/roles/:id/assignable-usersRESPONSE 200 · JSON

Daftar karyawan org yang bisa ditugaskan + status assignment mereka.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/roles/$ROLE_ID/assignable-users" \
  -H "Authorization: Bearer $CLERK_TOKEN"

Knowledge Library

2 ENDPOINT

GET/api/knowledgeRESPONSE 200 · JSON

Daftar dokumen knowledge org + kuota (draft, storage, limit). Dokumen DRAFT tidak pernah dipakai AI.

PARAM	TIPE	STATUS	DESKRIPSI
q	string	Opsional	Filter pencarian (max 200)

LIHAT CONTOH CURL

curl "$API/knowledge?q=espresso" \
  -H "Authorization: Bearer $CLERK_TOKEN"

POST/api/knowledge/documentsRESPONSE 201 · JSON

Membuat dokumen knowledge manual (DRAFT; perlu dikonfirmasi sebelum dipakai AI). Batas draft 5 dokumen; 409 jika penuh.

PARAM	TIPE	STATUS	DESKRIPSI
title	string	Required	Judul (max 200)
content	string	Required	Teks dokumen (max 400.000)
description	string	Opsional	Deskripsi (max 500)

LIHAT CONTOH CURL

curl -X POST "$API/knowledge/documents" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Prosedur Jam Buka","content":"1. Nyalakan mesin. 2. Kalibrasi espresso…"}'

Employee Learning

9 ENDPOINT

GET/api/my/modulesRESPONSE 200 · JSON

Modul yang ditugaskan ke sesi pengguna, lengkap dengan progress.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/my/modules" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/my/modules/:roleId/chaptersRESPONSE 200 · JSON

Chapter guide + quiz (tanpa kunci jawaban) untuk modul yang ditugaskan.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/my/modules/$ROLE_ID/chapters" \
  -H "Authorization: Bearer $CLERK_TOKEN"

POST/api/my/chapters/:id/completeRESPONSE 201 · JSON

Menandai chapter selesai (upsert ChapterProgress untuk pengguna).

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl -X POST "$API/my/chapters/$CHAPTER_ID/complete" \
  -H "Authorization: Bearer $CLERK_TOKEN"

POST/api/my/chapters/:id/quiz/submitRESPONSE 201 · JSON

Mengirim jawaban kuis. Digrading server-side; correctIndex tidak pernah dikirim sebelum submit.

PARAM	TIPE	STATUS	DESKRIPSI
answers	number[]	Required	Index jawaban, urutan sesuai soal

LIHAT CONTOH CURL

curl -X POST "$API/my/chapters/$CHAPTER_ID/quiz/submit" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answers":[0,2,1,3]}'

POST/api/my/chat/sessionsRESPONSE 201 · JSON

Membuat sesi chat AI Tutor untuk role tertentu. Kapasitas 10 sesi/role, sesi tertua otomatis dibersihkan.

PARAM	TIPE	STATUS	DESKRIPSI
roleId	string	Required	Role yang ditugaskan ke pengguna

LIHAT CONTOH CURL

curl -X POST "$API/my/chat/sessions" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"roleId":"$ROLE_ID"}'

POST/api/my/chat/sessions/:id/messagesRESPONSE 201 · JSON

Mengirim pesan ke AI Tutor. Dibatasi rate limit (30/10 menit) + cooldown 2 detik per sesi.

PARAM	TIPE	STATUS	DESKRIPSI
content	string	Required	Pertanyaan karyawan

LIHAT CONTOH CURL

curl -X POST "$API/my/chat/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Bagaimana prosedur kalibrasi espresso?"}'

GET/api/my/chat/sessionsRESPONSE 200 · JSON

Daftar sesi chat AI Tutor milik pengguna (opsional filter ?roleId=).

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/my/chat/sessions?roleId=$ROLE_ID" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/my/chat/sessions/:id/messagesRESPONSE 200 · JSON

Riwayat percakapan sebuah sesi (ownership diverifikasi per request).

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/my/chat/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $CLERK_TOKEN"

GET/api/dashboard/summaryRESPONSE 200 · JSON

Ringkasan dashboard admin: jumlah, skor kuis, completion per role, aktivitas terbaru.

TANPA PARAMETER BODY

LIHAT CONTOH CURL

curl "$API/dashboard/summary" \
  -H "Authorization: Bearer $CLERK_TOKEN"

Keamanan & Batas

Setiap model tenant-owned selalu dibatasi orgId dari token sesi.
Kuis digrading di server; kunci jawaban tidak pernah bocor sebelum submit.
Semua teks user dibungkus <business_data> sebagai data, bukan instruksi.
Dokumen Knowledge Library hanya dipakai AI setelah dikonfirmasi (AKTIF); dokumen DRAFT dibatasi 5 per org.
Rate limit: training 20 pesan/10 menit · guide 3/jam · chat 15 pesan/5 menit + cooldown 2 detik.
Lock training tunggal per role, staleness 30 menit.