Buy Now
  • Rackspace Cloud
  • Email & Apps
  • Fanatical Support for AWS
  • Managed Google Cloud Platform
  • Office 365
Login
  • MyRackspace Portal
  • Cloud Control Panel
  • Rackspace Webmail Login
  • Cloud Office Control Panel
  • Developer Home
  • Developer Documentation
  •  Blogs 
    • Expert Insights Tech Blog
    • Rackspace Blog
    • Solve: Thought Leadership
  • Support Documentation

Developer Docs


Let's build something powerful together!

End-to-End Multicloud Solutions.   Solving Together.™   Learn more at Rackspace.com

Submit an issue
  • Cloud Servers 2.0
  • Getting started
    • Get your credentials
    • Send API requests to Cloud Servers
      • Install CLI client and Cloud Servers Virtual Interface extension
        • Install the nova client
        • Install the Cloud Networks Virtual Interface extension
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Authenticating by using the nova client
      • Authenticating by using cURL
        • Send an authentication request
        • Review the authentication response
        • Configure environment variables
    • Cloud Servers Concepts
      • How Cloud Servers work
    • Create your first server
      • Listing images
        • Listing images (nova client)
        • Listing images (cURL)
      • Listing flavors
        • Listing flavors (nova client)
        • Listing flavors (cURL)
      • Booting a new server with your cloud network
        • Booting server (nova client)
        • Booting server (cURL)
      • Getting server details
        • Getting server details (nova client)
        • Getting server details (cURL)
      • Listing servers
        • Listing servers (nova client)
        • Listing servers (cURL)
      • Deleting your cloud server
        • Deleting server (nova client)
        • Deleting server (cURL)
    • Create your first network
      • Creating network
        • Creating network (nova client)
        • Creating network (cURL)
      • Listing flavors
        • Listing networks (nova client)
        • Listing networks (cURL)
      • Booting a new server with your cloud network
        • Booting server with network (nova client)
        • Booting server with network (cURL)
      • Getting network details
        • Getting network details (nova client)
        • Getting network details (cURL)
      • Deleting your cloud network
        • Deleting network (nova client)
        • Deleting network (cURL)
    • Attach your network to an existing server
      • Creating a virtual interface
        • Creating a virtual interface (nova client)
        • Creating a virtual interface (cURL)
      • Listing virtual interfaces for a server
        • Listing virtual interfaces (nova client)
        • Listing virtual interfaces (cURL)
      • Deleting a virtual interface from a server
        • Deleting a virtual interface (nova client)
        • Deleting a virtual interface (cURL)
  • General API information
    • Service access endpoints
    • Request and response types
    • Links and References
    • Paginated collections
      • JSON Collection
    • Efficient Polling with the Changes-Since Parameter
    • Limits
      • Rate Limits
      • Absolute Limits
    • Quotas
    • Faults
      • Synchronous Faults
      • Asynchronous Faults
      • badRequest
      • itemNotFound
      • overLimit
      • serviceUnavailable
      • unauthorized
    • Date and time format
    • Flavors
      • Virtual Cloud Server Flavors
      • OnMetal Cloud Server Flavors
      • Supported Flavors for Cloud Servers
    • Role-based access control (RBAC)
      • Assigning roles to account users
      • Roles available for Cloud Servers
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Cloud Servers API operations
  • API extensions
    • Rackspace Extensions
    • Disk Configuration Extension
      • Changes to Get Server/Image Details
      • Changes to Rebuild Server
      • Changes to Resize Server
      • Changes to Create Server
    • Extended Status Extension
      • Task states
    • Rescue Mode Extension
      • Rescue and unrescue server action operations
    • Used Limits Extension
      • Changes to List of rate and absolute limits to include used limits
    • Scheduled Images Extension
      • API operations for scheduling images
    • Flavors Extra Specs Extension
      • Changes to Get flavor details API operation
    • Flavors OS Extra Specs Extension
      • API operations for Flavor OS extra specs extension
    • Server Actions Extension
      • List server actions and show action details operations
    • Config Drive Extension
    • Volumes Extension
      • Volume attachment operations
    • Boot from volume
      • Create volume from image and boot instance
        • Procedure: To create a bootable image and boot a server
        • Procedure: To create a bootable image and boot a server in a single step
      • Use pre-made bootable volume to boot instance
      • API operations for creating or using bootable volumes
      • Block-device-mapping attribute versus block-device attribute
    • Network extension
      • API operations for networks extension
    • Virtual Interfaces extension
      • API operations for virtual interfaces extension
    • Scheduler Hint Extension
      • Why use scheduler hints?
      • Scheduler hint operations
  • API reference
    • Server operations
      • Create server
        • Request
        • Response
      • Create server with disk config
        • Request
        • Response
      • Create server with scheduler hints
        • Request
        • Response
      • Retrieve list of servers
        • Request
        • Response
      • List servers with details
        • Request
        • Response
      • Show server details
        • Request
        • Response
      • Update server
        • Request
        • Response
      • Delete server
        • Request
        • Response
      • Create a server key pair
        • Request
        • Response
      • Import a server key pair
        • Request
        • Response
      • Retrieve list of key pairs
        • Request
        • Response
      • Delete key pair
        • Request
        • Response
      • Attach volume to server
        • Request
        • Response
      • List server volumes
        • Request
        • Response
      • Show volume attachment details
        • Request
        • Response
      • Delete volume attachment from a server
        • Request
        • Response
      • Create bootable volume and server
        • Request
        • Response
      • Retrieve list of server actions
        • Request
        • Response
      • Retrieve log details for a specified server action
        • Request
        • Response
      • Change password for specified server
        • Request
        • Response
      • Reset network for server
        • Request
        • Response
      • Reboot specified server
        • Request
        • Response
      • Rebuild specified server
        • Request
        • Response
      • Resize specified server
        • Request
        • Response
      • Confirm server resize for specified server
        • Request
        • Response
      • Revert server resize for specified server
        • Request
        • Response
      • Migrate specified server
        • Request
        • Response
      • Create image of specified server
        • Request
        • Response
      • Rescue specified server
        • Request
        • Response
      • Unrescue specified server
        • Request
        • Response
      • Lock specified server
        • Request
        • Response
      • Unlock specified server
        • Request
        • Response
      • Start specified server
        • Request
        • Response
      • Stop specified server
        • Request
        • Response
      • Retrieves list of server addresses
        • Request
        • Response
      • Retrieve list of network addresses for server and network
        • Request
        • Response
      • List server metadata
        • Request
        • Response
      • Set server metadata
        • Request
        • Response
      • Update server metadata
        • Request
        • Response
      • Show server metadata item details
        • Request
        • Response
      • Set server metadata item
        • Request
        • Response
      • Delete server metadata item
        • Request
        • Response
    • Flavor operations
      • Retrieve list of flavors
        • Request
        • Response
      • Retrieve list of flavors with details
        • Request
        • Response
      • Retrieve flavor details
        • Request
        • Response
      • Show flavor with extra specs
        • Request
        • Response
      • List extra specs for flavors
        • Request
        • Response
      • Get details for specified flavor extra spec
        • Request
        • Response
    • Image operations
      • Retrieve list of images
        • Request
        • Response
      • Retrieve list of images with details
        • Request
        • Response
      • Retrieve image details
        • Request
        • Response
      • Delete image
        • Request
        • Response
      • Retrieve image metadata for specified image
        • Request
        • Response
      • Set image metadata for specified image
        • Request
        • Response
      • Retrieve image metadata item for specified image
        • Request
        • Response
      • Set image metadata item for specified image
        • Request
        • Response
      • Delete image metadata item for specified image
        • Request
        • Response
      • Enable scheduled Images
        • Request
        • Response
      • Show scheduled Images
        • Request
        • Response
      • Disable scheduled Images
        • Request
        • Response
    • Networks operations
      • Retrieve list of networks
        • Request
        • Response
      • Create network
        • Request
        • Response
      • Create server with network
        • Request
        • Response
      • Show network
        • Request
        • Response
      • Delete network
        • Request
        • Response
      • Retrieve list of virtual interfaces
        • Request
        • Response
      • Create virtual interface and attach to server
        • Request
        • Response
      • Delete virtual interface
        • Request
        • Response
    • Miscellaneous server operations
      • Retrieve list of rate and absolute limits
        • Request
        • Response
      • Retrieve list of limits including used limits
        • Request
        • Response
      • Get console
        • Request
        • Response
      • Retrieve quotas
        • Request
        • Response
      • Retrieve list of extensions
        • Request
        • Response
      • Retrieve details for the specified extension
        • Request
        • Response
  • Release Notes
    • API v2.0 updates, September 15, 2016
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, August 15, 2016
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, June 2, 2015
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, October 30, 2014
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, July 24, 2014
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, August 21, 2012
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, August 15, 2012
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, July 9, 2012
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 updates, June 13, 2012
      • What’s new
      • Resolved issues
      • Known issues
    • API v2.0 release, May 1, 2012
      • What’s new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Links and References#

Resources often need to refer to other resources. For example, when you create a server, you must specify the image from which to build the server. You can specify the image by providing an ID or a URL to a remote image. When you provide an ID for a resource, it is assumed that the resource exists in the current endpoint.

Example: Image Reference in Create Server Request: JSON Request

{
    "server" : {
        "name" : "api-test-server-1",
        "imageRef" : "3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
        "flavorRef" : "2",
        "config_drive": true,
        "key_name":"name_of_keypair",
        "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"
            }
        ]
    }
}

Example: Full Image Reference in Create Server Request: JSON Request

{
    "server" : {
        "name" : "myUbuntuServer",
        "imageRef" : "https://dfw.servers.api.rackspacecloud.com/v2/010101/images/3afe97b2-26dc-49c5-a2cc-a2fc8d80c001",
        "flavorRef" : "6",
        "metadata" : {
            "My Server Name" : "Ubuntu 11.10 server"
        },
        "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"
            }
        ]
    }
}

For convenience, resources contain links to themselves. This allows a client to easily obtain resource URIs rather than to construct them. The following kinds of link relations are associated with resources:

  • self. Contains a versioned link to the resource. Use these links when the link will be followed immediately.

  • bookmark. Provides a permanent link to a resource that is appropriate for long-term storage.

  • alternate. Contains an alternate representation of the resource. For example, a Cloud Servers image might have an alternate representation in the Cloud Servers image service.

In the following examples, the rel attribute shows the type of representation to expect when following the link.

Example: Server with Self Links: JSON

{
    "server" : {
        "id" : "52415800-8b69-11e0-9b19-734fcece0043",
        "name" : "my-server",
        "links": [
            {
                "rel" : "self",
                "href" : "http://dfw.servers.api.rackspacecloud.com/v2/010101/servers/52415800-8b69-11e0-9b19-734fcece0043"
            },
            {
                "rel" : "bookmark",
                "href" : "http://dfw.servers.api.rackspacecloud.com/010101/servers/52415800-8b69-11e0-9b19-734fcece0043"
            }
        ]
    }
}

Example: Server with Alternate Link: JSON

{
    "image" : {
        "id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
        "name" : "My Server Backup",
        "links": [
            {
                "rel" : "self",
                "href" : "http://dfw.servers.api.rackspacecloud.com/v2/010101/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            },
            {
                "rel" : "bookmark",
                "href" : "http://dfw.servers.api.rackspacecloud.com/010101/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            },
            {
                "rel"  : "alternate",
                "type" : "application/vnd.openstack.image",
                "href" : "http://glance.api.rackspacecloud.com/010101/images/52415800-8b69-11e0-9b19-734f5736d2a2"
            }
        ]
    }
}
Previous Request and response types
Next Paginated collections
Developer Network
  • Developer Center
  • API Documentation and User Guides
  • Rackspace How-To
Blogs
  • Expert Insights Tech Blog
  • Rackspace Blog
  • Solve: Thought Leadership
Other Information
  • Customer Stories
  • Events
  • Programs
  • Careers
  • Style Guide for Technical Content
©2020 Rackspace US, Inc.
About Rackspace
Privacy Statement
Website Terms
Trademarks