Manage device batches. See project endpoints to list batches for a particular project. Check out the product docs to learn more about Batch Deployment.

Retrieve all batches by project

GET
/projects/{id}/batches

Returns all batches for the given project

    /projects/{id}/batches
  • Parameters
  • id
    string  (required) in path

    Project UUID

    include
    string in query

    related attributes to include

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Retrieve a Batch

GET
/batches/{id}

Returns a Batch

    /batches/{id}
  • Parameters
  • id
    string  (required) in path

    Batch UUID

    include
    string in query

    related attributes to include

  •  
  • Response Body Show Hide
  • Request URL Show Hide
  • cURL Show Hide

Delete the Batch

/batches/{id}

Deletes the Batch.

    /batches/{id}
  • Parameters
  • id
    string  (required) in path

    Batch UUID

    remove_associated_instances
     (required) in body

    Default route

Create a devices batch

/projects/{id}/devices/batch

Creates new devices in batch and provisions them in our datacenter.

Type-specific options (such as operating_system for baremetal devices) should be included in the main data structure alongside hostname and plan.

The features attribute allows you to optionally specify what features your server should have.

For example, if you require a server with a TPM chip, you may specify { "features": { "tpm": "required" } } (or { "features": ["tpm"] } in shorthand).

The request will fail if there are no available servers matching your criteria. Alternatively, if you do not require a certain feature, but would prefer to be assigned a server with that feature if there are any available, you may specify that feature with a preferred value (see the example request below).

The request will not fail if we have no servers with that feature in our inventory.

The facilities attribute specifies in what datacenter you wish to create the device.

You can either specify a single facility { "facility": "f1" } , or you can instruct to create the device in the best available datacenter { "facility": "any" }. Additionally it is possible to set a prioritized location selection.

For example { "facility": ["f3", "f2", "any"] } will try to assign to the facility f3, if there are no available f2, and so on. If "any" is not specified for "facility", the request will fail unless it can assign in the selected locations.

With { "facility": "any" } you have the option to diversify to indicate how many facilities you are willing to be spread across. For this purpose use parameter: facility_diversity_level = N.

For example:

{ "facilities": ["sjc1", "ewr1", "any"] , "facility_diversity_level" = 1, "quantity" = 10 } will assign 10 devices into the same facility, trying first in "sjc1", and if there aren’t available, it will try in "ewr1", otherwise any other.

The ip_addresses attribute will allow you to specify the addresses you want created with your device.

To maintain backwards compatibility, If the attribute is not sent in the request, it will be treated as if { "ip_addresses": [{ "address_family": 4, "public": true }, { "address_family": 4, "public": false }, { "address_family": 6, "public": true }] } was sent.

The private IPv4 address is required and always need to be sent in the array. Not all operating systems support no public IPv4 address, so in those cases you will receive an error message.

For example, to only configure your server with a private IPv4 address, you can send { "ip_addresses": [{ "address_family": 4, "public": false }] }.

Note: when specifying a subnet size larger than a /30, you will need to supply the UUID(s) of existing ip_reservations in your project to assign IPs from.

For example, { "ip_addresses": [..., {"address_family": 4, "public": true, "ip_reservations": ["uuid1", "uuid2"]}] }

To access a server without public IPs, you can use our Out-of-Band console access (SOS) or use another server with public IPs as a proxy.

    /projects/{id}/devices/batch
  • Parameters
  • id
    string  (required) in path

    Project UUID

    batch
     (required) in body

    Batches to create

    {
    	"batches": [
    		{
    			"type": "object",
    			"plan": "string",
    			"hostname": "string",
    			"hostnames": "array",
    			"description": "string",
    			"billing_cycle": "string",
    			"operating_system": "string",
    			"always_pxe": "boolean",
    			"userdata": "string",
    			"locked": "boolean",
    			"termination_time": "string",
    			"tags": "array",
    			"project_ssh_keys": "array",
    			"user_ssh_keys": "array",
    			"features": "array",
    			"customdata": "string",
    			"ip_addresses": "array"
    		}
    	]
    }