Get started

The Automation API is a REST API that lets you programmatically trigger and perform most actions available in the Kameleoon web-based user interfaces. Use the Automation API to create software that interacts with the Kameleoon platform and uses its features.

For example, customers use the Automation API to connect Kameleoon with Git repositories and manage variation code within version control systems. You can also design a dashboard and populate it with experiment results from Kameleoon. The Automation API simplifies building custom systems that work with Kameleoon.

This document is the reference for version 1.1.0 of the Automation API. The Automation API is REST-compliant, which means you can call it with any REST-capable framework or programming language.

caution

Endpoints and parameters might change when Kameleoon releases new versions of the Automation API. To receive notifications about planned API changes, subscribe to updates on the Kameleoon changelog.

caution

The Automation API does not support high request volumes. Limit calls to no more than 12 times per minute for each account or user. Do not use the Automation API for every website visitor. For larger request volumes, use the Data API.

note

To request an enhancement to the Automation API, contact the Kameleoon team. Kameleoon can quickly add existing UI features to the Automation API and appreciates your feedback.

Tutorials

Create an experiment using the Automation API

This tutorial provides step-by-step instructions for key tasks on the Kameleoon platform using the Automation API.
You will learn how to:

• Create a new experiment
• Push and modify JavaScript code in the experiment variation
• Create a new segment for the experiment
• Create a new goal for the experiment
• Update the experiment with the goal and segment, then launch it

These tasks use the Automation API and the Kameleoon Code Editor for streamlined experimentation.

Retrieve experiment results

Once launched, the experiment generates results that provide insights to determine the best-performing variation. The Retrieving Experiments Results tutorial explains how to use the Automation API to request experiment results and determine the winning variation.

Authentication

The Automation API uses the OAuth 2.0 framework for authorization. The OAuth 2.0 framework is an industry-standard protocol for web applications that supports several flows.

The following OAuth flows are relevant for the Automation API:

• If you are a Kameleoon customer using the Automation API for internal purposes, use the Client Credentials Flow. This flow lets you programmatically manage your Kameleoon account and associated web properties. For example, you can connect your Content Management System (CMS) and Kameleoon to automatically create and run A/B experiments based on CMS content.

• If you are a technology partner integrating an application with Kameleoon, use the Authorization Code Flow. This flow lets you distribute software to users of both Kameleoon and your application. For example, use the Automation API to access A/B experiment results from Kameleoon and display them in your application.

Client Credentials Flow

The Client Credentials Flow is the simplest method for authentication. To use this flow, obtain an access token by providing a client_id and a client_secret to the authorization endpoint. After receiving the access token, include it as a Bearer Token in the Authorization HTTP request header to access the Automation API.

note

To obtain your credentials (client_id and client_secret), log in to the Kameleoon platform. On your profile page (Account icon > My profile), click See my API credentials.

Obtain 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. Send the client_id and client_secret as parameters in the request body.

Authorization response

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA"
}

The authorization server responds with a JSON object that contains the access_token.

Use the access token to access the API

REST API example request

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"

Use the access_token to verify your identity and make standard REST API calls. Include the token in the Authorization HTTP request header.

The general Automation API endpoint is https://api.kameleoon.com. The Client Credentials flow does not use refresh tokens. An access token remains valid for 2 hours by default.

Use HTTPS for all API requests. Requests made over plain HTTP or without authentication will fail.

Authorization Code Flow

The Authorization Code Flow lets partners and third-party developers integrate their applications with Kameleoon data. To use this flow, obtain permission from a user to access their Kameleoon account. This process generates an authorization code to exchange for an access token. Include the token as a Bearer Token in the Authorization HTTP request header to access the Automation API.

note

Contact your Kameleoon Technical Account Manager to request an OAuth application. Provide a redirect URL for your web application. After Kameleoon creates the application, you receive an application name (client_id) and a client_secret.

Obtain 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

Redirect users to the following URL from your web application. If users are not logged in, they must log in to the Kameleoon platform. After logging in, users must grant permission for the application to access their Kameleoon data and resources.

Redirect URL

https://application.company.com/?code=AUTHORIZATION_CODE

After authentication and authorization, Kameleoon redirects the user to your application URL with an authorization code in the query parameter.

Obtain 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/'

Exchange the authorization code for an access token and a refresh token. Base64 encode the client_id:client_secret string (such as my-application-name:x8er46f2gtZ) and include it in the Authorization: Basic header of the POST request. Include the authorization code in the code parameter and provide your redirect_uri.

Authorization response

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJLQU1FTEVPT05fQkFDS19PRkZJQ0UiLCJzdWIiOiJtaWNrYWVsLmdAYWxsb3BuZXVzLmNvbSIsImF1ZCI6IkJBQ0tfT0ZGSUNFIiwidHlwIjoiQUNDRVNTX1RPS0VOIiwiZXhwIjoxNTc3MzY1Nzc3fQ.Ulfz_dw1zGbyRJZMZwpn5STzWCVnrbXbL2UYQ6VhFb1sN81cVHJuljl3RsIMbTLz8NwyCUfMTQLZkLBz2ChnDA",
  "refresh_token": "eyJraWQiOiJrYW1lbGVvb24tZ3Jhdml0ZWUtQU0ta2V5IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiIzMzA2MTM2MC1mMjZiLTQ2MTctODYxMy02MGYyNmIxNjE3M2QiLCJhdWQiOiJ0ZXN0LWJvLWF1dGhvcml6YXRpb24tY29kZSIsImRvbWFpbiI6ImthbWVsZW9vbiIsImlzcyI6Imh0dHA6XC9cL2FwaS5rYW1lbGVvb24uY29tXC9hbVwva2FtZWxlb29uXC9vaWRjIiwiZXhwIjoxNjIxNTMzNzE5LCJpYXQiOjE2MjE1MTkzMTksImp0aSI6IlFwWERPVmhtNDFHX1RsWDUwVUYySUZkQ1hqaDhZVnBlaW5RcjdyeEdHUUEifQ.81nlwYpaoU_Y0T-WaCcPS9kgh3nTpIVFeydhzGtJfVU"
}

The authorization server responds with a JSON object that contains the access_token and refresh_token keys.

Use the access token to access the API

REST API example request

curl \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
"https://api.kameleoon.com/experiments"

Make standard REST API calls using the access_token. Include the token in the Authorization HTTP request header to verify your identity.

The general Automation API endpoint is https://api.kameleoon.com.

Obtain 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'

Obtain a refresh_token using the same method as an access_token. Follow the example provided.

Rate limiting

Rate limiting for the Automation API occurs per user access token.

Rate-limiting windows

The Automation API uses two rate-limiting windows to manage requests:

• 10-second interval: Up to 50 requests per user.
• 1-hour interval: Up to 1,000 requests per user.

The API returns an HTTP 429 Too Many Requests error code if an application exceeds the rate limit.

Tips to avoid rate limiting

Follow these tips to minimize the chance of rate limiting. Rate limiting might affect application features that require real-time results. For real-time information, use the Data API.

Caching

If you anticipate high usage, cache API responses in your application or website. For example, do not call the Automation API with every page load. Call the API less frequently and store the response in a local cache. When users visit your website, serve the cached results.

HTTP status codes

Code	Status	Description
200	OK	The request was successful and the API returned the requested resource.
201	Created	The POST request was successful and the resource was created.
400	BadRequest	The request does not contain a valid JSON body. Ensure the Content-Type: application/json header is present. If the JSON is valid, the error might refer to invalid fields.
401	Unauthorized	The API token is missing or formatted incorrectly.
403	Forbidden	The API token is invalid or revoked, or you lack the required access permissions.
429	Too Many Requests	You exceeded the rate limit. Refer to the Rate limiting section.
5xx	Server Error	An internal server error occurred. Contact Kameleoon support if the issue persists.

API usage: Paginate, filter, and sort parameters

For endpoints that retrieve multiple objects, such as experiments or goals, you can paginate, filter, or sort data using query parameters (referred to as paramsIO in the documentation). By default, queries return up to 20 items per page. The maximum limit is 200 items per page. Set perPage=-1 to retrieve the maximum allowed items (200).

When using a filter such as ( filter=[{"field":"name","operator":"EQUAL","parameters":["User Right Test"]}] ), send it 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 ).

Example query:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
"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 to filter
operator	enum	Operator to use: [EQUAL, NOT_EQUAL, LESS, GREATER, LESS_OR_EQUAL, GREATER_OR_EQUAL, LIKE, BETWEEN, IN, NOT_IN, NOT, IS_NULL, IS_NOT_NULL, IS_TRUE, IS_FALSE]
parameters	array	Parameters to filter by

Sorting parameters

Name	Type	Description
field	string	Field to sort
direction	enum	Direction to filter by: [ASC, DESC]