API Reference
The Automation API is a REST API that allows you to programmatically trigger and perform most of the actions that are possible in our standard (web-based) user interfaces. This means that you can write your own software interacting with our platform, harnessing all of its features and capabilities. For example, some customers use this API to implement bridges between Kameleoon and their own Git repositories so they can manage Kameleoon variation code directly within their version control system. You could also design your own dashboard and populate it with experiment results obtained from Kameleoon. This API makes it easy to build custom systems that interoperate with Kameleoon.
This is the reference documentation for version 1.1.0 of the Automation API. This API is a REST compliant API, so you can call it with any REST capable framework in any programming language.
Some endpoints and parameters may change as we release new versions of our Automation API. If you wish to be notified in advance of any planned API changes, you can subscribe to updates via our dedicated changelog.
This API is not intended to be used with a high volume of requests. By this we mean it's intended to be called a dozen of times per minute and per customer or user account on our systems. It's not scalable to millions of calls per minute, so should not be called for every visitor on your website (if you need to make a larger volume of requests, see the Data API instead).
If you would like to request an enhancement to our current Automation API, do not hesitate to contact our teams. We can add existing UI features to the Automation API quickly and welcome feedback.
Authentication
The Automation API uses the OAuth 2.0 framework to manage authorization. It's an industry-standard protocol for web applications that supports several flows (or use cases). There are two OAuth flows that are relevant for the Automation API:
- If you're a Kameleoon customer who intends to use the Automation API for your own purposes, you need to use the Client credentials flow. This allows you to control your Kameleoon account and the associated web properties programmatically. For example, you could build a bridge between your CMS (Content Management Software) and Kameleoon, automatically creating and running AB experiments based on the contents of your CMS platform.
- If you're a technological partner with Kameleoon, and you intend to build an integration between your own application and Kameleoon, you need to use the Authorization code flow. This allows you to distribute software for users of both services (Kameleoon and your own). For example, you could use this API to access AB experiments results from Kameleoon and present them in your own application.
Client Credentials Flow
The Client Credentials Flow is the simplest flow. For this flow, you only need to obtain an access token by providing a client_id and a client_secret to an authorization end-point. You will then be able to access the Automation API by using this token as a Bearer Token in a Authorization HTTP request header.
To obtain your credentials (client_id and a client_secret), login to the Kameleoon platform. On your profile page (top right icon > My profile), and click the See my API credentials link.
Obtaining an access_token
Authorization request
curl \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
"https://api.kameleoon.com/oauth/token"
Send a POST request to the https://api.kameleoon.com/oauth/token endpoint. Your client_id and client_secret should be sent as parameters in the body.
Authorization response
{
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA"
}
The authorization server then replies with a JSON object, containing an access_token.
Using the access_token to access the API
REST API example request
curl \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"
Using the access_token to prove your identity, you can make standard REST web API calls. Provide the token in the Authorization request header.
The general Automation API endpoint is https://api.kameleoon.com. For the Client Credentials flow, there are no refresh tokens. An access token is valid for a duration of 2 hours by default.
All API requests must be made over HTTPs. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Authorization Code Flow
The Authorization Code Flow is a flow adapted to partners or third party developers that need to integrate their applications with data from the Kameleoon platform. For this flow, you need to obtain permission from one of your users to access its Kameleoon account. The process will provide you with an authorization code that you need to exchange for an access token. You will then be able to access the Automation API by using this token as a Bearer Token present in a Authorization HTTP request header.
Ask your contact at Kameleoon to create an OAuth application for you in our system. You will need to provide us with a redirect URL (on your own web application). Once the application is created, we will provide it's name, which is used as the client_id value in the flow below. We will also provide with a client_secret value.
Obtaining authorization from the user
Initial request URL
https://api.kameleoon.com/oauth/authorize?client_id=my-application-name&response_type=code&redirect_uri=https://application.company.com/ HTTP/1.1
In your web application, you need to redirect your users to the following URL. If not logged in yet, the users will be asked to log in to the Kameleoon platform. They will then be asked to grant access permission to Kameleoon to access their Kameleoon data and resources.
Redirect URL
https://application.company.com/?code=AUTHORIZATION_CODE
Once your user has been authenticated and has granted permission to access their Kameleoon account, they will be redirected to your application URL with an authorization code as a query parameter.
Obtaining an access_token
Authorization request
curl --location --request POST 'https://api.kameleoon.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic dGVzdC1iby1hdXRob3JpemF0aW9uLWNvZGU6VzlSU3VVRmh0U01pSVNKb2VMNl9SOFhneFVKcWNWZFVuNENmdG44a0Z5WQ==' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=MagXU69dAxOb8Ry7UgXVTUdHSfdICaqXB-Ts86ay1L0' \
--data-urlencode 'redirect_uri=https://application.company.com/'
You can then exchange the authorization code for an access token and a refresh token. On the POST request, the value in the Authorization: Basic corresponds to the Base64 encoded value of the string client_id:client_secret (for example: my-application-name:x8er46f2gtZ). The code parameter contains the authorization code you obtained in the previous step. You also need to provide your redirect_uri.
Authorization response
{
"access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA",
"refresh_token": "eyJraWQiOiJrYW1lbGVvb24tZ3Jhdml0ZWUtQU0ta2V5IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiIzMzA2MTM2MC1mMjZiLTQ2MTctODYxMy02MGYyNmIxNjE3M2QiLCJhdWQiOiJ0ZXN0LWJvLWF1dGhvcml6YXRpb24tY29kZSIsImRvbWFpbiI6ImthbWVsZW9vbiIsImlzcyI6Imh0dHA6XC9cL2FwaS5rYW1lbGVvb24uY29tXC9hbVwva2FtZWxlb29uXC9vaWRjIiwiZXhwIjoxNjIxNTMzNzE5LCJpYXQiOjE2MjE1MTkzMTksImp0aSI6IlFwWERPVmhtNDFHX1RsWDUwVUYySUZkQ1hqaDhZVnBlaW5RcjdyeEdHUUEifQ.81nlwYpaoU_Y0T-WaCcPS9kgh3nTpIVFeydhzGtJfVU"
}
The authorization server replies with a JSON object, containing access_token and refresh_token keys.
Using the access_token to access the API
REST API example request
curl \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"
Using the access_token, you can make standard REST web API calls. It should be supplied in the Authorization request header to prove your identity.
The general Automation API endpoint is https://api.kameleoon.com.
Obtaining a refresh_token
Authorization request
curl --location --request POST 'https://api.kameleoon.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic dGVzdC1iby1hdXRob3JpemF0aW9uLWNvZGU6VzlSU3VVRmh0U01pSVNKb2VMNl9SOFhneFVKcWNWZFVuNENmdG44a0Z5WQ==' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=eyJraWQiOiJrYW1lbGVvb24tZ3Jhdml0ZWUtQU0ta2V5IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiIzMzA2MTM2MC1mMjZiLTQ2MTctODYxMy02MGYyNmIxNjE3M2QiLCJhdWQiOiJ0ZXN0LWJvLWF1dGhvcml6YXRpb24tY29kZSIsImRvbWFpbiI6ImthbWVsZW9vbiIsImlzcyI6Imh0dHA6XC9cL2FwaS5rYW1lbGVvb24uY29tXC9hbVwva2FtZWxlb29uXC9vaWRjIiwiZXhwIjoxNjIxNTMzNzE5LCJpYXQiOjE2MjE1MTkzMTksImp0aSI6IlFwWERPVmhtNDFHX1RsWDUwVUYySUZkQ1hqaDhZVnBlaW5RcjdyeEdHUUEifQ.81nlwYpaoU_Y0T-WaCcPS9kgh3nTpIVFeydhzGtJfVU'
Obtaining a refresh_token is done in the same way as obtaining an access_token. Follow the example on the right.
Rate limiting
Rate limiting of the automation API is primarily on a per-user basis - or more accurately described, per user access token.
Rate limiting windows
The Automation API uses two rate limiting windows. The first one is defined over a 10 seconds interval; no more than 50 requests from the same user are accepted. The second one is defined over a 1 hour interval; no more than 1000 requests from the same user are accepted.
When an application exceeds the rate limit for a given standard API endpoint, the API will return a HTTP 429 "Too Many Requests" response code.
Tips to avoid being rate limited
The tips below help you reduce the possibility of being rate limited. Some application features that you might want to provide may not be possible because of rate limiting, especially features around the freshness of results. If real-time information is an aim of your application, look into the Data API instead.
Caching
Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the Automation API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.
HTTP status codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Your request was correctly formatted and the resource you requested is returned |
| 201 | Created | Returned when a POST request was successful |
| 400 | BadRequest | Can happen if your request did not have a valid JSON body. It might help to specify a Content-Type: application/json header in your request. If you sent valid JSON, the error may also reference specific fields that were invalid |
| 401 | Unauthorized | Your API token was missing or not in the correct format |
| 403 | Forbidden | You provided an API token but it was invalid or revoked or you don't have read/write access to the entity you're trying to view/edit |
| 429 | Too Many Requests | You sent too many requests and were rate limited. See section about rate limiting for details |
| 5xx | Server Error | Something went wrong! Kameleoon engineers have been informed, but please don't hesitate to contact us. |
API usage : paginate, filter and sort parameters
For endpoints that allow you to retrieve multiple objects (e.g., experiments, goals, etc), you can paginate, filter, or sort your data using query parameters (referred to as paramsIO in each endpoint's documentation). By default, a single query returns up to 20 items per page, with a maximum limit of 200 items per page. You can also set perPage=-1 to retrieve the maximum number of items per page allowed by the server (200).
Let's say you need to use such a filter ( filter=[{"field":"name","operator":"EQUAL","parameters":["User Right Test"]}] ), it must be sent in the percent-encoded format ( filter=%5B%7B%22field%22%3A%22name%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22User%20Right%20Test%22%5D%7D%5D ).
An example of what your query would look like:
curl -H "Authorization: Bearer qwerty123456789" \
"https://api.kameleoon.com//personalizations?page=1&perPage=10&filter=%5B%7B%22field%22%3A%22name%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22User%20Right%20Test%
Paginating parameters
| Name | Type | Description |
|---|---|---|
| page | integer | start page |
| perPage | integer | items per page (default 20, maximum 200) |
| filter | array[FilteringParameter] | filtering parameters |
| sort | array[SortingParameter] | sorting parameters |
Filtering parameters
| Name | Type | Description |
|---|---|---|
| field | string | field you need to filter |
| operator | enum | can be [EQUAL, NOT_EQUAL, LESS, GREATER, LESS_OR_EQUAL, GREATER_OR_EQUAL, LIKE, BETWEEN |
| parameters | array | parameters you are filtering by |
Sorting parameters
| Name | Type | Description |
|---|---|---|
| field | string | field you need to sort |
| direction | enum | direction you are filtering by. Can be [ASC, DESC] |