Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Goal

The Automation API uses a paramsIO object to filter, paginate, and sort query collections. This tutorial demonstrates practical use cases for paramsIO, including:
  • Retrieving multiple siteIds using siteCode values
  • Filtering experiments by status
  • Setting pagination criteria to control result size
The paramsIO pattern is used across many endpoints and follows a consistent structure, making it a powerful tool for precise data retrieval.

​
Requirements

​
Access token

The Automation API requires an access token. Retrieve the token programmatically by following the instructions in the Get started article.

​
Understanding paramsIO

The paramsIO object passes structured queries to API endpoints. It typically includes pagination, sorting, and filtering tools. Refer to the Get started article for more information on paramsIO.

​
Filter Structure

Filters use a consistent JSON structure:
PropertyTypeDescription
fieldStringThe property in the collection to filter by (for example, "code", "status")
operatorStringThe comparison operator (for example, "EQUAL", "BETWEEN", "GREATER")
parametersArrayAn array of values to match against
Filter JSON objects must be URL-encoded when added to the endpoint URL. For example, [ becomes %5B and " becomes %22.

​
Use case 1: Retrieve multiple siteIds by siteCode

The Automation API requires the internal numeric id for most operations. This example retrieves multiple site IDs simultaneously using siteCode values.

​
Step 1: Define the filter

To retrieve multiple sites, use the EQUAL operator with an array of site codes: 
[
  {
    "field": "code",
    "operator": "EQUAL",
    "parameters": ["xdrio4plsn", "adflwp2mms", "lricdj5pqw"]
  }
]

​
Step 2: Send the request

Send a GET request to the /sites endpoint with the URL-encoded filter: Endpoint: GET https://api.kameleoon.com/sites Example request: 
curl -L -X GET 'https://api.kameleoon.com/sites?filter=%5B%7B%22field%22%3A%22code%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%2C%22adflwp2mms%22%2C%22lricdj5pqw%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

​
Step 3: Handle the response

The API returns all matching sites in a JSON array: 
[
  {
    "id": 42099,
    "url": "https://www.example-production.com/",
    "name": "Production Environment",
    "code": "xdrio4plsn"
    ...
  },
  {
    "id": 42100,
    "url": "https://www.example-staging.com/",
    "name": "Staging Environment",
    "code": "adflwp2mms"
    ...
  },
  {
    "id": 42101,
    "url": "https://www.example-test.com/",
    "name": "Test Environment",
    "code": "lricdj5pqw"
    ...
  }
]
Use these id values for subsequent API operations.

​
Use case 2: Filter active experiments with pagination

This example demonstrates how to combine filtering and pagination to retrieve active experiments in manageable batches.

​
Step 1: Define the filter and pagination

Create a filter for active experiments and specify pagination parameters: Filter JSON: 
[
  {
    "field": "status",
    "operator": "EQUAL",
    "parameters": ["ACTIVE"]
  }
]
Pagination parameters:
  • page=1: First page of results
  • perPage=200: Limit to 200 items per page

​
Step 2: Send the request

Send a GET request to the /experiments endpoint: Endpoint: GET https://api.kameleoon.com/experiments Example request: 
curl -L -X GET 'https://api.kameleoon.com/experiments?perPage=200&page=1&filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

​
Step 3: Handle the response

The API returns up to 200 active experiments: 
[
  {
    "id": 12345,
    "siteId": 54321,
    "name": "My Active Experiment",
    "description": "Testing new checkout page",
    "baseURL": "https://yourwebsite.com",
    "type": "AI",
    "trackingTools": [],
    "status": "ACTIVE",
    "dateCreated": "2026-02-03T18:41:00",
    "tags": ["checkout", "mobile"],
    ...
  }
]
To retrieve additional pages, increment the page parameter in subsequent requests.

​
Use case 3: Combining multiple filters

To query more precisely, combine multiple filter conditions. For example, find active experiments on a specific site: 
[
  {
    "field": "status",
    "operator": "EQUAL",
    "parameters": ["ACTIVE"]
  },
  {
    "field": "siteId",
    "operator": "EQUAL",
    "parameters": ["xdrio4plsn"]
  }
]
Example request: 
curl -L -X GET 'https://api.kameleoon.com/experiments?filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%2C%7B%22field%22%3A%22siteId%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'

​
Best Practices

  1. URL Encoding: URL-encode the filter JSON before adding it to the request URL.
  2. Pagination: Use perPage to limit result size and prevent timeouts on large collections
  3. Multiple filters: Combine filter conditions to reduce unnecessary data transfer
  4. Operator choice: Use operators for multiple values instead of multiple separate requests