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;

2. Create an instance of the HttpClient object.

HttpClient authClient = new HttpClient();

3. Add an Accept header to indicate that returning JSON as a response is ok.

authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

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

HttpContent content =
   new StringContent("{ \"username\":\"[username]\", \"password\":\"[password]\" }", null, "application/json");

5. Invoke the API and send the HTTP content using a POST command.

HttpResponseMessage message =
    await authClient.PostAsync("https://api.ctl.io/v2/authentication/login", content);

6. Load the response into a string for parsing.

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

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

  {
     "userName":"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."}

7. Submit a request: the following .NET code demonstrates how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".

  HttpClient authClient = new HttpClient();

  authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

  // Add bearer token to the header
  authClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Bearer [LONG TOKEN VALUE]");

  HttpResponseMessage message = await authClient.GetAsync("https://api.ctl.io/v2/datacenters/DEMO/CA1");

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

PowerShell Example

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

1. Log into the API.

$Body = @{ 
Username = 'CONTROL_USERNAME' 
Password = 'CONTROL_PASSWORD' 
}

2. Log in to the Platform and get back a bearerToken.

$LogonUri = 'https://api.ctl.io/v2/authentication/login' 
$LogonResponse = Invoke-RestMethod -Method Post -Uri $LogonUri -Body $Body -SessionVariable WebSession

3. Pull the BearerToken out of the response and format it correctly. Note that a prefix of "Bearer " is required.

$Bearer = 'Bearer ' + $LogonResponse.bearerToken

4. Add Accept and Authorization headers to the session variable to be used on future requests.

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

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

Here's an example of pulling server credentials:

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

Raw HTTP Example

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

Request

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

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

Response

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

{
  "userName": "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]

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.

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.

Overview

The following link definitions are related to the data center resource. They may be returned when making a call to Get Data Center List or other data center-related resources.

Data Center Link Definitions

Overview

The following link definitions are related to the firewall policy resource. They may be returned when making a call to Get Firewall Policy List or other network-related resources.

Firewall Link Definitions

Overview

The following link definitions are related to the groups resource. They may be returned when making a call to Get Group or other group-related resources.

Group Link Definition

Overview

The following link definitions are related to the shared load balancer resource. They may be returned when making a call to Get Shared Load Balancers or other load balancer-related resources.

Shared Load Balancer Link Definitions

Overview

The following link definitions are related to the network resource. They may be returned when making a call to Get Network List or other network-related resources.

Network Link Definitions

Overview

The following link definitions are related to the servers resource. They may be returned when making a call to Get Server or other server-related resources.

Server Link Definitions

Server Snapshot Definitions

Overview

The following link definitions are related to all types of resources.

Shared Link Definitions

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

Content Properties

Examples

JSON

{
    "id": "f02f8fbe23a211e8b4670ed5f89f718b"
}

Response

Entity Definition

Examples

JSON

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

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

Content Properties

Actions Entity

Triggers Entity

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

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

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

Response

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

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

Response

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

Entity Definition

Actions Entity

Triggers Entity

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

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

Response

Entity Definition

Actions Entity

Triggers Entity

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

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

Content Properties

Actions Entity

Triggers Entity

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

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

Examples

JSON

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

Response

Entity Definition

Examples

JSON

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

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

Response

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

Entity Definition

Range Definition

ScaleDownWindow Definition

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

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

Response

Entity Definition

Range Definition

ScaleDownWindow Definition

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

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

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.

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

Content Properties

Examples

JSON

    {
      "id": "3440b69f139c435b8f9462b0661014fc"
    }

Response

Entity Definition

Examples

JSON

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

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

Response

Entity Definition

Examples

JSON

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

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

Response

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

Entity Definition

Line Items Definition

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": []
        },
    ]
}

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

Response

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

Entity Definition

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

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

Response

Entity Definition

SKUs Definition

Memory Definition

Processor Definition

Storage Definition

OperatingSystems Definition

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

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

Response

Entity Definition

DeployableNetworks Definition

Templates Definition

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

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

Response

Entity Definition

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

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

Response

Entity Definition

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

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

Content Properties

Ports Definition

SourceRestrictions Definition

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

Examples

JSON

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

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

Content Properties

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

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

Content Properties

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

Examples

JSON

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

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

Response

There is no response upon the successful removal of the 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

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.

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

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

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

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

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

Response

Entity Definition

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

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

Response

Entity Definition

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

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

Response

Entity Definition

Ports Definition

SourceRestrictions Definition

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

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

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

Examples

JSON

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

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

Response

There is no response upon the successful update of the 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

Content Properties

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.

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

Content Properties

Ports Definition

SourceRestrictions Definition

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

Examples

JSON

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

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

Content Properties

CustomFields Definition

Examples

JSON

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

Response

Group Entity Definition

ChangeInfo Definition

CustomFields Definition

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

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

Response

Entity Definition

Examples

JSON

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

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

Response

Group Entity Definition

Groups Definition

Servers Definition

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

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

Response

Load Balancer Definition

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

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

Response

Entity Definition

Stats Definition

Disk Usage Definition

Guest Usage Definition

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

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

Response

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

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

Response

Group Entity Definition

ChangeInfo Definition

CustomFields Definition

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

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

Content Properties

PatchOperation Definition

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.

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

Content Properties

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

Memory Definition

Network Definition

PrimaryDNS Definition

SecondaryDNS Definition

TemplateName Definition

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

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

Content Properties

Load Balancer Pool

Example

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

Response

Load Balancer Definition

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

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

Content Properties

PatchOperation Definition

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.

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

Content Properties

PatchOperation Definition

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.

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

Content Properties

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

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

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

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

Examples

JSON

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

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

Content Properties

Response

Entity Definition

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

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

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

Content Properties

Notification Destination Definition

SysLogSettings Definition

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.

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

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.

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

Content Properties

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.

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

Content Properties

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

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

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

Content Properties

Node Properties

HealthCheck Properties

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

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

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

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

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

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

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

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

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

Response

Entity Definition

Load Balancer Definition

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

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

Response

Entity Definition

Pool Definition

Node Definition

HealthCheck Definition

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

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

Response

Entity Definition

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
}

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

Response

Entity Definition

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

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

Response

Entity Definition

Node Definition

HealthCheck Definition

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

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

Content Properties

Examples

JSON

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

Response

The response will be the updated load balancer

Entity Definition

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
}

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

Content Properties

Node Properties

HealthCheck Properties

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

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

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

Response [UPDATED JANUARY 19 2016]

Entity Definition

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

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

Response

Entity Definition

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

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

Response

Entity Definition

Examples

JSON

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

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

Response

Entity Definition