Getting started with REST API

Learn how to use the AIVA Cloud API. Currently, you can start tests and get information about running and finished tests. For more information, see API Reference.

Step 1: Generate your API key

1. Navigate to the API keys page: https://app.aiva.works/configurations?page=api-keys
2. Click "Generate new API key"
3. Enter desired name for the API key and click on "Generate"
4. Copy and securely store your API key - you'll need it for all API requests

⚠️ Important: Keep your API key secure and never share it publicly. Treat it like a password. Once you navigate away from the page, you will not be able to see the key again.

Step 2: Making API calls

Authentication

Include your API key in the X-API-KEY header of every request:

X-API-KEY: YOUR_API_KEY

REST API base URL

All API requests should be made to:

https://api.aiva.works

Example

You can try running a test via the interactive API documentation, or here is an example how to start a test using the cURL utility. You only need your API key and the test id (from GET /v2/tests); variable values and a gateway are optional.

Example: Run test:

curl -X POST "https://api.aiva.works/v2/tests/6fd9dece-893f-4d01-897f-6c3866631ce9/runs" \
  -H "X-API-KEY: YOUR_API_KEY"

More examples

Example: Run test with variables:

curl -X POST "https://api.aiva.works/v2/tests/6fd9dece-893f-4d01-897f-6c3866631ce9/runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

Example: Run test on a gateway:

Gateway ids come from GET /v2/gateways.

curl -X POST "https://api.aiva.works/v2/tests/6fd9dece-893f-4d01-897f-6c3866631ce9/runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gatewayId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

Response:

{
  "testRunId": "123e4567-e89b-12d3-a456-426614174000"
}

The returned testRunId can later be used as a query parameter to retrieve the status of a test run. See Check status of multiple tests.

Common use cases

1. Run a simple test

curl -X POST "https://api.aiva.works/v2/tests/6fd9dece-893f-4d01-897f-6c3866631ce9/runs" \
  -H "X-API-KEY: YOUR_API_KEY"

2. Run a test with custom variables

curl -X POST "https://api.aiva.works/v2/tests/6fd9dece-893f-4d01-897f-6c3866631ce9/runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

3. Check status of multiple tests

curl -X GET "https://api.aiva.works/v2/test-runs?testRunIds=test-id-1&testRunIds=test-id-2" \
  -H "X-API-KEY: YOUR_API_KEY"

4. Run a batch

curl -L 'https://api.aiva.works/v2/batch-executions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "name": "CI Batch",
  "labels": [
    "smoke",
    "regression"
  ],
  "maxNumberOfAgents": 3,
  "globalVariableOverrides": {
    "username": "testuser",
    "password": "testpass"
  },
  "variableOverridesPerTest": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "expectedText": "Success",
      "username": "otheruser"
    }
  },
  "gatewayName": "PrimaryGateway"
}'

Need help?

If you encounter issues or need assistance, please contact support.