Route Description
GET /providers Get list of all providers
GET /orgs/:orgId/providers Get list of all providers for an organization
GET /providers/all/agents Get all running agent details
GET /orgs/:orgId/providers/all/agents Get all running agent details for an organization
GET /providers/:id/agents Get running agent details for a provider
GET /providers/:id/regions/:regionId/agents Get running agent details for a provider + region
GET /regions/:regionId/agents Get running agents for region
POST /orgs/:orgId/regions Create or update region
GET /agents Search for agent by instance id or host name
PATCH /agents/:agentId Register shared agent in region
GET /providers/:id Get provider details
POST /providers Create provider
PATCH /providers/:id Update provider
DELETE /providers/:id Delete provider

Overview

Tests is run by one or more test runners (also known as a "provider" in the API). Each provider runs the test in one or more regions. Each region has a set of agents which are responsible for running your tests.

Get list of all providers

Retrieve a list of all providers your credentials allow access to. This includes the public shared grid, private shared grid, and any on demand providers. If an organization id is specified, only providers within that organization are returned.

GET /providers
GET /orgs/:orgId/providers

Request Parameters

  • down: Whether to include all provider regions. Defaults to false.
  • activeRegionsOnly: If down is true, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.
  • providerType: Filter for a certain type of provider only. Possible values: Shared and AwsOnDemand. If not specified, all provider types are returned.

Sample Response

[
   {
      "id":0,
      "createdAt":"2016-05-06T13:56:53.328Z",
      "updatedAt":"2016-05-06T13:56:53.328Z",
      "name":"Public Shared Grid",
      "public":true,
      "providerType":"Shared",
      "active":true
   },
   {
      "id":5,
      "createdAt":"2016-05-16T04:26:45.125Z",
      "updatedAt":"2016-05-16T04:26:45.125Z",
      "name":"AWS On Demand - Testable Account",
      "public":true,
      "providerType":"AwsOnDemand",
      "active":true
   },
   {
      "id":3,
      "createdAt":"2016-05-06T14:14:42.251Z",
      "updatedAt":"2016-05-06T14:14:42.251Z",
      "name":"My Shared Grid",
      "public":false,
      "providerType":"Shared",
      "organizationId":3,
      "active":true
   },
   {
      "id":12,
      "createdAt":"2016-05-18T13:18:08.180Z",
      "updatedAt":"2016-05-18T13:18:08.180Z",
      "name":"AWS On Demand - My Account",
      "public":false,
      "providerType":"AwsOnDemand",
      "organizationId":3,
      "metadata":{
         "awsAccessKeyId":"ABC",
         "awsSecretAccessKey":"DEF"
      },
      "active":true
   }
]

Get all running agent details

Retrieve details about all agents currently running globally to which you have access. This includes all agents running on public shared grid, your on premises private shared grid, and any on demand regions. If a region does not have any running agents, it will not appear in the results. If an organization id is specified, only providers within that organization are returned.

GET /providers/all/agents
GET /orgs/:orgId/providers/all/agents

Request Parameters

  • activeRegionsOnly: If down is true, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.
  • providerType: Filter for a certain type of provider only. Possible values: Shared and AwsOnDemand. If not specified, all provider types are returned.

Sample Response

{
    "regions":[
        {
            "region":{
                "id":1,
                "createdAt":"2015-07-11T18:21:39.170Z",
                "updatedAt":"2019-01-29T18:03:43.255Z",
                "name":"aws-us-east-1",
                "description":"AWS N. Virginia",
                "active":true,
                "isPaidExternally":false,
                "location":{
                    "id":58,
                    "createdAt":"2018-01-15T05:33:13.213Z",
                    "updatedAt":"2019-01-29T18:03:43.254Z",
                    "name":"aws-us-east-1",
                    "latitude":39.0481,
                    "longitude":-77.4729,
                    "description":"AWS N. Virginia",
                    "provider":{
                        "id":0,
                        "createdAt":"2016-05-24T16:18:36.461Z",
                        "updatedAt":"2016-05-24T16:18:36.461Z",
                        "name":"Public Shared Grid",
                        "public":true,
                        "providerType":"Shared",
                        "metadata":{

                        },
                        "active":true,
                        "locations":[

                        ],
                        "firstVersion":true
                    },
                    "regions":[

                    ],
                    "firstVersion":false
                },
                "instances":[

                ],
                "runningExecutions":[

                ],
                "firstVersion":false
            },
            "totalCapacity":1999999998,
            "availableCapacity":1999999998,
            "numHosts":2,
            "totalCpus":8,
            "cpuUtilization":1,
            "freeMemory":13672321024,
            "totalMemory":16007544832,
            "numAgents":2,
            "agents":[
                {
                    "id":"085e70c8-486f-4524-835a-26fb4c6d921c",
                    "regionId":1,
                    "pid":"",
                    "host":"ec2-54-211-48-163.compute-1.amazonaws.com",
                    "instanceId":"i-0c4xxxxxxx",
                    "isPaidExternally":false,
                    "containerId":"baae7e1aba1f79f218dadefac9b9867da78d18aa5118e0d0c33ec79e67ee557b",
                    "totalCapacity":999999999,
                    "availableCapacity":999999999,
                    "freeMemory":6824116224,
                    "totalMemory":8003772416,
                    "cpu":25.0,
                    "totalCpus":4,
                    "cpuUtilization":1,
                    "networkSent":9994,
                    "networkReceived":30976,
                    "disconnected":false,
                    "connections":68,
                    "version":"1.9.0",
                    "runningExecutions":[

                    ]
                }
            ]
        }
    ]
}

Get running agents for provider

Same as the above GET /provider/all/agents except for the specified provider.

GET /providers/:id/agents

Request Parameters

  • activeRegionsOnly: If down is true, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.

Get running agents for provider

Same as the above GET /provider/all/agents except for the specified provider + region.

GET /providers/:id/region/:regionId/agents

Get running agents for region

Same as the above GET /provider/:id/regions/:regionId/agents except without specifying the provider id directly.

GET /region/:regionId/agents

Create or update region

Create or update a region in private shared grid. If a region with the same name exists in your private shared grid it will simply update the description and return all details about that region.

POST /orgs/:orgId/regions

Request Body

  • name Required: Name of the the region.
  • providerId Required: The ID of the private shared grid provider to associate this region with.
  • description: Description of the the region.

Example:

{
   "name": "DC1",
   "description": "On Prem in our DC1 location",
   "providerId": 123
}

Sample Response

{
    "id":111,
    "createdAt":"2015-07-11T18:21:39.170Z",
    "updatedAt":"2019-01-29T18:03:43.255Z",
    "name":"DC1",
    "description":"On Prem in our DC1 location",
    "active":true,
    "isPaidExternally":false,
    "location":{
        "id":58,
        "createdAt":"2018-01-15T05:33:13.213Z",
        "updatedAt":"2019-01-29T18:03:43.254Z",
        "name":"DC1",
        "latitude":39.0481,
        "longitude":-77.4729,
        "description":"On Prem in our DC1 location",
        "provider":{
            "id":111,
            "createdAt":"2016-05-24T16:18:36.461Z",
            "updatedAt":"2016-05-24T16:18:36.461Z",
            "name":"Private Shared Grid",
            "public":true,
            "providerType":"Shared",
            "active":true,
            "firstVersion":true
        }
    }
}

Search for agent by instance id or host name

Search for test runners by instance id or host name.

GET /agents?q=[search]

Request Parameters

  • q: Comma separated list of instance IDs and/or host names. Finds any registered running agent in those regions.
  • includeInactive: Whether to include previously registered agents that are no longer running in the results. Defaults to false.

Sample Response

[
    {
        "id":30415,
        "createdAt":"2019-01-29T15:07:22.214Z",
        "updatedAt":"2019-01-29T15:48:18.692Z",
        "name":"c994f789-4614-4b57-bb1f-21e8a4eceaa0",
        "host":"ec2-18-232-63-123.compute-1.amazonaws.com",
        "instanceId":"i-072c9385cd304b4d4",
        "isPaidExternally":false,
        "active":true,
        "version":"1.9.0",
        "region":{
            "id":3388,
            "createdAt":"2018-06-05T03:45:41.100Z",
            "updatedAt":"2019-01-29T15:47:29.061Z",
            "name":"demo-region",
            "description":"demo-region",
            "active":true,
            "isPaidExternally":false,
            "location":{
                "id":81,
                "createdAt":"2018-06-05T03:45:40.998Z",
                "updatedAt":"2019-01-29T15:47:29.059Z",
                "name":"demo-region",
                "latitude":39.0481,
                "longitude":-77.4729,
                "description":"demo-region",
                "provider":{
                    "id":10,
                    "createdAt":"2016-10-07T04:14:51.264Z",
                    "updatedAt":"2016-10-07T04:14:51.264Z",
                    "name":"My Shared Grid",
                    "public":false,
                    "providerType":"Shared",
                    "organizationId":64,
                    "active":true
                }
            }
        }
    }
]

Register shared agent in region

Register a test runner agent in a private shared grid region.

PATCH /agents/:agentId

The agentId is the id attribute of the agent returned from an agent search

Request Body

  • regionId Required: ID of the region to associate with the agent.

Example:

{
   "regionId": 123,
}

Sample Response

{
    "id": 111,
    "createdAt": "2019-01-29T15:07:22.214Z",
    "updatedAt": "2019-01-29T15:43:28.794Z",
    "name": "c994f789-4614-4b57-bb1f-21e8a4eceaa0",
    "host": "xxxx.amazonaws.com",
    "instanceId": "i-072c9385cd304b4d4",
    "isPaidExternally": false,
    "active": true,
    "version": "1.9.0",
    "region": {
        "id": 3388,
        "createdAt": "2018-06-05T03:45:41.100Z",
        "updatedAt": "2018-10-23T14:39:32.839Z",
        "name": "demo-region",
        "description": "demo-region",
        "active": true,
        "isPaidExternally": false,
        "location": {
            "id": 115,
            "createdAt": "2018-06-05T03:45:40.998Z",
            "updatedAt": "2018-10-23T14:39:32.838Z",
            "name": "demo-region",
            "latitude": 39.0481,
            "longitude": -77.4729,
            "description": "demo-region",
            "provider": {
                "id": 112,
                "createdAt": "2016-10-07T04:14:51.264Z",
                "updatedAt": "2016-10-07T04:14:51.264Z",
                "name": "My Shared Grid",
                "public": false,
                "providerType": "Shared",
                "organizationId": 64,
                "metadata": {},
                "active": true,
                "locations": [],
                "firstVersion": true
            }
        }
    }
}

Get provider details

Get details about the specified provider

GET /providers/:id

Request Parameters

  • down: Whether to include all provider regions. Defaults to true.
  • activeRegionsOnly: If down is true, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.

Sample Response

{
   "id":12,
   "createdAt":"2016-05-18T13:18:08.180Z",
   "updatedAt":"2016-05-18T13:18:08.180Z",
   "name":"AWS On Demand - My Account",
   "public":false,
   "providerType":"AwsOnDemand",
   "organizationId":3,
   "metadata":{
      "awsAccessKeyId":"ABC",
      "awsSecretAccessKey":"DEF"
   },
   "active":true,
   "regions":[
      {
         "id":22,
         "createdAt":"2016-05-19T21:09:11.341Z",
         "updatedAt":"2016-05-19T21:12:33.028Z",
         "name":"exec-1211-us-east-1",
         "latitude":39.018,
         "longitude":-77.539,
         "description":"AWS",
         "active":true
      },
      {
         "id":31,
         "createdAt":"2016-05-20T05:45:03.987Z",
         "updatedAt":"2016-05-20T05:48:25.209Z",
         "name":"exec-1220-us-east-1",
         "latitude":39.018,
         "longitude":-77.539,
         "description":"AWS",
         "active":true
      }
   ]
}

Create provider

Create a new provider. A provider is also known as a test runner and is what actually allocates and runs your test.

POST /providers

Request Body

  • name Required: Name of the configuration.
  • organizationId Required: Organization to which this provider belongs. This can be found using the GET /login?key=<abc> with your API key.
  • providerType Required: Possible values are Shared and AwsOnDemand. A private shared provider is created automatically the first time you run an on premises agent.
  • metadata: An object containing provider specific details. For AWS on demand providers this includes awsAccessKeyId and awsSecretAccessKey.

Example:

{
   "name": "AWS On Demand - My Account",
   "organization": 3,
   "providerType": "AwsOnDemand",
   "providers":{
      "awsAccessKeyId": "abc",
      "awsSecretAccessKey": "def"
   }
}

Sample Response

{
   "id":12,
   "createdAt":"2016-05-18T13:18:08.180Z",
   "updatedAt":"2016-05-18T13:18:08.180Z",
   "name":"AWS On Demand - My Account",
   "public":false,
   "providerType":"AwsOnDemand",
   "organizationId":3,
   "metadata":{
      "awsAccessKeyId":"abc",
      "awsSecretAccessKey":"def"
   },
   "active":true
}

Update provider

Update the provider parameters. All parameters available when creating can be specified during update except providerType and organizationId.

PATCH /providers/:id

Request Body

{
   "name": "New Name",
   "metadata": {
      "awsAccessKeyId": "newabc",
      "awsSecretAccessKey": "newdef"
   }
}

Response

{
   "id":12,
   "createdAt":"2016-05-18T13:18:08.180Z",
   "updatedAt":"2016-05-18T13:18:08.180Z",
   "name":"AWS On Demand - My Account",
   "public":false,
   "providerType":"AwsOnDemand",
   "organizationId":3,
   "metadata":{
      "awsAccessKeyId":"newabc",
      "awsSecretAccessKey":"newdef"
   },
   "active":true
}

Delete provider

DELETE /providers/:id

Response

The deleted provider

{
   "id":12,
   "createdAt":"2016-05-18T13:18:08.180Z",
   "updatedAt":"2016-05-18T13:18:08.180Z",
   "name":"AWS On Demand - My Account",
   "public":false,
   "providerType":"AwsOnDemand",
   "organizationId":3,
   "metadata":{
      "awsAccessKeyId":"newabc",
      "awsSecretAccessKey":"newdef"
   },
   "active":true
}