Server operations

This section covers the following basic server operations:

Basic Operations:

• Create server

• Create server with disk config

• Create server with scheduler hints

• List servers

• List servers with details

• Show server with details

• Update server

• Delete server

Key Pairs Operations:

• Create key pair

• Import key pair

• List key pairs

• Delete key pair

Volume Operations:

• Attach volume to server

• List volumes

• Show volume details

• Detach volume from server

Boot from Volume Operation:

• Create server by booting from a volume

Server Action Logs:

• List recent server actions

• Show server action details

Server Action Operations:

• Change password

• Reset network

• Reboot server

• Rebuild server

• Resize server

• Confirm server resize

• Revert server resize

• Migrate server

• Create image

• Rescue server

• Unrescue server

• Lock server

• Unlock server

• Stop server

• Start server

Server Address Operations:

• List server addresses

• List server addresses with networks

Server Metadata Operations:

• List server metadata items

• Set server metadata items

• Update server metadata items

• List server metadata items for a specific server

• Set server metadata item for a specific server

• Update server metadata item for a specific server

Create server

POST /servers

This operation provisions a server asynchronously.

The full URL to the newly created server is returned through the Location header and is available as a self and bookmark link in the server representation.

The progress of the server build depends on factors including location of the requested image, network i/o, host load, and the selected flavor. You can check the progress of the build request by issuing a call to retrieve the details of the server. Once the build is complete, the server’s status is ACTIVE.

For OnMetal server builds, even after the status is ACTIVE, wait a few additional moments for the network configuration to complete. Once the new OnMetal server pings successfully, you can begin to use it.

Important

OnMetal servers must be created using an ssh key pair. Thus you should ignore the administrator password returned by a Create Server operation because it does not allow access to the OnMetal server.

The following extensions allow you to use other options when creating a new server:

• Config drive

• Boot from volume

• Networks for nova and for neutron

• Key pairs

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
server.name	String	The server name.
server.imageRef	Uuid	The image reference for the desired image for your server instance.
server.block_device_mapping_v2	Object (Optional)	The container of bootable volume details.
server.block_device_mapping_v2.boot_index	Integer (Optional)	The index of the bootable volume.
server.block_device_mapping_v2.uuid	Integer (Optional)	The id of the bootable volume.
server.block_device_mapping_v2.source_type	String (Optional)	The source type for the bootable volume.
server.block_device_mapping_v2.destination_type	String (Optional)	The destination type for the bootable volume.
server.block_device_mapping_v2.delete_on_termination	Boolean (Optional)	Flag to indicate whether the bootable volume should be deleted after server creation.
server.flavorRef	Uuid	The flavor reference for the desired flavor for your server instance.
server.config_drive	String (Optional)	Enables metadata injection in a server through a configuration drive. To enable a configuration drive, specify true. Otherwise, specify false.
server.key_name	String (Optional)	The name of the key pair used to authenticate by using key-based authentication instead of password- based authentication.
server.OS-DCF:diskConfig	String (Optional)	The disk configuration value. The image auto_disk_config metadata key set will affect the value you can choose to set the server OS- DCF:diskConfig. If an image has auto_disk_config value of disabled, you cannot create a server from that image when specifying OS-DCF:diskConfig value of AUTO. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.
server.metadata	String (Optional)	Metadata key and value pairs. The maximum size of each metadata key and value is 255 bytes each.
server.personality	Array (Optional)	The array of personality files for the server.
server.user_data	String (Optional)	Data used with config_drive for configuring a server.
server.personality.path	String	The path of the personality file.
server.personality.contents	String	The contents of the personality file.
server.networks	Array	The array of networks attached to the server. By default, the server instance is provisioned with all isolated networks for the tenant. You can specify multiple NICs on the server. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a Nova- network network, specify the UUID in the uuid attribute in a networks object. To provision the server instance with a NIC for a Neutron network, specify the UUID in the port attribute in a networks object.
server.networks.uuid	Uuid (Optional)	The UUID of the Nova-network network attached to the server.
server.networks.port	Uuid (Optional)	The UUID of the Neutron port attached to the server.

Example Create server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "server": {
        "name": "api-test-server-1",
        "imageRef": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
        "flavorRef": "2",
        "config_drive": true,
        "OS-DCF:diskConfig": "AUTO",
        "metadata": {
            "My Server Name": "API Test Server 1"
        },
        "networks": [
            {
                "uuid": "00000000-0000-0000-0000-000000000000"
            },
            {
                "uuid": "11111111-1111-1111-1111-111111111111"
            }
        ]
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	Uuid	The URL for the server and the associated rel.
server.links.rel	Uuid	The descriptive field for the associated href, which is either self or bookmark.
server.adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are AUTO and MANUAL.

Example Create server: JSON response

Status Code: 202 Accepted
Content-Length: 380
Content-Type: application/json
Date: Thu, 04 Dec 2014 18:47:30 GMT
Location: https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-b8b54344-41a9-4d6a-a92f-60f3dcab4b1f

{
  "server": {
    "OS-DCF:diskConfig": "AUTO",
    "id": "4b963871-f591-4b7d-b05f-7c0286e3c50f",
    "links": [
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f",
        "rel": "self"
      },
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/820712/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f",
        "rel": "bookmark"
      }
    ],
    "adminPass": "C3tfz8jQtnKC"
  }
}

Create server with disk config

POST /servers

This operation creates a server using disk config.

When you create a server from an image with the OS-DCF:diskConfig value set to AUTO, the server is built with a single partition that is expanded to the disk size of the flavor selected. When you set the OS-DCF:diskConfig attribute to MANUAL, the server is built by using the partition scheme and file system that is in the source image.  If the target flavor disk is larger, remaining disk space is left unpartitioned. A server inherits the OS-DCF:diskConfig attribute from the image from which it is created, based on the image’s auto-disk-config value. However, you may be able to override the server’s OS-DCF:diskConfig value when you create the server.

In this example, the server is created with OS-DCF:diskConfig set to AUTO.This request’s success depends on the image’s auto_disk_config metadata value. An image created from a server will have appropriate auto_disk_config metadata written to it. So, if the create server command succeeds, an image created from the server will have auto_disk_config = True on it.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request accepted.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
server.name	String	The server name.
server.imageRef	Uuid	The image reference for the desired image for your server instance.
server.block_device_mapping_v2	Object (Optional)	The container of bootable volume details.
server.block_device_mapping_v2.boot_index	Integer (Optional)	The index of the bootable volume.
server.block_device_mapping_v2.uuid	Integer (Optional)	The id of the bootable volume.
server.block_device_mapping_v2.source_type	String (Optional)	The source type for the bootable volume.
server.block_device_mapping_v2.destination_type	String (Optional)	The destination type for the bootable volume.
server.block_device_mapping_v2.delete_on_termination	Boolean (Optional)	Flag to indicate whether the bootable volume should be deleted after server creation.
server.flavorRef	Uuid (Required)	The flavor reference for the desired flavor for your server instance.
server.config_drive	String (Optional)	Enables metadata injection in a server through a configuration drive. To enable a configuration drive, specify true. Otherwise, specify false.
server.key_name	String (Optional)	The name of the key pair used to authenticate by using key-based authentication instead of password- based authentication.
server.OS-DCF:diskConfig	String (Optional)	The disk configuration value. The image auto_disk_config metadata key set will affect the value you can choose to set the server OS- DCF:diskConfig. If an image has auto_disk_config value of disabled, you cannot create a server from that image when specifying OS-DCF:diskConfig value of AUTO. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.
server.metadata	String (Optional)	Metadata key and value pairs. The maximum size of each metadata key and value is 255 bytes each.
server.personality	Array (Optional)	The array of personality files for the server.
server.user_data	String (Optional)	Data used with config_drive for configuring a server.
server.personality.path	String	The path of the personality file.
server.personality.contents	String	The contents of the personality file.
server.networks	Array	The array of networks attached to the server. By default, the server instance is provisioned with all isolated networks for the tenant. You can specify multiple NICs on the server. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a Nova- network network, specify the UUID in the uuid attribute in a networks object. To provision the server instance with a NIC for a Neutron network, specify the UUID in the port attribute in a networks object.
server.networks.uuid	Uuid (Optional)	The UUID of the Nova-network network attached to the server.
server.networks.port	Uuid (Optional)	The UUID of the Neutron port attached to the server.

Example Create server with disk config: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "server" : {
        "name" : "api-test-server-1",
        "imageRef" : "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
        "flavorRef" : "2",
        "config_drive": true,
        "OS-DCF:diskConfig" : "AUTO",
        "metadata" : {
            "My Server Name" : "API Test Server 1"
        },
        "personality" : [
            {
                "path" : "/etc/banner.txt",
                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ],
        "networks": [
            {
                "uuid": "4ebd35cf-bfe7-4d93-b0d8-eb468ce2245a"
            },
            {
                "uuid": "00000000-0000-0000-0000-000000000000"
            },
            {
                "uuid": "11111111-1111-1111-1111-111111111111"
            }
        ]
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	String	The URL for the server and the associated rel.
server.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
server.adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are AUTO and MANUAL.

Example Create server with disk config: JSON response

Status Code: 202 Accepted
Content-Length: 380
Content-Type: application/json
Date: Fri, 30 Jan 2015 18:38:52 GMT
Location: https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-186f2212-f4b7-4d0a-bbbb-92bc19797a1d

{
  "server": {
    "OS-DCF:diskConfig": "AUTO",
    "id": "b7509240-9ad2-4303-8614-a11a33aeb6f3",
    "links": [
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3",
        "rel": "self"
      },
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3",
        "rel": "bookmark"
      }
    ],
    "adminPass": "sYr9cptCwsLx"
  }
}

Create server with scheduler hints

POST /servers

This operation creates a server using a scheduler hint.

A scheduler hint allows a cloud server to be built near to, or far from, an existing server within a specific zone. Use either the public-zone-ip:near or the public-zone-ip:far parameter and be sure to use the server`s ID and not the server’s zone when making the request.

If a build request with a hint can not be satisfied then the build will not succeed, and the server, which will have a status of ERROR and a task state of scheduling, must be manually deleted.

A zone is a logical container for servers. The Public IP Zone is the zone in which a Public IP can be shared between two or more servers.

The public-zone-ip:near and public-zone-ip:far parameters allow you specify up to three server IP addresses, but we recommend you use just one IP address to reduce chance of failure.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request accepted.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
server.name	String	The server name.
server.imageRef	Uuid	The image reference for the desired image for your server instance.
server.block_device_mapping_v2	Object (Optional)	The container of bootable volume details.
server.block_device_mapping_v2.boot_index	Integer (Optional)	The index of the bootable volume.
server.block_device_mapping_v2.uuid	Integer (Optional)	The id of the bootable volume.
server.block_device_mapping_v2.source_type	String (Optional)	The source type for the bootable volume.
server.block_device_mapping_v2.destination_type	String (Optional)	The destination type for the bootable volume.
server.block_device_mapping_v2.delete_on_termination	Boolean (Optional)	Flag to indicate whether the bootable volume should be deleted after server creation.
server.flavorRef	Uuid (Required)	The flavor reference for the desired flavor for your server instance.
server.os:scheduler_hints	Uuid (Optional)	The container for a scheduler hint.
server.os:scheduler_hintspublic_ip_zone:near	Uuid (Optional)	An array of server IDs that new server will built near. One to three server IDs may listed.
server.os:scheduler_hintspublic_ip_zone:far	Uuid (Optional)	Alternative to public_ip_zone:near that specifies the new server should be built far from the specified server(s).
server.config_drive	String (Optional)	Enables metadata injection in a server through a configuration drive. To enable a configuration drive, specify true. Otherwise, specify false.
server.key_name	String (Optional)	The name of the key pair used to authenticate by using key-based authentication instead of password- based authentication.
server.OS-DCF:diskConfig	String (Optional)	The disk configuration value. The image auto_disk_config metadata key set will affect the value you can choose to set the server OS- DCF:diskConfig. If an image has auto_disk_config value of disabled, you cannot create a server from that image when specifying OS-DCF:diskConfig value of AUTO. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.
server.metadata	String (Optional)	Metadata key and value pairs. The maximum size of each metadata key and value is 255 bytes each.
server.personality	Array (Optional)	The array of personality files for the server.
server.user_data	String (Optional)	Data used with config_drive for configuring a server.
server.personality.path	String	The path of the personality file.
server.personality.contents	String	The contents of the personality file.
server.networks	Array	The array of networks attached to the server. By default, the server instance is provisioned with all isolated networks for the tenant. You can specify multiple NICs on the server. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a Nova- network network, specify the UUID in the uuid attribute in a networks object. To provision the server instance with a NIC for a Neutron network, specify the UUID in the port attribute in a networks object.
server.networks.uuid	Uuid (Optional)	The UUID of the Nova-network network attached to the server.
server.networks.port	Uuid (Optional)	The UUID of the Neutron port attached to the server.

Example Create server with scheduler hint: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{

   "os:scheduler_hints":{
          "public_ip_zone:near":["f841bab4-8c12-4223-a60f-76b224e053cf", "additional uuid", "additional uuid"]
   },
   "server":{
          "name":"TestIpZone2",
          "imageRef":"055143e8-2da9-439a-a52d-8063f845dec6",
          "flavorRef":"general1-1",
          "max_count":1,
          "min_count":1,
          "networks":[
                 {
                        "uuid":"00000000-0000-0000-0000-000000000000"
                 },
                 {
                        "uuid":"11111111-1111-1111-1111-111111111111"
                 }
          ]
   }
}'

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	String	The URL for the server and the associated rel.
server.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
server.adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are AUTO and MANUAL.

Example Create server with scheduler hint: JSON response

Status Code: 202 Accepted
Content-Length: 380
Content-Type: application/json
Date: Fri, 30 Jan 2015 18:38:52 GMT
Location: https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-186f2212-f4b7-4d0a-bbbb-92bc19797a1d

{
  "server": {
    "OS-DCF:diskConfig": "AUTO",
    "id": "a4209240-5ed2-4793-8614-a11a33aed22a",
    "links": [
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/v2/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3",
        "rel": "self"
      },
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/820712/servers/b7509240-9ad2-4303-8614-a11a33aeb6f3",
        "rel": "bookmark"
      }
    ],
    "adminPass": "sYr9cptCwsLx"
  }
}

Retrieve list of servers

GET /servers

Retrieves list of all servers (only IDs, names, and links).

Servers contain a status attribute that indicates the current server state. You can filter on the server status when you complete a list servers request. The server status is returned in the response body.

For a full list of possible server status values including the extended status extension ( OS-EXT-STS:power_state, OS-EXT-STS:vm_state, and OS-EXT-STS:task_state), see Extended status extension.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203 300	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This operation does not accept a request body.

Example Retrieves list of servers: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
servers	Uuid	The array of server data.
servers.id	Uuid	The ID of the server.
servers. links	Array	An array of the self and bookmark links to the server.
servers.links.href	String	The URL for the server and the associated rel.
servers.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
servers.name	String	The server name.
next	Anyuri	Moves to the next metadata item.
previous	Anyuri	Moves to the previous metadata item.

Example Retrieves list of servers: JSON response

Status Code: 200 OK
Content-Length: 1024
Content-Type: application/json
Date: Wed, 03 Dec 2014 14:40:57 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-fda78f69-d934-4ed3-a5b8-255894baa6aa

{
  "servers": [
    {
      "id": "8f64d643-f48a-459c-a7af-717dfc7580ee",
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/8f64d643-f48a-459c-a7af-717dfc7580ee",
          "rel": "self"
        },
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/8f64d643-f48a-459c-a7af-717dfc7580ee",
          "rel": "bookmark"
        }
      ],
      "name": "wordpress.myveryown.com"
    },
    {
      "id": "5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
          "rel": "self"
        },
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
          "rel": "bookmark"
        }
      ],
      "name": "DB2"
    },
    {
      "id": "d40dcb7f-2268-4fff-a592-b1944413f983",
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/d40dcb7f-2268-4fff-a592-b1944413f983",
          "rel": "self"
        },
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/d40dcb7f-2268-4fff-a592-b1944413f983",
          "rel": "bookmark"
        }
      ],
      "name": "Branwen"
    }
  ]
}

List servers with details

GET /servers/detail

This operation retrieves a detailed list of all servers in the tenant’s account.

Servers contain a status attribute that indicates the current server state. You can filter on the server status when you complete a list servers request. The server status is returned in the response body. For a full list of possible server status values, see Extended Status Extension.

The following extensions provide additional information when viewing server details:

• Config Drive:

• Scheduled Images:

• Extended Status ( OS-EXT-STS:power_state, OS-EXT-STS:vm_state, and OS-EXT-STS:task_state ):

• Block Device Mapping:

In the URI, specify the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the query parameters for the request:

Name	Type	Description
changes-since	Datetime	A time/date stamp for when the server last changed status.
image	Uuid	The image reference for the desired image for your server instance.
flavor	Uuid	The flavor reference for the desired flavor for your server instance.
name	Regexp	The name of the server, which can be queried with regular expressions. Notice that ?name=bob returns both “bob” and “bobbin”. If you need to match only “bob”, use a regular expression matching the syntax of the underlying database server implemented for Cloud Servers (such as MySQL or PostgreSQL).
marker	Uuid	The UUID of the server at which you want to set a marker.
limit	Int	The integer value used to limit the number of values which will be returned.
status	String	The status of the server. For example, you can filter on “ACTIVE”. For a full list of possible status values, see Server Status.
host	String	The name of the host.

This operation does not accept a request body.

Example List servers with details: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
servers	Object	A container of server details.
servers.accessIPv4	Ip	The public IP version 4 access address.
servers.accessIPv6	Ip	The public IP version 6 access address.
servers.addresses	Object	An object containing arrays of addresses for public, private, and isolated networks attached to the server.
servers.addresses.addr	Uuid	The IP address of the network.
servers.addresses.version	Integer	The version of the IP address of the network.
servers.id	Uuid	The ID of the server.
servers.created	Datestamp	The time stamp indicating the creation date of the server.
servers.flavor	Object	The flavor ID and links.
servers.image	Object	The image ID and links.
servers.hostId	Uuid	The host ID. The compute provisioning algorithm has an anti- affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. hostId represents the host your server runs on and can be used to determine this scenario if it is relevant to your application. HostId is unique only for an account and is not globally unique.
servers.links	Array	An array of the self and bookmark links to the server.
servers.links.href	String	The URL for the server and the associated rel.
servers.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
servers.metadata	String	Any metadata key and value pairs.
servers.name	String	The server name.
servers.progress	Integer	The build completion progress, as a percentage. Value ranges from 0 to 100.
servers.status	String	The status of the server. For a full list of possible status values, see Server Status.
servers.tenant_id	String	The tenant ID.
servers.updated	Datestamp	The time stamp of the last update.
servers.user_id	String	The user ID.
servers.OS-DCF:diskConfig	String	Extended attribute: The disk configuration value.. Valid values are AUTO and MANUAL.
servers.RAX- SI:image_schedule	String	Extended attribute: The image schedule reference is included only if scheduled images has been enabled for this server.
servers.OS-EXT-STS	String	Extended attribute. Shows the extended statuses for the server, including the VM, task, and power states.
servers.RAX-PUBLIC-IP- ZONE-ID:publicIPZoneId	Uuid	Extended attribute. Enables booting the server from a volume when additional parameters are given. If specified, the volume status must be available, and the volume attach_status must be detached.

Example List servers with details: JSON response

The following example show only one server in the list for brevity.

Status Code: 200 OK
Content-Length: 4543
Content-Type: application/json
Date: Wed, 03 Dec 2014 17:13:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-7b7ffed2-9b1f-46a8-a478-315518d35387

{
  "servers": [
    {
      "status": "ACTIVE",
      "updated": "2014-05-28T18:49:33Z",
      "hostId": "621cca5902d18b025468ae8e6bdcbbd5649a1ffe577716f267be4a93",
      "addresses": {
        "public": [
          {
            "version": 4,
            "addr": "198.61.212.87"
          },
          {
            "version": 6,
            "addr": "2001:4800:780e:0510:7e32:e3ee:ff04:ddc8"
          }
        ],
        "private": [
          {
            "version": 4,
            "addr": "10.180.19.16"
          }
        ],
        "SecureNet": [
          {
            "version": 4,
            "addr": "192.168.3.2"
          }
        ]
      },
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
          "rel": "self"
        },
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
          "rel": "bookmark"
        }
      ],
      "key_name": null,
      "image": {
        "id": "f19067a2-7233-4666-b0f2-f420a4776ff0",
        "links": [
          {
            "href": "https://dfw.servers.api.rackspacecloud.com/123456/images/f19067a2-7233-4666-b0f2-f420a4776ff0",
            "rel": "bookmark"
          }
        ]
      },
      "RAX-PUBLIC-IP-ZONE-ID:publicIPZoneId": "d12f4c3ef88ff2ca471f6b1a57d108c15db4a3478af762da6ae022b7",
      "OS-EXT-STS:task_state": null,
      "OS-EXT-STS:vm_state": "active",
      "RAX-SI:image_schedule": {
          "retention": 3
      },
      "flavor": {
        "id": "2",
        "links": [
          {
            "href": "https://dfw.servers.api.rackspacecloud.com/123456/flavors/2",
            "rel": "bookmark"
          }
        ]
      },
      "id": "5bccf43e-35fa-4d65-9390-2b2d6b23ec89",
      "user_id": "346289",
      "name": "DB2",
      "created": "2013-07-23T15:44:56Z",
      "tenant_id": "123456",
      "OS-DCF:diskConfig": "AUTO",
      "accessIPv4": "198.61.212.87",
      "accessIPv6": "2001:4800:780e:510:7e32:e3ee:ff04:ddc8",
      "progress": 100,
      "OS-EXT-STS:power_state": 1,
      "config_drive": "",
      "metadata": {}
    }
  ]
}

Show server details

GET /servers/{server_id}

Retrieves detailed information for a specified server.

The following extensions provide additional information when viewing server details:

• Config Drive:

• Scheduled Images:

• Extended Status ( OS-EXT-STS:power_state, OS-EXT-STS:vm_state, and OS-EXT-STS:task_state ):

In the URI, specify the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example Retrieve server details: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	A container of server details.
server.accessIPv4	Ip	The public IP version 4 access address.
server.accessIPv6	Ip	The public IP version 6 access address.
server.addresses	Object	An object containing arrays of addresses for public, private, and isolated networks attached to the server.
server.addresses.addr	Uuid	The IP address of the network.
server.addresses.version	Integer	The version of the IP address of the network.
server.id	Uuid	The ID of the server.
server.created	Datestamp	The time stamp indicating the creation date of the server.
server.flavor	Object	The flavor ID and links.
server.image	Object	The image ID and links.
server.hostId	Uuid	The host ID. The compute provisioning algorithm has an anti- affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. hostId represents the host your server runs on and can be used to determine this scenario if it is relevant to your application. HostId is unique only for an account and is not globally unique.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	String	The URL for the server and the associated rel.
server.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
server. metadata	String	Any metadata key and value pairs.
server.name	String	The server name.
server.progress	Integer	The build completion progress, as a percentage. Value ranges from 0 to 100.
server.status	String	The status of the server. For a full list of possible status values, see Server Status.
server.tenant_id	String	The tenant ID.
server.updated	Datestamp	The time stamp of the last update.
server.user_id	String	The user ID.
server.OS-DCF:diskConfig	String	Extended attribute: The disk configuration value. Valid values are AUTO and MANUAL.
server.RAX- SI:image_schedule	String	Extended attribute: The image schedule reference is included only if scheduled images has been enabled for this server.
server.OS-EXT-STS	String	Extended attribute. Shows the extended statuses for the server, including the VM, task, and power states.
server.RAX- PUBLIC-IP-ZONE- ID:publicIPZoneId	Uuid	Extended attribute. Enables booting the server from a volume when additional parameters are given. If specified, the volume status must be available, and the volume attach_status must be detached.

Example Retrieve server details: JSON response

Status Code: 200 Accepted
Content-Length: 380
Content-Type: application/json
Date: Thu, 04 Dec 2014 18:47:30 GMT
Location: https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-b8b54344-41a9-4d6a-c29e-60f3dcab4b1f

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "OS-EXT-STS:power_state": 1,
        "OS-EXT-STS:task_state": null,
        "OS-EXT-STS:vm_state": "active",
        "accessIPv4": "198.101.241.238",
        "accessIPv6": "2001:4800:780e:0510:d87b:9cbc:ff04:513a",
        "addresses": {
            "private": [
                {
                    "addr": "10.180.3.171",
                    "version": 4
                }
            ],
            "public": [
                {
                    "addr": "198.101.241.238",
                    "version": 4
                },
                {
                    "addr": "2001:4800:780e:0510:d87b:9cbc:ff04:513a",
                    "version": 6
                }
            ]
        },
        "created": "2012-08-16T18:41:43Z",
        "flavor": {
            "id": "2",
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/010101/flavors/2",
                    "rel": "bookmark"
                }
            ]
        },
        "hostId": "33ccb6c82f3625748b6f2338f54d8e9df07cc583251e001355569056",
        "id": "ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
        "image": {
            "id": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
                    "rel": "bookmark"
                }
            ]
        },
        "links": [
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
                "rel": "self"
            },
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/010101/servers/ef08aa7a-b5e4-4bb8-86df-5ac56230f841",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "My Server Name": "API Test Server 2"
        },
        "name": "api-test-server 2",
        "progress": 100,
        "status": "ACTIVE",
        "tenant_id": "010101",
        "updated": "2012-08-16T18:50:38Z",
        "user_id": "170454"
    }
}

Update server

PUT /servers/{server_id}

This operation updates one or more editable attributes for a specified server.

The attributes that can be edited are: name, accessIPv4, and accessIPv6. You can update any or all of the attributes in a single request.

Note

If you try to update a server by using the server bookmark link, the response code is HTTP 300, unless you use the Accept: application/json;version=1.1 header with the request.

In the URI, specify the target server ID.

In the request body, specify the element server, followed by the attribute, for example name, with the new value for that attribute. You can include one or more attributes in the server element.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
server	Object	A container for one or more server details to be updated.
server.name	String (Optional)	The server name.
server.accessIPv4	Ip (Optional)	The public IP version 4 access address.
server.accessIPv6	Ip (Optional)	The public IP version 6 access address.

Example Update server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "server" :{
       "name" : "new-test-server-1"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	A container of server details.
server.accessIPv4	Ip	The public IP version 4 access address.
server.accessIPv6	Ip	The public IP version 6 access address.
server.addresses	Object	An object containing arrays of addresses for public, private, and isolated networks attached to the server.
server.addresses.addr	Uuid	The IP address of the network.
server.addresses.version	Integer	The version of the IP address of the network.
server.id	Uuid	The ID of the server.
server.created	Datestamp	The time stamp indicating the creation date of the server.
server.flavor	Object	The flavor ID and links.
server.image	Object	The image ID and links.
server.hostId	Uuid	The host ID. The compute provisioning algorithm has an anti- affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. hostId represents the host your server runs on and can be used to determine this scenario if it is relevant to your application. HostId is unique only for an account and is not globally unique.
server.links	Array	An array of the self and bookmark links to the server.
server.links.href	String	The URL for the server and the associated rel.
server.links.rel	String	The descriptive field for the associated href, which is either self or bookmark.
server. metadata	String	Any metadata key and value pairs.
server.name	String	The server name.
server.progress	Integer	The build completion progress, as a percentage. Value ranges from 0 to 100.
server.status	String	The status of the server. For a full list of possible status values, see Server Status.
server.tenant_id	String	The tenant ID.
server.updated	Datestamp	The time stamp of the last update.
server.user_id	String	The user ID.
server.OS-DCF:diskConfig	String	Extended attribute: The disk configuration value. Valid values are AUTO and MANUAL.
server.RAX-SI:image_schedule	String	Extended attribute: The image schedule reference is included only if scheduled images has been enabled for this server.
server.OS-EXT-STS	String	Extended attribute. Shows the extended statuses for the server, including the VM, task, and power states.
server.RAX-PUBLIC-IP-ZONE- ID:publicIPZoneId	Uuid	Extended attribute. Enables booting the server from a volume when additional parameters are given. If specified, the volume status must be available, and the volume attach_status must be detached.

Example Update server: JSON response

Status Code: 200 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 04 Dec 2014 19:41:58 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-42d9-8e53-4478e2813c75

{
  "server": {
    "status": "ACTIVE",
    "updated": "2014-12-04T19:41:58Z",
    "hostId": "d535dcad0d51c97d20910a3c2a8264f0be8b847b8982e305bee27389",
    "addresses": {
      "public": [
        {
          "version": 6,
          "addr": "2001:4800:7812:514:be76:4eff:fe05:aaed"
        },
        {
          "version": 4,
          "addr": "166.78.149.149"
        }
      ],
      "private": [
        {
          "version": 4,
          "addr": "10.182.16.182"
        }
      ]
    },
    "links": [
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f",
        "rel": "self"
      },
      {
        "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/4b963871-f591-4b7d-b05f-7c0286e3c50f",
        "rel": "bookmark"
      }
    ],
    "image": {
      "id": "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
          "rel": "bookmark"
        }
      ]
    },
    "flavor": {
      "id": "2",
      "links": [
        {
          "href": "https://dfw.servers.api.rackspacecloud.com/123456/flavors/2",
          "rel": "bookmark"
        }
      ]
    },
    "id": "4b963871-f591-4b7d-b05f-7c0286e3c50f",
    "user_id": "346762",
    "name": "new-testserver-1",
    "created": "2014-12-04T18:47:30Z",
    "tenant_id": "123456",
    "OS-DCF:diskConfig": "AUTO",
    "accessIPv4": "166.78.149.149",
    "accessIPv6": "2001:4800:7812:514:be76:4eff:fe05:aaed",
    "progress": 100,
    "metadata": {
      "My Server Name": "API Test Server 1"
    }
  }
}

Delete server

DELETE /servers/{server_id}

This operation deletes the specified server.

If the operation succeeds, it returns an HTTP 202 status code with no response body.

In the URI, specify the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example Delete server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

Example Delete server: JSON response

Status Code: 204 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Create a server key pair

POST /os-keypairs

Creates a server key pair

Creates a key pair, with the name specified in the request body, to associate with a new server instance.

Important

Key Pair Naming Rules

The key name must be unique and may not exceed 255 characters. It can contain the following characters:

• alphanumeric

• spaces

• dashes

• underscores

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request accepted.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
keypair	Object	The container for the key pair request.
keypair.name	String	The name to associate with the key pair.

Example Create a server key pair: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
   "keypair":{
        "name":"name_of_keypair"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
keypair	Object	The container for the key pair details.
keypair.fingerprint	String	A short sequence of bytes used to authenticate, or look up, a longer public key.
keypair.name	String	The name of the key pair.
keypair.private_key	String	The private ssh key value.
keypair.public_key	String	The public ssh key value.
keypair. user_id	String	The ID of the user.

Example Create a server key pair: JSON response

Status Code: 200 OK
Content-Length: 2270
Content-Type: application/json
Date: Thu, 02 Apr 2015 17:54:20 GMT, Thu, 02 Apr 2015 17:54:21 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-2611a666-6693-46e0-a635-54c506eb7513

{
    "keypair": {
        "fingerprint": "35:9d:d0:c3:4a:80:d3:d8:86:f1:ca:f7:df:c4:f9:d8",
        "name": "name_of_keypair",
        "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIBAAKBgQC9mC3WZN9UGLxgPBpP7H5jZMc6pKwOoSgre8yun6REFktn/Kz7\nDUt9jaR1UJyRzHxITfCfAIgSxPdGqB/oF1suMyWgu5i0625vavLB5z5kC8Hq3qZJ\n9zJO1poE1kyD+htiTtPWJ88e12xuH2XB/CZN9OpEiF98hAagiOE0EnOS5QIDAQAB\nAoGAE5XO1mDhORy9COvsg+kYPUhB1GsCYxh+v88wG7HeFDKBY6KUc/Kxo6yoGn5T\nTjRjekyi2KoDZHz4VlIzyZPwFS4I1bf3oCunVoAKzgLdmnTtvRNMC5jFOGc2vUgP\n9bSyRj3S1R4ClVk2g0IDeagko/jc8zzLEYuIK+fbkds79YECQQDt3vcevgegnkga\ntF4NsDmmBPRkcSHCqrANP/7vFcBQN3czxeYYWX3DK07alu6GhH1Y4sHbdm616uU0\nll7xbDzxAkEAzAtN2IyftNygV2EGiaGgqLyo/tD9+Vui2qCQplqe4jvWh/5Sparl\nOjmKo+uAW+hLrLVMnHzRWxbWU8hirH5FNQJATO+ZxCK4etXXAnQmG41NCAqANWB2\nB+2HJbH2NcQ2QHvAHUm741JGn/KI/aBlo7KEjFRDWUVUB5ji64BbUwCsMQJBAIku\nLGcjnBf/oLk+XSPZC2eGd2Ph5G5qYmH0Q2vkTx+wtTn3DV+eNsDfgMtWAJVJ5t61\ngU1QSXyhLPVlKpnnxuUCQC+xvvWjWtsLaFtAsZywJiqLxQzHts8XLGZptYJ5tLWV\nrtmYtBcJCN48RrgQHry/xWYeA4K/AFQpXfNPgprQ96Q=\n-----END RSA PRIVATE KEY-----\n",
        "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9mC3WZN9UGLxgPBpP7H5jZMc6pKwOoSgre8yun6REFktn/Kz7DUt9jaR1UJyRzHxITfCfAIgSxPdGqB/oF1suMyWgu5i0625vavLB5z5kC8Hq3qZJ9zJO1poE1kyD+htiTtPWJ88e12xuH2XB/CZN9OpEiF98hAagiOE0EnOS5Q== Generated by Nova\n",
        "user_id": "fake"
    }
}

Import a server key pair

POST /os-keypairs

This operation imports, or uploads, a key pair, with the name and public key specified in the request body, to associate with a new server instance.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request accepted.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
keypair	Object	The container for the key pair request.
keypair.name	String	The name to associate with the key pair.
keypair.public_key	String	The public ssh key value.

Example Import a server key pair: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "keypair":{
        "name":"name_of_keypair",
        "public_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
keypair	Object	The container for the key pair details.
keypair.fingerprint	String	A short sequence of bytes used to authenticate, or look up, a longer public key.
keypair.name	String	The name of the key pair.
keypair.private_key	String	The private ssh key value.
keypair.public_key	String	The public ssh key value.
keypair. user_id	String	The ID of the user.

Example Import a server key pair: JSON response

Status Code: 200 OK
Content-Length: 545
Content-Type: application/json
Date: Thu, 02 Apr 2015 18:08:19 GMT, Thu, 02 Apr 2015 18:08:19 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-9efa9191-4f08-4d65-92c7-acd934e5c5b0

{
    "keypair":{
        "fingerprint":"1e:2c:9b:56:79:4b:45:77:f9:ca:7a:98:2c:b0:d5:3c",
        "name":"name_of_keypair-dab428fe-6186-4a14-b3de-92131f76cd39",
        "public_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDx8nkQv/zgGgB4rMYmIf+6A4l6Rr+o/6lHBQdW5aYd44bd8JttDCE/F/pNRr0lRE+PiqSPO8nDPHw0010JeMH9gYgnnFlyY3/OcJ02RhIPyyxYpv9FhY+2YiUkpwFOcLImyrxEsYXpD/0d3ac30bNH6Sw9JD9UZHYcpSxsIbECHw== Generated by Nova",
        "user_id":"fake"
    }
}

Retrieve list of key pairs

GET /os-keypairs

This operation retrieves a list of server key pairs.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This operation does not accept a request body.

Response

This table shows the body parameters for the response:

Name	Type	Description
keypairs	Array	An array of key pairs.
keypairs.keypair	Object	A container of key pair details.
keypairs.keypair.fingerprint	String	A short sequence of bytes used to authenticate, or look up, a longer public key.
keypairs.keypair.name	String	The name of the key pair.
keypairs.keypair.public_key	String	The public ssh key value.

Example Retrieve list of key pairs: JSON response

Status Code: 200 OK
Content-Length: 540
Content-Type: application/json
Date: Thu, 02 Apr 2015 18:09:36 GMT, Thu, 02 Apr 2015 18:09:36 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-5a9c3b9d-67cf-4b7f-b31d-0670e1c667a0

{
    "keypairs":[
        {
            "keypair":{
                "fingerprint":"15:b0:f8:b3:f9:48:63:71:cf:7b:5b:38:6d:44:2d:4a",
                "name":"name_of_keypair-601a2305-4f25-41ed-89c6-2a966fc8027a",
                "public_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC+Eo/RZRngaGTkFs7I62ZjsIlO79KklKbMXi8F+KITD4bVQHHn+kV+4gRgkgCRbdoDqoGfpaDFs877DYX9n4z6FrAIZ4PES8TNKhatifpn9NdQYWA+IkU8CuvlEKGuFpKRi/k7JLos/gHi2hy7QUwgtRvcefvD/vgQZOVw/mGR9Q== Generated by Nova\n"
            }
        }
    ]
 }

Delete key pair

DELETE /os-keypairs/{keypair_name}

This operation deletes the specified key pair. A return code of 202 indicates success.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{keypair_name}	String	The name of the key pair to be deleted.

This operation does not accept a request body.

Example Delete key pair: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

Example Delete key pair: JSON response

Status Code: 202 Accepted
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Date: Thu, 02 Apr 2015 18:06:52 GMT, Thu, 02 Apr 2015 18:06:52 GMT
Server: Jetty(9.2.z-SNAPSHOT)
Via: 1.1 Repose (Repose/6.2.1.2)
X-Compute-Request-Id: req-6b1bbebc-5b70-4775-9b1d-0e69db552b31

Attach volume to server

POST /servers/{server_id}/os-volume_attachments

This operation attaches a data volume to a specified server.

You can attach one or more volumes in a single request.

For information about creating volumes, see Rackspace Cloud Block Storage Developer Guide.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
volumeAttachment	Object	The container for the volume attachment specifications.
volumeAttachment.device	String	The name of the device, such as /dev/xvdb. Specify null for auto- assignment.
volumeAttachment.volumeId	Object	The ID of the volume that you want to attach to the server instance.

Example Attach volume to server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "volumeAttachment":{
        "device":null,
        "volumeId":"4ab50df6-7480-45df-8604-b1ee39fe857c"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
volumeAttachment	Object	The container for the volume attachment specifications.
volumeAttachment.device	String	The name of the device, such as /dev/xvdb. Specify null for auto- assignment.
volumeAttachment.Id	String	The ID of the volume that you attached to the server instance.
volumeAttachment.serverId	String	The ID of the server instance to which you attached the volume.
volumeAttachment.volumeId	String	The ID of the volume that you attached to the server instance.

Example Attach volume to server: JSON response

Status Code: 202 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 19:22:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-206e007a-9dfe-4ac4-b819-d64a74244506

{
    "volumeAttachment":{
        "device":"/dev/xvdb",
        "serverId":"76ddf257-2771-4097-aab8-b07b52110376",
        "id":"4ab50df6-7480-45df-8604-b1ee39fe857c",
        "volumeId":"4ab50df6-7480-45df-8604-b1ee39fe857c"
    }
}

List server volumes

GET /servers/{server_id}/os-volume_attachments

This operation retrieves list of all attached volumes for a specified server.

In the URI, specify the target server ID.

For information about creating volumes, see Rackspace Cloud Block Storage Developer Guide.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203 300	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example List server volumes: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
volumeAttachment	Array	The array of attached volumes.
volumeAttachments.device	String	The name of the device, such as /dev/xvdb.
volumeAttachments.Id	String	The ID of the volume attached to the server instance.
volumeAttachments.serverId	String	The ID of the server instance to which the volume is attached.
volumeAttachments.volumeId	String	The ID of the volume attached to the server instance.

Example List server volumes: JSON response

Status Code: 200 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 19:22:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-206e007a-9dfe-4ac4-b819-d64a74244506

{
    "volumeAttachments":[
        {
            "device":"/dev/xvdb",
            "serverId":"76ddf257-2771-4097-aab8-b07b52110376",
            "id":"4ab50df6-7480-45df-8604-b1ee39fe857c",
            "volumeId":"4ab50df6-7480-45df-8604-b1ee39fe857c"
        }
    ]
}

Show volume attachment details

GET /servers/{server_id}/os-volume_attachments/{attachment_id}

This operation retrieves volume details for the specified server ID and volume attachment ID

In the URI, specify the target server ID and the target attached volume ID to see details for that volume.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{attachment_id}	Uuid	The volume attachment ID.

This operation does not accept a request body.

Example Show volume attachment details: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
volumeAttachment	Object	The container for the volume attachment specifications.
volumeAttachment.device	String	The name of the device, such as /dev/xvdb. Specify null for auto- assignment.
volumeAttachment.Id	String	The ID of the volume that you attached to the server instance.
volumeAttachment.serverId	String	The ID of the server instance to which you attached the volume.
volumeAttachment.volumeId	String	The ID of the volume that you attached to the server instance.

Example Show volume attachment details: JSON response

Status Code: 200 OK
Content-Length: 32
Content-Type: application/json
Date: Tue, 20 Jan 2015 14:25:02 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-96b3fdf4-a6d9-42ce-91bb-2cea8eb5e14e

{
    "volumeAttachment":{
        "device":"/dev/xvdb",
        "serverId":"76ddf257-2771-4097-aab8-b07b52110376",
        "id":"4ab50df6-7480-45df-8604-b1ee39fe857c",
        "volumeId":"4ab50df6-7480-45df-8604-b1ee39fe857c"
    }
}

Delete volume attachment from a server

DELETE /servers/{server_id}/os-volume_attachments/{volume_id}

This operation deletes the specified volume attachment from the specified server.

If the operation succeeds, it returns an HTTP 202 status code with no response body.

In the URI, specify the target server ID and the target attached volume ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{volume_id}	Uuid	The volume attachment ID.

This operation does not accept a request body.

Example Delete volume attachment from server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

Example Delete volume attachment from server: JSON response

Status Code: 202 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 23:19:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-406a007a-9dfe-4ac4-b819-d64a74244506

Create bootable volume and server

POST /servers

This operation creates a bootable volume and boots a server in one step.

The full URL to the newly created server is returned through the Location header and is available as a self and bookmark link in the server representation.

The progress of the server build depends on factors including location of the requested image, network i/o, host load, and the selected flavor. You can check the progress of the build request by issuing a call to retrieve the details of the server. After the build completes, the server’s status is ACTIVE.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the body parameters for the request:

Name	Type	Description
server.name	String	The server name.
server.imageRef	Uuid	The image reference for the desired image for your server instance.
server.block_device_mapping_v2	Object	The container of bootable volume details.
server.block_device_mapping_v2.boot_index	Integer	The index of the bootable volume.
server.block_device_mapping_v2.uuid	Integer	The id of the bootable volume.
server.block_device_mapping_v2.source_type	String	The source type for the bootable volume. Must be volume.
server.block_device_mapping_v2.destination_type	String	The destination type for the bootable volume.
server.block_device_mapping_v2.delete_on_termination	Boolean	Flag to indicate whether the bootable volume should be deleted after server creation.
server.flavorRef	Uuid	The flavor reference for the desired flavor for your server instance.
server.config_drive	String (Optional)	Enables metadata injection in a server through a configuration drive. To enable a configuration drive, specify true. Otherwise, specify false.
server.key_name	String (Optional)	The name of the key pair used to authenticate by using key-based authentication instead of password- based authentication.
server.OS-DCF:diskConfig	String (Optional)	The disk configuration value. The image auto_disk_config metadata key set affects the value you can choose to set the server OS- DCF:diskConfig. If an image has auto_disk_config value of disabled, you cannot create a server from that image when specifying OS-DCF:diskConfig value of AUTO. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.
server.metadata	String (Optional)	Metadata key and value pairs. The maximum size of each metadata key and value is 255 bytes each.
server.personality	Array (Optional)	The array of personality files for the server.
server.user_data	String (Optional)	Data used with config_drive for configuring a server.
server.personality.path	String	The path of the personality file.
server.personality.contents	String	The contents of the personality file.
server.networks	Array	The array of networks attached to the server. By default, the server instance is provisioned with all isolated networks for the tenant. You can specify multiple NICs on the server. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a Nova- network network, specify the UUID in the uuid attribute in a networks object. To provision the server instance with a NIC for a Neutron network, specify the UUID in the port attribute in a networks object.
server.networks.uuid	Uuid (Optional)	The UUID of the Nova-network network attached to the server.
server.networks.port	Uuid (Optional)	The UUID of the Neutron port attached to the server.

Example Create bootable volume and server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "server":{
        "name":"BFVServer5",
        "imageRef":"",
        "block_device_mapping_v2":[
            {
                "boot_index":"0",
                "uuid":"bb02b1a3-bc77-4d17-ab5b-421d89850fca",
                "volume_size":"100",
                "source_type":"image",
                "destination_type":"volume",
                "delete_on_termination":false
            }
        ],
        "flavorRef":"compute1-15",
        "max_count":1,
        "min_count":1,
        "networks":[
            {
                "uuid":"00000000-0000-0000-0000-000000000000"
            },
            {
                "uuid":"11111111-1111-1111-1111-111111111111"
            }
        ]
    }
  }

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Uuid	An array of the self and bookmark links to the server.
server.links.href	Uuid	The URL for the server and the associated rel.
server.links.rel	Uuid	The descriptive field for the associated href, which is either self or bookmark.
server.adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are AUTO and MANUAL.

Example Create bootable volume and server: JSON response

{
   "server":{
      "OS-DCF:diskConfig":"MANUAL",
      "id":"42f9607f-41c4-48e5-8206-2732aee9456b",
      "links":[
         {
            "href":"https://iad.servers.api.rackspacecloud.com/v2/596067/servers/42f9607f-41c4-48e5-8206-2732aee9456b",
            "rel":"self"
         },
         {
            "href":"https://iad.servers.api.rackspacecloud.com/596067/servers/42f9607f-41c4-48e5-8206-2732aee9456b",
            "rel":"bookmark"
         }
      ],
      "adminPass":"pass"
   }
}

Retrieve list of server actions

GET /servers/{server_id}/os-instance-actions

This operation retrieves a list of available server actions.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example Retrieve list of server actions: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
instanceActions	Array	An array of instance action containers of action log entries for a server.
instanceActions.action	String	The type of action taken.
instanceActions.instance_uuid	Uuid	The server UUID where the action took place.
instanceActions.message	Uuid	The action log message, if any.
instanceActions.project_id	Uuid	The project id.
instanceActions. request_id	Uuid	The action request id.
instanceActions.start_time	Datetime	The date and time that the actin began.
instanceActions.user_id	String	The id of the user who requested the action.

Example Retrieve list of server actions: JSON response

{
    "instanceActions": [
        {
            "action": "reboot",
            "instance_uuid": "86cf2416-aaa7-4579-a4d7-0bfe42bfa8ff",
            "message": null,
            "project_id": "453265",
            "request_id": "req-7b6f6a5e-daf7-483e-aea5-a11993d1d357",
            "start_time": "2013-08-15T21:40:42.000000",
            "user_id": "35746"
        },
        {
            "action": "create",
            "instance_uuid": "86cf2416-aaa7-4579-a4d7-0bfe42bfa8ff",
            "message": null,
            "project_id": "453265",
            "request_id": "req-920c6627-c8c9-4d02-9d3d-81917e5586df",
            "start_time": "2013-07-12T21:35:37.000000",
            "user_id": "35746"
        }
    ]
}

Retrieve log details for a specified server action

GET /servers/{server_id}/os-instance-actions/{request-id}

This operation retrieves the log details for a specified server action.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{request_id}	Uuid	The server action request id.

This operation does not accept a request body.

Example Retrieve log details for a specified server action: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
instanceAction	Object	An container of instance action log entry data for a specific server and action.
instanceAction.action	String	The type of action taken.
instanceAction.instance_uuid	Uuid	The server UUID where the action took place.
instanceAction.message	Uuid	The action log message, if any.
instanceAction.project_id	Uuid	The project id.
instanceAction.request_id	Uuid	The action request id.
instanceAction.request_id	Datetime	The date and time that the actin began.
instanceAction.user_id	String	The id of the user who requested the action.

Example Retrieve log details for a specified server action: JSON response

{
     "instanceAction": {
        "action": "create",
        "instance_uuid": "86cf2416-aaa7-4579-a4d7-0bfe42bfa8ff",
        "message": null,
        "project_id": "453265",
        "request_id": "req-920c6627-c8c9-4d02-9d3d-81917e5586df",
        "start_time": "2013-07-12T21:35:37.000000",
        "user_id": "35746"
     }
}

Change password for specified server

POST /servers/{server_id}/action

This operation changes the admin password, or root password, for the specified server.

Note

OnMetal servers must be created using ssh key pairs. You should neither use nor modify the administrator password generated by the server build operation.

In the URI, specify the target server ID.

In the request body, specify the action changePassword, followed by the adminPass attribute with the new password.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
changePassword	Object	Specification of the changePassword action for the specified server
changePassword.adminPass	Object	The new adminstrator password. Though Rackspace does not enforce complexity requirements for the password, the operating system might. If the password is not complex enough, the server might enter an ERROR state.

Example Change password for specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "changePassword":
    {
        "adminPass": "Test1234"
    }
}

Response

Example Change password for specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Reset network for server

POST /servers/{server_id}/action

This operation resets the network to default for a server that you own.

Warning

Do not issue this call for a RackConnect v2 server. The call breaks RackConnect v2.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
resetNetwork	Object	Specification of the reset network action for the specified server. The key pair value is always null.

Example Reset network for specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "resetNetwork" : null
}

Response

This operation does not return a response body.

Example Reset network for specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

Reboot specified server

POST /servers/{server_id}/action

This operation performs a soft or hard reboot of the specified server. A soft reboot is a graceful shutdown and restart of your server’s operating system. A hard reboot power cycles your server, which performs an immediate shutdown and restart.

Specify the target server ID in the URI.

In the request body, specify the action reboot, optionally followed by the type attribute, either HARD or SOFT.

If you do not include the type attribute, a soft reboot is performed by default.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
reboot	Object	Specification of the reboot action for the specified server.
reboot.type	Object (Optional)	The type of reboot. Valid reboot types are: SOFTThe operating system is signaled to restart, which allows for a graceful shutdown and restart of all processes. HARDPower cycles your server, which performs an immediate shutdown and restart.

Example Reboot specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "reboot" :
    {
        "type" : "HARD"
    }
}

Response

Example Reboot specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Rebuild specified server

POST /servers/{server_id}/action

This operation rebuilds the specified server.

The rebuild operation removes all data on the server and replaces it with the specified image. The serverID and all IP addresses remain the same. If you specify name, metadata, accessIPv4, or accessIPv6 in the rebuild request, new values replace existing values. Otherwise, these values do not change. You can inject data into the file system during the rebuild.

Note

This operation is not available for OnMetal servers.

Specify the target server ID in the URI.

In the request body, specify the rebuild action followed by various attributes, listed in the following parameters section.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
rebuild	Object	Specification of the rebuild action for the specified server.
rebuild.name	Object (Optional)	The new name for the server.
rebuild.imageRef	Object	The image ID.
rebuild.accessIPv4	Object (Optional)	The IP version 4 address.
rebuild.accessIPv6	Object (Optional)	The IP version 6 address.
rebuild.adminPass	String (Optional)	The password assigned to provide login access to the server.
rebuild.metadata	String (Optional)	A metadata key and value pair.
rebuild.personality	String (Optional)	The file path and file contents.
rebuild.OS- DCF:diskConfig	String (Optional)	The disk configuration value. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.

Example Rebuild specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "rebuild" :{
        "name" : "new-server-test",
        "imageRef" : "d42f821e-c2d1-4796-9f07-af5ed7912d0e",
        "OS-DCF:diskConfig" : "AUTO",
        "adminPass" : "diane123",
        "metadata" : {
            "My Server Name" : "Apache1"
        },
        "personality" : [
            {
                "path" : "/etc/banner.txt",
                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
            }
        ]
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
server	Object	The container for server data.
server.id	Uuid	The ID of the server.
server.links	Uuid	An array of the self and bookmark links to the server.
server.links. href	Uuid	The URL for the server and the associated rel.
server.links.rel	Uuid	The descriptive field for the associated href, which is either self or bookmark.
server. adminPass	String	The password assigned to provide login access to the server.
server.OS- DCF:diskConfig	String	The disk configuration value. Valid values are AUTO and MANUAL.

Example Rebuild specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 04 Dec 2014 19:41:58 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-42d9-8e53-4478e2813c75

{
    "server": {
        "OS-DCF:diskConfig": "AUTO",
        "accessIPv4": "50.56.175.199",
        "accessIPv6": "2001:4800:780e:0510:d87b:9cbc:ff04:35f7",
        "addresses": {
            "private": [
                {
                    "addr": "10.180.12.68",
                    "version": 4
                }
            ],
            "public": [
                {
                    "addr": "2001:4800:780e:0510:d87b:9cbc:ff04:35f7",
                    "version": 6
                },
                {
                    "addr": "50.56.175.199",
                    "version": 4
                }
            ]
        },
        "adminPass": "diane123",
        "config_drive": "",
        "created": "2012-07-23T20:20:04Z",
        "flavor": {
            "id": "6",
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/123456/flavors/6",
                    "rel": "bookmark"
                }
            ]
        },
        "hostId": "791b847459d001f02f65f23ea82ae32c4b320ad34a3f892b7593c01f",
        "id": "32406068-8539-40ab-bdd3-8140d30823ad",
        "image": {
            "id": "d42f821e-c2d1-4796-9f07-af5ed7912d0e",
            "links": [
                {
                    "href": "https://dfw.servers.api.rackspacecloud.com/123456/images/d42f821e-c2d1-4796-9f07-af5ed7912d0e",
                    "rel": "bookmark"
                }
            ]
        },
        "links": [
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/v2/123456/servers/32406068-8539-40ab-bdd3-8140d30823ad",
                "rel": "self"
            },
            {
                "href": "https://dfw.servers.api.rackspacecloud.com/123456/servers/32406068-8539-40ab-bdd3-8140d30823ad",
                "rel": "bookmark"
            }
        ],
        "metadata": {
            "My Server Name": "Apache1"
        },
        "name": "new-server-test",
        "progress": 0,
        "status": "REBUILD",
        "tenant_id": "123456",
        "updated": "2012-07-26T16:09:16Z",
        "user_id": "170454"
    }
}

Resize specified server

POST /servers/{server_id}/action

This operation converts an existing Standard server to a different flavor, which scales the server up or down. The original server is saved for a period of time to allow roll back if a problem occurs. You should test and explicitly confirm all resizes. When you do so, the original server is removed. All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.

Note

This operation is not available for OnMetal servers.

Warning

The following list shows the availability of the resize operation for the flavor classes and server types:

• Standard flavor Linux servers that use the deprecated paravirtual (PV) virtualization mode: Can only resize down.

• All other flavors: Can only resize up.

If you have a Compute, Memory, or IO flavor server, and you need to change the size of your data disk(s), you will need to:

1. Image your system disk.

2. Back-up your data disk(s), using Cloud Backup or Cloud Block Storage.

3. Create a new server with the desired size and flavor class, using your image.

4. Add your backed-up data to the new data disk(s).

5. Delete the old server, once you are satisfied with the new server.

Specify the target server ID in the URI.

In the request body, specify the resize action followed by attributes.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
resize	Object	Specification of the resize action for the specified server.
resize.flavorRef	Object	The flavorRef for the new server.
resize.OS- DCF:diskConfig	String (Optional)	The disk configuration value. Valid values are: AUTO:The server is built with a single partition which is the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. AUTO is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images. MANUAL:The server is built using the partition scheme and file system of the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and it enables you to manage the disk configuration.

Example Resize specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "resize" : {
        "flavorRef" : "3",
        "OS-DCF:diskConfig" : "manual"
    }
}

Response

Example Resize specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Confirm server resize for specified server

POST /servers/{server_id}/action

This operation confirms the server resize for the specified server.

During a resize operation, the original server is saved for a period of time to allow roll back if a problem occurs. After you verify that the newly resized server works properly, use this operation to confirm the resize. After you confirm the resize, the original server is removed, and you cannot roll back to that server. All resizes are automatically confirmed after 24 hours, if you do not explicitly confirm, or revert, the resize.

Note

This operation is not available for OnMetal servers.

Specify the target server ID in the URI.

In the request body, specify the confirmResize action.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
confirmResize	Object	Specification of the confirmResize action for the specified server.

Example Confirm server resize for specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "confirmResize" : null
}

Response

Example Confirm server resize for specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Revert server resize for specified server

POST /servers/{server_id}/action

This operation reverts the server resize for the specified server.

During a resize operation, the original server is saved for a period of time to allow for roll back if a problem occurs. If you determine that a problem exists with a newly resized server, use this operation to revert the resize and roll back to the original server. All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.

Note

This operation is not available for OnMetal servers.

Specify the target server ID in the URI.

In the request body, specify the revertResize action.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
revertResize	Object	Specification of the revertResize action for the specified server.

Example Revert server resize for specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "revertResize" : null
}

Response

Example Revert server resize for specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Migrate specified server

POST /servers/{server_id}/action

This operation migrates the server to a different hypervisor host within the Rackspace Cloud in the same region without changing the server’s data and IP addresses.

During a migration, the server’s status changes to RESIZING because the migration function uses the resize operation to migrate the server. The original server is saved for 24 hours to allow rollback. You should test and explicitly confirm all migrations. After you confirm, the original server is removed. If you do not explicitly confirm or revert the migration, all migrations are automatically confirmed after 24 hours

Note

This operation is not available for OnMetal servers.

Specify the target server ID in the URI.

In the request body, specify the migrate action followed by attributes.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
migrate	Object	Specification of the migrate action for the specified server.

Example migrate specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "migrate" : {
    }
}

Response

Example Migrate specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Create image of specified server

POST /servers/{server_id}/action

This operation creates a new image for a specified server. Once complete, you can use your new image to rebuild or create servers. The full URL to the newly created image is returned through the Location header. You can retrieve additional attributes for the image including its creation status by issuing a subsequent GET on that URL.

Image creation is an asynchronous operation, so coordinating the creation with data quiescence, and so on, is currently not possible.

Note

This operation is not available for OnMetal servers.

In addition to creating images manually, you may also schedule images of your server automatically.

Specify the target server ID in the URI.

In the request body, specify the createImage action, followed by attributes.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
createImage	Object	Specification of the createImage action for the specified server.
createImage.name	String	The name of the new image.
createImage.metadata	Object	The container of the metadata for the new image.
createImage.meta	Object	A metadata keypair, specifying ImageType or ImageVersion, for example.

Example Create image of specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "createImage" : {
        "name" : "new-image",
        "metadata": {
            "ImageType": "Gold",
            "ImageVersion": "2.0"
        }
    }
}

Response

Example Create image of specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Rescue specified server

POST /servers/{server_id}/action

This operation puts a server into rescue mode.

You might enter rescue mode to reboot a virtual machine (VM) in rescue mode so that you can access the VM with a new root password and fix any file system and configuration errors.

Or you might enter rescue mode to debug system issues that prevent you from booting a server to a usable state.

When you place a server in rescue mode, the following events occur:

1. The VM is shut down.

2. A new VM is created with the following images attached:

   Primary image Cleanly running VM based on the image from which the original server was created, with a random password. This password is returned to you in a response to issuing the rescue mode API call. Use this clean image to boot the server and fix any problems.

   Secondary disk Image of the VM that needs to be rescued.

When you put a server into rescue mode, you cannot use it until its status goes from ACTIVE to RESCUE. This does not happen immediately.

For a full list of possible server status values, see Server Status.

Note

The SSH server key will be different on the rescue image than on the original server.

Specify the target server ID in the URI.

After you resolve any problems and reboot the rescued server, you can unrescue the server. The unrescue operation restores the repaired image to running state with its original password.

In the request body, specify the rescue action.

Note

If you use {"rescue": "none"} in the request body, the API will attempt to build the rescue mode server from whatever the image_base_image_ref field is set to in Nova DB (the original image used to build the server, normally).

If, instead, you use {"rescue": {"rescue_image_ref": " < imageID > "}}, the API uses the specified image for the rescue mode instance. This is extremely useful if the image originally used to build the server is now either non-functional or has been deleted.

The following extension provides additional rescue with image functionality.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
rescue	Object	Specification of the rescue action for the specified server.

Example Rescue specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "rescue" : "none"
}

Example Rescue specified server with image: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "rescue" :
        {
            "rescue_image_ref": "c11e2d37-bd93-44f0-b17e-bb87d1022975"
        }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
adminPass	Object	The new adminstrator password.

Example Rescue specified server (same for both requests): JSON request

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

{
  "adminPass": "m7UKdGiKFpqM"
}

Unrescue specified server

POST /servers/{server_id}/action

This operation takes the specified server out of rescue mode.

After you resolve any problems and reboot a rescued server, you can unrescue the server. Specify the unrescue action in the request body. When you unrescue the server, the repaired image is restored to its running state with your original password.

You can exit rescue mode at any time.

Specify the target server ID in the URI.

In the request body, specify the unrescue action.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Successful	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
unrescue	Object	Specification of the unrescue action for the specified server.

Example Unrescue specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "unrescue" : null
}

Response

Example Unrescue specified server: JSON response

Status Code: 202 No Content
Content-Length: 0
Content-Type: application/json
Date: Thu, 04 Dec 2014 21:45:47 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id

Lock specified server

POST /servers/{server_id}/action

This operation locks a server that you own.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
lock	Object	Specification of the lock action for the specified server. The key pair value is always null.

Example Lock specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "lock" : null
}

Response

This operation does not return a response body.

Example Lock specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

Unlock specified server

POST /servers/{server_id}/action

This operation unlocks a locked server.

Note

You must have administrator privileges, assigned by the cloud provider, to unlock a server that was locked by an administrator.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
unlock	Object	Specification of the unlock action for the specified server. The key pair value is always null.

Example Unlock specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "unlock" : null
}

Response

This operation does not return a response body.

Example Unlock specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

Start specified server

POST /servers/{server_id}/action

This operation starts a stopped server, and changes its status to ACTIVE.

Note

Prior to running this command, the server status must be SHUTTOFF.

If the server status is LOCKED, you must have administrator privileges to start the server.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
os-start	Object	Specification of the start action for the specified server. The key pair value is always null.

Example Start specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "os-start" : null
}

Response

This operation does not return a response body.

Example Start specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

Stop specified server

POST /servers/{server_id}/action

This operation stops a running server, and changes the server status to SHUTOFF and changes the clean_shutdown parameter to TRUE.

Note

Prior to running this command, the server status must be either ACTIVE or ERROR.

If the server status is LOCKED, you must have administrator privileges to stop the server.

Warning

The owner of the server will continue to be billed even if a server is stopped. To stop getting billed, delete the server

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
os-stop	Object	Specification of the stop action for the specified server. The key pair value is always null.

Example Stop specified server: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "os-stop" : null
}

Response

This operation does not return a response body.

Example Stop specified server: JSON response

Status Code: 202 OK
Content-Length: 1250
Content-Type: application/json
Date: Thu, 10 Dec 2014 19:43:18 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-8c905dfe-2c9a-17e5-8e53-4478e2813c75

Retrieves list of server addresses

GET /servers/{server_id}/ips

This operation retrieves a list of all server and network addresses associated with the specified server.

In the URI, specify the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example Retrieves list of server addresses: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
addresses	Object	A container for one or more server details to be updated.
addresses.nettype	Object	An array of private or public network address containers.
addresses.nettype.addr	Object	The IP address.
addresses.nettype.version	Object	The IP address version, either 4 or 6.

Example Retrieves list of server addresses: JSON response

Status Code: 200 OK
Content-Length: 191
Content-Type: application/json
Date: Fri, 12 Dec 2014 16:37:29 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
X-Compute-Request-Id: req-624fa036-8f73-4ca9-aa22-428df756c578

{
  "addresses": {
    "public": [
      {
        "version": 6,
        "addr": "2001:4800:7817:0104:7e32:e3ee:ff04:930f"
      },
      {
        "version": 4,
        "addr": "23.253.107.140"
      }
    ],
    "private": [
      {
        "version": 4,
        "addr": "10.208.196.170"
      }
    ]
  }
}

Retrieve list of network addresses for server and network

GET /servers/{server_id}/ips/{network_label}

This operation retrieves a list of all server and network addresses associated with the specified server and network.

In the URI, specify the target server ID and target network type ( public or private ).

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{network_label}	String	The network label, such as public or private.

This operation does not accept a request body.

Example Retrieves list of network addresses for server and network: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
nettype	Array	An array of private or public network address containers.
nettype.addr	Object	The IP address.
nettype.version	Object	The IP address version, either 4 or 6.

Example Retrieves list of network addresses for server and network: JSON response

Status Code: 200 OK
Content-Length: 121
Content-Type: application/json
Date: Fri, 12 Dec 2014 16:59:57 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
X-Compute-Request-Id: req-00daae97-384b-4a57-806c-dd8d2d635287

{
  "public": [
    {
      "version": 6,
      "addr": "2001:4800:7817:0104:7e32:e3ee:ff04:930f"
    },
    {
      "version": 4,
      "addr": "23.253.107.140"
    }
  ]
}

List server metadata

GET /servers/{server_id}/metadata

This operation retrieves a list of all metadata for a specified server.

In the URI, specify the target server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This operation does not accept a request body.

Example List server metadata: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
metadata	Object	Container for a metadata keypair for the specified server. This container holds one or more keypairs using format of “metadata key” : “metadata value”.
metadata.keyname	Keypair	Keypairs edcribing the metadata using format of “keyname” : “keyvalue”.

Example List server metadata: JSON response

Status Code: 200 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 19:22:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-206e007a-9dfe-4ac4-b819-d64a74244506

{
    "metadata": {
        "Label" : "Web",
        "Version" : "2.1"
    }
}

Set server metadata

PUT /servers/{server_id}/metadata

This operation creates or replaces metadata items for a specified server

You can add or update one or more new metadata items in a single request.

If metadata items in the request body do not exist, they are created. If they do exist, they are replaced.

Important

Existing metadata items are replaced with the ones provided in the request regardless of the names of the original metadata items.

If you exceed the maximum number of metadata items in the request, the call throws an overLimit (413) fault. To find the maximum number of key-value pairs that can be supplied for each server, use the maxServerMeta absolute limit query.

In the URI, specify the target server ID.

In the request body, specify the metadata element, followed by the new metadata key, for example version, with the value for that key.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
metadata	Object	Container for a metadata keypair for the specified server. This container holds one or more keypairs using format of “metadata key” : “metadata value”.
metadata.keyname	Keypair	Keypairs edcribing the metadata using format of “keyname” : “keyvalue”.

Example Set server metadata: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "metadata": {
        "Label" : "Web",
        "Version" : "2.1"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
metadata	Object	Container for a metadata keypair for the specified server. This container holds one or more keypairs using format of “metadata key” : “metadata value”.
metadata.keyname	Keypair	Keypairs edcribing the metadata using format of “keyname” : “keyvalue”.

Example Set server metadata: JSON response

Status Code: 200 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 19:22:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-206e007a-9dfe-4ac4-b819-d64a74244506

{
    "metadata": {
        "Label" : "Web",
        "Version" : "2.1"
    }
}

Update server metadata

POST /servers/{server_id}/metadata

This operation updates metadata items by key for a specified server.

You can update one or more metadata items that you previously added in a single request, but you should avoid changing metadata items that you did not add. The operation replaces existing metadata items with the same key. Items that are not explicitly mentioned in the request are not modified.

If you exceed the maximum number of metadata items in the request, the call throws an overLimit (413) fault. To find the maximum number of key-value pairs that can be supplied for each server, use the maxServerMeta absolute limit query.

In the URI, specify the target server ID.

In the request body, specify the metadata element, followed by the metadata key, for example version, with the new value for that key.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.

This table shows the body parameters for the request:

Name	Type	Description
parameters.metadata	Object	Container for a metadata keypair for the specified server. This container holds one or more keypairs using format of “metadata key” : “metadata value”.
parameters.metadata.keyname	Keypair	Keypairs edcribing the metadata using format of “keyname” : “keyvalue”.

Example Updates server metadata: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "metadata": {
        "Label" : "Web2"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
metadata	Object	Container for a metadata keypair for the specified server. This container holds one or more keypairs using format of “metadata key” : “metadata value”.
metadata.keyname	Keypair	Keypairs edcribing the metadata using format of “keyname” : “keyvalue”.

Example Updates server metadata: JSON response

Status Code: 200 OK
Content-Length: 32
Content-Type: application/json
Date: Mon, 19 Jan 2015 20:29:25 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-c342acf1-cd7e-4c88-84cc-dcbca523fc08

{
    "metadata" : {
        "Label" : "Web2",
        "Version" : "2.1"
    }
}

Show server metadata item details

GET /servers/{server_id}/metadata/{key}

Retrieves a metadata item by key for a specified server.

In the URI, specify the target server ID and the target metadata key.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200 203 300	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{key}	Metadatakey	The name of the target key in a metadata key pair. A string with maximum length of 255 characters.

This operation does not accept a request body.

Example Show server metadata item details: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

This table shows the body parameters for the response:

Name	Type	Description
meta	Object	Container for a metadata keypair for the specified server. This container holds a single keypair using format of “metadata key” : “metadata value”.
meta.keyname	Keypair	Keypair describing the metadata using format of “keyname” : “keyvalue”.

Example Show server metadata item details: JSON response

Status Code: 200 OK
Content-Length: 32
Content-Type: application/json
Date: Tue, 20 Jan 2015 14:07:57 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-85a2fdf4-a6d9-42ce-91bb-2cea8eb5e14e

{
    "meta" : {
        "Label" : "Web"
    }
}

Set server metadata item

PUT /servers/{server_id}/metadata/{key}

This operation creates or replaces metadata item by key for a specified server

In the URI, specify the target server ID and the target metadata key.

In the request body, specify the meta element, followed by the metadata key, for example version, with the new value for that key.

Note

The key specified in the request body must match the key specified in the URI request.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{key}	Metadatakey	The name of the target key in a metadata key pair. A string with maximum length of 255 characters.

This table shows the body parameters for the request:

Name	Type	Description
meta	Object	Container for a metadata keypair for the specified server. This container holds a single keypair using format of “metadata key” : “metadata value”.
meta.keyname	Keypair	Keypair describing the metadata using format of “keyname” : “keyvalue”.

Example Set server metadata item: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

{
    "meta" : {
        "Label" : "Web"
    }
}

Response

This table shows the body parameters for the response:

Name	Type	Description
meta	Object	Container for a metadata keypair for the specified server. This container holds a single keypair using format of “metadata key” : “metadata value”.
meta.keyname	Keypair	Keypair describing the metadata using format of “keyname” : “keyvalue”.

Example Set server metadata item: JSON response

Status Code: 200 OK
Content-Length: 32
Content-Type: application/json
Date: Tue, 20 Jan 2015 14:25:02 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-96b3fdf4-a6d9-42ce-91bb-2cea8eb5e14e

{
    "meta" : {
        "Label" : "Web"
    }
}

Delete server metadata item

DELETE /servers/{server_id}/metadata/{key}

This operation deletes a metadata item by key from the specified server.

If the operation succeeds, it returns an HTTP 202 status code with no response body.

In the URI, specify the target server ID and the target metadata key.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Delete Successful	Delete request succeeded.
400	Error	A general error has occured.
401	Unauthorized	Unauthorized.
403	Forbidden	Forbidden.
405	Bad Method	Bad method.
409	Conflicting Reqest	Conflicting request.
413	Over Limit	The number of items returned is above the allowed limit.
500	API Fault	API fault.
503	Service Unavailable	The requested service is unavailable.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{server_id}	Uuid	The UUID for the server.
{key}	Metadatakey	The name of the target key in a metadata key pair. A string with maximum length of 255 characters.

This operation does not accept a request body.

Example Delete server metadata item: JSON request

X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Content-Type: application/json
Accept: application/json

Response

Example Delete server metadata item: JSON response

Status Code: 204 OK
Content-Length: 120
Content-Type: application/json
Date: Mon, 19 Jan 2015 23:19:30 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
Via: 1.1 Repose (Repose/2.12)
x-compute-request-id: req-406a007a-9dfe-4ac4-b819-d64a74244506