{"openapi":"3.1.0","info":{"title":"Upskera API","version":"1.0.0","description":"REST API for Upskera academies. Authenticate with an academy API key: `Authorization: Bearer <key>`. Lists use cursor pagination (`limit`, `cursor` → `nextCursor`).","contact":{"name":"Upskera developer support","email":"developers@upskera.io"}},"servers":[{"url":"https://localhost:3400/api/v1","description":"This region"}],"tags":[{"name":"Users"},{"name":"Organisation"},{"name":"Groups"},{"name":"Learning"},{"name":"Assessment"},{"name":"Credentials"},{"name":"Commerce"}],"paths":{"/users":{"get":{"tags":["Users"],"summary":"List users","x-summary-ar":"قائمة المستخدمين","security":[{"bearerAuth":[]}],"x-required-scope":"users:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Filter by exact email","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"ACTIVE | SUSPENDED | DEACTIVATED | INVITED","schema":{"type":"string"}},{"name":"updatedSince","in":"query","required":false,"description":"ISO date — users active since","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"firstNameAr":{"type":"string"},"lastNameAr":{"type":"string"},"status":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"orgUnitId":{"type":"string"},"jobRoleId":{"type":"string"},"employeeNo":{"type":"string"},"managerId":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":"string","format":"date-time"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Users"],"summary":"Create or invite a user","x-summary-ar":"إنشاء مستخدم أو دعوته","security":[{"bearerAuth":[]}],"x-required-scope":"users:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"firstNameAr":{"type":"string"},"lastNameAr":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"orgUnitId":{"type":"string"},"employeeNo":{"type":"string"},"sendInvite":{"type":"boolean"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"firstNameAr":{"type":"string"},"lastNameAr":{"type":"string"},"status":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"orgUnitId":{"type":"string"},"jobRoleId":{"type":"string"},"employeeNo":{"type":"string"},"managerId":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/users/{id}":{"get":{"tags":["Users"],"summary":"Get a user","x-summary-ar":"عرض مستخدم","security":[{"bearerAuth":[]}],"x-required-scope":"users:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"firstNameAr":{"type":"string"},"lastNameAr":{"type":"string"},"status":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"orgUnitId":{"type":"string"},"jobRoleId":{"type":"string"},"employeeNo":{"type":"string"},"managerId":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Users"],"summary":"Update a user (status, org unit, job role)","x-summary-ar":"تحديث مستخدم","security":[{"bearerAuth":[]}],"x-required-scope":"users:write","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"orgUnitId":{"type":"string"},"jobRoleId":{"type":"string"},"employeeNo":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"firstNameAr":{"type":"string"},"lastNameAr":{"type":"string"},"status":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"orgUnitId":{"type":"string"},"jobRoleId":{"type":"string"},"employeeNo":{"type":"string"},"managerId":{"type":"string"},"joinedAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/org-units":{"get":{"tags":["Organisation"],"summary":"List org units","x-summary-ar":"قائمة الوحدات التنظيمية","security":[{"bearerAuth":[]}],"x-required-scope":"org-units:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"nameAr":{"type":"string"},"parentId":{"type":"string"},"type":{"type":"string"},"costCenter":{"type":"string"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/org-units/{id}":{"get":{"tags":["Organisation"],"summary":"Get an org unit","x-summary-ar":"عرض وحدة تنظيمية","security":[{"bearerAuth":[]}],"x-required-scope":"org-units:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"nameAr":{"type":"string"},"parentId":{"type":"string"},"type":{"type":"string"},"costCenter":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/groups":{"get":{"tags":["Groups"],"summary":"List groups","x-summary-ar":"قائمة المجموعات","security":[{"bearerAuth":[]}],"x-required-scope":"groups:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"nameAr":{"type":"string"},"type":{"type":"string"},"memberCount":{"type":"integer"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/groups/{id}":{"get":{"tags":["Groups"],"summary":"Get a group with member ids","x-summary-ar":"عرض مجموعة وأعضائها","security":[{"bearerAuth":[]}],"x-required-scope":"groups:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"nameAr":{"type":"string"},"type":{"type":"string"},"memberCount":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/groups/{id}/members":{"post":{"tags":["Groups"],"summary":"Add members to a static group","x-summary-ar":"إضافة أعضاء إلى مجموعة","security":[{"bearerAuth":[]}],"x-required-scope":"groups:write","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/courses":{"get":{"tags":["Learning"],"summary":"List published courses","x-summary-ar":"قائمة الدورات المنشورة","security":[{"bearerAuth":[]}],"x-required-scope":"courses:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"titleAr":{"type":"string"},"status":{"type":"string"},"level":{"type":"string"},"durationMinutes":{"type":"integer"},"publishedAt":{"type":"string","format":"date-time"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/courses/{id}":{"get":{"tags":["Learning"],"summary":"Get a course","x-summary-ar":"عرض دورة","security":[{"bearerAuth":[]}],"x-required-scope":"courses:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"titleAr":{"type":"string"},"status":{"type":"string"},"level":{"type":"string"},"durationMinutes":{"type":"integer"},"publishedAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/enrollments":{"get":{"tags":["Learning"],"summary":"List enrollments","x-summary-ar":"قائمة التسجيلات","security":[{"bearerAuth":[]}],"x-required-scope":"enrollments:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"userId","in":"query","required":false,"description":"Filter by user","schema":{"type":"string"}},{"name":"courseId","in":"query","required":false,"description":"Filter by course","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"courseId":{"type":"string"},"status":{"type":"string"},"progress":{"type":"number"},"enrolledAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time"},"source":{"type":"string"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Learning"],"summary":"Enrol a user in a course","x-summary-ar":"تسجيل مستخدم في دورة","security":[{"bearerAuth":[]}],"x-required-scope":"enrollments:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"courseId":{"type":"string"},"dueAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"courseId":{"type":"string"},"status":{"type":"string"},"progress":{"type":"number"},"enrolledAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time"},"source":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/completions":{"get":{"tags":["Learning"],"summary":"List course completions","x-summary-ar":"قائمة إتمام الدورات","security":[{"bearerAuth":[]}],"x-required-scope":"completions:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"ISO date — completed since","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"courseId":{"type":"string"},"status":{"type":"string"},"progress":{"type":"number"},"enrolledAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time"},"source":{"type":"string"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/exam-results":{"get":{"tags":["Assessment"],"summary":"List released exam results","x-summary-ar":"قائمة نتائج الاختبارات المعلنة","security":[{"bearerAuth":[]}],"x-required-scope":"exams:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"examId","in":"query","required":false,"description":"Filter by exam","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"examId":{"type":"string"},"userId":{"type":"string"},"status":{"type":"string"},"score":{"type":"number"},"passed":{"type":"boolean"},"submittedAt":{"type":"string","format":"date-time"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/credentials":{"get":{"tags":["Credentials"],"summary":"List issued credentials","x-summary-ar":"قائمة الشهادات الصادرة","security":[{"bearerAuth":[]}],"x-required-scope":"credentials:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"userId","in":"query","required":false,"description":"Filter by user","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"titleAr":{"type":"string"},"status":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"verifyUrl":{"type":"string"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/credentials/{id}":{"get":{"tags":["Credentials"],"summary":"Get a credential","x-summary-ar":"عرض شهادة","security":[{"bearerAuth":[]}],"x-required-scope":"credentials:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"titleAr":{"type":"string"},"status":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"verifyUrl":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orders":{"get":{"tags":["Commerce"],"summary":"List orders","x-summary-ar":"قائمة الطلبات","security":[{"bearerAuth":[]}],"x-required-scope":"orders:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 25)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's nextCursor","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"PAID | REFUNDED | PENDING_PAYMENT …","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"userId":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"totalMinor":{"type":"integer"},"vatMinor":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"}}}},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"get":{"tags":["Commerce"],"summary":"Get an order","x-summary-ar":"عرض طلب","security":[{"bearerAuth":[]}],"x-required-scope":"orders:read","parameters":[{"name":"id","in":"path","required":true,"description":"Resource id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"userId":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"totalMinor":{"type":"integer"},"vatMinor":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Academy API key (upk_live_… or upk_test_…)"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}