See the full API reference on the API documentation portal.

If you are familiar with Postman, you may want to look at our WIP version of the Open API collection.

General Information

To enable remote management of Courselle installations, we provide a comprehensive suite of API methods. To start using Open API, first you need to generate the API key.

To generate the API key, log in to Courselle, open your site, click Settings, go to the API tab, and click Regenerate. The generated API key will be displayed.

You will use this key to authenticate when sending API requests. If you believe that your API key may have been compromised, we recommend you to regenerate it by following these instructions again.

To execute an API request, you need to send a specifically formed HTTP packet. This packet must contain the following data:

  • The corresponding HTTP method
  • The hostname of your Courselle site.
  • The API version.
  • The API method you want to use with any arguments
  • Your API key

The HTTP method depends on the API method being used. GET is used to retrieve information, PATCH to edit the properties of an entity (user, group, etc.), POST to add new entities, and DELETE to remove them.

The API version and the API method in use are passed as a part of the URL formed according to the following rules:

https://{{site}}.courselle.com/openapi/v1/

For example, if your site name is mycompany, use the hostname: mycompany.courselle.com. To retrieve information about the groups belonging to the instance, add /groups to the URL. The complete request may look like this:

GET https://mycompany.courselle.com/openapi/v1/groups
X-API-KEY: f684cde3fdeb55e72e860815d4275d91

As a response, you can expect one of the following HTTP codes:

  • 200 Is returned for GET and POST requests with no errors
  • 204 Is returned for PATCH and DELETE requests with no errors
  • 400 Is returned for POST and PATCH requests if the data failed to pass validation
  • 402 Is returned for POST requests if the license limits have been exceeded on the instance
  • 403 Is returned for any request if the API KEY is invalid
  • 404 Is returned for any request if the specified resource is not found

If the API request has been executed correctly, you will also receive the corresponding JSON response packet. Otherwise, the response will contain the corresponding error message that will help you troubleshoot and resolve the issue.

Sending API requests using REST client for Google Chrome

The most user-friendly way to test Geenio API is to use Advanced REST client app for Google Chrome.

Simply install it to your browser and then set up some basic information:

This includes the request URL and additional HTTP header with name X-API-KEY and the value of your API key.

Once you click SEND it will process the request and output the results below:

It is also possible to switch request method and not only retrieve the data, but also perform modifications. For example, create a user account:

As the result you will see the newly created user data below:

Sending API requests from a command line

Here is how you would test the API call using curl console utility, which is available for most Unix-based OSes:

my-unix-box ~$ curl -H "X-API-KEY: 4aa14f6f0889d1c39d53c8293b47ab8b" -X GET https://example.courselle.com/openapi/v1/users/
{
  "users": [
    ...
    {
      "id": "14530267329445787",
      "name": "Test User via API",
      "occupation": "",
      "location": "",
      "timezone": null,
      "email": "test@mailinator.net",
      "isBanned": false,
      "role": {
        "alias": "learner"
      },
      "image": null
    },
    {
      "id": "1452710290255882",
      "name": "user name",
      "occupation": "",
      "location": "",
      "timezone": null,
      "email": "un@tl.dr",
      "isBanned": false,
      "role": {
        "alias": "learner"
      },
      "image": null
    }
  ],
  "totalCount": 6
}
Did this answer your question?