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