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.

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://yourdomain.docebosaas.com/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://yourdomain.docebosaas.com/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://yourdomain.docebosaas.com/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://yourdomain.docebosaas.com/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:

https://yourdomain.docebosaas.com/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 applies rate limits to API activity. These limits may vary depending on your platform configuration. For more information on system limits, please visit our Trust center page (opens in a new tab).

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 is 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.

Tip: 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.