NAV Navbar
shell

Introduction

Welcome to the Learnworlds API! You can use our API to access our endpoints, which can get information on various courses, user info and more.

We have language bindings in Shell! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Learnworlds uses OAuth2 to allow access to it's API. You may request credentials to start using the API with a Learning Center or Corporate plan via your School (under Settings -> Premium Subscriptions).

Authorization: Bearer your_access_token

Client credentials grant

# With shell, you can just pass the correct header with each request
curl "https://api.learnworlds.com/oauth2/access_token" \
  -H "Lw-Client: your_client_id" \
  -d data='{"client_id":"your_client_id","client_secret":"your_client_secret","grant_type":"client_credentials"}'

The above command returns JSON structured like this:

{
  "tokenData": {
    "access_token": "tZGB6EHKfzMs9ecUFhPxDtXflQPKqHACIvcrd4Wx",
    "token_type": "Bearer",
    "expires_in": 8000
  },
  "errors": [],
  "success": true
}

This grant is similar to the resource owner credentials grant except only the client’s credentials are used to authenticate a request for an access token. This grant should only be allowed to be used by trusted clients.

This grant is suitable for machine-to-machine authentication, for example for use in a cron job which is performing maintenance tasks over an API or sending information to a webhook about a new user purchase. Another example would be a client making requests to an API that doesn’t require user’s permission.

Keep this access_token a secret.

Resource owner credentials grant

# With shell, you can just pass the correct header with each request
curl "https://api.learnworlds.com/oauth2/access_token" \
  -H "Lw-Client: your_client_id" \
  -d data='{"client_id":"your_client_id","client_secret":"your_client_secret","grant_type":"password","email":"info@learnworlds.com","password":"learnworlds"}'

The above command returns JSON structured like this:

{
  "tokenData":{
    "access_token":"WU5I1WGdG8Q0c5ujbOhMdwxB8GUNqXZcIUIYSHbo",
    "token_type":"Bearer",
    "expires_in":8000,
    "refresh_token":"X5aGSMjMuSTDH2GJluEtaWbedL8E5GK5mCj9pw4D"
  },
  "errors":[],
  "success":true
}

When this grant is implemented the client itself will ask the user for their username and password (as opposed to being redirected to an IdP authorisation server to authenticate) and then send these to the authorisation server along with the client’s own credentials. If the authentication is successful then the client will be issued with an access token.

This grant is suitable for trusted clients such as a service’s own mobile client (for example Spotify’s iOS app).

We recommend using a proxy for retrieving user access_tokens as to not expose your client_secret. By sending the users username and password to your server and then adding the client_id/client_secret & grant to the request before forwarding it to us, your able to achieve this.

Refresh token grant

# With shell, you can just pass the correct header with each request
curl "https://api.learnworlds.com/oauth2/access_token" \
  -H "Lw-Client: your_client_id" \
  -d data='{"client_id":"your_client_id","client_secret":"your_client_secret","grant_type":"refresh_token","refresh_token":"your_refresh_token"}'

The above command returns JSON structured like this:

{
  "tokenData":{
    "access_token":"arixvvB0brmj4n79XFdkL2RIpZ2kGmyKKJ6mBMEC",
    "token_type":"Bearer",
    "expires_in":8000,
    "refresh_token":"sS1NWMgUokADowkG5jU1DFKWpapYz04mOir7Et7n"
  },
  "errors":[],
  "success":true
}

If you send a bad or expired access token we will respond with the following error.

{
  "errors": [
    {
      "code": 400,
      "context": "access_denied",
      "message": "The resource owner or authorization server denied the request."
    }
  ],
  "success": false
}

As you might have noticed, when using the Credentials grant you also get a refresh token. When the access token expires instead of sending the user back through the authorisation code grant the client can use to the refresh token to retrieve a new access token with the same permissions as the old one.

We recommend using a proxy for this request also, as not to expose your client_secret.

Courses

Get All Courses

curl "https://api.learnworlds.com/courses" \
  -H "Authorization: Bearer your_access_token" \
  -H "Lw-Client: your_client_id"

The above command returns JSON structured like this:

{
  "courses": {
    "55e636b08a54858e0d7b23c6": {
      "title": "Magic School Bus",
      "titleId": "magic_school_bus",
      "courseType": "path",
      "tags": [
        "magic",
        "bus"
      ],
      "keywords": "This is a description",
      "points": null,
      "authors": [],
      "quotes": null,
      "order": null,
      "courseImage": {
        "url": "https://www.learnworlds.com/app/themes/learnworlds/dist/images/learnworlds-nav-menu-logo.png",
        "name": "/learnworlds-nav-menu-logo.png"
      },
      "bgcolor": "#90c0dc",
      "price": "700",
      "discountFlag": true,
      "discountPrice": "200",
      "introVideoVimeoId": "126142034",
      "knowledgeBadges": "0",
      "goalTotal": "120 minutes",
      "numVideos": "0",
      "numPages": "0",
      "socialMedia": null,
      "access": "public",
      "created": 1441150959.6198,
      "modified": 1443142668.2891,
      "registeredUsers": 0,
      "id": "55e637ef8a54858e0d7b23c7",
      "premium": true,
      "currency": "$",
    }
  },
  "coursesTags": [
    {
      "tag": "",
      "count": 3
    }
  ],
  "errors": [],
  "success": true
}

This endpoint retrieves all courses.

HTTP Request

GET https://api.learnworlds.com/courses

Get parameters

Parameter Description
tag The tag you want to limit the results to (courses belonging to category "tag").
instructor Courses of an instructor (can be an email or user id).

Get a Specific Course

curl "https://api.learnworlds.com/course/:titleId" \
  -H "Authorization: Bearer your_access_token" \
  -H "Lw-Client: your_client_id"

The above command returns JSON structured like this:

{
  "course": {
    "title": "Welcome to Learnworlds",
    "titleId": "welcome_to_learnworlds",
    "courseType": "path",
    "tags": [
      "learnworlds"
    ],
    "keywords": "This is a description",
    "points": null,
    "authors": [],
    "quotes": null,
    "order": null,
    "courseImage": {
      "url": "https://www.learnworlds.com/app/themes/learnworlds/dist/images/learnworlds-nav-menu-logo.png",
      "name": "/learnworlds-nav-menu-logo.png"
    },
    "bgcolor": "#90c0dc",
    "price": "2221",
    "discountFlag": false,
    "discountPrice": "0",
    "introVideoVimeoId": "",
    "knowledgeBadges": "0",
    "goalTotal": "120 minutes",
    "numVideos": "0",
    "numPages": "0",
    "socialMedia": null,
    "access": "public",
    "created": 1441150640.499,
    "modified": 1443091571.6427,
    "registeredUsers": 5,
    "id": "55e636b08a54858e0d7b23c6",
    "premium": true,
    "currency": "$"
  },
  "errors": [],
  "success": true
}

This endpoint retrieves a specific course.

HTTP Request

GET https://api.learnworlds.com/course/<titleId>

All users in a course

curl "https://api.learnworlds.com/users/course/:titleId" \
  -H "Authorization: Bearer your_access_token" \
  -H "Lw-Client: your_client_id"

The above command returns JSON structured like this:

{
  "learners": [
    {"id" : "5591119ee4b4c8d522000000", "username" : "John Cena"},
    {"id" : "5591119ee4b4c8d522000001", "username" : "Jack Smith"}
  ],
  "errors": [],
  "success": true
}

This endpoint retrieves all users enrolled in a course.

HTTP Request

GET https://api.learnworlds.com/users/course/<titleId>

Users

Create a user

POST https://api.learnworlds.com/users

curl https://api.learnworlds.com/users \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token" \
-d data='{"username":"learnworlds","password":"learnworlds","email":"info@learnworlds.com","avatar":"http://placehold.it/100x100"}'

The above command returns JSON structured like this:

{
  "user":{
    "id":"560a96b48a548585107b23c7",
    "created":"1443534516.2655"
  },
  "errors":[],
  "success":true
}

This endpoint creates a user.

Post parameters

Parameter Description
username The user's username (not unique).
email The user's email (unique)
password The user's passoword.
avatar A url to a user's avatar.

Retrieve Users

GET https://api.learnworlds.com/users

curl "https://api.learnworlds.com/users" \
  -H "Authorization: Bearer your_access_token" \
  -H "Lw-Client: your_client_id"

The above command returns JSON structured like this:

{  
   "users":[{  
      "username":"John Smith",
      "bio":"Loves to learn!",
      "location":"",
      "url":"",
      "fb":"",
      "twitter":"",
      "google":"",
      "linkedin":"",
      "skype":"",
      "behance":"",
      "dribbble":"",
      "github":"",
      "courses":[  
         {  
            "titleId":"magic_school_bus",
            "id":"55e636b08a54858e0d7b23c6"
         },
         {  
            "titleId":"magic_school_bus_2",
            "id":"55e636b08a54858e0d7b23c7"
         },
         {  
            "titleId":"magic_school_bus3",
            "id":"55e636b08a54858e0d7b23c8"
         }
      ],
      "isInstructorIn":null,
      "id":"55e58b7f8a5485b4647b23c6",
      "followers_count":2,
      "following_count":2,
      "followers_last":[  
          {  
            "id":"560aaf8d8a548580107b23c6",
            "username":"John Smith"
          },
          {  
            "id":"55f6e1878a548593097b23c6",
            "username":"John Cena"
          }
      ],
      "following_last":[  
         {  
            "id":"560aaf8d8a548580107b23c6",
            "username":"John Smith"
         },
         {  
            "id":"55f6e1878a548593097b23c6",
            "username":"John Cena"
         }
      ],
      "groups":[  
         {  
            "name":"bookclub",
            "id":"562132b38a5485df257ae46d",
            "me_owner":true,
            "new_posts":0,
            "members_count":2
         }
      ],
      "stats":{  
         "hours":1497,
         "notes":4,
         "fav":1,
         "posts":27,
         "comments":4,
         "likes":2,
         "bestof":0,
         "tips":0,
         "lcs":0
      },
      "badges_list":[  
         {  
            "awarded_time":1441107572.2102,
            "category":"social",
            "expired_on":null,
            "expires":"no",
            "expires_time":null,
            "knowledge":null,
            "message":"are a new member.",
            "title":"Newbie",
            "url":null,
            "user_badge_id":false,
            "user_id":{  
               "id":"55e58b7f8a5485b4647b23c6",
               "username":"John Smith"
            },
            "image":"https:\/\/learnworlds.blob.core.windows.net\/startup\/badges\/newbie.png",
            "description":"new members",
            "badge_class_file":"System\\Newbie"
         },
         {  
            "url":null,
            "title":"Active Member",
            "awarded_time":1442153863.9428,
            "category":"social",
            "knowledge":null,
            "expires":"yes",
            "user_badge_id":false,
            "expired_on":null,
            "expires_time":null,
            "user_id":{  
               "id":"55e58b7f8a5485b4647b23c6",
               "username":"John Smith"
            },
            "message":"have made  10 social actions in 1 month.",
            "image":"https:\/\/learnworlds.blob.core.windows.net\/public\/startup\/active-member.png",
            "description":"members who have made 10 or more social actions in 1 month",
            "badge_class_file":"System\\ActiveMember"
         }
      ],
      "certifications":[  
         {  
            "object_id":"5628b8ef8a5485d2097b23c7",
            "courseId":"5628b2218a548572087b23c6",
            "title":"Certificate of Accomplishment in How to Build a Robot",
            "image":null,
            "created":1445513496.3002,
            "status":"active",
            "type":"certificate",
            "printed":null,
            "sent":null,
            "score":66,
            "id":"5628c9188a5485220c7b23c6",
            "courseTitle":"Magic School Bus",
            "courseTitleId":"magic_school_bus",
            "certForm":{  
               "title":"Mr",
               "firstname":"John",
               "middlename":"",
               "lastname":"Smith",
               "email":"info@learnworlds.com",
               "phone":"123231231",
               "mobile":"123123123",
               "address":"23 California St.",
               "city":"Los Angeles",
               "state":"California",
               "postcode":"92102",
               "company":"Learnworlds",
               "companyphone":"1233213123123",
               "experience":"4-6",
               "education":"Bachelors",
               "college":"UCLA",
               "graduation":"2010",
               "aggree":"yes"
            }
         }
      ]
   }],
   "errors":[],
   "success":true
}

Get parameters

Parameter Description
isInstructor Limit the results if a user is an instructor (true/false).

This endpoint retrieves users.

Enroll a user to a Product

POST https://api.learnworlds.com/user-product

This endpoint enrolls a user to a product.

curl https://api.learnworlds.com/user-product \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token" \
-d data='{"user":"info@learnworlds.com", "product":"welcome_to_learnworlds", "type":"course", "justification":"offline payment", "price":99}'

The above command returns JSON structured like this:

{
  "success": true
}

Post parameters

Parameter Description
user The user's email or id you want to give the product to.
product The id of the product (more info here).
type The product type (course, bundle, subscription)
justification Justify the course enrollment, ex. Offline Payment, API Enrollment or Transaction ID of payment (this is also shown to the user in their account page)
price (Optional) Defaults to 0 if not provided, must be a numeric value
create_user (Optional) If the user does not exist then an account will be created and a link will be sent via email to allow them to set a password to their account. The username parameter can also be provided in this case otherwise the email will be used by default.
username (Optional) Used in combination with create_user, defaults to the user's email if not provided

Unenroll a user from a Product

DELETE https://api.learnworlds.com/user-product

This endpoint unenrolls a user from a product.

curl -X DELETE https://api.learnworlds.com/user-product \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token" \
-d data='{"user":"info@learnworlds.com", "product":"welcome_to_learnworlds", "type":"course"}'

The above command returns JSON structured like this:

{
  "success": true
}

Delete parameters

Parameter Description
user The user's email or id you want to give the product to.
product The id of the product (more info here).
type The product type (course, bundle, subscription)

Retrieve User Profile

GET https://api.learnworlds.com/user/:user_id/profile

This endpoint retrieves a user's profile which includes information on courses user is enrolled in, certificates obtained, full basic user info, users following/followed by, groups user is in, badges and some user statistics.

curl https://api.learnworlds.com/user/:user_id/profile \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token" 

The above command returns JSON structured like this:

{  
   "user":{  
      "username":"John Smith",
      "bio":"Loves to learn!",
      "location":"",
      "url":"",
      "fb":"",
      "twitter":"",
      "google":"",
      "linkedin":"",
      "skype":"",
      "behance":"",
      "dribbble":"",
      "github":"",
      "courses":[  
         {  
            "title":"Magic School Bus",
            "titleId":"magic_school_bus",
            "courseType":"path",
            "tags":[],
            "keywords":"This is a description",
            "points":null,
            "authors":[],
            "quotes":null,
            "order":null,
            "courseImage": {
              "url": "https://www.learnworlds.com/app/themes/learnworlds/dist/images/learnworlds-nav-menu-logo.png",
              "name": "/learnworlds-nav-menu-logo.png"
            },
            "bgcolor":"#90c0dc",
            "price":"2221",
            "discountFlag":false,
            "discountPrice":"0",
            "introVideoVimeoId":"",
            "knowledgeBadges":"0",
            "goalTotal":"120 minutes",
            "numVideos":"0",
            "numPages":"0",
            "socialMedia":null,
            "access":"public",
            "created":1441150640.499,
            "modified":1454764035.9655,
            "registeredUsers":47,
            "id":"55e636b08a54858e0d7b23c6",
            "premium":true,
            "me":{  
               "registered":true,
               "premium":false,
               "badges":{  
                  "System\\Newbie":"Newbie",
                  "System\\ActiveMember":"Active Member"
               },
               "time_raw":51503.579545021,
               "time_val":14,
               "progress":"100",
               "last_app":"path-player",
               "last_chapter_id":"magic_welcome_",
               "last_video_id":"560167018a5485af0c7b23c6"
            },
            "currency":"$"
         },
         {  
            "title":"Magic School Bus 2",
            "titleId":"magic_school_bus_2",
            "courseType":"path",
            "tags":[],
            "description":" ",
            "keywords":"keyword1, keyword2, keyword3",
            "points":null,
            "authors":[],
            "quotes":null,
            "order":null,
            "courseImage": {
              "url": "https://www.learnworlds.com/app/themes/learnworlds/dist/images/learnworlds-nav-menu-logo.png",
              "name": "/learnworlds-nav-menu-logo.png"
            },
            "bgcolor":"#90c0dc",
            "price":"2222",
            "discountFlag":false,
            "discountPrice":"0",
            "introVideoVimeoId":"",
            "knowledgeBadges":"0",
            "goalTotal":"120 minutes",
            "numVideos":"0",
            "numPages":"0",
            "socialMedia":null,
            "access":"public",
            "created":1441150658.3196,
            "modified":1454016937.3518,
            "registeredUsers":4,
            "id":"55e636c28a5485890d7b23c6",
            "premium":true,
            "me":{  
               "registered":true,
               "premium":false,
               "badges":{  
                  "System\\Newbie":"Newbie",
                  "System\\ActiveMember":"Active Member",
                  "System\\Extroverter":"Extrovert",
                  "System\\Commentator":"Commentator"
               },
               "time_raw":0,
               "time_val":"00:00",
               "progress":"0",
               "last_app":"",
               "last_chapter_id":"",
               "last_video_id":""
            },
            "currency":"$"
         }
      ],
      "isInstructorIn":null,
      "id":"55e58b7f8a5485b4647b23c6",
      "followers_count":2,
      "following_count":2,
      "followers_last":[  
          {  
            "id":"560aaf8d8a548580107b23c6",
            "username":"John Smith"
          },
          {  
            "id":"55f6e1878a548593097b23c6",
            "username":"John Cena"
          }
      ],
      "following_last":[  
         {  
            "id":"560aaf8d8a548580107b23c6",
            "username":"John Smith"
         },
         {  
            "id":"55f6e1878a548593097b23c6",
            "username":"John Cena"
         }
      ],
      "groups":[  
         {  
            "name":"bookclub",
            "id":"562132b38a5485df257ae46d",
            "me_owner":true,
            "new_posts":0,
            "members_count":2
         }
      ],
      "stats":{  
         "hours":1497,
         "notes":4,
         "fav":1,
         "posts":27,
         "comments":4,
         "likes":2,
         "bestof":0,
         "tips":0,
         "lcs":0
      },
      "badges_list":[  
         {  
            "awarded_time":1441107572.2102,
            "category":"social",
            "expired_on":null,
            "expires":"no",
            "expires_time":null,
            "knowledge":null,
            "message":"are a new member.",
            "title":"Newbie",
            "url":null,
            "user_badge_id":false,
            "user_id":{  
               "id":"55e58b7f8a5485b4647b23c6",
               "username":"John Smith"
            },
            "image":"https:\/\/learnworlds.blob.core.windows.net\/startup\/badges\/newbie.png",
            "description":"new members",
            "badge_class_file":"System\\Newbie"
         },
         {  
            "url":null,
            "title":"Active Member",
            "awarded_time":1442153863.9428,
            "category":"social",
            "knowledge":null,
            "expires":"yes",
            "user_badge_id":false,
            "expired_on":null,
            "expires_time":null,
            "user_id":{  
               "id":"55e58b7f8a5485b4647b23c6",
               "username":"John Smith"
            },
            "message":"have made  10 social actions in 1 month.",
            "image":"https:\/\/learnworlds.blob.core.windows.net\/public\/startup\/active-member.png",
            "description":"members who have made 10 or more social actions in 1 month",
            "badge_class_file":"System\\ActiveMember"
         }
      ],
      "certifications":[  
         {  
            "object_id":"5628b8ef8a5485d2097b23c7",
            "courseId":"5628b2218a548572087b23c6",
            "title":"Certificate of Accomplishment in How to Build a Robot",
            "image":null,
            "created":1445513496.3002,
            "status":"active",
            "type":"certificate",
            "printed":null,
            "sent":null,
            "score":66,
            "id":"5628c9188a5485220c7b23c6",
            "courseTitle":"Magic School Bus",
            "courseTitleId":"magic_school_bus",
            "certForm":{  
               "title":"Mr",
               "firstname":"John",
               "middlename":"",
               "lastname":"Smith",
               "email":"info@learnworlds.com",
               "phone":"123231231",
               "mobile":"123123123",
               "address":"23 California St.",
               "city":"Los Angeles",
               "state":"California",
               "postcode":"92102",
               "company":"Learnworlds",
               "companyphone":"1233213123123",
               "experience":"4-6",
               "education":"Bachelors",
               "college":"UCLA",
               "graduation":"2010",
               "aggree":"yes"
            }
         }
      ]
   },
   "errors":[],
   "success":true
}

Url parameters

Parameter Description
user_id The user's id or email.

Update a user

PUT https://api.learnworlds.com/user/:user_id

This endpoint updates user information, useful for changing a user's email or username.

curl -X PUT https://api.learnworlds.com/user/:user_id \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token" \
-d data='{"username":"New Username"}'

The above command returns JSON structured like this:

{
  "success": true
}

Url parameters

Parameter Description
user_id The user's id or email.

PUT parameters

Parameter Description
username The username you would like to set.
email The email you would like to set.

Suspend a user

POST https://api.learnworlds.com/user/:user_id/suspend

This endpoint suspends a user, not allowing them to login or create another account.

curl -X POST https://api.learnworlds.com/user/:user_id/suspend \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token"

The above command returns JSON structured like this:

{
  "success": true
}

Url parameters

Parameter Description
user_id The user's id or email.

Unsuspend a user

POST https://api.learnworlds.com/user/:user_id/unsuspend

This endpoint unsuspends a user.

curl -X POST https://api.learnworlds.com/user/:user_id/unsuspend \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer your_access_token"

The above command returns JSON structured like this:

{
  "success": true
}

Url parameters

Parameter Description
user_id The user's id or email.

Single Sign-on

What is this?

It redirects users from your website/application to your LearnWorlds and seamlessly logs them in with the same email address they used to sign up for your original website/application. If no account with that email address exists yet, one is created. There is no need to synchronize any customer databases.

SSO with a User's Email or User ID

This is to be used in cases where you have a user's email address or the user's LearnWorlds User ID and would like to send them to your school already logged in. If a user does not exist then one will be automatically be created (in this case the email & username parameters are mandatory and the user_id parameter is ignored).

If a user already exists and username or avatar parameters are also provided in the request, then previous values will be overwritten (useful for syncing data).

The access token should be your application's access token, obtaining an application access token can be found here

POST https://api.learnworlds.com/sso

curl -X POST https://api.learnworlds.com/sso \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer users_access_token" \
-d data='{"email":"test@example.com", "username":"LearnWorlds", "avatar":"https://api.adorable.io/avatars/285/test@example.com.png", "redirectUrl":"https://learnworlds.com"}'

The above command returns JSON structured like this:

{
  "success": true,
  "url": "https://your-domain.com/login?code=secret-code-here"
}

Post parameters

Parameter Description
email The email of the user you want to login.
username The username of the user.
avatar A url to a user's avatar.
redirectUrl The full url you want the user to be redirected to after succefully logging in.
token (Optional) GET parameter that returns tokenData (more here) instead of a redirectUrl.

SSO with a User's Access Token

This is to be used in cases where you have a user's access token and would like to send them to your school already logged in.

The access token should be a user access token not your application's. Obtaining a user's access token can be found here

POST https://api.learnworlds.com/user/sso

curl -X POST https://api.learnworlds.com/user/sso \
-H "Lw-Client: your_client_id" \
-H "Authorization: Bearer users_access_token" \
-d data='{"redirectUrl":"https://learnworlds.com"}'

The above command returns JSON structured like this:

{
  "success": true,
  "url": "https://your-domain.com/login?code=secret-code-here"
}

Post parameters

Parameter Description
redirectUrl The full url you want the user to be redirected to after succefully logging in.