How to integrate kapptivate API within your CI/CD – kapptivate

Using the Kapptivate API, you can integrate your existing tests into your CI/CD pipeline to automatically detect regressions on your services.

By calling the continuous_integration endpoint with specific parameters in the request body, you will be able to trigger your test runs and retrieve their results directly from your pipeline.

Prerequisites

- You must have an existing Refresh Token (API key).
- You should know your Platform ID and your Test ID(s).
🔗 To learn how to create and use an API key, follow this article: How to generate and use a Kapptivate API key .

Step 1: Generate your JWT token

To use the Kapptivate API, you must include a valid JWT token in the Authorization header of your requests. This JWT token is generated from your Refresh Token by calling the refresh_token endpoint.

🔧 Important: replace your_domain_name.kapptivate.com with the actual domain of your kapptivate environment, that is visible on every kapptivate URL that you may see.

Make sure the following header is present in your request:
```
Content-Type: application/json
```
Example request (POST):
```
POST https://your_domain_name.kapptivate.com/api/auth/refresh-token/
Content-Type: application/json

{
  "refresh_token": "YOUR_API_KEY"
}
```
The response will contain your JWT token, which you will use in the Authorization header of subsequent API calls. By default, this token is valid for 2 minutes.

Step 2: Trigger your test(s) from your CI/CD pipeline

To trigger one or several tests from your pipeline, you will call the continuous_integration endpoint.

For this step, you will need:
- The Platform ID where your tests are defined.
- The Test ID(s) you want to run.
- Optionally, a variable group and some input variables.
How to find your Test ID

Open the edit panel of your test in the Kapptivate UI and copy the ID from the URL. It looks like this:
```
your_organization~your_product/testing/test/edit/YOUR_TEST_ID
```
How to find your Variable Group ID

To get the variable_group_id, open the variable group in the UI and copy the ID directly from the URL, as shown below:

Endpoint

You will use the /api/v1/continuous_integration/ endpoint with the following structure:

Parameters
- name: the name of your test run (string).
- variable_group_id: the ID of the variable group you want to use (integer).
- tests: an array of test configurations. Each entry can contain:
  - input_variables (optional): key/value pairs for variables required by the test, using their exact names.
  - id: the ID of the test to run.
  - direct_owners: the devices on which the test will run.
- options (optional): advanced options for the run.
Sample request
```
POST /api/v1/continuous_integration/
Content-Type: application/json
Authorization: JWT YOUR_JWT_TOKEN

{
  "name": "your_test_run_name",
  "variable_group_id": YOUR_VARIABLE_GROUP_ID,
  "tests": [
    {
      "input_variables": {
        "MY_INPUT_VARIABLE_NAME": "my_variable_value"
      },
      "direct_owners": {
        "your_device": "your_device_name"
      },
      "id": 1389
    }
  ],
  "options": {}
}
```

Step 3: Retrieve details of your test run

When you call the continuous_integration endpoint, the response will contain a status, a result_uri and a result_id.

Example response:

{
  "status": "success",
  "result_uri": "/api/v1/continuous_integration/results/RESULT_ID/",
  "result_id": RESULT_ID
}

To see detailed results of your test run, perform a GET request on the result_uri.

GET /api/v1/continuous_integration/results/RESULT_ID/
Content-Type: application/json
Authorization: JWT YOUR_JWT_TOKEN

The response includes:

Name of the test run
Status (success, failure…)
Timing (start, end, duration)
Number of tests and successes

{
  "name": "your_test_run_name",
  "result": {
    "status": "success",
    "timing": {
      "end": "2021-03-15T15:15:49.39303055Z",
      "start": "2021-03-15T15:15:47.597870374Z",
      "duration": 1.795160021
    },
    "nb_tests": 1,
    "nb_success": 1
  }
}

Step 4: Full API usage example (generic Bash script)

This example shows how to:

Retrieve a JWT token from your refresh token
Trigger a CI test run using the continuous_integration endpoint
(Optional) Clean large fields from the JSON output
Fetch the final result using result_uri

🔧 Important: Replace your_domain_name.kapptivate.com with the actual domain of your kapptivate workspace.

Reusable Bash script:

#!/bin/bash
set -euo pipefail

# 1) Get a fresh JWT token
curl -s -X POST -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"YOUR_REFRESH_TOKEN\"}" \
  https://your_domain_name.kapptivate.com/api/auth/refresh-token/ \
   /tmp/api_auth.json

Auth_Bearer=$(jq -r ".token" /tmp/api_auth.json)

if [ -z "$Auth_Bearer" ] || [ "$Auth_Bearer" = "null" ]; then
  echo "Failed to retrieve JWT token"
  exit 1
fi

echo "JWT token retrieved successfully."

# 2) Trigger a CI test run
curl --fail --location --request POST \
  "https://your_domain_name.kapptivate.com/api/v1/continuous_integration/" \
  --header "Content-Type: application/json;charset=UTF-8" \
  --header "Authorization: JWT $Auth_Bearer" \
  -d "@/path/to/your/body.json" \
   /tmp/test_result_raw.json

echo "Test triggered successfully."

# 3) (Optional) Clean the JSON output
jq "del(
      .. | .screenshot_url_before?,
      .. | .screenshot_url_after?,
      .. | .time_since_parent_start?
    )" \
    /tmp/test_result_raw.json \
     /tmp/test_result.json

echo "Clean JSON saved."

# 4) Retrieve final results
Result_URI=$(jq -r ".result_uri" /tmp/test_result_raw.json)

if [ -n "$Result_URI" ] && [ "$Result_URI" != "null" ]; then
  curl --fail --location --request GET \
    "https://your_domain_name.kapptivate.com${Result_URI}" \
    --header "Content-Type: application/json;charset=UTF-8" \
    --header "Authorization: JWT $Auth_Bearer" \
     /tmp/final_test_result.json

  echo "Final test results saved."
else
  echo "No result_uri found in the API response."
  exit 1
fi

Notes

Replace your_domain_name.kapptivate.com with your real environment URL.
Replace YOUR_REFRESH_TOKEN with your actual API refresh token.
body.json must contain your CI payload (tests, devices, variables, etc.).
result_uri points to the endpoint providing the final execution result.

Prerequisites

Step 1: Generate your JWT token

Step 2: Trigger your test(s) from your CI/CD pipeline

How to find your Test ID

How to find your Variable Group ID

Endpoint

Parameters

Sample request

Step 3: Retrieve details of your test run

Step 4: Full API usage example (generic Bash script)

Notes