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 to specify your API key, the test name and optionally also variable values.

Example: Run test using test id:

curl -X POST "https://api.aiva.works/v1/test-runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testId": "6fd9dece-893f-4d01-897f-6c3866631ce9"}'

More examples

Example: Run test using test name:

curl -X POST "https://api.aiva.works/v1/test-runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testName": "Basic test"}'

note

When both test id and test name are provided, the test id takes precedence and the test name is ignored.

Example: Run test with variables:

curl -X POST "https://api.aiva.works/v1/test-runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testName": "User registration flow",
    "variables": {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }'

Example: Run test on gateway:

curl -X POST "https://api.aiva.works/v1/test-runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testName": "Basic test",
    "gatewayName": "My internal network"
  }'

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/v1/test-runs" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"testId": "6fd9dece-893f-4d01-897f-6c3866631ce9"}'

2. Run a test with custom variables

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

3. Check status of multiple tests

curl -X GET "https://api.aiva.works/v1/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/v1/batches' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "name": null,
  "labels": [
    "smoke",
    "regression"
  ],
  "maxNumberOfAgents": 3,
  "globalVariablesOverrides": {
    "username": "testuser",
    "password": "testpass"
  },
  "variablesOverridesPerTest": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "expectedText": "Success",
      "username": "otheruser"
    }
  },
  "gatewayName": "PrimaryGateway"
}'

Need help?

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