API general information – Docebo Help & Support

Introduction

The Docebo APIs allow you to connect the learning management system with other applications. You can use them, for example, to help automate tasks and share information between systems.

The APIs provide endpoints through which you can perform a variety of actions on your platform, such as managing users, administering courses, retrieving data, and so on. For more information about the available actions see the article Overview of API services and endpoints.

Additionally, you can interact with the APIs using the API browser, enabling you to test and use the endpoints from a web interface, without needing to code an integration.

This article provides some general information applicable to all the Docebo APIs.

API browser

Reference documentation and a test environment for all Docebo’s publicly available APIs is available within your platform, through the API browser interface, located at: <yourplatform URL>/api-browser. This documentation is constantly updated along with your platform.

For an introduction on how to use the API browser see the article Get started with the Docebo API browser.

Note that, in some rare cases, dynamically generated attributes in JSON data cannot be properly rendered in the user interface of the reference documentation. This could prevent you from testing the API directly from the documentation itself. In this case, we suggest you use a dedicated tool (for example, Postman).

Base URL for API calls

The base URL for all API calls is the URL of your platform. For example, if in the API browser you see an endpoint path given as:

/course/v1/courses

This means the full request URL must be constructed as follows:

<your platform URL>/course/v1/courses

Current version

The default version of the currently exposed API is version 1 (v1). However, in the future, there may be specific microservices that already expose later versions (v2, v3,..). The version of the API you intend to use is specified within the endpoint URL. For example:

GET /learn/v1/location

HTTP request verbs

Following the REST guidelines, Docebo APIs require you to use an appropriate HTTP method on specific types of calls made to the server. The Docebo API structure does follow this guideline wherever it's technically possible, including:

GET requests: Used to retrieve resource representations
POST requests: Used to create new resources
PUT requests: Used to update existing resource
DELETE requests: Used for deleting resources

Schema

All APIs can be accessed by using both the HTTP protocol and the HTTPS protocol. We strongly suggest using the HTTPS protocol in order to protect sensitive information being transferred from your system to Docebo (and back). All API requests and responses should be in JSON format.

curl -i -X GET http:///manage/v1/group -H 'Authorization: Bearer f7bfc5f78877f6ec321a650b10e8aa3d32a18f32'

Response:

HTTP/1.1 200 OK
Server: openresty
Date: Tue, 29 May 2018 08:35:06 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 479
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-Docebo-Api-Version
X-Docebo-Api-Version: 1.0.0
X-UA-Compatible: IE=Edge,chrome=1
X-Frame-Option: SAMEORIGIN
X-XSS-Protection: 1
Access-Control-Allow-Origin: *
X-Docebo-Backyard: manage
Front-End-Https: on

Batch endpoints

Regarding the rules described previously for HTTP request verbs, some exceptions apply to certain endpoints used for bulk creation or updating of resources. In these cases, HTTP POST calls may also be used to update existing resources and create new ones in the same API call. The aim of this is to minimize the number of API calls done by the client and to exploit the chunking mechanism of the operations inherent in this type of call as much as possible. These endpoints are normally identified by the suffix /batch:

POST https:///manage/v1/user/batch

Please note: You cannot send concurrent calls for batch APIs.

Parameters

There are three ways to pass parameters to the Docebo APIs: path, query string, and request body.

Path parameters:

There are cases where the parameters are entered directly into the endpoint URL structure. This type of parameter generally contains immutable IDs, but in some cases may contain non-ID names of resources.

The following is an example URL of an endpoint that accepts a path parameter:

PUT https:///learn/v1/courses/{id}

Query string parameters:

Query string parameters are mainly used to allow you to filter, paginate and (generally speaking), modify the response that will be returned by an API call. The format for query string parameters is the full resource URL followed by a question mark and the optional parameters:

GET https:///learn/v1/enrollments?id_user{user_id}

Request body parameters:

For PUT and POST API calls, you should pass parameters within the request body in JSON format. From the API Reference, you should see the appropriate parameters that can be sent to a given endpoint for each endpoint.

Non-ID parameters (secondary identifiers)

For some resources, the Docebo APIs support non-ID parameter references, such as branch codes. However, it is important to remember that, unlike unique IDs, these values are mutable and may not be unique within your platform. The API will respond with an HTTP 400 error in those cases.

If you plan to use APIs with non-ID references, the uniqueness of those references should be checked and guaranteed by you. Additionally, you should explicitly communicate to the endpoint that it must work in non-ID mode, by setting the parameter use_secondary_identifier to true.

For example, the endpoint GET /manage/v1/orgchart/{branch_id} can accept both the unique internal ID or the alphanumeric branch code. If you want to use the branch code you need to pass the query parameter string use_secondary_identifier set to true.

In the case of a branch whose assigned code is code1562, the resulting request URL is:

GET https:///manage/v1/orgchart/code1562?use_secondary_identifier=true

API client libraries

At this time, Docebo does not provide any client library for Docebo APIs. You need to set up your own package to start coding against Docebo APIs.

API call limitations

To maintain optimum performance and to ensure APIs are available to all customers, Docebo’s APIs are limited to 1,000 API calls per hour from each IP address.

Warning: Branch API calls should never be run concurrently as unpredictable results may occur and the structure of the branches may risk being corrupted. The affected API calls are:

POST /manage/v1/user/batch (only if the call also creates the branches while importing the users)
POST /manage/v1/orgchart
DELETE /manage/v1/orgchart/{id}
PUT /manage/v1/orgchart/{branch_id}
POST /manage/v1/orgchart/{id}/move
DELETE /manage/v1/orgchart/batch
POST /manage/v1/orgchart/batch

Please make sure these branch API calls are run sequentially.

Managing HTTP redirects

Currently, none of the Docebo APIs use redirects. However, we understand that this may be needed in the future to manage some specific cases. For this reason, we invite you to consider a 3xx HTTP code as a possible response for all endpoints. Since it’s not a code representing an error, you should follow the redirect itself.

Pagination and sorting

All requests that return a variable (and potentially big) number of items are paginated by default. The default value for the number of elements per page is set to 10 elements. Please note that this value could be different for some endpoints due to performance reasons. You can change this limit by using the page_size parameter, which is passed to the endpoint by query string. The parameter accepts values between 1 and 200. Values outside these thresholds will not be considered valid. The page parameter allows you to get data from a specific page within the returned results. The default value for this parameter is 1, corresponding to the first page of the results. Even in this case, the parameter can be passed to the API through a query string:

curl -X GET https:///courses?page_size=5&page=2' -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Navigation links between the result pages can be pre-generated by the API itself, providing an array of HTTP links in the response that you can directly follow. This feature is disabled by default. To activate it, you can set the get_cursor parameter to 1 within the query string of the API call:

curl -X GET https:///courses?get_cursor=1 -H 'Authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Response:

{
 {[...OMITTED-JSON...]
 "_links": {
   "self": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "next": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   },
   "goto": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=__page__"
   },
   "first": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=1"
   },
   "last": {
     "href": "https:///learn/v1/courses?cursor=6b1af27dd7d849c6a0a399439a12ad791abb6708&page=2"
   }
 }
}

You can also control the sort order of records that are returned by the API call. The parameter with which the order can be determined is sort_attr. It can be passed through query string. The values that this parameter can assume are different from one endpoint to the next because the resources that are returned are different. You should check the available values for these parameters in each endpoint description in the API Reference. In any case, you can specify only one attribute to use for sorting, and you cannot specify consecutive sorting attributes. The default value for the parameter depends on the endpoint. The sorting direction can be governed with the sort_dir parameter. The acceptable values are asc for an ascending order and desc for a descending order. The default value is always descending:

curl -X GET https:///courses?sort_attr=name&sort_dir=asc' -H 'authorization: Bearer 2af6ac532cfef197b00f69639aeeef86621d1975'

Error codes

The Docebo APIs return the standard HTTP error codes to indicate whether a request was successful or not. Specifically, each client must be able to handle the following HTTP codes:

HTTP Code	Description
200 - OK	Success - The task requested to the API has been performed.
400 - Bad Request	The request was not correct, usually due to a parameter issue.
401 - Unauthorized	The call was not properly authenticated.
403 - Forbidden	The client's request is formed correctly but the API refuses to honor it. For example, in case the user does not have the necessary permissions for the resource.
404 - Not Found	The requested resource doesn't exist.
408 - Request Timeout	The server did not receive a complete request message within the required time frame.
429 - Too Many Requests	The API rate limit was exceeded, you need to retry the call later.
500 - Server Errors	The call generated an error on the Docebo side.
503 - Service Unavailable	The server is currently unable to handle the request due to temporary overload or maintenance.

Policy for changes to APIs

Docebo makes every effort to keep API changes backward-compatible, but when this is not possible customers are informed according to the policies set out in this chapter.

Backward-compatible changes

Consider the changes listed below as backward-compatible. We invite you to structure your code to be able to support any such changes to the APIs. This type of change normally happens without any notification to customers. They may include:

Adding new endpoints
Adding new optional parameters to existing API endpoints
Adding new properties to API responses
Changing the order of properties in API responses
Any update to the API reference documentation

Non-backward-compatible changes

In case of API changes that could potentially impact existing integrations, customers are notified in advance through a “Heads up!” precommunication on the Product updates page. The notice period may vary due to technical and usage consideration, but generally the precommunication will occur at least one month before the change comes into effect.

→ This rule does not apply in the case of critical security vulnerabilities. In such cases, a fix is applied immediately, and a communication may appear on the Product updates page during or shortly after the fix.

API changelog

Docebo informs customers of any non backward-compatible changes or deprecations to Docebo APIs through the general Product updates page. Once you see communication related to APIs on this page, you can then refer to the official API reference (https://<yoursubdomain.docebosaas.com>/api-browser/) for a complete understanding of the changes that occurred.

In addition, the article Deprecated and changed API calls provides details about the API endpoints that have been changed or removed since January 2023. (However, it does not include API calls that have been introduced or released.)

API browser and additional fields

The additional fields used in the platform for the management of users, courses, and enrollment are managed by Superadmins as dynamic values, and cannot be documented in the API browser documentation, as they change from platform to platform. For the same reason, it is not possible to test additional fields from the API browser. As an example, if you want to filter courses according to a course additional field value where xx is the additional field ID (such as field_1, field_2, etc), the string to use would be something like:

https://yourdomain.docebosaas.com/learn/v1/enrollments?field_6=3

The ID to use in your query instead of xx will either be an integer (for example, for dropdown additional fields), a string (for a text additional field), an array, or a date (for date additional field). Here are some examples:

date:

'field_12': {'from': '2018-06-26','to': '2018-06-30'},

textfield:

'field_6': 'abc'

'field_6': ['abc', 'def'], dropdown: 'field_8': 3

iframe additional fields:

Extend field_xx and field_xx_yy where yy is the field from the JSON configuration and use a this syntax: '$^speakers^speaker'. The value will either be a string (for text additional field) or an array or a date (for date additional field). Examples: