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
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-08-11T17:03:34.761Z",
            "updatedAt":"2015-08-11T17:03:34.761Z",
            "name":"aws-us-east-1",
            "latitude":39.0436,
            "longitude":-77.4878,
            "description":"AWS N. Virginia",
            "active":true,
            "provider":{
               "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
            }
         },
         "totalCapacity":600,
         "availableCapacity":600,
         "numAgents":2,
         "agents":[
            {
               "id":"616ba2d4-c91c-4c5f-88e2-200bbeade667",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"3ff3096a0805611cb2ec8733dfe30e95b41b3b31410d3707ee5801b1cc68ca07",
               "totalCapacity":300,
               "availableCapacity":300
            },
            {
               "id":"cad6d281-c7f4-4bd0-aeaa-eacd70a6286c",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"4bb05642ac44c37f3182593ac3b45d1d55ec74dd38ed22ae18ccfc98fdf7d249",
               "totalCapacity":300,
               "availableCapacity":300
            }
         ]
      }
   ]
}

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.

Sample Response

{
   "regions":[
      {
         "region":{
            "id":1,
            "createdAt":"2015-08-11T17:03:34.761Z",
            "updatedAt":"2015-08-11T17:03:34.761Z",
            "name":"aws-us-east-1",
            "latitude":39.0436,
            "longitude":-77.4878,
            "description":"AWS N. Virginia",
            "active":true,
            "provider":{
               "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
            }
         },
         "totalCapacity":600,
         "availableCapacity":600,
         "numAgents":2,
         "agents":[
            {
               "id":"616ba2d4-c91c-4c5f-88e2-200bbeade667",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"3ff3096a0805611cb2ec8733dfe30e95b41b3b31410d3707ee5801b1cc68ca07",
               "totalCapacity":300,
               "availableCapacity":300
            },
            {
               "id":"cad6d281-c7f4-4bd0-aeaa-eacd70a6286c",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"4bb05642ac44c37f3182593ac3b45d1d55ec74dd38ed22ae18ccfc98fdf7d249",
               "totalCapacity":300,
               "availableCapacity":300
            }
         ]
      }
   ]
}

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

Request Parameters

None

Sample Response

{
   "regions":[
      {
         "region":{
            "id":1,
            "createdAt":"2015-08-11T17:03:34.761Z",
            "updatedAt":"2015-08-11T17:03:34.761Z",
            "name":"aws-us-east-1",
            "latitude":39.0436,
            "longitude":-77.4878,
            "description":"AWS N. Virginia",
            "active":true,
            "provider":{
               "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
            }
         },
         "totalCapacity":600,
         "availableCapacity":600,
         "numAgents":2,
         "agents":[
            {
               "id":"616ba2d4-c91c-4c5f-88e2-200bbeade667",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"3ff3096a0805611cb2ec8733dfe30e95b41b3b31410d3707ee5801b1cc68ca07",
               "totalCapacity":300,
               "availableCapacity":300
            },
            {
               "id":"cad6d281-c7f4-4bd0-aeaa-eacd70a6286c",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"4bb05642ac44c37f3182593ac3b45d1d55ec74dd38ed22ae18ccfc98fdf7d249",
               "totalCapacity":300,
               "availableCapacity":300
            }
         ]
      }
   ]
}

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

Request Parameters

None

Sample Response

{
   "regions":[
      {
         "region":{
            "id":1,
            "createdAt":"2015-08-11T17:03:34.761Z",
            "updatedAt":"2015-08-11T17:03:34.761Z",
            "name":"aws-us-east-1",
            "latitude":39.0436,
            "longitude":-77.4878,
            "description":"AWS N. Virginia",
            "active":true,
            "provider":{
               "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
            }
         },
         "totalCapacity":600,
         "availableCapacity":600,
         "numAgents":2,
         "agents":[
            {
               "id":"616ba2d4-c91c-4c5f-88e2-200bbeade667",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"3ff3096a0805611cb2ec8733dfe30e95b41b3b31410d3707ee5801b1cc68ca07",
               "totalCapacity":300,
               "availableCapacity":300
            },
            {
               "id":"cad6d281-c7f4-4bd0-aeaa-eacd70a6286c",
               "pid":"13",
               "host":"ec2-52-2-187-201.compute-1.amazonaws.com",
               "containerId":"4bb05642ac44c37f3182593ac3b45d1d55ec74dd38ed22ae18ccfc98fdf7d249",
               "totalCapacity":300,
               "availableCapacity":300
            }
         ]
      }
   ]
}

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
}