Back to top

API v2.0 Authentication Overview

Important Notice! The Lumen Public Cloud Platform will go end-of-life on September 30th, 2023. Please ensure that you have a plan to migrate prior to this date as all services will terminate on October 1st, 2023.

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;
  1. Create an instance of the HttpClient object.
HttpClient authClient = new HttpClient();
  1. Add an Accept header to indicate that returning JSON as a response is ok.
authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
  1. 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");
  1. 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);
  1. 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":"user@company.com",
     "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."}
  1. 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' 
}
  1. 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
  1. Pull the BearerToken out of the response and format it correctly. Note that a prefix of "Bearer " is required.
$Bearer = 'Bearer ' + $LogonResponse.bearerToken
  1. 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": "user@company.com",
  "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

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.

Add Alert Policy To A Server

Adds an alert policy in a given account to 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 when you want to add a new alert policy within a given account to a server.

URL

Structure

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

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ACCTWB01

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account Yes
ServerId string ID of the server for alert policy to be added. 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 Id of the alert policy. Yes

Examples

JSON

{
    "id": "f02f8fbe23a211e8b4670ed5f89f718b"
}

Response

Entity Definition

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

Examples

JSON

{
   "id": "f02f8fbe23a211e8b4670ed5f89f718b",
   "links": [
        {
           "rel": "self",
           "href": "/v2/servers/ACCT/WA1ACCTWB01/alertPolicies/f02f8fbe23a211e8b4670ed5f89f718b",
           "verbs": [
              "DELETE"
           ]
        }
    ]
}

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":[
          "user@company.com"
        ]
      }
    }
  ],
  "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" : [
          "user@company.com"
        ]
      }
    }
  ],
  "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":[
              "user@company.com"
            ]
          }
        }
      ],
      "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":[
              "user@company.com"
            ]
          }
        }
      ],
      "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":[
          "user@company.com"
        ]
      }
    }
  ],
  "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":[
          "user@company.com"
        ]
      }
    }
  ],
  "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" : [
          "user@company.com"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 90.0
    }
  ]
}

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": "user@email.com",
    "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

    {
      "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": "billing@domain.com",
    "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 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"
      }
    ]
  }
]

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"
    }
  ]
}

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"
}

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 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 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 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 array Source addresses for traffic on the originating firewall, specified using CIDR notation
destination array Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount string Short code for a particular account
ports array 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"
                ]
            }
        ]
    },
]

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 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 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.

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"
}

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": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "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 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"
  }
]

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": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

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
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": "user@user.com",
    "createdDate": "2015-11-23T21:17:16Z",
    "modifiedBy": "user@user.com",
    "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"
    }
  ]
}

Delegate Management of an existing Instance

This service allows the user to delegate the management of an existing Instance to CenturyLink.

When to Use It

Use this API operation if you don't want CL to be able to manage your instance on your behalf.

NOTE: The following requirements need to be met in order to be able to make an instance managed:

  • Only "compute" instances (Linux and Windows) can be managed.
  • Terms and conditions need to be accepted. In order to do this, the following url param needs to be set to true:
accept_terms=true
  • The Instance needs to be in "Done" status.
  • The user making the request needs to have admin permissions on the instance.
  • The company owning the instance needs to support "Delegate Management".

Supported Operating Systems

  • Linux
  • Windows

URL

Structure

[PUT] /services/instances/{instance_id}/make_managed_os

Example

POST https://api.ctl.io/v2/instances/my_instance_id/make_managed_os?accept_terms=true

Request

URI Parameters

Name Type Description Req.
InscanceId string Id of the Instance Yes
accept_terms boolean Indicates that the client accepts the terms and conditions Yes

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": "youremail@site.com"
}

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.

Create LBaaS

Creates an LBaaS instance 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 create a new load balancer and get a VIP assigned in a given data center and for a given account.

URL

Structure

POST https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers

Example

POST https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers

Request

URI Parameters

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

Content Properties

Name Type Description Req.
name string The intended name of the new instance Yes
description string A short description of the load balancer No

Examples

JSON

{  
    "name": "ExampleGroup",
    "description": "Example Group for demo purposes"
} 

Response

The response will be an entity representing the request to create the new load balancer. Request status can be tracked from the Get LBaaS Request.

Entity Definition

Name Type Description
id string ID of the LBaaS create request
status string Initially the response will show a status for the request of "ACTIVE". A status of "COMPLETE" will show in the Response of a function when the Group has been created with the new configuration.
description string Describes the activity running within the LBaaS Group create process
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of LBaaS Group creation. Null value returned until process has completed
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",
    "status": "ACTIVE",  
    "description": "Create Load Balancer a4ad7c71-1575-400e-8eb2-cef74ed557ad",  
    "requestDate": 1450383770701,  
    "completionDate": null,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "a4ad7c71-1575-400e-8eb2-cef74ed557ad"  
        }  
    ]  
}

Create Pool

Creates a pool on an LBaaS instance 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 create a new pool on an existing load balancer.

URL

Structure

POST https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}/pools

Example

POST https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31/pools

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer Yes

Content Properties

Name Type Description Req.
port integer The port on which incoming traffic will send requests. Valid port ranges are between 23 and 65534 Yes
loadBalancingMethod string Method for load balancing - valid values are leastconn, roundrobin, source, or uri. If null will default to roundrobin No
persistence string Persistence method for client connections to backend nodes - none or source_ip. If null will default to none No
idleTimeout integer Timeout value for idle client connections to backend nodes in milliseconds - defaults to 180000 No
loadBalancingMode string Indicates the type of load balancing – tcp or http (layer4-TCP or layer7-HTTP(s)) Yes
nodes array Collection of entity values that describe the customer backend nodes being load balanced No
forceHttps boolean Will redirect incoming traffic on port 80 to port 443. loadBalancingMode must be set to tcp and port must be set to 443 No
healthCheck object Configures a health check that is applied to all nodes in the pool, provided they do not already have a healthCheck configured No

Node Properties

Name Type Description Req.
ipAddress string IP of the server that will be load balanced Yes
privatePort integer Port on which the server that will be load balanced is listening Yes
status string enabled or disabled. Nodes set to disabled will not have any traffic directed to them. Defaults to enabled No
healthCheck object Configures a health check on this specific node. Will override any healthCheck configured on the pool No
serverWeight integer Adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights. Range is 1 to 256. Default is 1 No

HealthCheck Properties

Name Type Description Req.
unhealthyThreshold integer Number of times server healthcheck can fail befre being removed from rotation. Valid range between 2 and 10 Yes
healthyThreshold integer Number of times unhealthy servers must pass healthcheck before being readded to rotation. Valid range is between 2 and 10 Yes
intervalSeconds integer Seconds to wait between healthchecks. Valid range is between 5 and 300 Yes
targetPort integer Port of the healthcheck on the server Yes
mode string Mode over which to send healthcheck. Options are TCP, SSL, HTTP. Defaults to TCP No
httpHealthCheckMethod string HttpMethod to use when querying healthcheck. Only valid when mode is set to HTTP No
httpHealthCheckUrl string Url location of healthcheck. Only valid when mode is set to HTTP No

Examples

JSON

{
    "port": 443,
    "loadBalancingMethod": "roundrobin",
    "persistence": "none",
    "idleTimeout": 180000,
    "loadBalancingMode": "tcp",
    "nodes": [
        {
            "ipAddress": "10.140.218.25",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        },
        {
            "ipAddress": "10.140.218.26",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        }
    ],
    "forceHttps": true,
    "healthCheck": {
        "unhealthyThreshold": 5,
        "healthyThreshold": 2,
        "intervalSeconds": 60,
        "targetPort": 122,
        "mode": "TCP",
        "httpHealthCheckMethod": null,
        "httpHealthCheckUrl": null
    } 
}

Response

The response will be an entity representing the request to create the new pool. Request status can be tracked from the Get LBaaS Request.

Entity Definition

Name Type Description
id string ID of the Pool create request
status string Initially the response will show a status for the request of "ACTIVE". A status of "COMPLETE" will show in the Response of a function when the load balancer has been updated with the new configuration.
description string Describes the activity running within the Pool create process
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of pool creation. Null value returned until process has completed
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",
    "status": "ACTIVE",  
    "description": "Add Pool to Load Balancer 329a98e6-977a-4c25-a7c8-174209fe1d31",  
    "requestDate": 1450383770701,  
    "completionDate": null,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "329a98e6-977a-4c25-a7c8-174209fe1d31"  
        },  
        { 
            "red": "pool", 
            "href": "", 
            "resourceId": "a4ad7c71-1575-400e-8eb2-cef74ed557ad" 
        } 
    ]  
}

Delete Load Balancer

Deletes an LBaaS instance 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 delete an existing load balancer.

URL

Structure

DELETE https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}

Example

DELETE https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer you want to delete Yes

Response

The response will be an entity representing the request to delete the load balancer. Request status can be tracked from the Get LBaaS Request.

Entity Definition

Name Type Description
id string ID of the load balancer delete request
status string Initially the response will show a status for the request of "ACTIVE". A status of "COMPLETE" will show in the Response of a function when the load balancer has been deleted.
description string Describes the activity running within the Load Balancer delete process
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of load balancer delete. Null value returned until process has completed
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",
    "status": "ACTIVE",  
    "description": "Delete Load Balancer 329a98e6-977a-4c25-a7c8-174209fe1d31",  
    "requestDate": 1450383770701,  
    "completionDate": null,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "329a98e6-977a-4c25-a7c8-174209fe1d31"  
        }
    ]  
}

Delete Pool

Deletes an existing pool from an LBaaS instance 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 remove a pool from a load balancer configuration.

URL

Structure

DELETE https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}/pools/{poolId}

Example

DELETE https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31/pools/a4ad7c71-1575-400e-8eb2-cef74ed557ad

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer Yes
poolId string Id of the pool you want to delete Yes

Response

The response will be an entity representing the request to delete the pool. Request status can be tracked from the Get LBaaS Request.

Entity Definition

Name Type Description
id string ID of the Pool delete request
status string Initially the response will show a status for the request of "ACTIVE". A status of "COMPLETE" will show in the Response of a function when the load balancer has been updated with the new configuration.
description string Describes the activity running within the Pool delete process
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of pool delete. Null value returned until process has completed
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",
    "status": "ACTIVE",  
    "description": "Remove Pool to Load Balancer 329a98e6-977a-4c25-a7c8-174209fe1d31",  
    "requestDate": 1450383770701,  
    "completionDate": null,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "329a98e6-977a-4c25-a7c8-174209fe1d31"  
        },
        {
            "red": "pool",
            "href": "",
            "resourceId": "a4ad7c71-1575-400e-8eb2-cef74ed557ad"
        } 
    ]  
}

Get All LBaaS Instances

Allows the user to retrieve all LBaaS instances 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 retrieve every LBaaS instance for one data center

URL

Structure

GET https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers

Example

GET https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center Yes

Response

Entity Definition

Name Type Description
values array Collection containing all load balancers in a data center

Load Balancer Definition

Name Type Description
id string ID of the request
name string Name of this load balancer instance
description string A short description of this load balancer
publicIPAddress string The external (public) IP address of the load balancer
pools array Collection of pools configured for this load balancer
status string Status of the load balancer: active, deleted, creating, or failed
accountAlias string The account which owns the load balancer
dataCenter string The data center in which the load balancer resides
creationTime string Date-time stamp of the load balancer creation
deletionTime string Date-time stamp of the load balancer deletion. Will be null if load balancer not in deleted status

Examples

JSON

{
    "values": [
        {
            "id": "329a98e6-977a-4c25-a7c8-174209fe1d31",
            "name": "ExampleGroup",
            "description": "Sample load balancer",
            "publicIPAddress": "64.211.224.123",
            "pools": [
                {
                    "id": "efdfc028-a694-481d-b406-cb68e5bf2f04",
                    "port": 443,
                    "loadBalancingMethod": "roundrobin",
                    "persistence": "none",
                    "idleTimeout": 180000,
                    "loadBalancingMode": "tcp",
                    "nodes": [
                        {
                            "ipAddress": "10.140.218.125",
                            "privatePort": 443,
                            "status": "enabled",
                            "healthCheck": null,
                            "serverWeight": null
                        },
                        {
                            "ipAddress": "10.140.218.126",
                            "privatePort": 443,
                            "status": "enabled",
                            "healthCheck": null,
                            "serverWeight": null
                        }
                    ],
                    "forceHttps": true,
                    "healthCheck": null,
                    "sslOffloading": null
                }
            ],
            "status": "active",
            "accountAlias": "DV01",
            "dataCenter": "NY1",
            "creationTime": 1471902898537,
            "deletionTime": null
        }
    ]
}

Get All Pool

Gets all of the pools that are currently configured on an LBaaS instance 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 retrieve the configuration of all existing pools on a load balancer.

URL

Structure

GET https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}/pools

Example

GET https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31/pools

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer Yes

Response

Entity Definition

Name Type Description
values array Collection containing all pools on a load balancer

Pool Definition

Name Type Description
id string The id of the pool
port integer The port on which incoming traffic will send requests. Valid port ranges are between 23 and 65534
loadBalancingMethod string Method for load balancing - valid values are leastconn, roundrobin, source, or uri. If null will default to roundrobin
persistence string Persistence method for client connections to backend nodes - none or source_ip. If null will default to none
idleTimeout integer Timeout value for idle client connections to backend nodes in milliseconds - defaults to 180000
loadBalancingMode string Indicates the type of load balancing – tcp or http (layer4-TCP or layer7-HTTP(s))
nodes array Collection of entity values that describe the customer backend nodes being load balanced
forceHttps boolean Will redirect incoming traffic on port 80 to port 443.
healthCheck object Configures a health check that is applied to all nodes in the pool, provided they do not already have a healthCheck configured

Node Definition

Name Type Description
ipAddress string IP of the server that will be load balanced
privatePort integer Port on which the server that will be load balanced is listening
status string enabled or disabled. Nodes set to disabled will not have any traffic directed to them. Defaults to enabled
healthCheck object Configures a health check on this specific node. Will override any healthCheck configured on the pool
serverWeight integer Adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights. Range is 1 to 256. Default is 1

HealthCheck Definition

Name Type Description
unhealthyThreshold integer Number of times server healthcheck can fail befre being removed from rotation. Valid range between 2 and 10
healthyThreshold integer Number of times unhealthy servers must pass healthcheck before being readded to rotation. Valid range is between 2 and 10
intervalSeconds integer Seconds to wait between healthchecks. Valid range is between 5 and 300
targetPort integer Port of the healthcheck on the server
mode string Mode over which to send healthcheck. Options are TCP, SSL, HTTP. Defaults to TCP
httpHealthCheckMethod string HttpMethod to use when querying healthcheck. Only valid when mode is set to HTTP
httpHealthCheckUrl string Url location of healthcheck. Only valid when mode is set to HTTP

Examples

JSON

{
    "values": [
        {
            "id": "a4ad7c71-1575-400e-8eb2-cef74ed557ad",
            "port": 443,
            "loadBalancingMethod": "roundrobin",
            "persistence": "none",
            "idleTimeout": 180000,
            "loadBalancingMode": "tcp",
            "nodes": [
                {
                    "ipAddress": "10.140.218.25",
                    "privatePort": 8443,
                    "status": "enabled",
                    "healthCheck": null,
                    "serverWeight": null
                },
                {
                    "ipAddress": "10.140.218.26",
                    "privatePort": 8443,
                    "status": "enabled",
                    "healthCheck": null,
                    "serverWeight": null
                }
            ],
            "forceHttps": true,
            "healthCheck": {
                "unhealthyThreshold": 5,
                "healthyThreshold": 2,
                "intervalSeconds": 60,
                "targetPort": 122,
                "mode": "TCP",
                "httpHealthCheckMethod": null,
                "httpHealthCheckUrl": null
            } 
        }
    ]
}

Get LBaaS Instance

Allows the user to retrieve a single LBaaS instance. 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 retrieve the details of a single LBaaS instance.

URL

Structure

GET https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}

Example

GET https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center in which the load balancer was created Yes
loadBalancerId string The id of the load balancer. Yes

Response

Entity Definition

Name Type Description
id string ID of the request
name string Name of this load balancer instance
description string A short description of this load balancer
publicIPAddress string The external (public) IP address of the load balancer
pools array Collection of pools configured for this load balancer
status string Status of the load balancer: active, deleted, creating, or failed
accountAlias string The account which owns the load balancer
dataCenter string The data center in which the load balancer resides
creationTime string Date-time stamp of the load balancer creation
deletionTime string Date-time stamp of the load balancer deletion. Will be null if load balancer not in deleted status

Examples

JSON

{
    "id": "329a98e6-977a-4c25-a7c8-174209fe1d31",
    "name": "ExampleGroup",
    "description": "Sample load balancer",
    "publicIPAddress": "64.211.224.123",
    "pools": [
        {
            "id": "efdfc028-a694-481d-b406-cb68e5bf2f04",
            "port": 443,
            "loadBalancingMethod": "roundrobin",
            "persistence": "none",
            "idleTimeout": 180000,
            "loadBalancingMode": "tcp",
            "nodes": [
                {
                    "ipAddress": "10.140.218.125",
                    "privatePort": 443,
                    "status": "enabled",
                    "healthCheck": null,
                    "serverWeight": null
                },
                {
                    "ipAddress": "10.140.218.126",
                    "privatePort": 443,
                    "status": "enabled",
                    "healthCheck": null,
                    "serverWeight": null
                }
            ],
            "forceHttps": true,
            "healthCheck": null,
            "sslOffloading": null
        }
    ],
    "status": "active",
    "accountAlias": "DV01",
    "dataCenter": "NY1",
    "creationTime": 1471902898537,
    "deletionTime": null
}

Get LBaaS Request

Allows the user to retrieve a request from the LBaaS service.

When to Use It

Use this API operation when you need to check the status of a request to the LBaaS service.

URL

Structure

GET https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/requests/{id}

Example

GET https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/requests/d685c028-5852-4b6f-8511-a407147db0e4

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center the request was created in Yes
id string The id of the request the user is interested in. Yes

Response

Entity Definition

Name Type Description
id string ID of the request
status string Current status of the request. Possible values are 'ACTIVE', 'COMPLETE', and 'FAILED'
description string Describes the type of the request
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of when request completed.
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",  
    "status": "COMPLETE",  
    "description": "Create Load Balancer a4ad7c71-1575-400e-8eb2-cef74ed557ad",  
    "requestDate": 1450383770701,  
    "completionDate": 1450383813624,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "a4ad7c71-1575-400e-8eb2-cef74ed557ad"  
        }  
    ]  
}

Get Pool

Gets the configuration of a pool on an LBaaS instance 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 retrieve the configuration of an existing pool on a load balancer.

URL

Structure

GET https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}/pools/{poolId}

Example

GET https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31/pools/a4ad7c71-1575-400e-8eb2-cef74ed557ad

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer Yes
poolId string Id of the pool you want to view Yes

Response

Entity Definition

Name Type Description
id string The id of the pool
port integer The port on which incoming traffic will send requests. Valid port ranges are between 23 and 65534
loadBalancingMethod string Method for load balancing - valid values are leastconn, roundrobin, source, or uri. If null will default to roundrobin
persistence string Persistence method for client connections to backend nodes - none or source_ip. If null will default to none
idleTimeout integer Timeout value for idle client connections to backend nodes in milliseconds - defaults to 180000
loadBalancingMode string Indicates the type of load balancing – tcp or http (layer4-TCP or layer7-HTTP(s))
nodes array Collection of entity values that describe the customer backend nodes being load balanced
forceHttps boolean Will redirect incoming traffic on port 80 to port 443.
healthCheck object Configures a health check that is applied to all nodes in the pool, provided they do not already have a healthCheck configured

Node Definition

Name Type Description
ipAddress string IP of the server that will be load balanced
privatePort integer Port on which the server that will be load balanced is listening
status string enabled or disabled. Nodes set to disabled will not have any traffic directed to them. Defaults to enabled
healthCheck object Configures a health check on this specific node. Will override any healthCheck configured on the pool
serverWeight integer Adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights. Range is 1 to 256. Default is 1

HealthCheck Definition

Name Type Description
unhealthyThreshold integer Number of times server healthcheck can fail befre being removed from rotation. Valid range between 2 and 10
healthyThreshold integer Number of times unhealthy servers must pass healthcheck before being readded to rotation. Valid range is between 2 and 10
intervalSeconds integer Seconds to wait between healthchecks. Valid range is between 5 and 300
targetPort integer Port of the healthcheck on the server
mode string Mode over which to send healthcheck. Options are TCP, SSL, HTTP. Defaults to TCP
httpHealthCheckMethod string HttpMethod to use when querying healthcheck. Only valid when mode is set to HTTP
httpHealthCheckUrl string Url location of healthcheck. Only valid when mode is set to HTTP

Examples

JSON

{
    "id": "a4ad7c71-1575-400e-8eb2-cef74ed557ad",
    "port": 443,
    "loadBalancingMethod": "roundrobin",
    "persistence": "none",
    "idleTimeout": 180000,
    "loadBalancingMode": "tcp",
    "nodes": [
        {
            "ipAddress": "10.140.218.25",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        },
        {
            "ipAddress": "10.140.218.26",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        }
    ],
    "forceHttps": true,
    "healthCheck": {
        "unhealthyThreshold": 5,
        "healthyThreshold": 2,
        "intervalSeconds": 60,
        "targetPort": 122,
        "mode": "TCP",
        "httpHealthCheckMethod": null,
        "httpHealthCheckUrl": null
    } 
}

Update LBaaS

Updates an LBaaS instance 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 update the name and description of a given load balancer.

URL

Structure

PUT https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}

Example

 PUT https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for a particular account Yes
dataCenter string Short string representing the data center in which the load balancer was created Yes
loadBalancerId string The id of the load balancer. Yes

Content Properties

Name Type Description Req.
name string The intended name of the new instance Yes
description string A short description of the load balancer No

Examples

JSON

{  
    "name": "ExampleGroup-updated",
    "description": "Example Group for demo purposes"
} 

Response

The response will be the updated load balancer

Entity Definition

Name Type Description
id string ID of the request
name string Name of this load balancer instance
description string A short description of this load balancer
publicIPAddress string The external (public) IP address of the load balancer
pools array Collection of pools configured for this load balancer
status string Status of the load balancer: active, deleted, creating, or failed
accountAlias string The account which owns the load balancer
dataCenter string The data center in which the load balancer resides
creationTime string Date-time stamp of the load balancer creation
deletionTime string Date-time stamp of the load balancer deletion. Will be null if load balancer not in deleted status

Examples

JSON

{
    "id": "329a98e6-977a-4c25-a7c8-174209fe1d31",
    "name": "ExampleGroup-updated",
    "description": "Example group for demo purposes",
    "publicIPAddress": "64.211.224.123",
    "pools": [],
    "status": "active",
    "accountAlias": "DV01",
    "dataCenter": "NY1",
    "creationTime": 1471902898537,
    "deletionTime": null
}

Update Pool

Updates an existing pool on an LBaaS instance 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 modify the configuration of an existing pool on a load balancer.

URL

Structure

PUT https://api.loadbalancer.ctl.io/{accountAlias}/{dataCenter}/loadbalancers/{loadBalancerId}/pools/{poolId}

Example

PUT https://api.loadbalancer.ctl.io/DV01/NY1/loadbalancers/329a98e6-977a-4c25-a7c8-174209fe1d31/pools/a4ad7c71-1575-400e-8eb2-cef74ed557ad

Request

URI Parameters

Name Type Description Req.
accountAlias string Short code for the particular account which owns the load balancer Yes
dataCenter string Short string representing the data center in which the load balancer resides Yes
loadBalancerId string Id of the load balancer Yes
poolId string Id of the pool you want to update Yes

Content Properties

Name Type Description Req.
id string The id of the pool Yes
port integer The port on which incoming traffic will send requests. Valid port ranges are between 23 and 65534 Yes
loadBalancingMethod string Method for load balancing - valid values are leastconn, roundrobin, source, or uri. If null will default to roundrobin No
persistence string Persistence method for client connections to backend nodes - none or source_ip. If null will default to none No
idleTimeout integer Timeout value for idle client connections to backend nodes in milliseconds - defaults to 180000 No
loadBalancingMode string Indicates the type of load balancing – tcp or http (layer4-TCP or layer7-HTTP(s)) Yes
nodes array Collection of entity values that describe the customer backend nodes being load balanced No
forceHttps boolean Will redirect incoming traffic on port 80 to port 443. loadBalancingMode must be set to tcp and port must be set to 443 No
healthCheck object Configures a health check that is applied to all nodes in the pool, provided they do not already have a healthCheck configured No

Node Properties

Name Type Description Req.
ipAddress string IP of the server that will be load balanced Yes
privatePort integer Port on which the server that will be load balanced is listening Yes
status string enabled or disabled. Nodes set to disabled will not have any traffic directed to them. Defaults to enabled No
healthCheck object Configures a health check on this specific node. Will override any healthCheck configured on the pool No
serverWeight integer Adjust the server's weight relative to other servers. All servers will receive a load proportional to their weight relative to the sum of all weights. Range is 1 to 256. Default is 1 No

HealthCheck Properties

Name Type Description Req.
unhealthyThreshold integer Number of times server healthcheck can fail befre being removed from rotation. Valid range between 2 and 10 Yes
healthyThreshold integer Number of times unhealthy servers must pass healthcheck before being readded to rotation. Valid range is between 2 and 10 Yes
intervalSeconds integer Seconds to wait between healthchecks. Valid range is between 5 and 300 Yes
targetPort integer Port of the healthcheck on the server Yes
mode string Mode over which to send healthcheck. Options are TCP, SSL, HTTP. Defaults to TCP No
httpHealthCheckMethod string HttpMethod to use when querying healthcheck. Only valid when mode is set to HTTP No
httpHealthCheckUrl string Url location of healthcheck. Only valid when mode is set to HTTP No

Examples

JSON

{
    "id": "a4ad7c71-1575-400e-8eb2-cef74ed557ad",
    "port": 443,
    "loadBalancingMethod": "roundrobin",
    "persistence": "none",
    "idleTimeout": 180000,
    "loadBalancingMode": "tcp",
    "nodes": [
        {
            "ipAddress": "10.140.218.25",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        },
        {
            "ipAddress": "10.140.218.26",
            "privatePort": 8443,
            "status": "enabled",
            "healthCheck": null,
            "serverWeight": null
        }
    ],
    "forceHttps": true,
    "healthCheck": {
        "unhealthyThreshold": 5,
        "healthyThreshold": 2,
        "intervalSeconds": 60,
        "targetPort": 122,
        "mode": "TCP",
        "httpHealthCheckMethod": null,
        "httpHealthCheckUrl": null
    } 
}

Response

The response will be an entity representing the request to update the pool. Request status can be tracked from the Get LBaaS Request.

Entity Definition

Name Type Description
id string ID of the Pool update request
status string Initially the response will show a status for the request of "ACTIVE". A status of "COMPLETE" will show in the Response of a function when the load balancer has been updated with the new configuration.
description string Describes the activity running within the Pool update process
requestDate string Date-time stamp of the request
completionDate string Date-time stamp of pool update. Null value returned until process has completed
links array Collection of entity links that point to resources related to this LBaaS Group

Examples

JSON

{  
    "id": "d685c028-5852-4b6f-8511-a407147db0e4",
    "status": "ACTIVE",  
    "description": "Update Pool to Load Balancer 329a98e6-977a-4c25-a7c8-174209fe1d31",  
    "requestDate": 1450383770701,  
    "completionDate": null,  
    "links": [  
        {  
            "rel": "loadbalancer",  
            "href": "",  
            "resourceId": "329a98e6-977a-4c25-a7c8-174209fe1d31"  
        },
        {
            "red": "pool",
            "href": "",
            "resourceId": "a4ad7c71-1575-400e-8eb2-cef74ed557ad"
        } 
    ]  
}

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"
  }
}

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 Log Forwarding Address

Gets the current configuration for network log forwarding. 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 address and protocol currently configured for network log forwarding.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly. Only accounts using virtual firewall can use network log forwarding.

URL

Structure

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

Example

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

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
remoteAddress string Address of the remote logging server
protocol string Protocol used when sending logs

Examples

JSON

{
    "remoteAddress": "1.2.3.4",
    "protocol": "tcp"
}

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 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"
            ]
        }
    ]
}

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 Log Forwarding Address

Updates the network log forwarding configuration for a given data center 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 remote address and protocol used for network log forwarding in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly. Only accounts using virtual firewall can use network log forwarding.

URL

Structure

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

Example

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

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

Content Properties

Name Type Description Option Req.
remoteAddress string Address of the remote logging server. If not provided, log forwarding will be disabled for this account No
protocol string Protocol used when sending logs tcp, udp Yes

Examples

JSON

{
    "remoteAddress": "1.2.3.4",
    "protocol": "tcp"
}

Response

The response is an operation used for tracking the status of the new configuration.

Entity Definition

Name Type Description
operationID string ID used for tracking operation status
status string Current status of operation

Examples

JSON

{
    "operationID": "dc5fe58f311f45b3b50de4c9c48ff2e0",
    "status": "pending"
}

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 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

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

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."
  }
]

Public IP: See Firewall

APIs for Public IP are located within the Firewall section.

.

.

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"
}

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": "P@ssw0rd1",
  "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
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 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 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": "P@ssw0rd1",
  "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":"P@ssw0rd1"
}

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 Managed applications, 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": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "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"
      ]
    }
  ]
}

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
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": "P@ssw0rd1",
  "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":"OldP@ssw0rd1",
         "password":"NewP@ssw0rd2"
      }
   }
]

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"
}

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

The legacy shared load balancers have been deprecated. To create a new load balancer see LBaaS.

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"
        ]
      }
    ]
  }
]

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.

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 -- this field is ignored if backupSchedule is defined Yes1
backupSchedule string Quartz-flavored CRON expression describing the execution schedule for backups Yes1
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 No
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

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "paths": [
    "/opt"
  ],
  "retentionDays": 7,
  "backupSchedule": "0 0 12 ? * TUE,SUN *"
}

Response

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for 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,
  "backupSchedule": "0 0 12 ? * SUN *"
  "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.

Download Anywhere Server Installer

Downloads a Simple Backup Anywhere Server agent installer. 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 the SBS Anywhere Server installation package

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/createInstallerScript

Example

POST https://api.backup.ctl.io/clc-backup-api/api/createInstallerScript

Request

Content Properties

Name Type Description Req.
provisioningToken string The provisioning token is given when a server is registered as Anywhere Server Yes

Examples

JSON

{
  "provisioningToken": "PROVISIONbdb54aa4-a4fc-43a3-b452-3b4afda66096"
}

Response

Headers

Name Type Description
x-filename string This is the script name
Content-Type string The script is returned in text/plain;charset=UTF-8 format

Entity Definition

Name Type Description
data text/plain This is the agent installation script returned for specific provisioning token sent in the request

Examples

plain/text

# ==========================================================================================================
# sbs-windows-install-BAAD-DELETEMESERVER-67.ps1    Version 2.0   Created Date: 1510169782942
# ==========================================================================================================

#
# If this script is not able to execute, please run Powershell 3.0 or later as ADMINISTRATOR
#
# Check you ExecutionPolicy in Powershell.
# Example: Get-ExecutionPolicy -list
#
# You may need to allow an UnRestricted ExecutionPolicy while installing SBS
# Example: echo . | powershell Set-ExecutionPolicy UnRestricted -FORCE
#
# After installing SBS you can return the ExecutionPolicy to the former value.
# Example: echo . | powershell Set-ExecutionPolicy UnDefined -FORCE
#
# Please use an internet search of "echo . | powershell Set-ExecutionPolicy UnRestricted -FORCE"
# for additional information.
#

#Setting up a log mechanism that displays and logs
Function Log-Message([string]$stringData)
{
   Write-Output $stringData
}

function IsNullOrEmpty($str) {if ($str) {$False} else {$True}}

#####################################################
# FakeCurl - used to download a file like *nix curl #
#####################################################
function FakeCurl {
	param ( $url, $file )

	Write-Output "Downloading $file from $url"
	$storageDir = $pwd
	$webclient = New-Object System.Net.WebClient
	$filepathname = "$storageDir\$file"
	$webclient.DownloadFile($url, $filepathname)
	Write-Output "Downloaded to $filepathname"
	$global:RETURN=$filepathname
}

################
# MAIN PROGRAM #
################
Function Main()
{
	Set-PSDebug -Strict
	Set-PSDebug -Trace 0

	$DATETIME=Get-Date -Format g
	Log-Message "sbs-windows-install-BAAD-DELETEMESERVER-67.ps1     Version 2.0"
	Log-Message "Script Created by anil.baad on 1510169782942"
	Log-Message "Execution Time: $DATETIME"

#
# Set variables
#
	$USERNAME="anil.baad"
	$ACCOUNTALIAS="BAAD"
	$HOSTNAME="DELETEMESERVER-67"
	$SBS_PROVISIONING_TOKEN="PROVISIONbdb54aa4-a4fc-43a3-b452-3b4afda66096"

#
# Display powershell version -- 3+ required
#	
	$PSVersionTable
	if ($PSVersionTable.PSVersion.Major -lt 3)
	{
		Log-Message "This script requires Powershell Version 3.0+"
		exit 0
	}

#
# Setup TLS1.2 for all HTTPS traffic
#
	Log-Message "Setup TLS1.2 for all HTTPS traffic in script..."
	[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

#	
# Setup proxy for windows
#
	Log-Message "Use netsh to setup proxy using IE as the source..."
	netsh winhttp import proxy source=ie 

#
# Download the sbs-windows-install.ps1 file
#		
	$SBS_INSTALL_SCRIPT = "sbs-windows-install.ps1"
	$SBS_INSTALL_URL = "https://s3.amazonaws.com/sbs-agent/$SBS_INSTALL_SCRIPT"
	$SBS_INSTALL_FILE = "$SBS_INSTALL_SCRIPT"
	FakeCurl -url $SBS_INSTALL_URL -file $SBS_INSTALL_FILE	
	$file = $RETURN
	Log-Message "Check download file $file..."
	
	If ( -not ( Test-Path -path "$file" ) )
	{
		Log-Message "$SBS_INSTALL_SCRIPT FAILED to download and was not used to install SBS"
		exit 0
	}

#
# Requires hard-coded script name
#
	Log-Message ".\sbs-windows-install.ps1 -accountalias $ACCOUNTALIAS -hostname $HOSTNAME -sbs_provisioning_token $SBS_PROVISIONING_TOKEN -DEVQAPROD DEV"
	.\sbs-windows-install.ps1 -accountalias $ACCOUNTALIAS -hostname $HOSTNAME -sbs_provisioning_token $SBS_PROVISIONING_TOKEN -DEVQAPROD DEV

}

Main

Exit 0

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-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for 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,
      "backupSchedule": "0 0 12 ? * SUN *",
      "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 Anywhere Server List

Get a list of SBS Anywhere servers. The id field can be used as serverIds to create server policies for an Anywhere 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 SBS Anywhere servers.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters/anywhereServers

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters/anywhereServers

Response

Entity Definition

Name Type Description
anywhereServerAliases Array[Anywhere Server] Array of AnywhereServers corresponding to the user's CLC alias

Examples

JSON

{
  [2]
  0:  {
          "id":"026b28ae-9b1f-4a3b-a3ab-89da0ebb68af",
		  "accountAlias":"ACME",
		  "osType":"Linux",
		  "serverAlias":"my-linux-server"
      }
  1:  {
          "id":"a3dc3866-68b7-4482-b645-66163ffbe4a2",
		  "accountAlias":"ACME",
		  "osType":"Windows",
		  "serverAlias":"My.Windows.Server"
      }
}

Get Csv Restore Jobs Report

Gets an up-to-date list of all restore jobs performed, including a summary for each. 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 a list of all the restores performed and summary for each.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/csv/restoreJobsReport

Example

GET https://api.backup.ctl.io/clc-backup-api/api/csv/restoreJobsReport

Response

content-type: text/plain, content-disposition: attachment

Note for "Anywhere Servers" in this report: the "Server Id" column will contain the friendly name given to the server, next a colon delimiter, and finally the reference id for the anywhere server record

Examples

CSV

  Server Id,Server Policy Id,Restore Point Id,Storage Region,Restore Status,Restore Start Time,Restore Latest Progress Time,Restore Finished Time,Protected Data Bytes Restored,Protected Data Bytes Failed To Restore,Number Of Critical Errors,Files Transferred From Storage,Bytes Transferred From Storage,Files Failed Transfer From Storage,Files Failed Transfer From Storage Due To S3 Throttling,Files Failed Transfer From Storage Due To S3 Unavailable,Files Failed Applying Attributes,Directories Restored,Directories Failed To Restore,Number Of Messages,Messages
  testServerId20180627014200,8903f6d9-40de-47f9-9d2a-9b0dee4f141f,362bef22-e386-4a17-b10c-ae5a4a482a95,CANADA,IN_PROGRESS,2018-06-27T01:42:05.187Z,2018-06-27T01:42:05.641Z,,0,0,0,0,0,0,0,0,0,0,0,0,
  testServerId20180627014130,cc573c6e-aafa-4dc1-956b-4707b7cc8d58,1c11515f-9199-42f0-8602-a83a69657a9e,CANADA,SUCCESS,2018-06-27T01:41:34.978Z,2018-06-27T01:41:35.396Z,2018-06-27T01:41:34.979Z,37188,0,0,345,34688,0,0,0,0,0,0,0,

Get Csv Restore Points Report

Gets a list of restore point details within a specified date range for 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

Use this API operation when you want to view the backup history for a server that is configured to use Simple Backup Service.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/csv/{serverPolicyId}/restorePointsReport

Example

GET https://api.backup.ctl.io/clc-backup-api/api/csv/aee021f6-e9d3-4c13-bff1-a9733bef7532/restorePointsReport?inRetentionOnly=false&backupFinishedStartDate=2018-01-01&backupFinishedEndDate=2018-06-26

Request

URI Parameters

Name Type Description Req.
serverPolicyId string The server policy id identifies the backup configuration for a specific server Yes

QueryString Parameters

Name Type Description Req.
inRetentionOnly string Setting to false will include all restore points found within the date range. Setting to true will omit restore points that have fallen out of retention and can no longer be used to perform restores. No
backupFinishedStartDate string Describes the beginning of the date range for inclusion in this report. Format is yyyy-MM-dd No
backupFinishedEndDate string Describes the end of date range for inclusion in this report. Cannot be more than one year after the start date. Format is yyyy-MM-dd No

Response

content-type: text/plain, content-disposition: attachment

Note for "Anywhere Servers" in this report: the "Server Id" column will contain the friendly name given to the server, next a colon delimiter, and finally the reference id for the anywhere server record

Examples

CSV

  Server Id,Server Policy Id,Server Policy Status,Storage Region,Account Policy Name,Account Policy Id,Account Policy Status,OS Type,Protected Files,Protected Bytes,Latest Backup Status,Latest Backup Start Time,Latest Backup Finished Time,Latest Files Transferred To Storage,Latest Bytes Transferred To Storage,Latest Files Failed To Transfer To Storage,Latest Bytes Failed To Transfer To Storage,Latest Files Removed From Disk,Latest Bytes Removed From Disk,Latest Unchanged Files Not Transferred,Latest Unchanged Bytes Not Transferred
  UC1BAADWIND1602-clone-2:19452303-9a91-4ba0-907a-c1d0f7ce915d,d6af6782-1d2f-426b-9bdc-377f09433e0a,ACTIVE,US EAST,dcbjr-test-win-sbstest2,3f81cd2f-2134-470f-b403-f96e7b8d0376,ACTIVE,Windows,89,16216064,SUCCESS,20180625 17:02:05,20180625 17:02:09,0,0,0,0,0,0,89,16216064
  UC1BAADWIND1602-clone-2:19452303-9a91-4ba0-907a-c1d0f7ce915d,d6af6782-1d2f-426b-9bdc-377f09433e0a,ACTIVE,US EAST,dcbjr-test-win-sbstest2,3f81cd2f-2134-470f-b403-f96e7b8d0376,ACTIVE,Windows,89,16216064,SUCCESS,20180625 16:02:05,20180625 16:02:10,0,0,0,0,0,0,89,16216064

Get Csv Summary Report

Gets an up-to-date list of details for each Server Policy, its Account Policy, and current backup status. 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 big-picture status report for all of your servers that are configured to use Simple Backup Service.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/csv/summaryReport

Example

GET https://api.backup.ctl.io/clc-backup-api/api/csv/summaryReport?withServerPolicyStatus=ACTIVE,INACTIVE

Request

QueryString Parameters

Name Type Description Req.
withServerPolicyStatus string Filter results for status in comma separated list 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'PENDING_INSTALL', 'ERROR', 'DELETED' No

Response

content-type: text/plain, content-disposition: attachment

Note for "Anywhere Servers" in this report: the "Server Id" column will contain the friendly name given to the server, next a colon delimiter, and finally the reference id for the anywhere server record

Examples

CSV

  Server Id,Server Policy Id,Server Policy Status,Storage Region,Account Policy Name,Account Policy Id,Account Policy Status,OS Type,Protected Files,Protected Bytes,Latest Backup Status,Latest Backup Start Time,Latest Backup Finished Time,Latest Files Transferred To Storage,Latest Bytes Transferred To Storage,Latest Files Failed To Transfer To Storage,Latest Bytes Failed To Transfer To Storage,Latest Files Removed From Disk,Latest Bytes Removed From Disk,Latest Unchanged Files Not Transferred,Latest Unchanged Bytes Not Transferred
  UC1BAADWIND1602-clone-2:19452303-9a91-4ba0-907a-c1d0f7ce915d,d6af6782-1d2f-426b-9bdc-377f09433e0a,ACTIVE,US EAST,dcbjr-test-win-sbstest2,3f81cd2f-2134-470f-b403-f96e7b8d0376,ACTIVE,Windows,89,16216064,SUCCESS,20180625 15:02:05,20180625 15:02:09,0,0,0,0,0,0,89,16216064

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 (Reading)"
  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:  "VA1 - US East (Sterling)"
  11:  "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-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for 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,
      "backupSchedule": "0 0 12 ? * SUN *",
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

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-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for the Policy
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
  "backupSchedule": "0 0 12 ? * SUN *"
  "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 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-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for 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,
  "backupSchedule": "0 0 12 ? * SUN *",
  "policyId": "4ca70660-f08a-407b-830d-e8e9c6c1d59a"
}

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 No
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
}

Register Anywhere Server

Registers a server as 'Anywhere Server' for Backup Anywhere 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 register a server for Backup Anywhere Service.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/provisioning

Example

POST https://api.backup.ctl.io/clc-backup-api/api/provisioning

Request

Content Properties

Name Type Description Req.
serverId string The name of the server being registered Yes
osType string 'Linux' or 'Windows' -- OS of the server Yes

Examples

JSON

{
  "serverId": "My-AWS-Server-1",
  "osType": "Linux"
}

Response

Entity Definition

Name Type Description
provisioningToken string This is a provisioning token massaged into the installer package for one time use only
clcAccountAlias string The account alias to which the Anywhere Server is registered to
osType string 'Linux' or 'Windows' -- OS of the server
issuedTimestamp long This is the timestamp when Backup Anywhere installer package is used for a Anywhere server
redeemedTimestamp long This is the timestamp when SBS agent is installed on the Anywhere server and has communicated back to SBS Backup Anywhere infrastructure
revokedTimestamp long This is a timestamp which is set when SBS Backup Anywhere service is removed for a Anywhere Server

Examples

JSON

{
  "provisioningToken": "PROVISIONbdb54aa4-a4fc-43a3-b452-3b4afda66096",
  "clcAccountAlias": "BAAS",
  "osType": "Linux",
  "issuedTimestamp": 1510090581000,
  "redeemedTimestamp": null,
  "revokedTimestamp": 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 -- ignored if backupSchedule is defined Yes1
backupSchedule string Quartz-flavored CRON expression describing the execution schedule for backups Yes1
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

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

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,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Response

Entity Definition

Name Type Description
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule string Quartz-flavored CRON string describing the execution schedule for 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,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

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 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"
            }
        ]
    }
]

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"                      
 }
}

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");

    })

  3. 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 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.

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.

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.

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": "/v2/users/demo@user.com",
  "accountUri": "/v2/accounts/DEMO",
  "accountAlias": "DEMO",
  "userName": "demo@user.com",
  "emailAddress": "demo@user.com",
  "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": "demo@user.com",
    "createdDate": "2012-12-17T01:17:17Z",
    "modifiedBy": "demo@user.com",
    "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.