This document describes the API endpoints available for programmable access to core Xen functions.

Introduction

Xen runs a comprehensive set of REST APIs which cover everything from viewing the course catalogue, to managing users, to administering e-commerce operations, and extracting insights/analytics data. 

These APIs are leveraged extensively within the Xen codebase itself for inter-application communications and operations across its many components, but they can also be leveraged for external access during an integration with a third party system or building a custom Django app to be loaded in Xen platform.

Access

All endpoints are private by default. When required, Xen may expose endpoints to specific customers and third-parties, by deploying dedicated proxy endpoints via secured token-based authentication using the Django REST Framework.

Documentation

1. Authentication 1.0.
   This API provides the functionality of receiving and updating the user account details and preferences, helping provide personalised user experience across multiple devices.

2. Users API version 1.0.
   This API provides the functionality of receiving and updating the user account details and preferences, helping provide personalised user experience across multiple devices.

3. Enrolments API version 1.1.
   This API allows finding out whether the user enrolled on a course or not, how many users are enrolled for a course, list all courses the user is enrolled to and actually enrol the user to a course.

4. Courseware API version 1.2.
   This API allows interacting with the courseware catalog stored in the Xen platform and getting the details for each of programs and courses.

5. Progress API version 1.0.
   This API allows the retrieval of Learners current grades and completion of pre-requisites in each course they are enrolled in.

Preamble

Important concepts

Programs

A Program can bundle an unlimited amount of individual Courses of any type and origins, and in a specific order. Programs have a schedule and an optional maximum quota of Learners associated, and are ran for a specific organisation or sub-organisation of the tenant.

The program ID is the unique primary key referencing a Program of Courses on the Xen platform.

Courses

A Course is the smallest package of content that Learners can be enrolled in on the Xen platform.

The course ID is the unique primary key referencing a course and its run on the Xen platform.
It is created automatically by the platform when a new course is created, using key information: 

1. The courseware version ("course-v1"),

2. The colon separator (":"),

3. The organisation’s short name (ex: "XEN"),

4. The plus sign separator ("+"),

5. The course “number”, as provided during the course creation process (ex: "DEMO"),

6. The plus sign separator ("+"),

7. the course run, as provided during the course creation process (ex: "1").

Example:
course-v1:XEN+DEMO+1

Course mode

The mode defines how the learners are enrolled in a course. It describes the requirement level for identity verification, in use-cases such as accredited courses for the purpose of certificates as well as recognition of prior learning.

Organisations running un-accredited courses would only use "honor" mode, which indicate there is no Identification requirement.

State of data

Real-time

The data available from these endpoints is deemed near-real time, with most endpoints returning up-to-date data. In some particular use-cases, endpoints can have a potential delay up to 15 minutes due to the platform’s architecture and the traffic incurred on jobs pipelines and workers. 

Typically, this would affect Grading and Completion endpoints, as well as large operations in updating the courseware (import/export/drag & drop of sections …).

Historical records

Some endpoints can return historical data. if it is available in the platform, such as reporting on activities, insights, analytics . This data can be traversed via date and time filters.

Other endpoints will only return absolute data which state is overwritten over time, such as course content, user status, enrolment status …. For such endpoints, Xen encourage API users to regularly pull and save whenever historical tracking is required. Xen can implement custom notifications to alert remote systems whenever a change has occurred - Ref. next section “Webhooks”.

Webhooks

Custom triggers can be added by the Xen Engineering team upon request, to push notifications via webhooks to remote systems on specific events (change to a user status, unsubscribe from alerts, grades & completion, …).

Pagination

Pagination is enforced on all endpoints to:

• Serve requests in a timely manner (e.g. < 2s)

• Ensure the amount of data returned remains within a manageable payload (ex: < 500kb)

• Ensure the data in the response is easily manageable to improve the user experience when directly connected to a front-end (ex: courseware widgets).

Out of range

If the client requests a page that this out of the valid range for the collection, then the response body will contain an empty collection with HTTP Status code as 200.

Credentials

Xen will issue 2 sets of authentication for each implementation: Sandbox and Production.

Sandbox

Production

Postman

On request, Xen may provide an API definition file for import into Postman.

Test courses

Test courses will be provided in staging environment to test the API endpoints, and communicated to your team or integration partner.

Staging

API calls

Allowed HTTP/S requests

• POST - To create or update a resource

• GET - To retrieve a resource or list of resources

Standard server responses

• 200 OK - GET - the request was successful, an existing resource is returned

• 201 Created - POST - the request was successful, a new resource is created and returned

• 204 No Content - DELETE - the request was successful, an existing resource is removed

• 401 Unauthorized - POST - authentication failed, or user lacks permission to execute the requested operation.

• 403 Forbidden - POST - authentication successful, but user is inactive

• 404 Not Found - GET - no existing resource matches the provided identifier

• 405 Method Not Allowed - POST/GET/DELETE - requested method is not supported for resource.

• 406 Not Acceptable - POST - request syntax is correct, but semantic issue(s) were encountered.

• 409 Conflict - POST - request conflicts with existing system state (e.g., duplicate resource).
  _{409 Conflicts arise during POST operations due to duplicate requests against constrained entities. 
  An additional set of elements may be included in the response:}  
  { . . . "message":"Information related to the conflict.", "field_conflict":"fieldname" }

1. Authentication 

1.1 Access Token

The Xen Platform APIs utilise ReST design principles with OAuth2 authentication functionality and employ the JSON format of data interchange.

To Get the Access Token for the API access:

End Point: 

POST <base_url>/oauth2/access_token

Parameters:

{
  grant_type: client_credentials,
  token_type: jwt,
  client_id: <client_id>,
  client_secret: <client_secret>
}

Sample Response:

{
    "token_type": "JWT",
    "scope": "profile openid email permissions",
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzY29wZXMiOiBbInByb2ZpbGUiLCAib3BlbmlkIiwgImVtYWlsIiwgInBlcm1pc3Npb25zIl0sICJhZG1pbmlzdHJhdG9yIjogdHJ1ZSwgInN1cGVydXNlciI6IHRydWUsICJwcmVmZXJyZWRfdXNlcm5hbWUiOiAiZ2FuZXNoIiwgImZpbHRlcnMiOiBbXSwgImlhdCI6IDE2MzcyMTc2NTIsICJzdWIiOiAiMjFkZTI2N2I4ZGJmYTQwNzA2NjFmMjRkYzdkMDRmZGYiLCAiZmFtaWx5X25hbWUiOiAiIiwgImF1ZCI6ICJzdGcueGVub3BzLmlvIiwgImlzcyI6ICJodHRwczovL2xlYXJuLnN0Zy54ZW5vcHMuaW8vb2F1dGgyIiwgImVtYWlsX3ZlcmlmaWVkIjogdHJ1ZSwgIm5hbWUiOiAiR2FuZXNoIEt1bWFyIiwgInZlcnNpb24iOiAiMS4xLjAiLCAiZ2l2ZW5fbmFtZSI6ICIiLCAiZXhwIjogMTY2ODc1MzY1MSwgImlzX3Jlc3RyaWN0ZWQiOiBmYWxzZSwgImVtYWlsIjogImdhbmVzaGt1bWFya0BjcnlzdGFsZGVsdGEuY29tIn0.JHtcQIiHUwo-IInkbXyKjt042l7dhaHU6K35wK6c0Ow",
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmYW1pbHlfbmFtZSI6IiIsImFkbWluaXN0cmF0b3IiOnRydWUsInN1YiI6IjIxZGUyNjdiOGRiZmE0MDcwNjYxZjI0ZGM3ZDA0ZmRmIiwiaXNzIjoiaHR0cHM6Ly9sZWFybi5zdGcueGVub3BzLmlvL29hdXRoMiIsInVzZXJfdHJhY2tpbmdfaWQiOjgsInByZWZlcnJlZF91c2VybmFtZSI6ImdhbmVzaCIsIm5hbWUiOiJHYW5lc2ggS3VtYXIiLCJsb2NhbGUiOiJlbiIsImdpdmVuX25hbWUiOiIiLCJleHAiOjE2MzcyMjEyNTIsImlhdCI6MTYzNzIxNzY1MiwiZW1haWwiOiJnYW5lc2hrdW1hcmtAY3J5c3RhbGRlbHRhLmNvbSIsImF1ZCI6IjFiMGU2ODY1NGVjNjJmYTIxZDcyIn0.MwcnIHEQbcdz7oNWND2RX7HDY5OEqakBCG3F9lweAY8",
    "expires_in": 31535999
}

2. User

2.1 Get user  

For the requested username, returns 200 or 404. 

End Point: 

GET <base_url>/xened/api/v1/user/account/{username}

Headers:

Authorization: JWT <access_token>

Sample Response:

200

2.2 Create User 

Registers a new user in the organisation and grants access to the login, dashboard, and profile page.

Parameters

• username (mandatory): The learner’s username. Must be unique across the organisation.

• email (mandatory): The learner’s email address. Must be unique across the organisation.

• name (mandatory): The learner’s full name in a single string.

By default, no activation email nor invitation will be sent.

End Point: 

POST <base_url>/xened/api/v1/user/account

Headers:

Authorization: JWT <access_token>

Request Body: 

{
    "username": "johndoe",
    "email": "john.doe@gmail.com",
    "name": "John Doe"
}

Sample Response:

201

2.3 Update User 

Updates a registered user in the organisation.

Parameters

• name (mandatory): The learner’s full name in a single string.

• email (mandatory): The learner’s email address. Must be unique across the organisation.

• is_active (mandatory): A boolean flag to activate/deactivate the user’s registration status.

End Point: 

POST <base_url>/xened/api/v1/user/account_update/<username>

Headers:

Authorization: JWT <access_token>

Request Body: 

{
    "name": "johndoe",
    "email": "john.doe@Xen.education",
    "is_active": true or false # to make user active or inactive
}

Sample Response:

201

3. Enrolment

3.1 Get Enrolments  

Returns the list of enrolments available for the the specified objects:

• A single registered user,

• A single existing course,

• Or the combination of both.

Parameters

• username (optional): The learner’s unique username. Must be a registered user.

• course_id (optional): The course’s unique ID. Must be a valid running course (actively scheduled) and open for enrolment. The value must be URL encoded. Refer to Course ID for more information.

End Point: 

GET <base_url>/xened/api/v1/enrollments/{course_id},{username}

Headers:

Authorization: JWT <access_token>

Sample Response:

{
  "course_id": "course-v1:XEN+DEMO+1",
  "username": "johndoe"
}

3.2 Enrol user into a single course 

Enrols the specified registered user in the specified course for this organisation.

Parameters

• username (mandatory): The learner’s unique username. Must be a registered user.

• course_id (mandatory): The course’s unique ID. Must be a valid running course (active schedule) and open for enrolment. The value must be URL encoded. Refer to Course ID for more information.

• is_active (mandatory): A boolean flag to activate/deactivate the enrolment. Set to true in order to remove the enrolment. 

• mode (mandatory): The enrolment type based on the course, from “honor”, “no-id-professional”, “verified”, “audit”, “staff”.

End Point: 

POST <base_url>/xened/api/v1/user/enroll

Headers:

Authorization: JWT <access_token>

Request Body:

{
    "username": "jdoe1234",
    "is_active": true,
    "course_id": "course-v1:XEN+DEMO+1"
}

Sample Response:

{
    "created": "2021-11-18T16:39:45.914758Z",
    "mode": "honor",
    "is_active": true,
    "course_details": {
        "course_id": "course-v1:XEN+DEMO+1",
        "course_name": " Xen - Demo Course",
        "enrollment_start": null,
        "enrollment_end": null,
        "course_start": "2030-01-01T00:00:00Z",
        "course_end": null,
        "invite_only": false,
        "course_modes": [ 
            {
                "slug": "honor",
                "name": "Honor",
                "min_price": 0,
                "suggested_prices": "",
                "currency": "aud",
                "expiration_datetime": null,
                "description": null,
                "sku": null,
                "bulk_sku": null
            }
        ]
    },
    "user": "ganesh"
}

3.3. Un-Enrol user form a single course 

Removes the enrolment for a specified user in a specified course within the organisation.

Parameters

• username (mandatory): The learner’s unique username. Must be a registered user.

• course_id (mandatory): The course’s unique ID. Must be a valid running course (active schedule) and open for enrolment. The value must be URL encoded. Refer to Course ID for more information.

• is_active (mandatory): A boolean flag to activate/deactivate the enrolment.
  Set to false in order to remove the enrolment.

End Point: 

POST <base_url>/xened/api/v1/user/enroll

Headers:

Authorization: JWT <access_token>

Request Body: 

{
    "username": "jdoe1234",
    "course_id": "course-v1:XEN+DEMO+1",
    "is_active": false
}

Sample Response:

{
    "created": "2021-11-18T16:39:45.914758Z",
    "mode": "honor",
    "is_active": false, # false means the enrolment is inactive
    "course_details": {
        "course_id": "course-v1:XEN+DEMO+1",
        "course_name": " Xen - Demo Course",
        "enrollment_start": null,
        "enrollment_end": null,
        "course_start": "2030-01-01T00:00:00Z",
        "course_end": null,
        "invite_only": false,
        "course_modes": [
            {
                "slug": "honor",
                "name": "Honor",
                "min_price": 0,
                "suggested_prices": "",
                "currency": "aud",
                "expiration_datetime": null,
                "description": null,
                "sku": null,
                "bulk_sku": null
            }
        ]
    },
    "user": "ganesh"
}

4. Courseware

4.1 Create Course  

Creates a course in the organisation’s courseware.

Parameters

• name (mandatory): Course name, min. 3 chars.

• course_number (mandatory): An alphanumerical value to identify the course.
  Ex: "DEMO" (for "Xen Demo Course").

• course_run (mandatory): An alphanumerical value to identify version of the course.
  Ex: "1" (for "Xen Demo Course").

• start_date (mandatory): The date & time (past or future) when the course can start, in the format 2020-01-01 00:00:00+00:00

• end_date (mandatory): the date & time (past or future, but after the start_date) when the course will stop, in the format 2020-01-01 00:00:00+00:00

• enrolment_start_date (mandatory): The date & time (past or future, but before course start_date) when the learners can enrol in the course, in the format 2020-01-01 00:00:00+00:00

• enrolment_end_date (mandatory): the date & time (past or future, but after enrolment_start_date and before course end_date) when learners can no longer enrol, in the format 2020-01-01 00:00:00+00:00

The primary key Course ID will be created automatically, based on:

1. Platform version (“course-v1”)

2. Organisation short name (Ex: "XEN")

3. Course number

4. Course run

Ex: course-v1:XEN+DEMO+1

Refer to “Course ID” for more information.

By default, a new course is un-scheduled and open for enrolment, so every call inherits the following attributes:

• Start date: 01/01/2030

• End date: Empty

• Enrolment start: Empty

• Enrolment End: Empty

End Point: 

POST <base_url>/xened/api/v1/course/

Headers:

Authorization: JWT <access_token>

Request Body: 

{
    "name": "Xen Course Demo",
    "course_number": "DEMO",
    "course_run": "1"
}

Sample Response:

{
  "course_id": "course-v1:XEN+DEMO+1"
}

4.2 Update Course  

Update an existing course for the organisation, using the unique Course ID provided in the “Create Course” call. The course_id value must be URL encoded. Refer to “Course ID” for more information.

Parameters

• name (optional): Course name, min. 3 chars.

• start_date (optional): The date & time (past or future) when the course can start, in the format 2020-01-01 00:00:00+00:00

• end_date (optional): the date & time (past or future, but after the start_date) when the course will stop, in the format 2020-01-01 00:00:00+00:00

• enrolment_start_date (optional): The date & time (past or future, but before course start_date) when the learners can enrol in the course, in the format 2020-01-01 00:00:00+00:00

• enrolment_end_date (optional): the date & time (past or future, but after enrolment_start_date and before course end_date) when learners can no longer enrol, in the format 2020-01-01 00:00:00+00:00

End Point: 

POST <base_url>/xened/api/v1/course/{course_id}

Headers:

Authorization: JWT <access_token>

Request Body: 

{
    "name": "Xen Demo Course"
}

Sample Response:

201

4.3 List Courses  

Returns the list of courses available in the organisation and some meta data for each course:

• Course ID.

• Name (title).

• Short description.

• Hidden (visibility in the courseware, as a boolean).

• Effort.

• Start Date (2020-01-01 00:00:00+00:00).

• End Date (2020-01-01 00:00:00+00:00).

• Enrolment Start Date (2020-01-01 00:00:00+00:00).

• Enrolment End Date (2020-01-01 00:00:00+00:00).

• Media:

  • Card Image URI (single size).

  • Video URI (single format).

• Pacing (self-paced or instructor-led)

• Custom Attributes array (these can be used in the catalog search front-end and are specific to each organisation).

End Point: 

GET <base_url>/xened/api/v1/courses/

Headers:

Authorization: JWT <access_token>

Sample Response:

{
  "results": [
    {
      "id": "course-v1:XEN+DEMO+1",
      "effort": "2:00",
      "end": null,
      "enrollment_start": "2015-07-21T10:00:00Z",
      "enrollment_end": "2016-06-29T10:00:00Z",
      "media": {
        "course_image": {
          "uri": "/asset-v1:adam+Mac_APccx+e0d+type@asset+block@Davidson_xen-68_1_.png"
        },
        "course_video": {
          "uri": "http://www.youtube.com/watch?v=sAnHwOL8aAs"
        }
      },
      "name": "ntest",
      "short_description": "This course teaches the fundamentals for engineering long-lived software using Agile techniques to develop Software as a Service (SaaS) using Ruby on Rails.",
      "start": "2016-06-27T14:10:44Z",
      "pacing": "instructor",
      "hidden": false,
      "attributes": {
        "topics": ["Software Engineering","Business & Management", "IT & Computer Science"],
        "color": ["Red","Blue"]
        }
      },
    },
    {
      "id": "course-v1:XEN+DEMO+1",
      "effort": "2:00",
      "end": null,
      "enrollment_start": "2015-07-21T10:00:00Z",
      "enrollment_end": "2016-06-29T10:00:00Z",
      "media": {
        "course_image": {
          "uri": "/asset-v1:adam+Mac_APccx+e0d+type@asset+block@Davidson_xen-68_1_.png"
        },
        "course_video": {
          "uri": "http://www.youtube.com/watch?v=sAnHwOL8aAs"
        }
      },
      "name": "ntest",
      "short_description": "This course teaches the fundamentals for engineering long-lived software using Agile techniques to develop Software as a Service (SaaS) using Ruby on Rails.",
      "start": "2016-06-27T14:10:44Z",
      "pacing": "instructor",
      "hidden": false,
      "attributes": {
        "topics": ["Software Engineering","Business & Management", "IT & Computer Science"],
        "color": ["Red","Blue"]
        }
      },
    },
    {
      "id": "course-v1:XEN+INTER+1",
      "effort": "2:00",
      "end": null,
      "enrollment_start": "2015-07-21T10:00:00Z",
      "enrollment_end": "2016-06-29T10:00:00Z",
      "media": {
        "course_image": {
          "uri": "/asset-v1:adam+Mac_APccx+e0d+type@asset+block@Davidson_xen-68_1_.png"
        },
        "course_video": {
          "uri": "http://www.youtube.com/watch?v=sAnHwOL8aAs"
        }
      },
      "name": "ntest",
      "short_description": "This course teaches the fundamentals for engineering long-lived software using Agile techniques to develop Software as a Service (SaaS) using Ruby on Rails.",
      "start": "2016-06-27T14:10:44Z",
      "pacing": "instructor",
      "hidden": false,
      "attributes": {
        "topics": ["Software Engineering","Business & Management", "IT & Computer Science"],
        "color": ["Red","Blue"]
        }
      },
    },
    {
      "id": "course-v1:XEN+STARTER+1",
      "effort": "2:00",
      "end": null,
      "enrollment_start": "2015-07-21T10:00:00Z",
      "enrollment_end": "2016-06-29T10:00:00Z",
      "media": {
        "course_image": {
          "uri": "/asset-v1:adam+Mac_APccx+e0d+type@asset+block@Davidson_xen-68_1_.png"
        },
        "course_video": {
          "uri": "http://www.youtube.com/watch?v=sAnHwOL8aAs"
        }
      },
      "name": "ntest",
      "short_description": "This course teaches the fundamentals for engineering long-lived software using Agile techniques to develop Software as a Service (SaaS) using Ruby on Rails.",
      "start": "2016-06-27T14:10:44Z",
      "pacing": "instructor",
      "hidden": false,
      "attributes": {
        "topics": ["Software Engineering","Business & Management", "IT & Computer Science"],
        "color": ["Red","Blue"]
        }
      }
    }
  ]
}

4.5 Single course details  

Returns the full details of the specified course:

• Course ID.

• Name (title).

• Short description.

• Hidden (visibility in the courseware as a boolean).

• URL.

• Start Date (2020-01-01 00:00:00+00:00).

• End Date (2020-01-01 00:00:00+00:00).

• Enrolment Start Date (2020-01-01 00:00:00+00:00).

• Enrolment End Date (2020-01-01 00:00:00+00:00).

• Duration.

• Associated Media URLs:

  • Card Image URI (single size).

  • Video URI (single format).

• Custom Attributes (these are specific to each organisation):

  • Type.

  • Topics.

  • …

• Requirements.

• Effort (in hourly format hh:mm)

• Pacing (self-paced or instructor-led)

• Pre-requisite (returns the linked Course ID)

End Point: 

GET <base_url>/xened/api/v1/program/{program_id}

Headers:

Authorization: JWT <access_token>

Sample Response:

5. Grades & Progress

WARNING: This endpoint is scheduled to be deprecated by mid-2026, and should not be used for new integration. All integrations requesting progress, grades, and usage data should favour implementing xAPI statements into the Xen LRS.

Exposes grades and progress (pre-requisites completion, incl. pages viewed, videos finished, games success), at all levels:

• Course (or lesson)

• Programs (or course)

• Overall (all programs & courses enrolled).

What is that data, and its types - need map entities and their dependencies & relationships.

5.1 Get grades 

Returns all progress entries.