API Reference
The Automation API is a REST API that enables you to programmatically trigger and perform most actions available in our standard web-based user interfaces. This allows you to create your own software that interacts with our platform, utilizing all of its features and capabilities.
For instance, some customers use this API to connect Kameleoon with their own Git repositories, enabling them to manage Kameleoon variation code directly within their version control systems. Additionally, you can design your own dashboard and populate it with experiment results obtained from Kameleoon. The Automation API simplifies the process of building custom systems that work in conjunction with Kameleoon.
This is the reference documentation for version 1.1.0 of the Automation API. This 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 designed for high volumes of requests. It is intended to be called no more than a dozen times per minute for each customer or user account on our systems. It cannot handle millions of calls per minute, so it should not be used for every visitor on your website. If you need to make a larger volume of requests, please refer to the Data API instead.
If you would like to request an enhancement to our current Automation API, please feel free to contact our team. We can quickly add existing UI features to the Automation API, and we welcome your 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 are a Kameleoon customer planning to use the Automation API for personal purposes, you should utilize the Client Credentials Flow. This flow enables you to manage your Kameleoon account and its associated web properties programmatically. For instance, you could create a connection between your Content Management System (CMS) and Kameleoon, allowing for the automatic creation and execution of A/B experiments based on the content from your CMS.
-
On the other hand, if you are a technology partner working with Kameleoon and wish to establish an integration between your application and Kameleoon, you should use the Authorization Code Flow. This approach allows you to distribute software that serves users of both Kameleoon and your application. For example, you could use this API to access A/B experiment results from Kameleoon and display them within your own application.
Client Credentials Flow
The Client Credentials Flow is the simplest authentication method. In this flow, you only need to obtain an access token by providing a client_id and a client_secret to an authorization endpoint. Once you have the access token, you can use it as a Bearer Token in the Authorization HTTP request header to access the Automation API.
To obtain your credentials (client_id and a client_secret), login to the Kameleoon platform. On your profile page (top right icon > My profile), 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"
After using the access_token to verify your identity, you can make standard REST web API calls. Include 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 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 designed for partners or third-party developers who need to integrate their applications with data from the Kameleoon platform. To use this flow, you must first obtain permission from one of your users to access their Kameleoon account. This process will provide you with an authorization code that you can exchange for an access token. Once you have the token, you can access the Automation API by including it as a Bearer Token in the Authorization HTTP request header.
Please contact your Technical Account Manager at Kameleoon to request the creation of an OAuth application in our system. You will need to provide a redirect URL from your web application. Once the application is created, we will give you its name, which will serve as the client_id value in the process outlined below. Additionally, we will provide you 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 users to the URL below. If they are not logged in, they will be prompted to log in to the Kameleoon platform. After logging in, users will be asked to grant Kameleoon permission to access their data and resources.
Redirect URL
https://application.company.com/?code=AUTHORIZATION_CODE
After a user is authenticated and has granted permission to access their Kameleoon account, they will be redirected to your application URL with an authorization code included 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 exchange the authorization code for an access token and a refresh token. In the POST request, the value in the Authorization: Basic header should be the Base64 encoded string of client_id:client_secret (for example: my-application-name:x8er46f2gtZ). The code parameter must include the authorization code you obtained in the previous step. Additionally, you 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"
You can make standard REST web API calls using the access_token. 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 primarily occurs on a per-user basis, or more accurately, per user access token.
Rate limiting windows
The Automation API implements two rate limiting windows to manage requests. The first window spans a 10-second interval, during which no more than 50 requests from the same user are allowed. The second window covers a 1-hour interval, limiting users to a maximum of 1,000 requests.
If an application exceeds the rate limit for a standard API endpoint, the API will respond with an HTTP 429 "Too Many Requests" error code.
Tips to avoid being rate limited
Here are some tips to help you minimize the chances of being rate limited. Certain features in your application may be impacted by rate limiting, particularly those related to obtaining up-to-date results. If your application aims to provide real-time information, consider using the Data API instead.
Caching
Store API responses in your application or on your website if you anticipate high usage. For instance, avoid calling the Automation API with every page load of your landing page. Instead, call the API less frequently and save the response in a local cache. When users visit your website, serve them 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 | Happens 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 formatted incorrectly |
| 403 | Forbidden | You provided an invalid or a revoked API token 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 this 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] |