Skip to main content

Using paramsIO

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
note

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