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

HTTP Verbs

Following the REST guidelines, Docebo APIs require you to use an appropriate HTTP method on specific type 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

Batch Endpoints

Regarding the rules described above, exceptions may be applied to some endpoints dedicated to a massive creation or updating of resources within Docebo. In these cases, in fact, it may happen that HTTP POST calls can 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 API: path, query string, and request body. Refer to the corresponding sections of the article below to learn more about each way to pass parameters.

Path Parameters

There are cases where the parameters are entered directly into the endpoint URL structure. This type of parameter generally contains immutable IDs or, in some cases, names of resources. Here’s an example URL of an endpoint that accepts a path parameter:

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

Support for Non-ID Dereferencing

As previously mentioned in this article, for some resources we support non-ID dereferencing. It’s important to note that values used for non-ID references (i.e. group name or orgchart branch code) are mutable and possibly not unique within your Docebo subdomain instance. There is no way for Docebo to guarantee their uniqueness or immutability. The API will respond with an HTTP 400 error in those cases. It's assumed therefore that, in case you plan to use APIs with non-ID references, the uniqueness of the references should be guaranteed by you. Generally speaking, whenever we allow you to work with a non-ID parameter in the path, we request that it is explicitly communicated to the endpoint with which it will have to work in non-ID mode, passing the query parameter string use_secondary_identifier set to true.

GET https:///manage/v1/group/{group_name}?use_secondary_identifier=true

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.

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: