Get started - Kameleoon Documentation

The Automation API is a REST-compliant service that lets you programmatically perform most actions available in the Kameleoon web interface. Use the Automation API to build custom software that interacts with the Kameleoon platform and its core features. For example, you can use the Automation API to:

Connect Kameleoon with Git repositories to manage variation code.
Design custom dashboards populated with real-time experiment results.
Automate the creation of goals and segments across multiple projects.

Kameleoon might change endpoints and parameters in new versions of the Automation API. Subscribe to updates on the Kameleoon changelog for notifications about planned changes.

The Automation API does not support high request volumes. Limit calls to 12 times per minute per account or user. Do not use the Automation API for high-frequency tracking of every website visitor. For larger request volumes, use the Data API.

Contact the Kameleoon team to request an enhancement to the Automation API. We appreciate your feedback and can quickly add existing UI features to the API.

Tutorials

Create an experiment

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

Retrieve experiment results

After you launch an experiment, it generates results that provide insights to determine the best-performing variation. Learn how to request results and identify the winning variation in the Retrieving Experiments Results tutorial.

Authentication

The Automation API uses the OAuth 2.0 framework for authorization. Kameleoon supports two primary flows depending on your use case:

Client Credentials Flow: Use this flow if you are a Kameleoon customer using the API for internal purposes. This flow allows you to programmatically manage your own account and web properties.
Authorization Code Flow: Use this flow if you are a technology partner integrating an application with Kameleoon. This flow allows you to securely access data on behalf of other Kameleoon users.

Client Credentials flow

The Client Credentials flow is the simplest authentication method. To use this flow, exchange your client credentials for an access token.

You can find your client_id and client_secret on the Kameleoon platform. Navigate to Account > My profile and click See my API credentials.

1. Obtain an access token

Send a POST request to the token endpoint with your credentials.

curl

curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"

The authorization server responds with a JSON object containing the access_token:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}

2. Access the API

Include the access token as a Bearer token in the Authorization HTTP header of your requests.

curl

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

Access tokens remain valid for 2 hours by default.
The Client Credentials flow does not use refresh tokens.
You must use HTTPS for all API requests. Requests made over plain HTTP will fail.

Authorization Code flow

The Authorization Code flow allows third-party developers to integrate their applications with Kameleoon data. You must obtain explicit permission from a user to access their account resources.

Contact your Kameleoon Technical Account Manager to request an OAuth application. You must provide a redirect URL for your application. Kameleoon will then provide a client_id and client_secret.

1. Redirect the user for authorization

Redirect users from your application to the authorization URL:

https://api.kameleoon.com/oauth/authorize?client_id=my-application-name&response_type=code&redirect_uri=https://application.company.com/

After the user grants permission, Kameleoon redirects the user to your application URL with an authorization code:

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

2. Obtain access and refresh tokens

Exchange the authorization code for tokens. Base64 encode the client_id:client_secret string and include it in the Authorization: Basic header.

curl

curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=authorization_code" \
     -d "code=AUTHORIZATION_CODE" \
     -d "redirect_uri=https://application.company.com/"

The response contains both access and refresh tokens:

{
  "access_token": "...",
  "refresh_token": "..."
}

3. Refresh an expired token

To obtain a new access token without re-authorizing the user:

curl

curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=YOUR_REFRESH_TOKEN"

Rate limiting

Rate limiting for the Automation API occurs per user access token. Kameleoon uses two rate-limiting windows:

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

If you exceed these limits, the API returns an HTTP 429 Too Many Requests error. To minimize rate limiting:

Implement caching: Store API responses locally and avoid calling the API on every page load.
Use the Data API: If your application requires real-time tracking at scale, use the Data API.

HTTP status codes

Code	Status	Description
200	OK	The request was successful.
201	Created	The resource was successfully created.
400	Bad Request	The request body is invalid. Ensure the `Content-Type: application/json` header is present.
401	Unauthorized	The API token is missing or malformed.
403	Forbidden	You lack required permissions or the token is revoked.
429	Too Many Requests	You exceeded the rate limit.
5xx	Server Error	An internal error occurred. Contact Kameleoon support if the issue persists.

Query parameters

For endpoints that retrieve multiple objects, use query parameters to paginate, filter, or sort data.

Pagination

Queries return 20 items per page by default (maximum 200). Use perPage=-1 to retrieve the maximum limit.

Parameter	Type	Description
`page`	integer	The page number to retrieve.
`perPage`	integer	Items per page (default 20, max 200).
`filter`	array	Filtering parameters.
`sort`	array	Sorting parameters.

Filtering

You must percent-encode filters when sending them in a URL. Example: filter=[{"field":"name","operator":"EQUAL","parameters":["Test"]}]

Field	Type	Description
`field`	string	The field to filter by.
`operator`	enum	Options include: `EQUAL`, `NOT_EQUAL`, `LESS`, `GREATER`, `LIKE`, `IN`, `IS_NULL`, etc.
`parameters`	array	The specific values to match.

Sorting

Field	Type	Description
`field`	string	The field to sort by.
`direction`	enum	`ASC` (ascending) or `DESC` (descending).

​Tutorials

​Create an experiment

​Retrieve experiment results

​Authentication

​Client Credentials flow

​1. Obtain an access token

​2. Access the API

​Authorization Code flow

​1. Redirect the user for authorization

​2. Obtain access and refresh tokens

​3. Refresh an expired token

​Rate limiting

​HTTP status codes

​Query parameters

​Pagination

​Filtering

​Sorting

Tutorials

Create an experiment

Retrieve experiment results

Authentication

Client Credentials flow

1. Obtain an access token

2. Access the API

Authorization Code flow

1. Redirect the user for authorization

2. Obtain access and refresh tokens

3. Refresh an expired token

Rate limiting

HTTP status codes

Query parameters

Pagination

Filtering

Sorting