Back to top

API v2.0 Overview

The CenturyLink Cloud has a new, improved API for performing the same actions programmatically as you can with the Control Portal. The API is RESTful and works with JSON messages over HTTP. It relies on the standard HTTP verbs including GET, POST, PUT, DELETE, and PATCH.

The URL format of the service is: https://api.ctl.io/v2/{resource}/{account alias}. As an example, to retrieve the top level Group for a given data center, you would issue a GET request to https://api.ctl.io/v2/datacenters/ALIAS/WA1. The HTTP request must include Content-Type and Accepts headers set to application/json.

Authentication

Service authentication is done via bearer tokens and is outlined in the Authentication Overview and also the Login API description.

Links Framework

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. See more information in our overview of the Links Framework.

HTTP Response Codes

The service responds to requests using standard HTTP codes, and if applicable, a JSON payload.

HTTP Code Description
200 OK. Sent when requests are immediately successful and did NOT create a new URL-addressable resource.
201 CREATED. Sent when requests are immediately successful and DID create a new URL-addressable resource.
202 ACCEPTED. Sent when requests result in a scheduled activity. Response body will include a URL for them to get the status of the activity.
204 NO CONTENT. Sent when requests are immediately successful but return no additional information about the resource.
400 BAD REQUEST. Sent when something is wrong with the query string or message body.
401 UNAUTHORIZED. Sent when a bearer token is not provided.
403 FORBIDDEN. Sent if the request violates the security demands of the service.
404 NOT FOUND. Sent if the URL points to a non-existent resource.
500 INTERNAL SERVER ERROR. Sent if the service experiences an error through no fault of the user.

API v2.0 Authentication Overview

Summary

Authentication to the API v2 is done with the same credentials used to access the CenturyLink Cloud Control Portal. The username and password are provided to the API and in return, the user gets back a credentials object that contains a valid bearer token. This token -- which can be reused for up to 2 weeks -- must be provided on each subsequent API request.

Walkthrough

.NET Framework Example

Below is a brief demonstration of using the .NET framework to retrieve a valid token from the API authentication service.

  1. Reference the assemblies needed to make HTTP requests.

    using System.Net.Http;
    using System.Net.Http.Headers;
    
  2. Create an instance of the HttpClient object.

    HttpClient authClient = new HttpClient();
    
  3. Add an Accept header to indicate that returning JSON as a response is ok.

    authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    
  4. Create an HttpContent object to hold the JSON payload ({"username": "[username]", "password": "[password]"}) sent to the API. Also, note that the content type application/json is set.

    HttpContent content =
      new StringContent("{ \"username\":\"[username]\", \"password\":\"[password]\" }", null, "application/json");
    
  5. Invoke the API and send the HTTP content using a POST command.

    HttpResponseMessage message =
       await authClient.PostAsync("https://api.ctl.io/v2/authentication/login", content);
    
  6. Load the response into a string for parsing.

    string responseString = await message.Content.ReadAsStringAsync();
    

    If valid credentials are provided, an HTTP 200 status is returned along with the following JSON payload:

     {
        "userName":"[email protected]",
        "accountAlias":"RLS1",
        "locationAlias":"WA1",
        "roles":[
           "ServerAdmin",
           "AccountAdmin"
        ],
        "bearerToken":"[LONG TOKEN VALUE]"
     }
    

    These results show the user's parent account, default data center location, and assigned platform roles. The bearerToken is the value that must be added to the HTTP Authorization header when calling any other API service. This token identifies who the user is and what they are allowed to do in the API.

    If you provide invalid credentials, you will get an HTTP 400 (Bad Request) and the following response message:

    {"message":"We didn't recognize the username or password you entered. Please try again."}
    
  7. Submit a request: the following .NET code demonstrates how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".

     HttpClient authClient = new HttpClient();
    
     authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    
     // Add bearer token to the header
     authClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Bearer [LONG TOKEN VALUE]");
    
     HttpResponseMessage message = await authClient.GetAsync("https://api.ctl.io/v2/datacenters/DEMO/CA1");
    
     string responseString = await message.Content.ReadAsStringAsync();
    

PowerShell Example

Below is a brief demonstration of how PowerShell can be used to retrieve a valid token from the API authentication service.

  1. Log into the API.

    $Body = @{ 
    Username = 'CONTROL_USERNAME' 
    Password = 'CONTROL_PASSWORD' 
    }
    
  2. Log in to the Platform and get back a bearerToken.

    $LogonUri = 'https://api.ctl.io/v2/authentication/login' 
    $LogonResponse = Invoke-RestMethod -Method Post -Uri $LogonUri -Body $Body -SessionVariable WebSession
    
  3. Pull the BearerToken out of the response and format it correctly. Note that a prefix of "Bearer " is required.

    $Bearer = 'Bearer ' + $LogonResponse.bearerToken
    
  4. Add Accept and Authorization headers to the session variable to be used on future requests.

    $WebSession.Headers.Add('Accept', 'application/json') 
    $WebSession.Headers.Add('Authorization', $Bearer)
    

You can now use the session variable for authenticating further API calls. Example:

Here's an example of pulling server credentials:

  $AccountAlias = 'ACCOUNT_ALIAS' 
  $ServerName = 'SERVER_NAME' 
  $ServercredsURL = "https://api.ctl.io/v2/servers/$AccountAlias/$ServerName/credentials" 
  $ServerCreds = Invoke-RestMethod -Uri $servercredsURL -WebSession $WebSession 
  $ServerCreds

Raw HTTP Example

Below is an example of the raw HTTP request and response messages when retrieving a valid token from the API authentication service.

Request

POST https://api.ctl.io/v2/authentication/login HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 54

{
  "username": "[username]",
  "password": "[password]"
}

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:23:45 GMT
Content-Length: 149

{
  "userName": "[email protected]",
  "accountAlias": "RLS1",
  "locationAlias": "WA1",
  "roles": [
    "ServerAdmin",
    "AccountAdmin"
  ],
  "bearerToken": "[LONG TOKEN VALUE]"
}

These results show the user's parent account, default data center location, and assigned platform roles. The bearerToken is the value that must be added to the HTTP Authorization header when calling any other API service. This token identifies who the user is and what they are allowed to do in the API.

If you provide invalid credentials, you will get an HTTP 400 (Bad Request) and the following response message:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:26:45 GMT
Content-Length: 89

{"message":"We didn't recognize the username or password you entered. Please try again."}

The following raw HTTP request message shows how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".

GET https://api.ctl.io/v2/datacenters/RLS1/WA1 HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 0
Authorization: Bearer [LONG TOKEN VALUE]

API v2.0 Links Framework

Overview

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. Many of the JSON response entities include a links attribute which contains an array of link entities for resources that are related the object that was just acted upon.

This link model helps with both discoverability as well as use-case scalability. In addition, it provides a mechanism for exposing only those endpoints that are available to a user based on their role. In other words, a user will only see links and associated actions that they have access to. Each link entity contains a URL in the href attribute so the API user may simply follow the link to perform a followup action.

Link Entity

Each link entity defines the following properties. For more details about each specific link type, see the Link Definitions for each resource type.

Name Type Description Req.
rel string The link type, as described in the table below. Yes
href string Address of the resource. Yes
id string Unique ID of the resource. No
name string Friendly name of the resource. No
verbs array Valid HTTP verbs that can act on this resource. If none are explicitly listed, GET is assumed to be the only one. No

Create Alert Policy

Creates an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new alert policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/alertPolicies/ALIAS

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
name string Name of the alert policy. Yes
actions array The actions to perform when the alert is triggered. Yes
triggers array The definition of the triggers that fire the alert. Yes

Actions Entity

Name Type Description
action string The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric string The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration string The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold number The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 80%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "[email protected]"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":80.0
    }
  ]
}

Response

Entity Definition

Name Type Description
id string ID of the alert policy.
name string Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 80%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "[email protected]"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 80.0
    }
  ]
}

Delete Alert Policy

Deletes a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific alert policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the alert policy being queried. Yes

Response

The response will not contain JSON content, but should return a standard HTTP 200 OK response upon deletion of the policy.

Get Alert Policies

Gets a list of alert policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of alert policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that alert policy using the API.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Response

The response will be an items objects referencing an array containing one entity for each alert policy in the given account.

Entity Definition

Name Type Description
id string ID of the alert policy.
name string Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type Description
action string The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric string The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration string The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold number The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "items":[
    {
      "id":"999de90f25ab4308a6c346cd03602fef",
      "name":"Memory Above 90%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "[email protected]"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"memory",
          "duration":"00:10:00",
          "threshold":90.0
        }
      ]
    },
    {
      "id":"175c3b5743d64cea952a5cca03bdb2da",
      "name":"CPU Above 75%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "[email protected]"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/175c3b5743d64cea952a5cca03bdb2da",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"cpu",
          "duration":"00:05:00",
          "threshold":75.0
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Alert Policy

Gets a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific alert policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the alert policy being queried. Yes

Response

Entity Definition

Name Type Description
id string ID of the alert policy.
name string Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type Description
action string The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric string The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration string The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold number The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "id":"999de90f25ab4308a6c346cd03602fef",
  "name":"Memory Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "[email protected]"
        ]
      }
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers":[
    {
      "metric":"memory",
      "duration":"00:10:00",
      "threshold":90.0
    }
  ]
}

Update Alert Policy

Updates the name of an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing alert policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the alert policy being updated. Yes

Content Properties

Name Type Description Req.
name string Name of the alert policy. Yes
actions array The actions to perform when the alert is triggered. Yes
triggers array The definition of the triggers that fire the alert. Yes

Actions Entity

Name Type Description
action string The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type Description
metric string The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration string The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold number The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "[email protected]"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":90.0
    }
  ]
}

Response

Entity Definition

Name Type Description
id string ID of the alert policy.
name string Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 90%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "[email protected]"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 90.0
    }
  ]
}

Create Anti-Affinity Policy

Creates an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new anti-affinity policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
name string Name of the anti-affinity policy. Yes
location string Data center location of the anti-affinity policy. Yes

Examples

JSON

{
  "name":"New Anti-Affinity Policy",
  "location":"VA1"
}

Response

Entity Definition

Name Type Description
id string ID of the anti-affinity policy.
name string Name of the anti-affinity policy.
location string Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{

  "id":"80a7bf90b459454b859399aef54f4173",
  "name":"New Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b459454b859399aef54f4173"
    }
  ]
}

Delete Anti-Affinity Policy

Deletes a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific anti-affinity policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the anti-affinity policy being queried. Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy.

Get Anti-Affinity Policies

Gets a list of anti-affinity policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of anti-affinity policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that anti-affinity policy using the API.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Response

The response will be an items objects referencing an array containing one entity for each anti-affinity policy in the given account.

Entity Definition

Name Type Description
id string ID of the anti-affinity policy.
name string Name of the anti-affinity policy.
location string Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "items":[
    {
      "id":"80a7bf90b199454b859399bff54f4173",
      "name":"My Anti-Affinity Policy",
      "location":"VA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        },
        {
          "rel":"server",
          "href":"/v2/servers/alias/va1aliashypsc01",
          "id":"va1aliashypsc01",
          "name":"VA1ALIASHYPSC01"
        }
      ]
    },
    {
      "id":"ca8b07035cf844f3b4f953074c2630eb",
      "name":"My Other Anti-Affinity Policy",
      "location":"WA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/ca8b07035cf844f3b4f953074c2630eb",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Anti-Affinity Policy

Gets a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific anti-affinity policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the anti-affinity policy being queried. Yes

Response

Entity Definition

Name Type Description
id string ID of the anti-affinity policy.
name string Name of the anti-affinity policy.
location string Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Update Anti-Affinity Policy

Updates the name of an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing anti-affinity policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
PolicyId string ID of the anti-affinity policy being updated. Yes

Content Properties

Name Type Description Req.
name string Name of the anti-affinity policy. Yes

Examples

JSON

{
  "name":"Changed Name of Anti-Affinity Policy",
}

Response

Entity Definition

Name Type Description
id string ID of the anti-affinity policy.
name string New name of the anti-affinity policy.
location string Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173"
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Acquires an authentication token used for subsequent queries to the API.

When to Use It

Use this API operation before you call any other API operation. It shows a user's roles, primary data center, and a valid bearer token.

URL

Structure

POST https://api.ctl.io/v2/authentication/login

Request

Content Properties

Name Type Description Req.
username string Control Portal user name value Yes
password string Control Portal password value. Yes

Examples

JSON

{
   "username":"demouser1",
   "password":"mypassword"
}

Response

Entity Definition

Name Type Description
userName string Control Portal user name value
accountAlias string Account that contains this user record
locationAlias string Default data center of the user
roles array Permission roles associated with this user
bearerToken string Security token for this user that is included in the Authorization header for all other API requests as "Bearer [LONG TOKEN VALUE]".

Examples

JSON

{
    "userName": "[email protected]",
    "accountAlias": "ALIAS",
    "locationAlias": "DC1",
    "roles": [
        "AccountAdmin",
        "ServerAdmin"
    ],
    "bearerToken": "[LONG TOKEN VALUE]"
}

Get Vertical Autoscale Policies

Gets a list of vertical autoscale policies for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of vertical autoscale policies for a given account, and to see what servers are associated with these policies. You can also use the IDs provided in this list to add a server to that autoscale policy using Set Vertical Autoscale Policy On Server API method.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes

Response

The response will be an array containing one entity for each autoscale policy in the given account.

Entity Definition

Name Type Description
id string ID of the vertical autoscale policy
name string Name of the vertical autoscale policy
resourceType string The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs; this is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type Description
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type Description
start string Start time of window in UTC
end string End time of window in UTC

Examples

JSON

      {
        "id": "3b6f26003c224596bc7e748a0adc97d5",
        "name": "Production Database Scale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 6,
          "min": 2
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "02:00",
          "end": "04:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/3b6f26003c224596bc7e748a0adc97d5"
          }
        ]
      },
      {
        "id": "23a68b22e35b4983abd1051fae10ee7b",
        "name": "Another CPU Autoscale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 4,
          "min": 1
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "00:00",
          "end": "23:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/23a68b22e35b4983abd1051fae10ee7b"
          }
        ]
      }

Get Vertical Autoscale Policy

Gets a given vertical autoscale policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a vertical autoscale policy for a given account.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS/80a7bf90b199464b859399bff54f4173

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
policyId string ID of the autoscale policy being queried Yes

Response

Entity Definition

Name Type Description
id string ID of the vertical autoscale policy
name string Name of the vertical autoscale policy
resourceType string The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs. This is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type Description
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type Description
start string Start time of window in UTC
end string End time of window in UTC

Examples

JSON

```json { "id": "9d14822c1e8541cea11703cf2b078c9d", "name": "Production Database Scale Policy", "resourceType": "cpu", "thresholdPeriodMinutes": 5, "scaleUpIncrement": 1, "range": { "max": 6, "min": 2 }, "scaleUpThreshold": 85, "scaleDownThreshold": 15, "scaleDownWindow": { "start": "02:00", "end": "04:00" }, "links": [ { "rel": "self", "href": "/v2/autoscalePolicies/ALIAS/9d14822c1e8541cea11703cf2b078c9d" } ] }

Remove Vertical Autoscale Policy from Server

Removes the autoscale policy from a given server, if the policy has first been applied to the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to remove the autoscale policy from a server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server. Retrieved from query to containing a group, or by looking at the URL when viewing a server in the Control Portal. Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy from the server.

Set Vertical Autoscale Policy on Server

Sets the autoscale policy for a specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set the autoscale policy of a server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

PUT https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
id string The unique identifier of the autoscale policy to apply to the server. Can be retrieved by calling Get Vertical Autoscale Policies. Yes

Examples

JSON

    {
      "id": "3440b69f139c435b8f9462b0661014fc"
    }

Response

Entity Definition

Name Type Value Description
id string ID of the autoscale policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON


  {
    "id": "3440b69f139c435b8f9462b0661014fc",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

View Vertical Autoscale Policy on Server

Gets the autoscale policy of a given server, if a policy has been applied on the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the autoscale policy of a given server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Response

Entity Definition

Name Type Value Description
id string ID of the autoscale policy
links array Collection of entity links that point to resources related to this policy

Examples

JSON

  {
    "id": "6c8d7b5349054fe6a532539ff066b53b",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

Get Invoice Data for an Account Alias

Gets a list of invoicing data for a given account alias for a given month. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

NOTE: THE DATA RETURNED IN THIS API ARE USAGE ESTIMATES ONLY, AND DOES NOT REPRESENT AN ACTUAL BILL.

When to Use It

Use this API operation when you want to get invoicing data for a given account for a given month.

URL

Structure

GET https://api.ctl.io/v2/invoice/{accountAlias}/{year}/{month}

Example

GET https://api.ctl.io/v2/invoice/ALIAS/2015/7/?pricingAccount=PALIAS

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
year integer Year of usage, in YYYY format. Yes
month integer Monthly period of usage, in M format. Yes
pricingAccountAlias string Short code of the account that sends the invoice for the accountAlias No

Response

The response includes a JSON object containing an array with invoicing data.

Entity Definition

Name Type Description
id string ID of the account alias being queried
terms string payment terms associated with the account
companyName string Description of the account name
accountAlias string Short code for a particular account
pricingAccountAlias string Short code for a particular account that receives the bill for the accountAlias usage
parentAccountAlias string Short code for the parent account alias associated with the account alias being queried
address1 string First line of the address associated with accountAlias
address2 string Second line of the address associated with accountAlias
city string City associated with the accountAlias
stateProvince string State or province associated with the accountAlias
postalCode string Postal code associated with the accountAlias
billingContactEmail string Billing email address associated with the accountAlias
invoiceCCEmail string Additional billing email address associated with the accountAlias
totalAmount decimal Invoice amount in dollars
invoiceDate string Date the invoice is finalized
poNumber string Purchase Order associated with the Invoice
lineItems array Usage details of a resource or collection of similar resources

Line Items Definition

Name Type Description
quantity integer Quantity of the line item
description string Text description of the line item
unitCost decimal Unit cost of the line item
itemTotal decimal Total cost of the line item
serviceLocation string Location of the line item
itemDetails complex Details about the line item

Examples

JSON

{
    "id": "ALIAS69849A66",
    "terms": "Net 15",
    "companyName": "CTL Cloud Solutions",
    "accountAlias": "ALIAS",
    "pricingAccountAlias": "ALIAS",
    "parentAccountAlias": "PALIAS",
    "address1": "1100 112th Ave NE",
    "address2": "Suite 400",
    "city": "Bellevue",
    "stateProvince": "WA",
    "postalCode": "98004",
    "billingContactEmail": "[email protected]",
    "invoiceCCEmail": "",
    "totalAmount": 0,
    "invoiceDate": "2015-08-01T00:00:00Z",
    "poNumber": "",
    "lineItems": [
        {
            "quantity": 1,
            "description": "Server Group: DEMO - VA1",
            "unitCost": 153.93,
            "itemTotal": 153.93,
            "serviceLocation": "VA1",
            "itemDetails": [
                {
                    "description": "VA1ALIASJMB01",
                    "cost": 153.93
                }
            ]
        },
        {
            "quantity": 1,
            "description": "Shared Load Balancer - CA1",
            "unitCost": 29.76,
            "itemTotal": 29.76,
            "serviceLocation": "CA1",
            "itemDetails": []
        },
        {
            "quantity": 1,
            "description": "Additional Networks - GB3",
            "unitCost": 45,
            "itemTotal": 45,
            "serviceLocation": "GB3",
            "itemDetails": []
        },
    ]
}

Get Custom Fields

Retrieves the custom fields defined for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to find out the details of what custom fields are defined for an account.

URL

Structure

GET https://api.ctl.io/v2/accounts/{accountAlias}/customFields

Example

GET https://api.ctl.io/v2/accounts/ACCT/customFields

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Response

The response will be an array containing one entity for each custom field defined in the given account.

Entity Definition

Name Type Description
id string Unique identifier of the custom field.
name string Friendly name of the custom field as it appears in the UI.
isRequired boolean Boolean value representing whether or not a value is required for this custom field.
type string The type of custom field defined. Will be either "text" (free-form text field), "checkbox" (boolean value), or "option" (dropdown list).
options array Array of name-value pairs corresponding to the options defined for this field. (Empty for "text" or "checkbox" field types.)

Examples

JSON

[
  {
    "id":"dba67b156f77123fb413ddfa3dc4ac1d",
    "name":"Cost Center",
    "isRequired":false,
    "type":"text",
    "options":[]
  },
  {
    "id":"58f83af6123846769ee6cb091ce3561e",
    "name":"Production",
    "isRequired":true,
    "type":"checkbox",
    "options":[]
  },
  {
    "id":"22f002123e3b46d9a8b38ecd4c6df7f9",
    "name":"Color",
    "isRequired":true,
    "type":"option",
    "options":[
      {
        "name":"red",
        "value":"Red"
      },
      {
        "name":"blue",
        "value":"Blue"
      }
    ]
  }
]

Get Data Center

Gets the details of a specific data center the account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the name of the root hardware group for a data center. Once you have that group alias, you can issue a secondary query to retrieve the entire group hierarchy for a given data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}?groupLinks=true|false

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1?groupLinks=true

Request

URI and Querystring Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
GroupLinks boolean Determine whether link collections are returned for each group No

Response

Entity Definition

Name Type Description
id string Short value representing the data center code
name string Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "id": "DC1",
  "name": "DC FRIENDLY NAME",
  "links": [
    {
      "rel": "self",
      "href": "/v2/datacenters/ALIAS/DC1"
    },
    {
      "rel":"group",
      "href":"/v2/groups/ALIAS/54faef9c2bfd41d6b30f787567f9b0d4",
      "id":"54faef9c2bfd41d6b30f787567f9b0d4",
      "name":"DC1 Hardware"
    }
  ]
}

Get Data Center Bare Metal Capabilities

Gets the list of bare metal capabilities that a specific data center supports for a given account, including the list of configuration types and the list of supported operating systems. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of related to provisioning bare metal servers in a data center for your account. Specifically, this operation is helpful for retrieving the list of configuration identifiers and OS types to use when creating a bare metal server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/bareMetalCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/VA1/bareMetalCapabilities

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Response

Entity Definition

Name Type Description
skus array Collection of available bare metal configuration types to pass in to configurationId when creating a bare metal server
operatingSystems array Collection of available operating systems when creating a bare metal server

SKUs Definition

Name Type Description
id string The configurationId to pass to the Create Server API operation when creating a bare metal server.
hourlyRate number Price per hour for the given configuration.
availability string The level of availability for the given configuration: either high, low, or none.
memory array Information about the memory on the server.
processor complex Information about the physical processors on the server.
storage array Collection of disk information, each item representing one physical disk on the server.

Memory Definition

Name Type Description
capacityGB number Memory capacity in gigabytes

Processor Definition

Name Type Description
coresPerSocket number Number of cores for each processor socket
description string Description of the processor including model and clock speed
sockets number Number of sockets

Storage Definition

Name Type Description
capacityGB number Drive capacity in gigabytes
speedRpm number RPM (revolutions per minutes) speed of the disk
type string Disk type. Only Hdd currently supported.

OperatingSystems Definition

Name Type Description
type string Underlying unique name for the OS type
description string Friendly description for the OS type
hourlyRatePerSocket number Price per hour per socket for the OS type.

Examples

JSON

{
  "skus": [
    {
      "id": "529e2592a3e640a7c2617b5e8bc8feaed95eab22",
      "hourlyRate": 0.56,
      "availability": "high",
      "memory": [
        {
          "capacityGB": 16
        }
      ],
      "processor": {
        "coresPerSocket": 4,
        "description": "Intel(R) Xeon(R) CPU E3-1271 v3 @ 3.60GHz",
        "sockets": 1
      },
      "storage": [
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    },
    {
      "id": "f24b18ba2ce23657657444601649c7b8b7f9b60c",
      "hourlyRate": 1.65,
      "availability": "none",
      "memory": [
        {
          "capacityGB": 64
        }
      ],
      "processor": {
        "coresPerSocket": 6,
        "description": "Intel(R) Xeon(R) CPU E5-2620 v3 @ 2.40GHz",
        "sockets": 2
      },
      "storage": [
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    }
  ],
  "operatingSystems": [
    {
      "type": "centOS6_64Bit",
      "description": "CentOS 6 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "redHat6_64Bit",
      "description": "RedHat Enterprise Linux 6 64-bit",
      "hourlyRatePerSocket": 0.075
    },
    {
      "type": "ubuntu14_64Bit",
      "description": "Ubuntu 14 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "windows2012R2Standard_64bit",
      "description": "Windows 2012 R2 Standard 64-bit",
      "hourlyRatePerSocket": 0.04
    },
    {
      "type": "windows2012R2Datacenter_64bit",
      "description": "Windows 2012 R2 Datacenter 64-bit",
      "hourlyRatePerSocket": 0.279
    }
  ]
}

Get Data Center Deployment Capabilities

Gets the list of capabilities that a specific data center supports for a given account, including the deployable networks, OS templates, and whether features like shared load balancer configuration are available. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of a data center for your account. Specifically, this operation is helpful for retrieving network identifiers and OS template names to use when creating a server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/deploymentCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1/deploymentCapabilities

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Response

Entity Definition

Name Type Description
supportsSharedLoadBalancer boolean Whether or not this data center provides support for shared load balancer configuration
supportsBareMetalServers boolean Whether or not this data center provides support for provisioning bare metal servers
deployableNetworks array Collection of networks that can be used for deploying servers
templates array Collection of available templates in the data center that can be used to create servers
importableOSTypes array Collection of available OS types that can be imported as virtual machines.

DeployableNetworks Definition

Name Type Description
name string User-defined name of the network
networkId string Unique identifier of the network
type string Network type, usually "private" for networks created by the user
accountID string Account alias for the account in which the network exists

Templates Definition

Name Type Description
name string Underlying unique name for the template
description string Description of the template at it appears in the Control Portal UI
storageSizeGB integer The amount of storage allocated for the primary OS root drive
capabilities array List of capabilities supported by this specific OS template (example: whether adding CPU or memory requires a reboot or not)
reservedDrivePaths array List of drive path names reserved by the OS that can't be used to name user-defined drives
drivePathLength integer Length of the string for naming a drive path, if applicable

Examples

JSON

{
  "supportsBareMetalServers":false,
  "supportsSharedLoadBalancer":true,
  "deployableNetworks":[
    {
      "name":"My Network",
      "networkId":"a933432bd8894e84b6c4fb123e48cb8b",
      "type":"private",
      "accountID":"ACCT"
    }
  ],
  "templates":[
    {
      "name":"UBUNTU-14-64-TEMPLATE",
      "description":"Ubuntu 14 | 64-bit",
      "storageSizeGB":17,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    },
    {
      "name":"WIN2012R2DTC-64",
      "description":"Windows 2012 R2 Datacenter Edition | 64-bit",
      "storageSizeGB":60,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "a",
        "b",
        "c",
        "d"
      ],
      "drivePathLength":1
    },
    {
      "name":"WA1ACCTCUST01",
      "description":"My Custom Template",
      "storageSizeGB":16,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    }
  ]
}

Get Data Center List

Gets the list of data centers that a given account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of data center names and codes that you have access to. Using that list of data centers, you can then query for the root group, and all the child groups in an entire data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}

Example

GET https://api.ctl.io/v2/datacenters/ALIAS

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Response

Entity Definition

Name Type Description
id string Short value representing the data center code
name string Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

[
  {
    "id": "DC1",
    "name": "DC FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC1"
      }
    ]
  },
  {
    "id": "DC2",
    "name": "DC2 FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC2"
      }
    ]
  }
]

Create a Cross Data Center Firewall Policy

Creates a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy between networks in different data centers for a given account.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Content Properties

Name Type Description Req.
destinationAccountId string Short code for a particular account Yes
destinationLocationId string Short code for a particular location Yes
destinationCidr string Destination address for traffic on the terminating firewall, specified using CIDR notation Yes
enabled string Indicates if the policy is enabled (true) or disabled (false) Yes
sourceCidr string Source address for traffic on the originating firewall, specified using CIDR notation, on the originating firewall Yes

Example

JSON

{
    "destinationAccountId" : "dest",
    "destinationLocationId" : "UC1",
    "destinationCidr" : "10.1.1.0/24",
    "enabled" : true,
    "sourceCidr" : "10.2.2.0/24"
}

Response

The response will be an entity representing the new firewall policy that was created.

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "pending",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Create an Intra Data Center Firewall Policy

Creates a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Content Properties

Name Type Description Req.
destinationAccount string Short code for a particular account Yes
source string Source addresses for traffic on the originating firewall, specified using CIDR notation, on the originating firewall Yes
destination string Destination addresses for traffic on the terminating firewall, specified using CIDR notation Yes
ports string Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP). No

Examples

JSON

{
    "destinationAccount": "DEST_ALIAS",
    "source":["123.45.223.1/32", "123.45.223.2/32", "123.45.223.3/32"],
    "destination":["123.45.223.1/32", "123.45.223.2/32"],
    "ports":["tcp/1-600"]
}

Response

The response will be an entity representing the new firewall policy that was created.

Entity Definition

Name Type Description
links array Collection of entity links that point to resources related to this firewall policy

Examples

JSON

{
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/DEST_ALIAS/WA1/71f912d00e1c11e5b9390800200c9a66",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Delete a Cross Data Center Firewall Policy

Deletes a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Yes
policyId string ID of the firewall policy Yes

Response

There is no response upon the successful removal of the firewall policy.

Delete an Intra Data Center Firewall Policy

Deletes a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Yes
firewallPolicy string ID of the firewall policy Yes

Response

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful removal of the firewall policy.

Get Cross Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
policyId string ID of the firewall policy Yes

Response

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "active",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Cross Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account, between networks in different data centers ("cross data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountId}/{dataCenter}?destinationAccountId={destinationAccountId}

Example

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1?destinationAccountId=DEST_ALIAS

Request

URI Parameters

Name Type Description Req.
sourceAccountId string Short code for a particular account Yes
dataCenter string Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation. Yes
destinationAccountId string Short code for another account No

Response

Example

JSON

[
 {
   "id": "921670344d781378a8df6159c00bddea",
   "status": "pending",
   "enabled": true,
   "sourceCidr": "10.2.2.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "1a4b72963130e7a4d1a3343299f84edc",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.5.5.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest1",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src5/wa1/1a4b72963130e7a4d1a3343299f84edc",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "372d37109487b0584db2c87b16f654b1",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.7.7.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.9.9.0/24",
   "destinationAccount": "dest2",
   "destinationLocation": "il1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src7/gb3/372d37109487b0584db2c87b16f654b1",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 }
]

Get Intra Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
firewallPolicy string ID of the firewall policy Yes

Response

Entity Definition

Name Type Description
id string ID of the firewall policy
status string The state of the policy; either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
enabled boolean Indicates if the policy is enabled (true) or disabled (false)
source string Source addresses for traffic on the originating firewall, specified using CIDR notation
destination string Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount string Short code for a particular account
ports string Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

{
    "id": "1ac853b00e1011e5b9390800200c9a6",
    "status": "active",
    "enabled": true,
    "source": [
        "123.45.678.1/32",
        "123.45.678.2/32",
        "123.45.678.3/32"
    ],
    "destination": [
        "245.21.223.1/32",
        "245.21.223.2/32"
    ],
    "destinationAccount": "DEST_ALIAS",
    "ports": [
        "any"
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a6",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Intra Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account in a given data center ("intra data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies in a given data center for a given account. Using that list of firewall policies, you can then query for a specific policy in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}?destinationAccount={destinationAccountAlias}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1?destinationAccount=DEST_ALIAS

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
destinationAccountAlias string Short code for a particular account No

Response

Entity Definition

Name Type Description
id string ID of the firewall policy
status string The state of the policy: either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
enabled boolean Indicates if the policy is enabled (true) or disabled (false)
source string Source addresses for traffic on the originating firewall, specified using CIDR notation
destination string Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount string Short code for a particular account
ports string Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

[
    {
        "id": "c59b96600e0d11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32",
            "123.45.678.2/32",
            "123.45.678.3/32"
        ],
        "destination": [
            "234.56.789.1/32",
            "234.56.789.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/c59b96600e0d11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "bbb377290e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": false,
        "source": [
            "145.67.890.1/32",
            "145.67.890.2/32",
            "145.67.890.3/32"
        ],
        "destination": [
            "156.78.901.1/32",
            "156.78.901.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/bbb377290e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "d56587800e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32"
        ],
        "destination": [
            "234.23.435.200/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "tcp/8080",
            "tcp/1-8000"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/d56587800e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
]

Update Cross Data Center Firewall Policy

Updates a given firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}?enabled=true/false

Example

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea?enabled=false

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation. Yes
enabled string true or false Yes

Response

There is no response upon the successful update of the firewall policy.

Update Intra Data Center Firewall Policy

Updates a given firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

PUT https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/e46ef2500e1011e5b9390800200c9a66

Request

URI Parameters

Name Type Description Req.
sourceAccountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation. Yes
destinationAccountAlias string Short code for a particular account No

Content Properties

Name Type Description Req.
enabled boolean Indicates if the policy is enabled (true) or disabled (false) No
source string Source addresses for traffic on the originating firewall, specified using CIDR notation No
destination string Destination addresses for traffic on the terminating firewall, specified using CIDR notation No
ports string Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP). No

Examples

JSON

{
    "enabled":false,
    "source":["123.45.678.1/32"],
    "destination":["234.4.678.2/32"],
    "ports":["udp/8080"]
}

Response

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of firewall policy attributes.

Create Group

Creates a new group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}

Example

POST https://api.ctl.io/v2/groups/ALIAS/

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
name string Name of the group to create. Yes
description string User-defined description of this group No
parentGroupId string ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Yes
customFields complex Collection of custom field ID-value pairs to set for the server. No

CustomFields Definition

Name Type Description
id string ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value string Value to set the custom field to for this server.

Examples

JSON

{
  "name": "New Group",
  "description": "A new group.",
  "parentGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "customFields": [
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "value": "1100003"
    }
  ]
}

Response

Group Entity Definition

Name Type Description
id string ID of the group being queried
name string User-defined name of the group
description string User-defined description of this group
locationId string Data center location identifier
type string Group type which could include system types like "archive"
status string Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the group was created
createdBy string Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy string Who modified the group last

CustomFields Definition

Name Type Description
id string Unique ID of the custom field
name string Friendly name of the custom field
value string Underlying value of the field
displayValue string Shown value of the field

Examples

JSON

{
  "id": "56b789a2a72f43a98ae2227061e8f8f8",
  "name": "New Group",
  "description": "A new group.",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "groups": [
    {
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Parent Group Name",
      "description": "The parent group.",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities",
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/scheduledActivities"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "[email protected]",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "[email protected]"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Delete Group

Sends the delete operation to a given group and adds operation to queue. This operation will delete the group and all servers and groups underneath it. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a group and all objects underneath it.

URL

Structure

DELETE https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

DELETE https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupId string ID of the group to be deleted. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes

Response

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Get Group

Gets the details for a individual server group and any sub-groups and servers that it contains. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to identify the servers in a particular group, retrieve a group hierarchy, or get links to information (e.g. billing, monitoring, scheduled activities) about a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes

Response

Group Entity Definition

Name Type Description
id string ID of the group being queried
name string User-defined name of the group
description string User-defined description of this group
locationId string Data center location identifier
type string Group type which could include system types like "archive"
status string Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the group was created
createdBy string Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy string Who modified the group last

CustomFields Definition

Name Type Description
id string Unique ID of the custom field
name string Friendly name of the custom field
value string Underlying value of the field
displayValue string Shown value of the field

Examples

JSON

{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "name": "Web Applications",
  "description": "public facing web apps",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "serversCount": 2,
  "groups": [
    {
      "id": "31d13f501459411ba59304f3d47486eb",
      "name": "Training Environment",
      "description": "Temporary servers",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/231c3f3fec0e46499290b351199d555f",
          "id": "231c3f3fec0e46499290b351199d555f"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/8a03fcae8dd65411b05f00505682315a/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/31d13f501459411ba59304f3d47486eb/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/scheduledActivities"
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/540494152d0c4a9ab61869562b4c1471",
      "id": "540494152d0c4a9ab61869562b4c1471"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities"
    },
    {
      "rel": "server",
      "href": "/v2/servers/acct/wa1acctpre7101",
      "id": "WA1ACCTPRE7101"
    },
    {
      "rel": "server",
      "href": "/v2/servers/btdi/wa1acctpre7202",
      "id": "WA1ACCTPRE7202"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "[email protected]",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "[email protected]"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Get Group Billing Details

Gets the current and estimated charges for each server in a designated group hierarchy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out the charges associated with a specific group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/billing

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/billing

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal Yes

Response

Group Entity Definition

Name Type Description
date datetime Date that this billing information applies to
groups array List of groups (with the first being the queried group) in the requested hierarchy. Group ID listed before each group entity description

Groups Definition

Name Type Description
name string User-defined name of the group
servers array Collection of servers in this group, each with billing information. Server ID listed before each entity description

Servers Definition

Name Type Description
templateCost float Cost of templates stored in the group
archiveCost float Cost of archived servers in this group
monthlyEstimate float Projected charges for the servers given current usage
monthToDate float Charges up until the requested time
currentHour float Charges for the most recent hour

Examples

JSON

{
  "date": "2014-04-07T21:33:51.9743015Z",
  "groups": {
    "8c95fbaf74b7497fb671235aa318b44c": {
      "name": "Web Applications",
      "servers": {
        "wa1acctserv7101": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 77.76,
          "monthToDate": 17.93,
          "currentHour": 0.108
        },
        "wa1acctserv7202": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 156.96,
          "monthToDate": 36.19,
          "currentHour": 0.218
        }
      }
    },
    "4bca7bf6ead14cd59053e1eb1cd2d01f": {
      "name": "Training Environment",
      "servers": {}
    }
  }
}

Get Group Horizontal Autoscale Policy

Retrieves the details of a horizontal autoscale policy associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a horizontal autoscale policy associated to a Group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Yes

Response

Name Type Description
groupId string ID of the group
policyId string The unique identifier of the autoscale policy
locationId string Data center location identifier
name string Name of the Policy
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection string Direction to Scale (In or Out )
scaleResourceReason string Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex Information about the load balancer associated with the policy
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type Description
id string ID of the load balancer
name string Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP string The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "Up",
  "scaleResourceReason": "MinimumResourceCount",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 443,
    "privatePort": 300,
    "publicIP": "1.1.1.1",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "timestamp": "2015-10-20T21:20:02Z",
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/WHIM/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Get Group Monitoring Statistics

Gets the resource consumption details for whatever window specified in the request. Data can be retrieve for a variety of time windows and intervals. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to track the resource usage of servers within a group hierarchy. It can be used to populate a local data mart or chart the results on a dashboard.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/statistics?type=hourly&start={datetime}&end={datetime}&sampleInterval={dd:hh:mm:ss}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/statistics?type=hourly&start=2014-04-05T07:52:47.302Z&end=2014-04-07T07:52:47.302Z&sampleInterval=01:00:00

Request

URI and Querystring Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes
type string Valid values are latest, hourly, or realtime.

latest will return a single data point that reflects the last monitoring data collected. No start, end, or sampleInterval values are required for this type.

hourly returns data points for each sampleInterval value between the start and end times provided. The start and sampleInterval parameters are both required for this type.

realtime will return data from the last 4 hours, available in smaller increments. To use realtime type, start parameter must be within the last 4 hours. The start and sampleInterval parameters are both required for this type.
Yes
start datetime DateTime (UTC) of the query window. Note that statistics are only held for 14 days. Start date (and optional end date) must be within the past 14 days. Value is not required if choosing the latest query type. Yes, except for latest type
end datetime DateTime (UTC) of the query window. Default is the current time in UTC. End date (and start date) must be within the past 14 days. Not a required value if results should be up to the current time. No
sampleInterval timespan Result interval. For the default hourly type, the minimum value is 1 hour (01:00:00) and maximum is the full window size of 14 days. Note that interval must fit within start/end window, or you will get an exception that states: "The 'end' parameter must represent a time that occurs at least one 'sampleInterval' before 'start.'" If realtime type is specified, interval can be as small as 5 minutes (05:00). Yes, except for latest type

Response

Entity Definition

Name Type Description
name string Name of the server
stats array Collection of stats for the server for the interval chosen

Stats Definition

Name Type Description
timestamp datetime Timestamp of the monitoring results
cpu float CPU allocation during the interval
cpuPercent float CPU consumption (out of 100%) during the interval
memoryMB float Memory allocation during the interval
memoryPercent float Memory consumption (out of 100%) during the interval
networkReceivedKbps float Public network consumption in during the interval
networkTransmittedKbps float Public network consumption out during the interval
diskUsageTotalCapacityMB float Total disk allocation during the interval
diskUsage array List of physical disks attached to the virtual machine
guestDiskUsage array List of partitions used inside the guest OS

Disk Usage Definition

Name Type Description
id string Disk identifier
capacityMB integer Capacity (in MB) allocated for this disk

Guest Usage Definition

Name Type Description
path string Path of this partition
capacityMB integer Total capacity available to this partition
consumedMB integer Amount of capacity in use by this partition

Examples

JSON

(/v2/groups/ALIAS/GROUP/statistics?start=2014-04-09T20:00:00&sampleInterval=01:00:00)

[
  {
    "name": "wa1acctser7101",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 5.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 2.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      }
    ]
  },
  {
    "name": "wa1acctser7202",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.14,
        "memoryMB": 2048.0,
        "memoryPercent": 9.24,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.02,
        "memoryMB": 2048.0,
        "memoryPercent": 2.32,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      }
    ]
  }
]

Get Group Scheduled Activities

Gets the scheduled activities associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the scheduled activities for a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Yes

Response

Name Type Description
id string ID of the group
locationId string Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status string State of scheduled activity: on or off
type string Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUtc datetime Time when scheduled activity should start
repeat string How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire string When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUtc datetime When the scheduled activity should expire
timeZoneOffset string To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run

Examples

JSON

[
  {
    "id": "95715f96f8a145d68ace797fe542c9ae",
    "locationId": "WA1",
    "changeInfo": {
      "createdBy": "john.doe",
      "createdDate": "2015-03-16T18:12:02Z",
      "modifiedBy": "john.doe",
      "modifiedDate": "2015-10-20T22:20:25Z"
    },
    "links": [
      {
        "rel": "group",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8",
        "id": "fc06fd421e2ee41190460050568600e8",
        "name": "Default Group"
      },
      {
        "rel": "self",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/scheduledActivities/95715f96f8a145d68ace797fe542c9ae",
        "verbs": [
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    ],
    "status": "on",
    "type": "shutdown",
    "beginDateUTC": "2015-03-16T18:11:00Z",
    "repeat": "customWeekly",
    "customWeeklyDays": [
      "tue",
      "thu"
    ],
    "expire": "never",
    "timeZoneOffset": "-07:00:00",
    "isExpired": false,
    "occurrenceCount": 0,
    "nextOccurrenceDateUTC": "2015-10-22T18:11:00Z"
  }
]

Set Group Custom Fields

Changes the custom field values for an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupId string ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the group. In this case, the value must be "set" for setting the custom field values.
member string The property of the group to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the group. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Group call to see all the details of the group or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Defaults

Sets the defaults for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set defaults for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/defaults

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/defaults

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Yes

Content Properties

Name Type Description Req.
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers) No
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers) No
networkId string ID of the Network. This can be retrieved from the Get Network List API operation. No
primaryDns string Primary DNS to set on the server. If not supplied the default value set on the account will be used. No
secondaryDns string Secondary DNS to set on the server. If not supplied the default value set on the account will be used. No
templateName string Name of the template to use as the source. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.) No

Examples

JSON

{
  "cpu": "1",
  "memoryGB": "2",
  "networkId": "fb46f06f8278421d8e94d78cf6409ba5",
  "primaryDns": "8.8.8.8",
  "secondaryDns": "8.8.4.4",
  "templateName": "UBUNTU-10-64-TEMPLATE"
}

Response

Cpu Definition

Name Type Description
value int How many vCPUs are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Memory Definition

Name Type Description
value int How many GB of memory are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Network Definition

Name Type Description
value string ID of the Network
inherited bool Whether the value is set explicitly (false) or by its parent (true)

PrimaryDNS Definition

Name Type Description
value string Primary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

SecondaryDNS Definition

Name Type Description
value string Secondary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

TemplateName Definition

Name Type Description
value string ID Name of the default template
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Examples

JSON

{
  "cpu": {
    "value": 1,
    "inherited": false
  },
  "memoryGB": {
    "value": 2,
    "inherited": false
  },
  "networkId": {
    "value": "ee600a2b4b734aac8ab0de2642597433",
    "inherited": true
  },
  "primaryDns": {
    "value": "8.8.8.8",
    "inherited": false
  },
  "secondaryDns": {
    "value": "8.8.4.4",
    "inherited": false
  },
  "templateName": {
    "value": "UBUNTU-10-64-TEMPLATE",
    "inherited": false
  }
}

Set Group Horizontal Autoscale Policy

Applies a horizontal autoscale policy to a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to apply a horizontal autoscale policy to a group.

URL

Structure

PUT https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

PUT https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Yes

Content Properties

Name Type Description Req.
policyId string The unique identifier of the autoscale policy Yes
loadBalancerPool complex Information about the load balancer Yes

Load Balancer Pool

Name Type Description Req.
id string ID of the load balancer Yes
publicPort int Port configured on the public-facing side of the load balancer pool. Yes
privatePort int The internal (private) port of the node server Yes

Example

{
  "policyId" : "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "loadBalancerPool" :  
  {
    "id" : "bf82320cc96d42048fc7d5e41b0cdada",
    "privatePort" : 80,
    "publicPort" : 80
  }
}

Response

Name Type Description
groupId string ID of the group
policyId string The unique identifier of the autoscale policy
locationId string Data center location identifier
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection string Direction to Scale (In or Out )
scaleResourceReason string Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type Description
id string ID of the load balancer
name string Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP string The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Example

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "None",
  "scaleResourceReason": "Cpu",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 80,
    "privatePort": 80,
    "publicIP": "63.251.170.219",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Set Group Name/Description

Changes the name and description of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name or description of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupId string ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the group. In this case, the value must be "set" for setting the name and description.
member string The property of the group to perform the operation on. In this case, the value will be either "name" or "description".
value string The value to set for the given member. This is the name or description to set for the group.

Examples

JSON

[
   {
      "op":"set",
      "member":"name",
      "value":"New Name"
   },
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Parent

Changes the parent group of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the parent of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
GroupId string ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the group. In this case, the value must be "set" for setting the parent group.
member string The property of the group to perform the operation on. In this case, the value will be "parentGroupId".
value string The value to set for the given member. This is the group identifier for the new parent group.

Examples

JSON

[
   {
      "op":"set",
      "member":"parentGroupId",
      "value":"af7552c50e1b40b28d8023ed5eeaa74c"
   }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Scheduled Activities

Sets scheduled activities for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set scheduled activities for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI. Yes

Content Properties

Name Type Description Req.
status string State of scheduled activity: on or off Yes
type string Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown Yes
beginDateUTC datetime Time when scheduled activity should start Yes
repeat string How often to repeat: never, daily, weekly, monthly, customWeekly Yes
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat No
expire string When the scheduled activities are set to expire: never, afterDate, afterCount Yes
expireCount int Number of times scheduled activity should run before expiring No
expireDateUTC datetime When the scheduled activity should expire No
timeZoneOffset string To display in local time Yes

Examples

JSON

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:41:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "weekly",
  "expire": "never"
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:40:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "customWeekly",
  "expire": "never",
  "customWeeklyDays": [
    "mon",
    "wed",
    "fri"
  ]
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T21:27:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "daily",
  "expire": "afterCount",
  "expireCount": "10"
}

Response

Name Type Description
id string ID of the group
locationId string Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status string State of scheduled activity: on or off
type string Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUTC datetime Time when scheduled activity should start
repeat string How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire string When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUTC datetime When the scheduled activity should expire
timeZoneOffset string To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run
{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "locationId": "WA1",
  "changeInfo": {
    "createdBy": "[email protected]",
    "createdDate": "2015-11-23T21:17:16Z",
    "modifiedBy": "[email protected]",
    "modifiedDate": "2015-11-23T21:17:16Z"
  },
  "links": [
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Default Group Name"
    },
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/5b824632e319e411929e00505682315a/scheduledActivities/2a5c0b9662cf4fc8bf6180f139facdc0",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ],
  "status": "on",
  "type": "pause",
  "beginDateUTC": "2015-11-23T19:41:00Z",
  "repeat": "daily",
  "customWeeklyDays": [],
  "expire": "never",
  "timeZoneOffset": "-08:00:00",
  "isExpired": false,
  "occurrenceCount": 0,
  "nextOccurrenceDateUTC": "2015-11-24T19:41:00Z"
}

Archive Group

Sends the archive operation to a group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive an entire group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/archive

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/archive

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes
GroupID string ID of the group to archive. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the group will be archived as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Restore Group

Sends the restore operation to an archived group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore an archived group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/restore

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/restore

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes
GroupID string ID of the group to restore. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes

Content Properties

Name Type Description Req.
targetGroupId string The unique identifier of the target group to restore the group to. Yes

Response

Entity Definition

Name Type Description
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this group operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "isQueued":true,
  "links":[
    {
      "rel":"self",
      "href":"/v2/groups/bryf/2a5c0b9662cf4fc8bf6180f139facdc0?AccountAlias=ALIAS&identifier=2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel":"status",
      "href":"/v2/operations/bryf/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Configure Intrusion Protection Service Notifications

Configures notifications associated with an IPS agent running on a designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to configure the notifications of an installed IPS agent on CenturyLink Cloud servers.

The calls below will perform all of the operations for configuring, retrieving, updating, and deleting a notification destination.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

Create and Update

PUT https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Retrieve

GET https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Delete

DELETE https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Example

PUT https://api.client-security.ctl.io/ips/api/notifications/ALIAS/VA1ALIASTEST04

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverName string The name of the server that has the agent already installed Yes

Content Properties

Name Type Description Req.
notificationDestinations array List of Notification Destinations Yes

Notification Destination Definition

Name Type Description Req.
url string The URL endpoint for WEBHOOK or SLACK notification No
typeCode string This is the type of destination (either SYSLOG, EMAIL, or WEBHOOK) Yes
sysLogSettings array This contains all of the options for SYSLOG No
emailAddress string This object will contain options for an EMAIL notification No

SysLogSettings Definition

Name Type Description Req.
ipAddress string The IP address of customers syslog server Yes
udpPort integer The port the syslog is listening on Yes
facility integer This is an Integer, 16-23, to set the type of program logging messages. Yes

Example

PUT http://api.client-security.ctl.io/ips/api/notification/ALIAS/VA1ALIASMYSVR01

{
    "url": "http://my.slack.webhook",
    "typeCode": "SLACK"
},
{
    "url": "http://my.generic.webhook",
    "typeCode": "WEBHOOK"
},
{
    "typeCode": "SYSLOG",
    "sysLogSettings":
        {
            "ipAddress": "12345",
            "udpPort": "8081",
            "facility": "16"
        }
},
{
    "typeCode": "EMAIL",
    "emailAddress": "[email protected]"
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response. For details on what's included in each alert, please refer to this knowledge base article.

Install Intrusion Protection Service Agent

Installs an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to install an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

POST https://api.client-security.ctl.io/ips/api/app/

Example

POST https://api.client-security.ctl.io/ips/api/app/

Request

Content Properties

Name Type Description Req.
hostName string The name of the server that will ha Data center location of the anti-affinity policy. Yes
accountAlias string Short code for a particular account Yes

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the install of the agent.

Uninstall Intrusion Protection Service Agent

Uninstalls an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to uninstall an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

DELETE https://api.client-security.ctl.io/ips/api/app/

Example

DELETE https://api.client-security.ctl.io/ips/api/app/

Request

URI Parameters

Name Type Description Req.
hostName string The name of the server that is the target destination for the agent uninstall Yes
accountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
hostName string The name of the server that will ha Data center location of the anti-affinity policy. Yes
accountAlias string Short code for a particular account Yes

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the uninstall of the agent.

Claim Network

Claims a network for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to claim a network in a given data center you are able to access. Once you have a network, you can then perform various actions like getting IP addresses and updating its name.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/claim

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/claim

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Response [UPDATED JANUARY 19 2016]

Entity Definition

Name Type Description
operationId string Unique identifier for network claim operation
uri string URI to check status of operation

Examples

The initial response from the Claim Network API provides the unique identifier for the asynchronous operation to claim the network and a URI to check the status of that operation.

{
  "operationId": "c387aa9873ab4f7399ea8964dd61510d",
  "uri": "/v2-experimental/operations/{accountAlias}/status/{operationId}"
}

While the operation is executing, the response from the operation URI will provide a summary of the operation.

{
  "requestType": "blueprintOperation",
  "status": "running",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

When the operation completes successfully the response will provide a status property as "succeeded" and a link to the claimed network.

{
  "requestType": "blueprintOperation",
  "status": "succeeded",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}",
    "links": [
      {
        "rel": "network",
        "href": "/v2-experimental/networks/{accountAlias}/{locationAlias}/{networkId}",
        "id": "{networkId}"
      }
    ]
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

If the operation to claim a network were to fail, the response will come back with status "failed" along with the operation summary information.

{
  "requestType": "blueprintOperation",
  "status": "failed",
  "summary": {
    "blueprintId": 92123,
    "locationId": "{locationId}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:43:42Z"
  }
}

Create a Site to Site VPN

Creates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a Site to Site VPN for a given account.

URL

Structure

POST https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

POST https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

Request

URI Parameters

Name Type Description Req.
accountId string Short code for a particular account Yes

Content Properties

Name Type Description Req.
local string Local site properties Yes
remote string Remote site properties Yes
ike string IKE properties Yes
ipsec string IPSec properties Yes

Local Entity

Name Type Description Req.
locationAlias string Short code for a particular location Yes
subnets string Local address for Site to Site VPN, specified using CIDR notation Yes

Remote Entity

Name Type Description Req.
siteName string Friendly name of the site Yes
deviceType string Friendly name of the device type Yes
address string Remote address for Site to Site VPN, specified using CIDR notation Yes
subnets string Remote network address for Site to Site VPN, specified using CIDR notation Yes

IKE Entity

Name Type Description Option Req.
encryption string Encryption algorithm aes128, aes192, aes256, tripleDES Yes
hashing string Hashing algorithm sha1_96, sha1_256, md5 Yes
diffieHellmanGroup string Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5 Yes
preSharedKey string The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection Yes
lifetime string Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400 Yes
mode string Protocol mode main, aggressive Yes
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false No
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false No
remoteIdentity string The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address Yes

IPSec Entity

Name Type Description Option Req.
encryption string Encryption algorithm aes128, aes192, aes256, tripleDES Yes
hashing string Hashing algorithm sha1_96, sha1_256, md5 Yes
protocol string IPSec protocol esp, ah Yes
pfs string PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5 Yes
lifetime string Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400 Yes

Example

JSON

{
  "local": {
    "locationAlias": "WA1",                  
    "subnets": [                          
      "10.10.10.0/24"
    ]
  },
  "remote": {
    "siteName": "API test",                
    "deviceType": "SRX and stuff",        
    "address": "1.2.3.4",
    "subnets": [                          
      "10.1.1.0/24"
    ]
  },
  "ike": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "diffieHelmanGroup": "group2",        
    "preSharedKey": "Password123",
    "lifetime": 28800,                    
    "mode": "main",                       
    "deadPeerDetection": false,
    "natTraversal": false,
    "remoteIdentity": null                
  },
  "ipsec": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "protocol": "esp",                    
    "pfs": "group2",                      
    "lifetime": 3600                      
  }
}

Response

The response will be an entity representing the new Site to Site VPN that was created.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "pendingTaskId": "",
    "accountAlias": "ACCT",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "local": {
   "locationAlias": "WA1",               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "Password123",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "protocol": "esp",                    
   "pfs": "group2",                      
   "lifetime": 3600                      
 }
}

Delete a Site to Site VPN

Deletes a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a Site to Site VPN for a given account.

URL

Structure

DELETE https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

DELETE https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Request

URI Parameters

Name Type Description Req.
accountId string Short code for a particular account Yes
vpnId string ID of the VPN Yes

Response

The response will be the job ID in the Queue, for the Site to Site VPN that is to be deleted.

Example

JSON

"54851"

Get Details for a Site to Site VPN

Gets Details for a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get details for a Site to Site VPN for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Request

URI Parameters

Name Type Description Req.
accountId string Short code for a particular account Yes
vpnId string ID of the VPN Yes

Response

The response will be an entity representing the details for a Site to Site VPN for a given account.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
    "accountAlias": "ACCT",
    "local": {
        "address": "4.3.2.1",
        "locationAlias": "WA1",
        "locationDescription": "WA1 - US West (Seattle)",
        "subnets": [
            "10.10.10.0/24"
        ]
    },
    "remote": {
        "siteName": "Montreal Office",                
        "deviceType": "Cisco ASA5520 v8.3",
        "address": "1.2.3.4",
        "subnets": [
            "10.1.1.0/24"
        ]
    },
    "ike": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "diffieHellmanGroup": "group2",
        "lifetime": 28800,
        "mode": "main",
        "deadPeerDetection": false,
        "natTraversal": false,
        "remoteIdentity": null
    },
    "ipsec": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "protocol": "esp",
        "pfs": "group2",
        "lifetime": 3600
    },
    "links": [
        {
            "rel": "self",
            "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
        }
    ]
}

Get IP Address List

Gets the list of IP addresses for a network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of IP Addresses associated with a given network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/ipAddresses?type=claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses?type=claimed

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
Network string ID of the Network. These can be retrieved from the Get Network List API operation Yes
type string Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses) No

Response

Entity Definition

Name Type Description
address string An IP Address on the Network
claimed boolean Indicates claimed status of the address, either true or false
server string ID of the server associated with the IP address, if claimed
type string Indicates if the IP address is private, publicMapped, or virtual

Examples

JSON

[
    {
        "address": "11.22.33.12",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.13",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.14",
        "claimed": false,
        "type": "private"
    },
    {
        "address": "65.43.210.123",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "publicMapped"
    }
]

Get Network

Gets the details of a specific network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover properties of a network in a data center. You may optionally query details of IP Addresses on this network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}?ipAddresses=none|claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077?ipAddresses=claimed

Request

URI and Querystring Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
Network string ID of the Network. This can be retrieved from the Get Network List API operation. Yes
ipAddresses string Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "none" (returns details of the network only), "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses). Refer to Get IP Address List for the data shape of returned IP addresses. No

Response

Entity Definition

Name Type Description
id string ID of the network
cidr string The network address, specified using CIDR notation
description string Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway string Gateway IP address of the network
name string User-defined name of the network; the default is the VLAN number combined with the network address
netmask string A screen of numbers used for routing traffic within a subnet
type boolean Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

{
    "id": "ec6ff75a0ffd4504840dab343fe41077",
    "cidr": "11.22.33.0/24",
    "description": "vlan_9999_11.22.33",
    "gateway": "11.22.33.1",
    "name": "vlan_9999_11.22.33",
    "netmask": "255.255.255.0",
    "type": "private",
    "vlan": 9999,
    "ipAddresses": [
        {
            "address": "11.22.33.12",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "11.22.33.13",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "65.43.210.123",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "publicMapped"
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
            "verbs": [
                "GET",
                "PUT"
            ]
        },
        {
            "rel": "ipAddresses",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
            "verbs": [
                "GET"
            ]
        },
        {
            "rel": "release",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
            "verbs": [
                "POST"
            ]
        }
    ]
}

Get Network List

Gets the list of networks available for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available networks in a given data center you are able to access. Using that list of networks, you can then query for a specific network in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Response

Entity Definition

Name Type Description
id string ID of the network
cidr string The network address, specified using CIDR notation
description string Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway string Gateway IP address of the network
name string User-defined name of the network; the default is the VLAN number combined with the network address
netmask string A screen of numbers used for routing traffic within a subnet
type string Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

[
    {
        "id": "711725920a1f4002ac49e634e1789206",
        "cidr": "12.34.0.0/24",
        "description": "vlan_9998_12.34.0",
        "gateway": "12.34.0.1",
        "name": "vlan_9998_12.34.0",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9998,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    },
    {
        "id": "ec6ff75a0ffd4504840dab343fe41077",
        "cidr": "11.22.33.0/24",
        "description": "vlan_9999_11.22.33",
        "gateway": "11.22.33.1",
        "name": "vlan_9999_11.22.33",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9999,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    }
]

Get Site to Site VPNs

Gets all Site to Site VPNs for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get a list Site to Site VPNs for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

Request

URI Parameters

Name Type Description Req.
accountId string Short code for a particular account Yes

Response

The response will be an entity representing the Site to Site VPNs for a given account.

Example

JSON

[
    {
        "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
        "changeInfo": {
            "createdBy": "username",
            "createdDate": "2016-06-14T16:22:51Z",
            "modifiedBy": "username",
            "modifiedDate": "2016-06-14T17:53:12Z"
        },
        "accountAlias": "ACCT",
        "local": {
            "address": "4.3.2.1",
            "locationAlias": "WA1",
            "locationDescription": "WA1 - US West (Seattle)",
            "subnets": [
                "10.10.10.0/24"
            ]
        },
        "remote": {
            "siteName": "Montreal Office",                
            "deviceType": "Cisco ASA5520 v8.3",
            "address": "1.2.3.4",
            "subnets": [
                "10.1.1.0/24"
            ]
        },
        "ike": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "diffieHellmanGroup": "group2",
            "lifetime": 28800,
            "mode": "main",
            "deadPeerDetection": false,
            "natTraversal": false,
            "remoteIdentity": null
        },
        "ipsec": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "protocol": "esp",
            "pfs": "group2",
            "lifetime": 3600
        },
        "links": [
            {
                "rel": "self",
                "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
            }
        ]
    }
]

Release Network

Releases a network from a given account in a given data center to a pool for another user to claim. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you no longer need a network, and wish to to release it back a given data center. Before you can release a network, there must be no IP addresses claimed by servers.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/release

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
Network string ID of the Network. This can be retrieved from the Get Network List API operation Yes

Response

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful release of the network.

Update a Site to Site VPN

Updates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a Site to Site VPN for a given account.

URL

Structure

PUT https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

PUT https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

Request

URI Parameters

Name Type Description Req.
accountId string Short code for a particular account Yes
vpnId string ID of the VPN Yes

Content Properties

Name Type Description Req.
local string Local site properties No
remote string Remote site properties No
ike string IKE properties No
ipsec string IPSec properties No

Local Entity

Name Type Description Req.
subnets string Local address for Site to Site VPN, specified using CIDR notation No

Remote Entity

Name Type Description Req.
siteName string Friendly name of the site No
deviceType string Friendly name of the device type No
address string Remote address for Site to Site VPN, specified using CIDR notation No
subnets string Remote network address for Site to Site VPN, specified using CIDR notation No

IKE Entity

Name Type Description Option Req.
encryption string Encryption algorithm aes128, aes192, aes256, tripleDES No
hashing string Hashing algorithm sha1_96, sha1_256, md5 No
diffieHelmanGroup string Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5 No
preSharedKey string The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection No
lifetime string Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400 No
mode string Protocol mode main, aggressive No
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false No
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false No
remoteIdentity string The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address No

IPSec Entity

Name Type Description Option Req.
encryption string Encryption algorithm aes128, aes192, aes256, tripleDES No
hashing string Hashing algorithm sha1_96, sha1_256, md5 No
protocol string IPSec protocol esp, ah No
pfs string PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5 No
lifetime string Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400 No

Example

JSON

{
  "ike": {
    "preSharedKey": "321drowssaP"
  }
}

Response

The response will be an entity representing the Site to Site VPN that was updated.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "pendingTaskId": "54847",
 "accountAlias": "ACCT",
 "local": {
   "address": "4.3.2.1",
   "locationAlias": "WA1",
   "locationDescription": "WA1 - US West (Seattle)"               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "321drowssaP",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
     "encryption": "aes128",
     "hashing": "sha1_96",
     "protocol": "esp",
     "pfs": "group2",
     "lifetime": 3600
 },
 "links": [
     {
         "rel": "self",
         "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"                      
 }
}

Update Network

Updates the attributes of a given Network via PUT. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name and description of a network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}

Example

PUT https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077

Request

URI and Querystring Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation. Yes
Network string ID of the Network. These can be retrieved from the Get Network List API operation Yes

Content Properties

Name Type Description Req.
name string User-defined name of the network; the default is the VLAN number combined with the network address Yes
description string Description of VLAN, a free text field that defaults to the VLAN number combined with the network address No

Examples

JSON

{
    "name": "VLAN for Development Servers",
    "description": "Development Servers on 11.22.33.0/24"
}

Response

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of network attributes.

Applying Patches to Operating Systems

This service allows the user to patch virtual machines to the latest available patches provided by the OS vendor, using the Execute Package API. It does not discriminate patches based on patch severity or any other vendor categorization. The package will kick off one or multiple attempts to apply patches, including a series of reboots. Reboots will cease and the execution will complete when there are no more patches to apply. Additional information on this capability is in this knowledge base article.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to patch operating systems with updates from OS vendors.

NOTE: Servers require Internet access to be patched. It is also recommended to place servers in Maintenance Mode before patching. Further, an API request can deploy against all VMs a user is authorized to administer under a single alias.

Supported Operating Systems

Currently, the Operating Systems that may be updated with this service are show below:

  • CentOS 5
  • CentOS 6
  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Red Hat Enterprise Linux 7
  • Windows 2012
  • Windows 2012R2

Exceptions

  • Red Hat Enterprise Linux and CentOS: This service will exclude some updates. It will exclude kernel patches and nss packages.

Package Details

Operating Systems Blueprint Name Script Package Name Package ID
Windows 2012 and 2012R2 Auto Patching Windows 2012 Auto Patching Windows 2012 b229535c-a313-4a31-baf8-6aa71ff4b9ed
Red Hat Enterprise Linux 5, 6, and 7 OR CentOS 5 and 6 Yum Update Script Yum Update c3c6642e-24e1-4c37-b56a-1cf1476ee360

Example

JSON

{
    "servers": [
        "WA1ALIASSERV0101"
    ],
    "package": {
        "packageId": "c3c6642e-24e1-4c37-b56a-1cf1476ee360",
        "parameters": {"patch.debug.mode": "false"

        }
    }
}

Response

The response will be an array containing one entity for each server that the operation was performed on.

In addition, you will receive an email confirming that the patch was requested. A second email will be sent upon the successful application of the auto-patch capability.

Get a Summary of All Patches Deployed to a Server

This service shows a history of all the patches deployed to a given server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied to a server using the Patching-as-a-Service feature.

The response will contain a high-level overview of all the patches installed for each execution and when they were applied.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{accountAlias}/server/{serverID}/patch

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/ALIAS/server/WA1ALIASSERV0101/patch

Request

URI

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server Yes

Response

Name Type Description
execution_id string The execution ID associated with a particular patch
status string Either pending or completed
start_time date/Time Either the start time of the entire execution (which contains all initiations) or a particular initiation
end_time date/Time Either the end time of the entire execution (which contains all initiations) or a particular initiation
init_messages complex Shows the quantity of initiations
init_begin_message string "Invoking SUS API" or "Invoking yum check-update"
init_end_mesasge string identifies how many updates were installed and the URLS (for Windows) or names of the patches/updates

Get Details of Patches Applied to a Server During a Single Execution

This services returns details on all attempted patches for a single execution against a server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied for a given execution to a server using the Patching-as-a-Service feature.

The response will contain information from the vendor about the patch and the status of the attempt.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{alias}/server/{serverID}/patch/{execution_id}

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/OSD/server/VA1OSDPATCH33/patch/VA1-132457

Request

URI

Name Type Description
accountAlias string Short code for a particular account
serverID string ID of the server
execution_id string Correlation ID for all the patches included with a single update execution, obtained from the Patch Summary response or emails regarding a patch request. The execution ID format will be aa#-######

Response

Name Type Description
execution_id string The execution ID associated with a particular patch
status string Either pending or completed
start_time dateTime When this value is superior to patches, indicates the start time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the start time of the patch.
end_time dateTime When this value is superior to patches, indicates the end time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the end time of the patch.
duration string The minutes and seconds between the start and end time
begin_message string "Update Process BEGIN"
end_message string "Updating Complete"
patches Number Quantity of patches installed
patch_begin_message string Identifies the Software or OS updated and the reference number (if Windows, KB#######) for that particular update
patch_end_message string Result code established by Microsoft, defining the possible results of an install. These same codes will be used for other Operating Systems as well. https://msdn.microsoft.com/en-us/library/windows/desktop/aa387095(v=vs.85).aspx
status string Status of an individual patch, either pending, completed, or failed

Pause Server

Sends the pause operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to pause a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the pause command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/pause

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/pause

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform pause operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power Off Server

Sends the power off operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power off a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power off command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOff

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOff

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform power off operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power On Server

Sends the power on operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power on a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power on command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOn

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOn

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform power on operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
array complex Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reboot Server

Sends the reboot operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reboot a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reboot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reboot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reboot

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform reboot operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reset Server

Sends the reset operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reset a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reset command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reset

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reset

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform reset operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Set Maintenance Mode

Sends a specified setting for maintenance mode per server to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly turn on or off maintenance mode on multiple servers. Specifically, this call can be used if you want set some servers to have maintenance mode on and others to have it off. If you want to set maintenance mode for servers to all on or all off, you can use the respective methods for starting maintenance mode or stopping maintenance mode for multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/setMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/setMaintenance

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
servers array List of server ID and maintenance mode pairs to set. Yes

Servers Definition

Name Type Description
id string ID of server to set maintenance mode on or off
inMaintenanceMode boolean Indicator of whether to place server in maintenance mode or not

Examples

JSON

{
  "servers":[
    {
      "id": "wa1aliaswb01",
      "inMaintenanceMode": "true"
    },
    {
      "id": "wa1aliaswb02",
      "inMaintenanceMode": "false"
    }
  ]
}

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Shut Down Server

Sends the shut down operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to shut down a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the shut down command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/shutDown

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/shutDown

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform shut down operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Start Maintenance Mode

Sends a the start maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly start maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/startMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/startMaintenance

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to start maintenance mode on. Yes

Request Example

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Stop Maintenance Mode

Sends a the stop maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly stop maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/stopMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/stopMaintenance

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to stop maintenance mode on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Add Public IP Address

Claims a public IP address and associates it with a server, allowing access to it on a given set of protocols and ports. It may also be set to restrict access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a public IP address to an existing server. The public IP can be exposed on multiple protocols and ports and also be set to restrict access based on source IP ranges.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
internalIPAddress string The internal (private) IP address to map to the new public IP address. If not provided, one will be assigned for you. No
ports array The set of ports and protocols to allow access to for the new public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address claimed here. Yes
sourceRestrictions array The source IP address range allowed to access the new public IP address. Used to restrict access to only the specified range of source IPs. No

Ports Definition

Name Type Description
protocol string The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr string The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Get Public IP Address

Gets the details for the public IP address of a server, including the specific set of protocols and ports allowed and any source IP restrictions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out information about a specific public IP address for an existing server. This operation is linked to from the Get Server response that lists all public IPs assigned to a server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes
PublicIP string The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Yes

Response

Entity Definition

Name Type Description
internalIPAddress string The internal (private) IP address mapped to the public IP address.
ports array The set of accessible ports and protocols for the public IP address.
sourceRestrictions array The source IP address range allowed to access the new public IP address. Only traffic from this range will have access to the public IP on the specified ports.

Ports Definition

Name Type Description
protocol string The specific protocol to support for the given port(s). Should be either "tcp", "udp", or "icmp" (which is enabled by default).
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr string The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "internalIPAddress":"10.11.12.13",
  "ports":[
    {
      "protocol":"ICMP",
      "port":0
    },
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Remove Public IP Address

Releases the given public IP address of a server so that it is no longer associated with the server and available to be claimed again by another server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to stop using a specific public IP address on an existing server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes
PublicIP string The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Yes

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will no longer be associated with the server.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Update Public IP Address

Updates a public IP address on an existing server, allowing access to it on a given set of protocols and ports as well as restricting access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to update the ports and protocols or source IP restrictions for a public IP address on an existing server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

PUT https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes
PublicIP string The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server. Yes

Content Properties

Name Type Description Req.
ports array The set of ports and protocols to allow access to for the public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address specified here. Yes
sourceRestrictions array The source IP address range allowed to access the public IP address. Used to restrict access to only the specified range of source IPs. No

Ports Definition

Name Type Description
protocol string The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type Description
cidr string The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Get Status

Gets the status of a particular job in the queue, which keeps track of any long-running asynchronous requests (such as server power operations or provisioning tasks). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to check the status of a specific job in the queue. It is usually called after running a batch job and receiving the job identifier from the status link (e.g. Power On Server, Create Server, etc.) and will typically continue to get called until a "succeeded" or "failed" response is returned.

URL

Structure

GET https://api.ctl.io/v2/operations/{accountAlias}/status/{statusId}

Example

GET https://api.ctl.io/v2/operations/ALIAS/status/wa1-12345

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes
Status ID string ID of the job to query. Retrieved from the status link in the response to a batch job request. Yes

Response

Entity Definition

Name Type Description
Status string The status of the operation. Will be one of the following: "notStarted", "executing", "succeeded", "failed", "resumed" or "unknown".

Examples

JSON

{
  "status":"succeeded"
}

Getting Started

The Relational DataBase Services (RDBS) API focuses on manipulating Subscriptions to the RDBS service. A Subscription includes the backing database server(s), certificates, database backups, and notifications.

You can also view RDBS billing, action history, and promotions applied to your account.

The RDBS api is a satellite of the platform API and offered on a separate URL.

Base URL: https://api.rdbs.ctl.io/v1/

Create Subscription

Create a new subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new subscription.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
instanceType string One of MYSQL, MySQL_REPLICATION Yes
location string Datacenter id. Available datacenters are listed in Get Datacenters method Yes
externalId string The hostname part of the connection string Yes
machineConfig Object Server provisioning information for cpu, memory, and storage Yes
backupRetentionDays number Number of days to retain database backups Yes
destinations array Server capacity notification destinations No
users array Initial database user account. Yes
backupTime object Time of day to run backups (UTC) Yes

MachineConfig Definition

Name Type Description Req.
cpu number Number of CPUs to allocate to server Yes
memory number Amount of RAM to allocate to server (GB) Yes
storage number Amount of disk storage to allocate to server (GB) Yes

Destination Definition

Name Type Description Req.
destinationType string EMAIL Yes
location string Where to send notifications. For EMAIL, this is an email address. Yes
notifications array A list of notifications to receive. Yes

User Definition

Name Type Description Req.
name string User name. Yes
password string User password. The password must pass our minimum requirements: at least 9 characters and contain at least 3 of the following: uppercase letters, lowercase letters, numbers, symbols Yes

BackupTime Definition

Name Type Description Req.
hour number Hour of day to start backup (UTC). Yes
minute number Minute of minute to start backup (UTC). Yes

Example

{
  "instanceType": "MySQL",
  "location": "VA1",
  "externalId": "st-api-test",
  "machineConfig": {
    "cpu": 1,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 7,
  "destinations": [
    {
      "destinationType": "EMAIL",
      "location": "[email protected]",
      "notifications": [
        "CPU_UTILIZATION",
        "MEMORY_UTILIZATION"
      ]
    }
  ],
  "users": [
   {
     "name": "admin",
     "password": "AstrongPW!"
   }
  ],
  "backupTime": {
    "hour": 9,
    "minute": 15
  }
}

Response

Entity Definition

Name Type Description
id number Subscription id
location string Datacenter id
instanceType string Type of relational database.
externalId string External id used in connection strings, etc.
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown
backupTime string Scheduled backup time in "hour:minute"
backupRetentionDays string Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host string Host DNS name used in connection strings.
port string Host port used in connection strings.
certificate string TLS certificate used to secure subscription connections.

Server Entity Definition

Name Type Description
id number Server id
alias string Server alias (hostname)
location string Datacenter id where server is located
cpu number Number of CPUs allocated to the server
memory number Amount of RAM allocated to the server (GB)
storage number Amount of disk storage allocated to the server (GB)
attributes object Misc attributes for the server
connections number Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "9:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 1,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

Create Subscription Backup

Create a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to initiate a subscription backup. Backup creation is an asynchronous process; valid requests will be accepted and the create request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Create Subscription Backup Operation

Initiation a subscription backup's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a subscription's backup. You may restore a backup to the subscription it was created from, or to another subscription with equal or greater storage. Backup restore is an asynchronous process; valid requests will be accepted and the restore request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957/operations

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes
backupId number Backup id. Yes

Content Properties

Name Type Description Req.
type string 'restore' Yes
toSubscriptionId number The id of the subscription you want to restore this backup to. The target subscription may be any subscription in your account that has equal or greater storage. Yes

Create Subscription Notification

Create a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a subscription's notification. Subscriptions can be configured to notify users of high CPU or Storage use through Notifications. When a new notification is created, the recipient must validate their email through a url provided in a notification verification email before they begin to receive email notifications.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Content Properties

Name Type Description Req.
destinationType string EMAIL. Yes
recipient string Email address to send notificaitons to. Yes
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION. Yes

Response

Entity Definition

Name Type Description
id number Notification id.
destinationType string EMAIL
recipient string Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "[email protected]",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]

Create Subscription Notification Operation

Initiate a subscription notification's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to verify a subscription notification. You must provide the token sent in the notification verification email.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19/operations

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes
notificationId number Notification id. Yes

Content Properties

Name Type Description Req.
type string 'verify' Yes
token string Token included in the notification verification email. Yes

Create Subscription Operation

Initiate a subscription's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to failover a replicated subscription. Subscription failover is an asynchronous process; valid requests will be accepted and the failover request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/operations

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Content Properties

Name Type Description Req.
type string 'failover' Yes

Delete Subscription

Delete an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
subscriptionId number Subscription id Yes

Delete Subscription Backup

Delete a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription backup. Backup deletion is an asynchronous process; valid requests will be accepted and the delete request queued for further processing.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes
backupId number Backup id. Yes

Delete Subscription Notification

Delete a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription notification.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes
notificationId number Notification id. Yes

Get Billing

Returns current RDBS billing for an entire account or individual subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see current billing for the entire account or a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/billing?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/billing?subscriptionId=744

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Query Parameters

Name Type Description
subscriptionId number Subscription id to narrow billing focus to a single subscription. You can get a list of all subscriptions with Get Subscriptions API operation.

Response

Entity Definition

Name Type Description
productCode future future
metadata object future
monthlyEstimate string Estimate of monthly charge for this account or subscription.
monthToDate string Monthly charges to date for this account or subscription.
currentHour string Hourly charges for this account or subscription.

JSON

{
  "productCode": null,
  "metadata": {},
  "monthlyEstimate": "$446.83",
  "monthToDate": "$85.52",
  "currentHour": "$0.60"
}

Get Datacenters

Get a list of datacenters providing RDBS subscriptions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to identify datacenters that you may create subscriptions in. You will use the dataCenter response attribute in create subscription requests.

URL

Example

GET https://api.rdbs.ctl.io/v1/datacenters

Response

Entity Definition

Name Type Description
dataCenter string Short string representing the data center.
friendlyName string Name of the datacenter.
active boolean Is the datacenter accepting new subscriptions.

JSON

[
  {
    "dataCenter": "UC1",
    "friendlyName": "UC1 - US West (Santa Clara)",
    "active": true
  },
  {
    "dataCenter": "VA1",
    "friendlyName": "VA1 - US East (Sterling)",
    "active": true
  }
]

Get History

Returns an ordered history of actions performed on all account subscriptions, or a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see actions performed on all subscriptions on an account, or actions performed on a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/history?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/history
GET https://api.rdbs.ctl.io/v1/ALIAS/history?subscriptionId=744

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes

Query Parameters

Name Type Description
subscriptionId number Subscription id to narrow focus to a single subscription. Subscription Ids are listed in the Get Subscriptions API operation.

Response

Entity Definition

Name Type Description
timestamp number Unix style timestamp; milliseconds since epoch.
message string Summary message of form "subscription name: message".
details string Additional details, if available.
user string User initiating the action. An RDBS service account is listed when the action is provided by the service, like automated failover to replicated instances.

JSON

[
  {
    "timestamp": 1459878501968,
    "message": "demo-dev: created.",
    "details": "1 CPU, 1GB RAM, 1GB storage",
    "user": "user1"
  },
  {
    "timestamp": 1459878122697,
    "message": "poc1-test: deleted.",
    "details": null,
    "user": "user2"
  },
  {
    "timestamp": 1459455272384,
    "message": "config-db: failed over (automatic).",
    "details": "Primary server became active.",
    "user": "dbaas_service"
  },
  ...
]

Get Promotions

Returns all promotions applied to this account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all promotions applied to an account.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/promotions

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/promotions

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes

Response

Entity Definition

Name Type Description
code string Promotion code.

JSON

{
  "code": "PROMO_2016"
}

Get Subscription

Returns details of a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a single subscription's details.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Response

Entity Definition

Name Type Description
id number Subscription id.
location string Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType string Type of relational database.
externalId string External id used in connection strings, etc.
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime string Scheduled backup time in "hour:minute".
backupRetentionDays string Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host string Host DNS name used in connection strings.
port string Host port used in connection strings.
certificate string TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id number Server id.
alias string Server alias (hostname).
location string Datacenter id where server is located.
cpu number Number of CPUs allocated to the server.
memory number Amount of RAM allocated to the server (GB).
storage number Amount of disk storage allocated to the server (GB).
attributes object Misc attributes for the server.
connections number Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type Description
id number Backup id.
fileName string Backup file name.
backupTime number Unix timestamp of milliseconds since epoch.
backupType string One of Automated, Manual .
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size number Size of the compressed backup.

JSON

{
"id": 2957,
"location": "IL1",
"instanceType": "MySQL",
"externalId": "config-db",
"status": "Active",
"backupTime": "0:0",
"backupRetentionDays": 7,
"servers": [
  {
    "id": 2917,
    "alias": "IL1DBPDMYSQLXXXX",
    "location": "IL1",
    "cpu": 1,
    "memory": 1,
    "storage": 1,
    "attributes": {
      "INTERNAL_IP": "10.90.85.43"
    },
    "connections": 89
  }
],
"host": "config-db.il1.rdbs.ctl.io",
"port": 49929,
"certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
"backups": [
  {
    "id": 27538,
    "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
    "backupTime": 1459296004000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2841295
  },
  ...
}

Get Subscription Backups

Returns details of subscription backups. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's backups.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Response

Entity Definition

Name Type Description
id number Backup id.
fileName string Backup file name.
backupTime number Unix timestamp of milliseconds since epoch.
backupType string One of Automated, Manual .
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size number Size of the compressed backup.

JSON

[
  {
    "id": 2656,
    "fileName": "UC1DBDVMYSQL566-2016-04-06_23-00-01.tar.gz",
    "backupTime": 1459983603000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842348
  },
  {
    "id": 2674,
    "fileName": "UC1DBDVMYSQL566-2016-04-07_23-00-01.tar.gz",
    "backupTime": 1460070003000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842335
  },
  ...
}

Get Subscription Certificate

Returns the subscription TLS certificate as a stream. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to download a subscription certificate. Subscription certificates are included in the Get Subscription API operation; this API operation downloads the certificate as a file.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/certificate

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/certificate

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Response

Entity Definition

Name Type Description
N/A octet stream The certificate is returned as application/octet-stream with a default name of <subscription.externalId>.pem

Get Subscription Notifications

Returns all subscription notifications. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's notifications.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Response

Entity Definition

Name Type Description
id number Notification id.
destinationType string EMAIL
recipient string Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "[email protected]",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]

Get Subscriptions

Returns a list of all subscriptions and details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all subscriptions and their details. You can narrow focus to a single datacenter and/or subscription status.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions?dataCenter={dataCenterId}&status={status}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?staus=ACTIVE
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1&staus=PENDING

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes

Query Parameters

Name Type Description
dataCenter string Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation
status string One of: ACTIVE, BACKING_UP, CONFIGURING, DELETED, FAILED, PENDING, READY, RESTORING, SUCCESS, TERMINATED, UNKNOWN

Response

Entity Definition

Name Type Description
id number Subscription id.
location string Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType string Type of relational database.
externalId string External id used in connection strings, etc.
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime string Scheduled backup time in "hour:minute".
backupRetentionDays string Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host string Host DNS name used in connection strings.
port string Host port used in connection strings.
certificate string TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id number Server id.
alias string Server alias (hostname).
location string Datacenter id where server is located.
cpu number Number of CPUs allocated to the server.
memory number Amount of RAM allocated to the server (GB).
storage number Amount of disk storage allocated to the server (GB).
attributes object Misc attributes for the server.
connections number Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type Description
id number Backup id.
fileName string Backup file name.
backupTime number Unix timestamp of milliseconds since epoch.
backupType string One of Automated, Manual.
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size number Size of the compressed backup.

JSON

[
  {
    "id": 2957,
    "location": "IL1",
    "instanceType": "MySQL",
    "externalId": "config-db",
    "status": "Active",
    "backupTime": "0:0",
    "backupRetentionDays": 7,
    "servers": [
      {
        "id": 2917,
        "alias": "IL1DBPDMYSQLXXXX",
        "location": "IL1",
        "cpu": 1,
        "memory": 1,
        "storage": 1,
        "attributes": {
          "INTERNAL_IP": "10.90.85.43"
        },
        "connections": 89
      }
    ],
    "host": "config-db.il1.rdbs.ctl.io",
    "port": 49929,
    "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
    "backups": [
      {
        "id": 27538,
        "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
        "backupTime": 1459296004000,
        "backupType": "Automated",
        "status": "SUCCESS",
        "size": 2841295
      },
      ...
    ]
  },
  ...

Patch Subscription

Modify an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to resize a subscription server(s), change the number of days to keep backups, or the backup time.

NOTE: A subscription storage allocation cannot be reduced.

URL

Structure

PATCH https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

PATCH https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes

Content Properties

Name Type Description Req.
machineConfig Object Server provisioning information for cpu, memory, and storage. Yes
backupRetentionDays number Number of days to retain database backups. Yes
backupTime object Time of day to run backups (UTC). Yes

MachineConfig Definition

Name Type Description Req.
cpu number Number of CPUs to allocate to server. Yes
memory number Amount of RAM to allocate to server (GB). Yes
storage number Amount of disk storage to allocate to server (GB). Yes

BackupTime Definition

Name Type Description Req.
hour number Hour of day to start backup (UTC). Yes
minute number Minute of minute to start backup (UTC). Yes

Example

{
  "machineConfig": {
    "cpu": 2,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 6,
  "backupTime": {
    "hour": 1,
    "minute": 15
  }
}

Response

Entity Definition

Name Type Description
id number Subscription id.
location string Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType string Type of relational database.
externalId string External id used in connection strings, etc.
status string One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime string Scheduled backup time in "hour:minute".
backupRetentionDays string Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host string Host DNS name used in connection strings.
port string Host port used in connection strings.
certificate string TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type Description
id number Server id.
alias string Server alias (hostname).
location string Datacenter id where server is located.
cpu number Number of CPUs allocated to the server.
memory number Amount of RAM allocated to the server (GB).
storage number Amount of disk storage allocated to the server (GB).
attributes object Misc attributes for the server.
connections number Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "1:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 2,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

Update Subscription Notification

Update a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change a subscription notification.

URL

Structure

PUT https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

PUT https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account. Yes
subscriptionId number Subscription id. Yes
notificationId number Notification id. Yes

Content Properties

Name Type Description Req.
destinationType string EMAIL. Yes
recipient string Email address to send notificaitons to. Yes
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION. Yes

Response

Entity Definition

Name Type Description
id number Notification id.
destinationType string EMAIL
recipient string Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "[email protected]",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]

Get Server

Gets the details for a individual server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out all the details for a server. It can be used to look for changes, its status, or to retrieve links to associated resources.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Response

Server Entity Definition

Name Type Description
id string ID of the server being queried
name string Name of the server
displayName string Friendly display name for the server (can be the same as the name)
description string User-defined description of this server
groupId string ID of the parent group
isTemplate boolean Boolean indicating whether this is a custom template or running server
locationId string Data center that this server resides in
osType string Friendly name of the Operating System the server is running
isManagedOS boolean Describes whether the server is managed or not. Only appears when the server is managed.
isManagedBackup boolean Describes whether the server has Managed Backup or not. Only appears when the server has both Managed OS and Managed Backup.
status string Describes whether the server is active or not
details complex Resource allocations, alert policies, snapshots, and more.
type string Whether a standard or premium server
storageType string Whether it uses standard or premium storage
changeInfo complex Describes "created" and "modified" details
links array Collection of entity links that point to resources related to this server

Details Definition

Name Type Description
ipAddresses complex Details about IP addresses associated with the server
alertPolicies complex Describe each alert policy applied to the server
cpu integer How many vCPUs are allocated to the server
diskCount integer How many disks are attached to the server
hostName string Fully qualified name of the server
inMaintenanceMode boolean Indicator of whether server has been placed in maintenance mode
memoryMB integer How many MB of memory are allocated to the server
powerState string Whether the server is running or not
storageGB integer How many total GB of storage are allocated to the server
disks complex The disks attached to the server
partitions complex The partitions defined for the server
snapshots complex Details about any snapshot associated with the server
customFields complex Details about any custom fields and their values
processorDescription string Processor configuration description (for bare metal servers only)
storageDescription string Storage configuration description (for bare metal servers only)

IPAddresses Definition

Name Type Description
public string If applicable, the public IP
internal string Private IP address. If associated with a public IP address, then the "public" value is populated

AlertPolicies Definition

Name Type Description
id string Unique identifier of the policy
name string User-defined name of the alert policy
links array Collection of entity links that point to resources related to this policy

Disks Definition

Name Type Description
id string Unique identifier of the disk
sizeGB integer Size of the disk in GB
partitionPaths array List of partition paths on the disk

Partitions Definition

Name Type Description
sizeGB number Size of the partition in GB
path string File system location path of the partition

Snapshots Definition

Name Type Description
name string Timestamp of the snapshot
links array Collection of entity links that point to resources related to this snapshot

CustomFields Definition

Name Type Description
id string Unique ID of the custom field
name string Friendly name of the custom field
value string Underlying value of the field
displayValue string Shown value of the field

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the server was created
createdBy string Who created the server
modifiedDate dateTime Date/time that the server was last updated
modifiedBy string Who modified the server last

Examples

JSON

{
  "id": "WA1ALIASWB01",
  "name": "WA1ALIASWB01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.82.131.44"
      },
      {
        "public": "91.14.111.101",
        "internal": "10.82.131.45"
      }
    ],
    "alertPolicies": [
      {
        "id": "15836e6219e84ac736d01d4e571bb950",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/15836e6219e84ac736d01d4e571bb950"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/15836e6219e84ac736d01d4e571bb950",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      },
      {
        "id": "2bec81dd90aa4217887548c3c20d7421",
        "name": "Production Web Servers - Disk",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/2bec81dd90aa4217887548c3c20d7421"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/2bec81dd90aa4217887548c3c20d7421",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 2,
    "diskCount": 1,
    "hostName": "WA1ALIASWB01.customdomain.com",
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 60,
    "disks":[
      {
        "id":"0:0",
        "sizeGB":60,
        "partitionPaths":[]
      }
    ],
    "partitions":[
      {
        "sizeGB":59.654,
        "path":"C:\\"
      }
    ],
    "snapshots": [
      {
        "name": "2014-05-16.23:45:52",
        "links": [
          {
            "rel": "self",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "delete",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "restore",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40/restore"
          }
        ]
      }
    ],
    "customFields": [
      {
        "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": "58f83af6123846769ee6cb091ce3561e",
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "[email protected]",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "[email protected]"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/alias/WA1ALIASWB01",
      "id": "WA1ALIASWB01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/alias/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/alias",
      "id": "alias"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/alias/estimate-server/WA1ALIASWB01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/alias/WA1ALIASWB01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/alias/WA1ALIASWB01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/alias/WA1ALIASWB01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/alias/WA1ALIASWB01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses/91.14.111.101",
      "id": "91.14.111.101",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

Add Secondary Network

Adds a secondary network adapter to a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to add a secondary network adapter to a server. You will need a NetworkId to associate with the server. Users have the option to specify an IP address to assign to the server; otherwise the first available IP address in the network will be assigned. Up to four total network adapters can be attached to a server (i.e. a total of 3 secondary adapters). In addition, only one IP address per secondary network can be associated with a server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server Yes

Content Properties

Name Type Description Req.
networkId string ID of the network. These can be retrieved from the Get Network List API operation Yes
ipAddress string Optional IP address for the networkId No

Examples

JSON

{
      "networkId": "61a7e67908ce4bedabfdaf694a1360fe",
      "ipAddress": "123.456.1.1"
}

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be available on the server.

Entity Definition

Name Type Description
operationId string GUID for the item in the queue for completion
uri string Link to review status of the operation

Examples

JSON

  {
    "operationId": "2b70710dba4142dcaf3ab2de68e4f40c",
    "uri": "http://api.ctl.io/v2-experimental/operations/RSDA/status/2b70710dba4142dcaf3ab2de68e4f40c"
  }

Clone Server

Creates a new server as a clone of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

Request

The request parameters are the same as defined for Create Server with the addition of the sourceServerPassword parameter being required when cloning a server. Also, note that the sourceServerId parameter should be the name of the server that is being cloned rather than a template name.

Examples

JSON

{
  "name": "web",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "WA1ALIASWEB01",
  "sourceServerPassword": "[email protected]",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard"
}

Response

The response will be the same as specified in Create Server.

Create Server

Creates a new server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
name string Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-8 characters depending on the length of the account alias. The combination of account alias and server name here must be no more than 10 characters in length. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.) Yes
description string User-defined description of this server No
groupId string ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Yes
sourceServerId string ID of the server to use a source. May be the ID of a template, or when cloning, an existing server ID. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.) Yes
isManagedOS bool Whether to create the server as managed or not. Default is false. (Ignored for bare metal servers.) No
isManagedBackup bool Whether to add managed backup to the server. Must be a managed OS server. (Ignored for bare metal servers.) No
primaryDns string Primary DNS to set on the server. If not supplied the default value set on the account will be used. No
secondaryDns string Secondary DNS to set on the server. If not supplied the default value set on the account will be used. No
networkId string ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. No
ipAddress string IP address to assign to the server. If not provided, one will be assigned automatically. (Ignored for bare metal servers.) No
password string Password of administrator or root user on server. If not provided, one will be generated automatically. No
sourceServerPassword string Password of the source server, used only when creating a clone from an existing server. (Ignored for bare metal servers.) No
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers) Yes
cpuAutoscalePolicyId string ID of the vertical CPU Autoscale policy to associate the server with. Available IDs can be retrieved from the Get Autoscale Policies API operation. (Ignored for bare metal servers.) No
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers) Yes
type string Whether to create a standard, hyperscale, or bareMetal server Yes
antiAffinityPolicyId string ID of the Anti-Affinity policy to associate the server with. Only valid for hyperscale servers. Available IDs can be retrieved from the Get Anti-Affinity Policies API operation. No
customFields complex Collection of custom field ID-value pairs to set for the server. No
additionalDisks complex Collection of disk parameters (ignored for bare metal servers) No
ttl dateTime Date/time that the server should be deleted (ignored for bare metal servers) No
packages complex Collection of packages to run on the server after it has been built (ignored for bare metal servers) No
configurationId string Only required for bare metal servers. Specifies the identifier for the specific configuration type of bare metal server to deploy. A list of possible configs can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.) Yes
osType string Only required for bare metal servers. Specifies the OS to provision with the bare metal server. Currently, the only supported OS types are redHat6_64Bit, centOS6_64Bit, windows2012R2Standard_64Bit, windows2012R2Datacenter_64Bit, ubuntu14_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.) Yes

CustomFields Definition

Name Type Description
id string ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value string Value to set the custom field to for this server.

AdditionalDisks Definition

Name Type Description
path string File system path for disk (Windows drive letter or Linux mount point). Must not be one of reserved names.
sizeGB integer Amount in GB to allocate for disk, up to 1024 GB per.
type string Whether the disk should be raw or partitioned

Packages Definition

Name Type Description
packageId string ID of the package to run on the server after it builds. Available package IDs can be retrieved from the Get Packages API operation.
parameters complex Collection of name-value pairs to specify package-specific parameters.

Examples

JSON

{
  "name": "web",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "RHEL-6-64-TEMPLATE",
  "isManagedOS": false,
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "ipAddress": "10.123.456.12",
  "password": "[email protected]",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "additionalDisks":[
    {
      "path": "data",
      "sizeGB": 10,
      "type": "partitioned"
    }
  ],
  "ttl": "2014-12-17T01:17:17Z"
}

Response

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"web",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Delete Server

Sends the delete operation to a given server and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a server that is no longer being used.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTWB01

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server to be deleted. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Response

Entity Definition

Name Type Description
server string ID of the server that is being deleted.
isQueued boolean Boolean indicating whether the delete operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"wa1acctwb01",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Get Available Server Imports

Gets the list of available servers that can be imported. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the list of available OVFs that can be imported with the Import Server API. These OVFs are ones that have been uploaded to your FTP server as described in Using Self-Service VM Import.

URL

Structure

GET https://api.ctl.io/v2/vmImport/{accountAlias}/{locationId}/available

Example

GET https://api.ctl.io/v2/vmImport/ALIAS/WA1/available

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
LocationId string Data center location identifier Yes

Response

The response is an array of available servers for import. The list of available servers is dependent upon what OVFs have been uploaded to your FTP server as described in Using Self-Service VM Import.

Entity Definition

Name Type Description
id string ID of the OVF.
name string Name of the OVF.
storageSizeGB integer Number of GB of storage the server is configured with.
cpuCount integer Number of processors the server is configured with.
memorySizeMB integer Number of MB of memory the server is configured with.

Examples

JSON

[
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT",
    "name":"CUSTOM-OVF-IMPORT-RHEL-6-64",
    "storageSizeGB":16,
    "cpuCount":1,
    "memorySizeMB":1024
  },
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT-2",
    "name":"CUSTOM-OVF-IMPORT-2",
    "storageSizeGB":60,
    "cpuCount":2,
    "memorySizeMB":4096
  }
]

Get Server Credentials

Retrieves the administrator/root password on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the administrator/root password for an existing server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/credentials

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/credentials

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the credentials to return. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Response

Entity Definition

Name Type Description
userName string The username of root/administrator on the server. Typically "root" for Linux machines and "Administrator" for Windows.
password string The administrator/root password used to login.

Examples

JSON

{
  "userName":"root",
  "password":"[email protected]"
}

Import Server

Imports a new server from an uploaded OVF. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to import a new server from an OVF that has been uploaded to your FTP server. For more information about uploading an OVF for import, see Using Self-Service VM Import and make sure the OVF meets these requirements before attempting to import it.

URL

Structure

POST https://api.ctl.io/v2/vmImport/{accountAlias}

Example

POST https://api.ctl.io/v2/vmImport/ALIAS/

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
name string Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-7 characters depending on the length of the account alias. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.) Yes
description string User-defined description of this server No
groupId string ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal. Yes
primaryDns string Primary DNS to set on the server. If not supplied the default value set on the account will be used. No
secondaryDns string Secondary DNS to set on the server. If not supplied the default value set on the account will be used. No
networkId string ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. No
password string Password of administrator or root user on server. This password must match the one set on the server being imported or the import will fail. Yes
cpu integer Number of processors to configure the server with (1-16). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here. Yes
memoryGB integer Number of GB of memory to configure the server with (1-128). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here. Yes
type string Whether to create standard or hyperscale server Yes
customFields complex Collection of custom field ID-value pairs to set for the server. No
ovfId string The identifier of the OVF that defines the server to import. This can be retrieved from the Get Available Server Imports API operation.
ovfOsType string The OS type of the server being imported. Currently, the only supported OS types are redHat6_64Bit, windows2008R2DataCenter_64bit, and windows2012R2DataCenter_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Deployment Capabilities API operation.

CustomFields Definition

Name Type Description
id string ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value string Value to set the custom field to for this server.

Examples

JSON

{
  "name": "import",
  "description": "Custom Import Server",
  "groupId": "3d30a6bc6b5443388b7bc966d073e353",
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "password": "[email protected]",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "ovfId": "ALIAS/CUSTOM-OVF-IMPORT",
  "ovfOsType": "redHat6_64Bit"
}

Response

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"import",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Remove Secondary Network

Removes a secondary network adapter from a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to remove a secondary network adapter from a server. You will need a NetworkId to de-associate with the server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks/{networkId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks/f49875b17cee4b8c99bf1ab75aa286d6

Request

URI Properties

Name Type Description Req.
accountAlias string Short code for a particular account Yes
serverId string ID of the server Yes
networkId string ID of the network. These can be retrieved from the Get Network List API operation Yes

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be removed from the server.

Entity Definition

Name Type Description
operationId string GUID for the item in the queue for completion
uri string Link to review status of the operation

Examples

JSON

  {
    "operationId": "6c8d7b5349054fe6a532539ff066b53b",
    "uri": "http://api.ctl.io/v2-experimental/operations/ALIAS/status/6c8d7b5349054fe6a532539ff066b53b"
  }

Set Server CPU/Memory

Changes the amount of CPU cores and memory (in GB) on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the number of CPU cores or the amount of memory for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the CPU or memory configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the server. In this case, the value must be "set" for setting the CPU or memory amount.
member string The property of the server to perform the operation on. In this case, the value will be either "cpu" or "memory".
value integer The integer value to set for the given member. For CPU this represents the number of cores; for memory it is in GB.

Examples

JSON

[
   {
      "op":"set",
      "member":"cpu",
      "value":"4"
   },
   {
      "op":"set",
      "member":"memory",
      "value":"8"
   }
]

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Credentials

Changes the administrator/root password on an existing server given the current administrator/root password. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the administrator/root password on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the credentials to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the server. In this case, the value must be "set" for setting the credentials.
member string The property of the server to perform the operation on. In this case, the value must be "password" for setting the credentials.
value complex The current and new administrator/root password values.

Value Definition

Name Type Description
current string The current administrator/root password used to login.
password string The new administrator/root password to change to.

Examples

JSON

[
   {
      "op":"set",
      "member":"password",
      "value":
      {
         "current":"[email protected]",
         "password":"[email protected]"
      }
   }
]

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the password will be changed as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Custom Fields

Changes the custom field values for an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the server. In this case, the value must be "set" for setting the custom field values.
member string The property of the server to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the server. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Server call to see all the details of the server or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Description/Group

Changes the description and parent group of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the description or the parent group of a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the server. In this case, the value must be "set" for setting the description and parent group.
member string The property of the server to perform the operation on. In this case, the value will be either "description" or "groupId".
value string The value to set for the given member. This is either the description of the server to set, or the unique identifier of the group to set as the parent.

Examples

JSON

[
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   },
   {
      "op":"set",
      "member":"groupId",
      "value":"2a5c0b9662cf4fc8bf6180f139facdc0"
   }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Disks

Changes (adds or removes) disks on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the disks on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the disk configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server. Yes

PatchOperation Definition

Name Type Description
op string The operation to perform on a given property of the server. In this case, the value must be "set" for setting the disk configuration.
member string The property of the server to perform the operation on. In this case, the value must be "disks" for setting the disks.
value array A list of information for all disks to be on the server including type (raw or partition), size, and path.

Note: You must specify the complete list of disks to be on the server. If you want to add or resize a disk, specify all existing disks/sizes along with a new entry for the disk to add or the new size of an existing disk. To delete a disk, just specify all the disks that should remain. (You can get existing disk info by using the Get Server call to see all the details of the server.)

Examples

JSON

[
   {
      "op":"set",
      "member":"disks",
      "value":[
         {
           "diskId":"0:0",
           "sizeGB":1
           "type":"raw"
         },
         {
           "diskId":"0:1",
           "sizeGB":2
           "type":"raw"
         },
         {
           "diskId":"0:2",
           "sizeGB":16
           "type":"raw"
         },
         {
           "path":"/extra",
           "sizeGB":"20",
           "type":"partitioned"
         }
      ]  
   }
]

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Archive Server

Sends the archive operation to a list of servers and adds operation to queue. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the archive command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/archive

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/archive

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
serverIds array List of server IDs to perform archive operation on. Yes

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Create Snapshot

Sends the create snapshot operation to a list of servers (along with the number of days to keep the snapshot for) and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a snapshot of a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the create snapshot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/createSnapshot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/createSnapshot

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
snapshotExpirationDays integer Number of days to keep the snapshot for (must be between 1 and 10). Yes
serverIds array List of server names to perform create snapshot operation on. Yes

Examples

JSON

{
  "snapshotExpirationDays":"7",
  "serverIds":[
      "WA1ALIASWB01",
      "WA1ALIASWB02"
    ]
}

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Delete Snapshot

Deletes a given server snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing server snapshot.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the snapshot to delete. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes
SnapshotId string ID of the snapshot to delete. Retrieved from the links in the snapshots section of the Get Server response.

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Execute Package

Executes a single package on one or more servers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to execute a Blueprint package that is available from within a given account on one or more servers. The list of available packages can be retrieved from the Get Packages API operation.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/executePackage

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/executePackage

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Content Properties

Name Type Description Req.
servers array List of server IDs to run the package on. Yes
package complex The package entity describing which package to run on the specified servers. Yes

Package Definition

Name Type Description
packageId string Unique identifier of the package to execute.
parameters complex Set of key-value pairs for setting the package-specific parameters defined.

Examples

JSON

{
    "servers": [
        "wa1aliaswb01"
    ],
    "package": {
        "packageId": "86567681-c79c-1234-a530-850708435c23",
        "parameters": {
            "AB.HelloWorld.Variable": "someValue"
        }
    }
}

Response

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type Description
server string ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage string If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  }
]

Restore Server

Restores a given archived server to a specified group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a server that has been archived.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/restore

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/restore

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the archived server to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes

Content Properties

Name Type Description Req.
targetGroupId string The unique identifier of the target group to restore the server to. Yes

Examples

JSON

{
  "targetGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0"
}

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server will be restored as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Revert to Snapshot

Reverts a server to a snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to revert a server to the state it was in when the given snapshot was taken.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}/restore

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10/restore

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server with the snapshot to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal. Yes
SnapshotId string ID of the snapshot to restore. Retrieved from the links in the snapshots section of the Get Server response.

Response

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value Description
rel string status The link type
href string /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id string [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Shared Load Balancers Overview

Load Balancer

A shared load balancer is made up of a VIP (virtual IP) and a set of servers grouped by pools (i.e. access ports). The load balancer entity is merely a named container with an IP address that can further be configured to include multiple pools of servers behind the same IP.

Load Balancer Pool

Within a shared load balancer definition, multiple pools can be configured. Each pool defines the port that will respond to and redirect traffic to the server nodes in the pool. The pool is also where the load balancing method and persistence types are set.

The method can either be set to "round robin" or "least connection." For the round robin option, the load balancer cycles through a list of all the servers bound to it. It does not take into account server workload or latency and simply distributes traffic evenly across servers. The least connection option routes traffic to the server with the fewest active connections. An "active" connection is considered one where the HTTP request has not yet received a response. This is considered the best performing of the two algorithms.

The persistence type can be either "standard" or "sticky." The standard option employs no persistence and is best for stateless web applications. If an application does require server-based state, then choose the sticky option. The sticky choice uses source IP + destination IP address-based persistence to tie users to the target server.

If you choose round robin or least connection along with standard persistence, then requests are routed without any concern for where the last user's request came from. If you choose round robin or least connection along with sticky persistence, then the FIRST request will be routed based on either round robin or least connection, and each subsequent request from that source IP address will return to the server that responded to the initial request.

Load Balancer Node

For each pool, one or more nodes are configured corresponding to a server that is included in the load balancing pool. The node definition includes the server's private IP address and the port that is serving the content.

Create Load Balancer Pool

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancers in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes

Content Properties

Name Type Description Req.
port integer Port to configure on the public-facing side of the load balancer pool. Must be either 80 (HTTP) or 443 (HTTPS). Yes
method string The balancing method for this load balancer, either leastConnection or roundRobin. Default is roundRobin. See Shared Load Balancer Overview for more information about these options. No
persistence string The persistence method for this load balancer, either standard or sticky. Default is standard. See Shared Load Balancer Overview for more information about these options. No

Examples

JSON

{
    "port": 80,
    "method": "leastConnection",
  "persistence": "sticky"
}

Response

The response will be an entity representing the new load balancer pool that was created.

Entity Definition

Name Type Description
id string ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Empty array since no nodes will be configured yet for the new pool
links array Collection of entity links that point to resources related to this load balancer pool

Examples

JSON

{
  "id" : "40150dde098640e8b993de0e7417afc4",
  "port" : 80,
  "method" : "leastConnection",
  "persistence" : "sticky",
  "nodes" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Create Shared Load Balancer

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancer in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Content Properties

Name Type Description Req.
name string Friendly name for new the load balancer Yes
description string Description for new the load balancer Yes
status string Status to create the load balancer with: enabled or disabled No

Examples

JSON

{
    "name":"New Load Balancer",
    "description":"A brand new load balancer"
}

Response

The response will be an entity representing the new load balancer that was created.

Entity Definition

Name Type Description
id string ID of the load balancer
name string Friendly name of the load balancer
description string Description for the load balancer
ipAddress string The external (public) IP address of the load balancer
status string Status of the load balancer: enabled, disabled or deleted
pools array Empty array since no pools will be configured yet for the new shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Examples

JSON

{
  "id" : "6b66b474fce940b8b581242709b5b2f0",
  "name" : "New Load Balancer",
  "description" : "A brand new load balancer",
  "ipAddress" : "98.76.54.32",
  "status" : "enabled",
  "pools" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ],
}

Delete Load Balancer Pool

Deletes a given pool of a shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific pool from a given load balancer.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer with the pool to delete. Yes
PoolId string ID of the pool to delete. Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Delete Shared Load Balancer

Deletes a given shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific load balancer within a given account and data center.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer to delete. Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Get Load Balancer Nodes

Gets the list of nodes configured behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of nodes configured behind a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes
PoolId string ID of the pool containing the nodes Yes

Response

Entity Definition

The response will be an array containing one entity for each node configured.

Name Type Description
status string Status of the node: enabled, disabled or deleted.
ipAddress string The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.13",
    "privatePort" : 80
  },
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.14",
    "privatePort" : 80
  }
]

Get Load Balancer Pool

Gets a specified pool configured for the given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the details for a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes
PoolId string ID of the pool Yes

Response

Entity Definition

Name Type Description
id string ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
name string Name of the node (generally the IP address)
status string Status of the node: enabled, disabled or deleted.
ipAddress string The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "2fa937bd20dd47c9b856376e9499c0c1",
  "port" : 80,
  "method" : "roundRobin",
  "persistence" : "standard",
  "nodes" : [
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.13",
      "privatePort" : 80,
      "name" : "10.11.12.13"
    },
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.14",
      "privatePort" : 80,
      "name" : "10.11.12.14"
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Get Load Balancer Pools

Gets the list of pools configured for a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of pools configured for a given shared load balancer.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes

Response

Entity Definition

The response will be an array containing one entity for each pool configured on the given load balancer.

Name Type Description
id string ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
name string Name of the node (generally the IP address)
status string Status of the node: enabled, disabled or deleted.
ipAddress string The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "2fa937bd20dd47c9b856376e9499c0c1",
    "port" : 80,
    "method" : "roundRobin",
    "persistence" : "standard",
    "nodes" : [
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.13",
        "privatePort" : 80,
        "name" : "10.11.12.13"
      },
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.14",
        "privatePort" : 80,
        "name" : "10.11.12.14"
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "nodes",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
        "verbs" : [
          "GET",
          "PUT"
        ]
      }
    ]
  }
]

Get Shared Load Balancer

Gets the specified shared load balancer for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a specific shared load balancer configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes

Response

Entity Definition

Name Type Description
id string ID of the load balancer
name string Friendly name of the load balancer
description string Description for the load balancer
ipAddress string The external (public) IP address of the load balancer
status string Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type Description
id string ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
name string Name of the node (generally the IP address)
status string Status of the node: enabled, disabled or deleted.
ipAddress string The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "ae3bbac5d9694c70ad7de062476ccb70",
  "name" : "My Load Balancer",
  "description" : "My Load Balancer",
  "ipAddress" : "12.34.56.78",
  "status" : "disabled",
  "pools" : [
    {
      "id" : "2fa937bd20dd47c9b856376e9499c0c1",
      "port" : 80,
      "method" : "roundRobin",
      "persistence" : "standard",
      "nodes" : [
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.13",
          "privatePort" : 80,
          "name" : "10.11.12.13"
        },
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.14",
          "privatePort" : 80,
          "name" : "10.11.12.14"
        }
      ],
      "links" : [
        {
          "rel" : "self",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
          "verbs" : [
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel" : "nodes",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
          "verbs" : [
            "GET",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ]
}

Get Shared Load Balancers

Gets the list of shared load balancers that exist for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the list of shared load balancers configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes

Response

The response will be an array containing one entity for each load balancer in the given account and data center.

Entity Definition

Name Type Description
id string ID of the load balancer
name string Friendly name of the load balancer
description string Description for the load balancer
ipAddress string The external (public) IP address of the load balancer
status string Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type Description
id string ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type Description
name string Name of the node (generally the IP address)
status string Status of the node: enabled, disabled or deleted.
ipAddress string The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "ae3bbac5d9694c70ad7de062476ccb70",
    "name" : "My Load Balancer",
    "description" : "My Load Balancer",
    "ipAddress" : "12.34.56.78",
    "status" : "disabled",
    "pools" : [
      {
        "id" : "2fa937bd20dd47c9b856376e9499c0c1",
        "port" : 80,
        "method" : "roundRobin",
        "persistence" : "standard",
        "nodes" : [
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.13",
            "privatePort" : 80,
            "name" : "10.11.12.13"
          },
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.14",
            "privatePort" : 80,
            "name" : "10.11.12.14"
          }
        ],
        "links" : [
          {
            "rel" : "self",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
            "verbs" : [
              "GET",
              "PUT",
              "DELETE"
            ]
          },
          {
            "rel" : "nodes",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
            "verbs" : [
              "GET",
              "PUT"
            ]
          }
        ]
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "pools",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
        "verbs" : [
          "GET",
          "POST"
        ]
      }
    ]
  }
]

Update Load Balancer Nodes

Updates the nodes behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the list of nodes in a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes
PoolId string ID of the pool to update Yes

Content Properties

The body of the request is an array of node entities.

Name Type Description Req.
status string Status of the node: enabled, disabled or deleted. No
ipAddress string The internal (private) IP address of the node server Yes
privatePort integer The internal (private) port of the node server. Must be a value between 1 and 65535. Yes

Examples

JSON

[
  {
    "ipAddress" : "10.11.12.18",
    "privatePort" : 8080
  },
  {
    "ipAddress" : "10.11.12.19",
    "privatePort" : 8080
  }
]

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the list of load balancer nodes.

Update Load Balancer Pool

Updates a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the port, method, or persistence options for a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer Yes
PoolId string ID of the pool to update Yes

Content Properties

Name Type Description Req.
method string The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options. No
persistence string The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options. No

Examples

JSON

{
    "method": "roundRobin",
  "persistence": "standard"
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer pool.

Update Shared Load Balancer

Updates a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name, description, or status of a given shared load balancer.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
DataCenter string Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation. Yes
LoadBalancerId string ID of the load balancer to update Yes

Content Properties

Name Type Description Req.
name string Friendly name for new the load balancer Yes
description string Description for new the load balancer Yes
status string Status to create the load balancer with: enabled or disabled No

Examples

JSON

{
    "name":"Updated Load Balancer",
    "description":"An updated load balancer"
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer.

Create Policy

Creates a new backup policy associated with the account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a brand new backup policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Request

Content Properties

Name Type Description Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours Yes
clcAccountAlias string The account alias that the Policy belongs to No
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup Yes (May be null)
name string The name of the Policy Yes
osType string 'Linux' or 'Windows' Yes
paths Array[string] A list of the directories that the Policy includes in each backup Yes
retentionDays integer The number of days backup data will be retained Yes

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "paths": [
    "/opt"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12
}

Response

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy
clcAccountAlias string The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
name string The name of the Policy
osType string 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId string The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/opt"
  ],
  "excludedDirectoryPaths": [],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Create Server Policies

Create multiple Server Policies under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

Note that the endpoint for this operation is the same as the standard Create Server Policy API, but an additonal header (Bulk-Operation: true) is required, and both the request and response bodies will be different than the single policy create.

When to Use It

Use this API operation when you want to create multiple Server Policies.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/193fccfc-c144-4052-98da-145eed825e0a/serverPolicies

Request

URI Parameters

Name Type Description Req.
accountPolicyId string The unique Id of an account policy Yes

Headers

Name Type Description Req.
Bulk-Operation boolean Must be set to "true" for the multi-server-policy API Yes

Content Properties

Name Type Description Req.
serverId string Unique server name Yes
storageRegion string Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC" Yes

Examples

JSON

[{
  "serverId": "UC1BAADTEST01",
  "storageRegion": "US WEST"
 },{
  "serverId": "IL1BAADTEST01",
  "storageRegion": "US WEST"
}]

Response

Response List Definition

Name Type Description
status string Aggregate status for entire server policy creation request. 'SUCCESS', 'PARTIAL', 'FAILED'
success boolean Indicates if server policy creation was successful
error string Provides details for server policy creation failure related to system or infrastructure
validationMessages string Provides details for server policy creation failure related to parameter restrictions

Server Policy Definition

Name Type Description
serverPolicyId string Unique Id of the Server Policy
accountPolicyId string Unique Id of the Account Policy
serverId string Unique server name
storageRegion string Region where backups are stored
clcAccountAlias string The account alias that the Policy belongs to
status string The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
 "status": "PARTIAL",
 "createServerPolicyResponseList": [
  {
  "success": false,
  "error": "Failed to get server information for serverId=UC1BAADTEST01",
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": null,
    "accountPolicyId": null,
    "serverId": "UC1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": null,
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  },
  {
  "success": true,
  "error": null,
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": "80448207-332c-4f95-b82b-ac1fcb87b2c6",
    "accountPolicyId": "193fccfc-c144-4052-98da-145eed825e0a",
    "serverId": "IL1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": "PROVISIONING",
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  }
 ]
}

Create Server Policy

Create a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new Server Policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

Request

URI Parameters

Name Type Description Req.
accountPolicyId string The unique Id of an account policy Yes

Content Properties

Name Type Description Req.
clcAccountAlias string The account alias that the Policy belongs to Yes
serverId string Unique server name Yes
storageRegion string Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC" Yes

Examples

JSON

{
  "clcAccountAlias": "BAAD",
  "serverId": "VA1BAADTEST01",
  "storageRegion": "USEAST",
}

Response

Entity Definition

Name Type Description
serverPolicyId string Unique Id of the Server Policy
accountPolicyId string Unique Id of the Account Policy
serverId string Unique server name
storageRegion string Region where backups are stored
clcAccountAlias string The account alias that the Policy belongs to
status string The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
"serverPolicyId": "085384ce-200e-4205-8a13-ae1d0bdc71cd"
"accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
"serverId": "VA1BAADTEST01"
"storageRegion": "US EAST"
"clcAccountAlias": "BAAD"
"status": "PROVISIONING"
"expirationDate": 0
"unsubscribedDate": 0
"storageAccountId": null
}

Delete Server Policy

Delete a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing Server Policy.

URL

Structure

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies/085384ce-200e-4205-8a13-ae1d0bdc71cd

Request

URI Parameters

Name Type Description Req.
serverPolicyId string Unique Id of the Server Policy Yes
accountPolicyId string Unique Id of the Account Policy Yes

Response

The response will not contain JSON content, but will return the HTTP 204 No Content response upon successful deletion of the server policy. If an invalid account policy or server policy are passed in, a HTTP 404 Not Found response will be returned.

Get All Policies Eligible For ServerId

Returns a list of the backup policies that are eligible to be applied to the specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of policies that may be applied to a given server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/{serverId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/VA1ACMEDEMO01

Request

URI Parameters

Name Type Description Req.
serverId string Unique server name Yes

QueryString Parameters

Name Type Description Req.
limit integer Return up to this many results No
offset string Return results starting from this position in the list No
sortBy string Sort the results by the specified field No
ascendingSort boolean Sort the sortBy field in ascending order No

Response

Entity Definition

Name Type Description
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies eligible for the specified server
totalCount integer The total number of Policies eligible for the specified server

Account Policy Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy
clcAccountAlias string The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
name string The name of the Policy
osType string 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId string The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 1",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 2",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/opt"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 7,
      "backupIntervalHours": 12,
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get All Regions

Retrieves a list of backup storage regions which are available in Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of backup storage regions which are available in Simple Backup Service.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/regions

Example

GET https://api.backup.ctl.io/clc-backup-api/api/regions

Response

Entity Definition

Name Type Description
messages Array[string] A list of messages associated with the Storage Region
name string The name of the Storage Region
regionLabel string The label associated with the Storage Region

Examples

JSON

[
  {
    "name": "APAC",
    "regionLabel": "APAC (Singapore)",
    "messages": null
  },
  {
    "name": "GERMANY",
    "regionLabel": "EU (Germany)",
    "messages": null
  },
  {
    "name": "GREAT BRITAIN",
    "regionLabel": "EU (Ireland)",
    "messages": null
  },
  {
    "name": "US EAST",
    "regionLabel": "US East",
    "messages": null
  },
  {
    "name": "US WEST",
    "regionLabel": "US West",
    "messages": null
  },
  {
    "name": "CANADA",
    "regionLabel": "Canada",
    "messages": [
      "Backups stored in this region are NOT encrypted at rest"
    ]
  }
]

Get Datacenter List

Get a list of CLC Data Centers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of CLC Data Centers.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

Response

Entity Definition

Name Type Description
datacenters Array[string] Array of string values corresponding to each datacenter

Examples

JSON

{
  [13]
  0:  "CA1 - Canada (Vancouver)"
  1:  "CA2 - Canada (Toronto)"
  2:  "CA3 - Canada (Toronto)"
  3:  "DE1 - Germany (Frankfurt)"
  4:  "GB1 - Great Britain (Portsmouth)"
  5:  "GB3 - Great Britain (Slough)"
  6:  "IL1 - US Central (Chicago)"
  7:  "NY1 - US East (New York)"
  8:  "SG1 - APAC (Singapore)"
  9:  "UC1 - US West (Santa Clara)"
  10:  "UT1 - US Central (Salt Lake City)"
  11:  "VA1 - US East (Sterling)"
  12:  "WA1 - US West (Seattle)"
}

Get OS Types

Returns the list of valid OS types supported by Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of supported OS types.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

Example

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

Response

Entity Definition

Name Type Description
osTypes Array[string] Array of string values corresponding to each supported OS type

Examples

JSON

[
  "Linux",
  "Windows]
]

Get Policies

Gets a list of backup policies associated with an account. Calls to this operation must include a bearer token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of all policies associated with a given account.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies?limit=20&offset=0&withStatus=ACTIVE&sortBy=name&ascendingSort=true

Request

QueryString Parameters

Name Type Description Req.
limit integer Return up to this many results No
offset string Return results starting from this position in the list No
withStatus string Filter results for either 'ACTIVE' or 'INACTIVE' Policies No
sortBy string Sort the results by the specified field No
ascendingSort boolean Sort the sortBy field in ascending order No

Response

Entity Definition

Name Type Description
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies associated with the Account
totalCount integer The total number of Policies associated with the Account

Account Policy Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy
clcAccountAlias string The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
name string The name of the Policy
osType string 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId string The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Windows",
      "name": "Example Windows Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "C:\\backupthisup"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 1,
      "backupIntervalHours": 24,
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get Policy

Gets the backup policy associated with the specified accountPolicyId. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the details of a specific backup policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/4ca70660-f08a-407b-830d-e8e9c6c1d59a

Request

URI Parameters

Name Type Description Req.
accountPolicyId string The unique id associated with the backup policy to retrieve Yes

Response

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy
clcAccountAlias string The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
name string The name of the Policy
osType string 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId string The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var"
  ],
  "excludedDirectoryPaths": [
    "/var/run"
  ],
  "retentionDays": 5,
  "backupIntervalHours": 36,
  "policyId": "4ca70660-f08a-407b-830d-e8e9c6c1d59a"
}

Get Policy Details By Server

Get policy details by server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of policies and policy details for all policies associated with a specified server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails?serverId=VA1BAAPPRDTST01

Request

QueryString Parameters

Name Type Description Req.
serverId string Unique server name Yes
withStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED' No

Response

Entity Definition

Name Type Description
accountPolicyId string Unique ID of an account policy
osType string 'Linux' or 'Windows'
name string The name of the Policy
clcAccountAlias string The account alias that the Policy belongs to
accountPolicyStatus string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'
paths Array[string] A list of the directories that the Policy includes in each backup
backupProvider string Not currently used
retentionDays integer The number of days backup data will be retained
backupIntervalHours integer The backup frequency of the Policy specified in hours
serverPolicyId string Unique server policy identifier
serverId string Unique server identifier
storageRegion string Region where backups are stored. "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC"
serverPolicyStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED'
eligibleForBackup boolean Indicates if the account policy or server policy are active/inactive

Examples

JSON

{
  [2]
  0:  {
  "accountPolicyId": "5323900d-1288-47c8-9cce-e29790c9afbb"
  "osType": "Windows"
  "name": "TestingPolicy_1/12/16"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [2]
  0:  "C:\BackupFolder1"
  1:  "C:\BackupFolder12"
  -
  "backupProvider": null
  "retentionDays": 2
  "backupIntervalHours": 22
  "serverPolicyId": "6d05d351-9cb8-4fed-bca6-064e3034caeb"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "CANADA"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }-
  1:  {
  "accountPolicyId": "16965823-5472-49c1-a38a-727dca9cb7a0"
  "osType": "Windows"
  "name": "C Drive"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [1]
  0:  "C:\"
  -
  "backupProvider": null
  "retentionDays": 21
  "backupIntervalHours": 2
  "serverPolicyId": "f37088d7-22ba-4704-ba61-25ecd2e8a086"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "US EAST"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }
}

Get Restore Point Details

Gets a list of restore point details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to obtain restore point details for a specific serverPolicyId.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/restorePointDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/restorePointDetails?backupFinishedStartDate=2016-01-01&backupFinishedEndDate=2016-04-01

Request

URI Parameters

Name Type Description Req.
serverPolicyId string Unique Id of the Server Policy Yes
accountPolicyId string Unique Id of the Account Policy Yes

QueryString Parameters

Name Type Description Req.
limit integer Limit the number of records returned No
offset integer No
inRetentionOnly boolean No
backupFinishedStartDate string Valid date format is 'YYYY-MM-DD' Yes
backupFinishedEndDate string Valid date format is 'YYYY-MM-DD' Yes
sortBy string Sort results by: [policyId, retentionDay, backupStartedDate, backupFinishedDate, retentionExpiredDate, backupStatus, filesTransferredToStorage, bytesTransferredToStorage, filesFailedTransferToStorage, bytesFailedToTransfer, unchangedFilesNotTransferred, unchangedBytesNotTransferred, filesRemovedFromDisk, bytesRemovedFromDisk] No
ascendingSort boolean No

Response

Entity Definition

Name Type Description
restorePointId string Unique restore point identifier
policyId string Unique policy identifier
retentionDays integer Days of retention applied to the restore point
backupFinishedDate string Timestamp of backup completion
retentionExpiredDate string Timestamp or retention expiration
restorePointCreationStatus string 'SUCCESS', 'PARTIAL_SUCCESS', 'FAILED', or 'CANCELLED'
filesTransferredToStorage integer Number of backup files transferred to storage
bytesTransferredToStorage integer Total bytes of backup data sent to storage
filesFailedTransferToStorage integer Number of backup files that failed transfer to storage
bytesFailedToTransfer integer Total bytes of backup data that failed transfer to storage
unchangedFilesNotTransferred integer Number of unchanged files not requiring retransfer to storage
unchangedBytesInStorage integer Total bytes of unchanged data not requiring retransfer to storage
filesRemovedFromDisk integer Number of files removed from local disk
bytesInStorageForItemsRemoved integer Total bytes of data removed from local disk
numberOfProtectedFiles integer Number of files currently in storage for the restore point
backupStartedDate string Timestamp of backup start

Examples

JSON

{
  "limit": 100
  "offset": 0
  "nextOffset": 0
  "results": [2]
    0:  {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401225505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T22:55:10.849Z"
        "retentionExpiredDate": "2016-04-07T22:55:05.277Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T22:55:05.277Z"
  }
  -1:   {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401214505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T21:45:10.802Z"
        "retentionExpiredDate": "2016-04-07T21:45:05.261Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T21:45:05.261Z"
  }
  "totalCount": 2
}

Get Server Policies

Gets a list of Server Policies associated to an Account Policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of all Server Policies attached to an Account Policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

Request

URI Parameters

Name Type Description Req.
accountPolicyId string Unique Id of the Account Policy Yes

QueryString Parameters

Name Type Description Req.
accountPolicyId string Unique ID of an account policy Yes
limit integer Return up to this many results No
offset string Return results starting from this position in the list No
withStatus string Filter results for either 'ACTIVE' or 'INACTIVE' Policies No
sortBy string Sort the results by the specified field No
ascendingSort boolean Sort the sortBy field in ascending order No

Response

Entity Definition

Name Type Description
limit integer The maximum number of results requested
offset integer The starting position in the list of results
nextOffset integer The next position in the list of results for a subsequent call
results Array[Server Policy] An array of the Server Policies associated with the Account Policy
totalCount integer The total number of Server Policies associated with the Account Policy

Server Policy Definition

Name Type Description
serverPolicyId string The next position in the list of results for a subsequent call
accountPolicyId string Unique Id of the Account Policy
serverId string Unique server name
storageRegion string Region where backups are stored
clcAccountAlias string The account alias that the Policy belongs to
status string The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId string Not currently used

Examples

JSON

  {
  "limit": 1000
  "offset": 0
  "nextOffset": 0
  "results": [1]
      0:  {
          "serverPolicyId": "7796a750-db6a-4d6d-a9c0-93f729e9977e"
          "accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
          "serverId": "VA1BAADTEST01"
          "storageRegion": "US EAST"
          "clcAccountAlias": "BAAD"
          "status": "ACTIVE"
          "expirationDate": 0
          "unsubscribedDate": 0
          "storageAccountId": "f5c2c756-94b6-4b74-92e9-60f648caed15"
          }
  "totalCount": 1
  }

Get Server Policy

Get details of a specific server policy associated to an account policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get details for a specific server policy. Use the getServerPolicies API to obtain details for all server policies associated with an account policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

Request

URI Parameters

Name Type Description Req.
accountPolicyId string Unique ID of an account policy Yes
serverPolicyId string Unique Id of the Server Policy Yes

Response

Entity Definition

Name Type Description
serverPolicyId string Unique Id of the Server Policy
accountPolicyId string Unique Id of the Account Policy
serverId string Unique server name
storageRegion string Region where backups are stored
clcAccountAlias string The account alias that the Policy belongs to
status string The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED', 'PENDING_INSTALL'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId string Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Get Servers By Datacenter

Get a list of servers based on CLC Data Center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of servers associated with a CLC Data Center.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api//api/datacenters/{datacenter}/servers

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters/VA1%20-%20US%20East%20(Sterling)/servers

Request

URI Parameters

Name Type Description Req.
datacenter string CLC Data Center Yes

Response

Entity Definition

Name Type Description
list Array[string] Array of string values corresponding to each server

Examples

JSON

{
  [3]
  0:  "VA1BAAPXAMPLE01"
  1:  "VA1BAAPXAMPLE02"
  2:  "VA1BAAPXAMPLE03"
}

Get Stored Data By Server Policy

Gets the amount of stored data for a server policy on a specified date. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to determine the amount of backed up data in storage for a server on a specific day.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/storedData

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/storedData?searchDate=2016-03-29

Request

URI Parameters

Name Type Description Req.
accountPolicyId string Unique account policy identifier Yes
serverPolicyId string Unique server policy identifier Yes

QueryString Parameters

Name Type Description Req.
searchDate string Valid date format is 'YYYY-MM-DD' Yes

Response

Entity Definition

Name Type Description
gigabytesStored string Amount of stored backup data in gigabytes
bytesStored string Amount of stored backup data in bytes

Examples

JSON

{
  "gigabytesStored": "0.541"
  "bytesStored": "581560320"
}

Patch Policy

Updates specific values of a server policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Because of the business rules that apply to this product, there are limited scenarios when this operation is allowed. Specifically, you may use this API operation when you want to change the status of a server policy from 'ERROR', 'PENDING_INSTALL', or 'PROVISIONING' to 'INACTIVE'. Other attempts to modify the server policy will result in errors.

URL

Structure

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

Request

URI Parameters

Name Type Description Req.
accountPolicyId string Unique ID of an account policy Yes
serverPolicyId string Unique Id of the Server Policy Yes

Content Properties

Name Type Description Req.
op string The patch operation to perform: 'add', 'remove', 'replace' Yes
path string The only change allowed currently is to the status. Valid transitions are: ERROR to INACTIVE, PENDING_INSTALL to INACTIVE, and PROVISIONING to INACTIVE Yes
value string The new value to set path to. Yes

Examples

JSON

{
  "op": "replace",
  "path": "/status",
  "value": "INACTIVE"
}

Response

Entity Definition

Name Type Description
serverPolicyId string Unique Id of the Server Policy
accountPolicyId string Unique Id of the Account Policy
serverId string Unique server name
storageRegion string Region where backups are stored
clcAccountAlias string The account alias that the Policy belongs to
status string The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId string Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Update Policy

Updates a backup policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the settings of a backup policy. It can be used to modify the name, frequency, paths to include, and paths to exclude. Operating System and Retention may not be modified.

URL

Structure

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/107e6129-46b6-4b01-afcc-ea733db37214

Request

URI Parameters

Name Type Description Req.
accountPolicyId string The unique id associated with the backup policy to update Yes

Content Properties

Name Type Description Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours Yes
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup Yes
name string The name of the Policy Yes
osType string 'Linux' or 'Windows' Yes
paths Array[string] A list of the directories that the Policy includes in each backup Yes
policyId string The unique Id associated with the Policy Yes
retentionDays integer The number of days backup data will be retained Yes
status string 'ACTIVE' or 'INACTIVE' Yes

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Response

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy
clcAccountAlias string The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
name string The name of the Policy
osType string 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId string The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status string The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Webhooks FAQ

Description

The CenturyLink Cloud supports Webhooks which send push notifications to an HTTP endpoint specified by the customer. This FAQ addresses commonly asked questions about the service. For a walkthrough of how to use Webhooks, see Configuring Webhooks and Consuming Notifications.

Q: What exactly is a Webhook?

A: Webhooks make it possible to create push notification solutions. Platform events (e.g. "server created") are sent in real-time to a web endpoint configured for the Webhook. Whenever an event occurs, a JSON message is sent as an HTTP POST request.

Q: Did CenturyLink Cloud invent the idea of Webhooks?

A: No, but we're among the first to use it in an IaaS cloud. Webhooks are in use today for a variety of web properties including Wordpress, Trello, and Zoho. CenturyLink Cloud sees value in embracing this model for public cloud customers who want to be more responsive to changes in their cloud account.

Q: In what scenario would I use a Webhook?

A: We've identified numerous use cases where Webhooks can replace or augment the components of existing processes:

  • Replace polling-based synchronization solutions. Customers often use request-response API operations to retrieve data about their assets in the CenturyLink Cloud. However, polling is fairly inefficient as the caller is simply asking "Do you have anything for me?" over and over again. With Webhooks, there's no longer a need to poll for changes. Instead, the CenturyLink Cloud immediately tells customers whenever key events occur in the platform.
  • Perform real-time data analytics. Customers can use this data to assess their cloud usage. For resellers, Webhooks provide an opportunity to observe server provisioning and detect trends. They could use it to watch for fraudulent signup scenarios my detecting abnormal combinations of account creation and server provisioning.
  • Monitor activities with security, compliance implications. For customers who closely govern their cloud usage, Webhooks provide the opportunity to immediately see what users are doing. Whether adding public IP addresses, or creating new user accounts, customers can quickly monitor and respond to activities that are counter to company policies.

Q: What triggers a Webhook?

A: There are currently Webhooks for four major categories: Accounts, Users, Alerts, and Servers.

  • Accounts. Triggered on account creation and deletion. Triggered on account changes including account status, business name, address, telephone, fax, and time zone.
  • Users. Triggered on user creation and deletion. Triggered on user changes including user status, password, security PIN, email address, alternative email address, first name, last name, title, office number, mobile number, fax number, time zone.
  • Alerts. Triggered when a user-defined alert policy threshold is exceeded, and when the server returns to a utilization level below the alert policy threshold.
  • Servers. Triggered on server creation and deletion. Triggered on server changes including server archive, server restore, convert to template, convert from template, add/delete/edit disks, edit CPU, edit memory, assigned Group, description, add/remove IP addresses, power on/off, and shutdown.

Q: What data is sent in the Webhook event notification?

A: Some push notification systems only send a bare minimum of information and ask the user to call-back for the full data payload. CenturyLink Cloud Webhooks send a full JSON-encoded payload AND include a URL to the referenced resource.

The Account event payload:

{
  "addressLine1": "112 112th Ave NE",
  "addressLine2": "Ste 300",
  "city": "Bellevue",
  "stateProvince": "WA",
  "country": "USA",
  "postalCode": "98004",
  "telephone": "800-buy-cloud",
  "status": "Active",
  "isManaged": true,
  "links": [
    {
      "rel": "self",
      "href": "/v2/accounts/DEMO"
    },
    {
      "rel": "parentAccount",
      "href": "/v2/accounts/T3N"
    }
  ],
  "accountAlias": "DEMO",
  "businessName": "Seroter Industries",
  "parentAlias": "T3N",
  "primaryDataCenter": "WA1"
}

The User event payload:

{
  "uri": "[email protected]",
  "accountUri": "/v2/accounts/DEMO",
  "accountAlias": "DEMO",
  "userName": "[email protected]",
  "emailAddress": "[email protected]",
  "firstName": "Richard",
  "lastName": "Seroter",
  "status": "Active"
}

The Server event payload:

{
  "id": "WA1DEMOSERVER01",
  "name": "WA1DEMOSERVER01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.81.123.11"
      },
      {
        "public": "74.41.155.112",
        "internal": "10.81.123.14"
      }
    ],
    "alertPolicies": [
      {
        "id": "45866e6219e84ab786d07d4f570ba960",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/DEMO/45866e6219e84ab786d07d4f570ba960"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies/45866e6219e84ab786d07d4f570ba960",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 1,
    "diskCount": 1,
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 50,
    "disks": [
      {
        "id": "0:0",
        "sizeGB": 50,
        "partitionPaths": []
      }
    ],
    "partitions": [],
    "snapshots": [],
    "customFields": [
      {
        "id": 22,
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": 237,
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdBy": "[email protected]",
    "createdDate": "2012-12-17T01:17:17Z",
    "modifiedBy": "[email protected]",
    "modifiedDate": "2014-06-18T18:28:54Z"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01",
      "id": "WA1DEMOSERVER01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/DEMO/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/DEMO",
      "id": "demo"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/DEMO/serverPricing/WA1DEMOSERVER01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses/74.41.155.112",
      "id": "74.41.155.112",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

*Note that server delete events will only contain the accountAlias and name fields as the server has been deleted and any other information is no longer available.

The Alert event payload:

{
  "accountAlias": "DEMO",
  "serverName": "WA1DEMOSERVER01",
  "triggers": [
    {
      "data": {
        "cpu": 2,
        "cpuPercent": 39.34
      },
      "duration": "00:05:00",
      "metric": "cpu",
      "stateEndTime": "2014-06-18T18:23:46Z",
      "stateStartTime": "2014-06-18T18:20:00Z",
      "state": "notTriggered"
    }
  ]
}

Q: Where do I go to set a Webhook?

A: Webhooks are available at the Account-level under the API menu. There is now a sub-menu called "Webhooks." Customers can set a target URL for each Webhook event listed. Webhooks Configuration

Q: Can notifications be sent for events that occur within sub-accounts?

A: Yes. For each individual Webhook event, customers can specify whether they want sub-account events to ALSO be sent to the designated endpoint. If a parent account has the "include sub-accounts" checkbox selected, and a sub-account has specified their own Webhook endpoint for the same event, then a copy of the event notification is sent to both endpoints

Q: Are there any requirements for the service that receives the Webhook notification?

A: All Webhook listener services must support secure HTTP transport via HTTPS. The data transmitted in the event may be sensitive and shouldn't travel over unprotected channels. Secondly, listener services must be on the public internet in a location reachable by the CenturyLink CLoud platform. If a customer plans on consuming this data within an internal system, consider using a reverse proxy or another mechanism to forward traffic from a public-facing web service to an internal system.

Q: How can listener services be sure that it was CenturyLink Cloud that sent the message and not someone spoofing you?

A: While SSL ensures that the message cannot be read in transit, it doesn't protect you from rogue callers who target your public endpoint. Each Webhook notification includes a signature hash of the message payload. The Tier3-RsaSha1 header is signed with our private key, leveraging the JSON payload as input. This signature can be verified with the following public key and the received JSON body. Customers can use this process to ensure that the message wasn't tampered with. For more details and sample code on how to verify the signature, see Configuring Webhooks and Consuming Notifications.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnmwsVLJ22Y8lmnk+1fI/
JKkm4bM1GvggI7DN10KIoPDgBbNcePZqcFayDdmVuq/jL9MFBrqFSfVszgdq8OWF
G9lEB5vP29K/N+0kRg5V2NDXddI5AOzx6jDjkNM/jjb45UXeDcPzMMdMOl/ds6uT
p6mbfG3U8dWqM/if7mzjEbbhYkBM3OuacEFk38Tkm49IJ4jHnC0p9qWO2iaxJqRc
08M2cJ+yKcFudCVKX8ANE6g6YKK+5aSabxfHX83Vjr4I0kpqo0cfP4aSW/CPDUZ7
yR4bFiy5Wv2de2V+FOGVBQF+/viSzrtrwQjUOJViuxEnifc06xuDF0QFta9anz4d
LQIDAQAB
-----END PUBLIC KEY-----

Q: How soon after an event occurs does a Webhook notification get sent?

A: As soon as the event occurs in the CenturyLink Cloud platform, it is routed through our messaging infrastructure and sent to each Webhook endpoint. In reality, this means that messages are often received within 5 seconds of the event occurring.

Q: What happens if the destination is unreachable?

A: There is no guaranteed delivery with CenturyLink Cloud Webhooks. We make a single attempt to send a message to the designated endpoint and if it fails, it is not retried. This means two things: (1) design your endpoints to be highly available and withstand failures of any single component in the solution, and (2) rely on a combination of Webhooks and daily web service API calls to ensure that your local repositories stay in sync.

Q: Are there more Webhooks on the way?

A: Yes! We have ideas for additional Webhooks to add to the platform, but would like to hear from you. If you have suggestions for other Webhooks, send an email to [email protected].

Add Webhook Target Uri

Add a target uri to the webhook for a specified event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a uri to the collection of targetUris in a webhook.

URL

Structure

POST https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris

Example

POST https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris

Request

Uri Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
Event string The name of the webhook event being configured Yes

Content Properties

Name Type Description Req.
targetUri string A uri that will be called when the event occurs Yes

Examples

JSON

{ targetUri: "https://test.api/account/created" }

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Configuring Webhooks and Consuming Notifications

Description

Webhooks make it possible to subscribe to key events that occur in the CenturyLink Cloud. In this article, we will walk through how to create a Webhook listener, configure a Webhook, and receive a notification. For general details on Webhooks, read the Webhook FAQ.

Prerequisites

  • Must have a CenturyLink Cloud account
  • Must be able to deploy applications to an internet-facing location that has legitimate SSL certificates

Detailed Steps

Build the Webhook Listener

A Webhook listener is simply a web application that can receive a JSON message via HTTP POST. A working example application written in Node.js can be downloaded from GitHub. When designing a Webhook listener, consider the following activities:

  1. Decide what events to subscribe to. Webhooks support Account, Alert, User, and Server events.
  2. Process HTTP POST requests. In the example Node.js application, this is done in the app.js file.
app.post('/webhook/account', function(req, res){

  //extract the signature header
  var signatureHeader = req.get('Tier3-RsaSha1');

  //call function to send webhook data to client browser
  BroadcastAccountWebhook(req.body, signatureHeader);

  //send OK response to CenturyLink Cloud
  res.send("ok");

})
  1. Handle the payload for each message type. In the example project, this is done in a client-side JavaScript file and the entire payload is shown to the user. A listener application that uses typed object definitions must be able to deserialize the JSON structures. Examples of each payload type can be found in the Webhooks FAQ.

Deploy the Webhook Listener

  1. Webhooks must be deployed to an internet-facing location that is reachable by the CenturyLink Cloud platform.

  2. Identify a host (public cloud IaaS, public cloud PaaS, or on-premises data center) with a valid (not self-signed) SSL certificate.

  3. Deploy the application and ensure that it's reachable. For this demonstration, the listener was deployed to a non-CenturyLink Cloud public Cloud Foundry environment hosted by Pivotal. Webhooks Example Application

Configure a Webhook in the CenturyLink Cloud

  1. Go to the CenturyLink Control Portal, log in, and select the API option from the navigation menu. Control Portal Menu - API

  2. Switch to the Webhooks sub-tab and review the list of available Webhooks. You can configure unique endpoints for each individual Webhook. In the image below, notice that the Account.Updated Webhook was set with the URL to the listener web application. A Webhook will respond to events that occur in sub-accounts if the "include sub-accounts" checkbox is selected. Webhooks Configuration

  3. Click Save when the configuration is complete.

  4. Add Webhook URLs for any other Webhooks of interest.

Test the Webhook

  1. Trigger an event in the platform that the Webhook will respond to. View the Webhook FAQ for a list of what platform events will trigger a Webhook notification. To get the Account.Updated Webhook configured above to fire, change an account setting such as the mailing address. Update Account Info

  2. Save the account change. Within seconds, the Webhook listener service should receive the notification message. In the sample application, this information is pushed to the browser. Clicking on the updated account's name reveals both the full payload and the hashed signature value. Update Account Info

Verifying the Webhook Signature

Each Webhook notification includes a signature attached in the Tier3-RsaSha1 header. This signature is generated by creating a SHA-1 hash from the JSON payload and encrypting it with an RSA private key. It can be verified by following these steps:

  • Generate a SHA-1 hash from the message body
  • Decrypt the signature using CenturyLink Cloud's public key (which can be found in the Webhook FAQ)
  • Compare these two values and confirm they are equal. If they're not, the message did not come from CenturyLink Cloud.

Though someone trying to be malicious may change the JSON message, they will not be able to get the correct signature to match up without the use of the private key. This confirms that the message indeed came from CenturyLink Cloud and not someone spoofing or tampering with the message in-flight.

Notice in the screenshot above that under the hashed signature value, there is a VERIFIED message in green. This is because the example application performs this verification and outputs the results. In the code above for the account Webhook handler, we retrieve the signature from the Tier3-RsaSha1 header. Later in the code, we verify the signature

function VerifySignature(data, signatureHeader) {
  var publicKey = fs.readFileSync(path.resolve(__dirname, 'public.pem')).toString();
  var key = new rsa(publicKey, 'pkcs8-public-pem', {"signingScheme":"sha1"});
  return key.verify(data, signatureHeader, 'utf8', 'base64');
}

If this verification failed because the message was tampered with or came from someone else, the following message would appear. Notice the message matches the one above, but signature does not.

Update Account Info

Delete Webhook

Delete a webhook for an event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete the webhook for an event. This will delete all the targetUris for the specified event.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

Request

Uri Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
Event string The name of the event for which the webhook will be deleted Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Delete Webhook Target Uri

Delete a target uri from a webhook. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a single target uri from a particular webhook.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris?targetUri={uri}

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris?targetUri=https%3A%2F%2Ftest.api%2Faccount%2Fcreated

Request

Uri Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
Event string The name of the event from which the target uri will be deleted Yes
targetUri string The uri that will be removed Yes

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Get Webhooks

Gets the details on the configured webhooks. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover all the webhooks that have been configured for every available event and get links to operations for modifying those webhooks.

URL

Structure

GET https://api.ctl.io/v2/webhooks/{accountAlias}

Example

GET https://api.ctl.io/v2/webhooks/ALIAS

Request

Uri Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes

Response

Webhook Collection Entity Definition

Name Type Description
items Webhook[] A list of webhooks, one per available event

Webhook Entity Definition

Name Type Description
name string The name of the event that triggers the webhook
configuration Configuration Details about the webhook handling the event

Configuration Entity Definition

Name Type Description
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts
targetUris TargetUri[] The list of targets to be called when the event occurs

TargetUri Entity Definition

Name Type Description
targetUri string A uri that will be called when the event occurs

Examples

JSON

{
  "items": [
    {
      "name": "Account.Created",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://uri.test/account/created"
          },
          {
            "targetUri": "https://api.test/account/created"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Deleted",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://api.test/account/deleted"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Alert.Notification",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Alert.Notification/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/v2/webhooks/RJP"
    }
  ]
}

Set Webhook

Change the configuration of a webhook for a specific event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the configuration of a webhook including the uris that get called when the event occurs and whether the uris are called when the event occurs in a sub-account.

URL

Structure

PUT https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

PUT https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

Request

Uri Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
Event string The name of the webhook event being configured Yes

Content Properties

Name Type Description Req.
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts Yes
targetUris TargetUri[] The targets called when the event occurs No

TargetUri Entity Definition

Name Type Description Req.
targetUri string A uri that will be called when the event occurs Yes

Examples

JSON

{
  recursive: true,
  targetUris: [
    { targetUri: "https://test.uri/account/created" },
    { targetUri: "https://test.api" }
  ]
}

Response

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.