Packet Host Batches API
Manage device batches. See project endpoints to list batches for a particular project. Check out the product docs to learn more about [Batch Deployment](https://metal.equinix.com/developers/docs/deploy/batch-deployment/).
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: support@equinixmetal.com
name: Equinix Metal API Team
description: "# Introduction\nEquinix Metal provides a RESTful HTTP API which can be reached at <https://api.equinix.com/metal/v1>. This document describes the API and how to use it.\n\nThe API allows you to programmatically interact with all\nof your Equinix Metal resources, including devices, networks, addresses, organizations,\nprojects, and your user account. Every feature of the Equinix Metal web interface is accessible through the API.\n\nThe API docs are generated from the Equinix Metal OpenAPI specification and are officially hosted at <https://metal.equinix.com/developers/api>.\n\n# Common Parameters\n\nThe Equinix Metal API uses a few methods to minimize network traffic and improve throughput. These parameters are not used in all API calls, but are used often enough to warrant their own section. Look for these parameters in the documentation for the API calls that support them.\n\n## Pagination\n\nPagination is used to limit the number of results returned in a single request. The API will return a maximum of 100 results per page. To retrieve additional results, you can use the `page` and `per_page` query parameters.\n\nThe `page` parameter is used to specify the page number. The first page is `1`. The `per_page` parameter is used to specify the number of results per page. The maximum number of results differs by resource type.\n\n## Sorting\n\nWhere offered, the API allows you to sort results by a specific field. To sort results use the `sort_by` query parameter with the root level field name as the value. The `sort_direction` parameter is used to specify the sort direction, either either `asc` (ascending) or `desc` (descending).\n\n## Filtering\n\nFiltering is used to limit the results returned in a single request. The API supports filtering by certain fields in the response. To filter results, you can use the field as a query parameter.\n\nFor example, to filter the IP list to only return public IPv4 addresses, you can filter by the `type` field, as in the following request:\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/projects/id/ips?type=public_ipv4\n```\n\nOnly IP addresses with the `type` field set to `public_ipv4` will be returned.\n\n## Searching\n\nSearching is used to find matching resources using multiple field comparissons. The API supports searching in resources that define this behavior. Currently the search parameter is only available on devices, ssh_keys, api_keys and memberships endpoints.\n\nTo search resources you can use the `search` query parameter.\n\n## Include and Exclude\n\nFor resources that contain references to other resources, sucha as a Device that refers to the Project it resides in, the Equinix Metal API will returns `href` values (API links) to the associated resource.\n\n```json\n{\n ...\n \"project\": {\n \"href\": \"/metal/v1/projects/f3f131c8-f302-49ef-8c44-9405022dc6dd\"\n }\n}\n```\n\nIf you're going need the project details, you can avoid a second API request. Specify the contained `href` resources and collections that you'd like to have included in the response using the `include` query parameter.\n\nFor example:\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=projects\n```\n\nThe `include` parameter is generally accepted in `GET`, `POST`, `PUT`, and `PATCH` requests where `href` resources are presented.\n\nTo have multiple resources include, use a comma-separated list (e.g. `?include=emails,projects,memberships`).\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=emails,projects,memberships\n```\n\nYou may also include nested associations up to three levels deep using dot notation (`?include=memberships.projects`):\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=memberships.projects\n```\n\nTo exclude resources, and optimize response delivery, use the `exclude` query parameter. The `exclude` parameter is generally accepted in `GET`, `POST`, `PUT`, and `PATCH` requests for fields with nested object responses. When excluded, these fields will be replaced with an object that contains only an `href` field.\n"
license:
name: Equinix Metal
url: https://metal.equinix.com/legal/
termsOfService: https://metal.equinix.com/legal/
title: Metal Authentication Batches API
version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
tags:
- description: 'Manage device batches. See project endpoints to list batches for a particular project. Check out the product docs to learn more about [Batch Deployment](https://metal.equinix.com/developers/docs/deploy/batch-deployment/).
'
externalDocs:
url: https://metal.equinix.com/developers/docs/deploy/batch-deployment/
name: Batches
paths:
/batches/{id}:
delete:
description: Deletes the Batch.
operationId: deleteBatch
parameters:
- description: Batch UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: Delete all instances created from this batch
in: query
name: remove_associated_instances
schema:
default: false
type: boolean
responses:
'204':
description: no content
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Delete the Batch
tags:
- Batches
get:
description: Returns a Batch
operationId: findBatchById
parameters:
- description: Batch UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Retrieve a Batch
tags:
- Batches
/projects/{id}/batches:
get:
description: Returns all batches for the given project
operationId: findBatchesByProject
parameters:
- description: Project UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BatchesList'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Retrieve all batches by project
tags:
- Batches
/projects/{id}/devices/batch:
post:
description: Creates new devices in batch and provisions them in our datacenter.
operationId: createDeviceBatch
parameters:
- description: Project UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstancesBatchCreateInput'
description: Batches to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/BatchesList'
description: created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Create a devices batch
tags:
- Batches
components:
schemas:
Mount:
example:
format: format
options:
- options
- options
device: device
point: point
properties:
device:
type: string
format:
type: string
point:
type: string
options:
items:
type: string
type: array
type: object
DeviceCreateInput_billing_cycle:
description: The billing cycle of the device.
enum:
- hourly
- daily
- monthly
- yearly
type: string
InstancesBatchCreateInput_batches_inner:
allOf:
- properties:
hostnames:
items:
type: string
type: array
quantity:
description: The number of devices to create in this batch. The hostname may contain an `{{index}}` placeholder, which will be replaced with the index of the device in the batch. For example, if the hostname is `device-{{index}}`, the first device in the batch will have the hostname `device-01`, the second device will have the hostname `device-02`, and so on.
type: integer
type: object
- oneOf:
- $ref: '#/components/schemas/DeviceCreateInMetroInput'
- $ref: '#/components/schemas/DeviceCreateInFacilityInput'
Error:
description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
properties:
error:
description: A description of the error that caused the request to fail.
type: string
errors:
description: A list of errors that contributed to the request failing.
items:
description: An error message that contributed to the request failing.
type: string
type: array
type: object
MetroInput:
properties:
metro:
description: 'Metro code or ID of where the instance should be provisioned in.
Either metro or facility must be provided.'
example: sv
type: string
required:
- metro
type: object
IPAddress:
properties:
address_family:
$ref: '#/components/schemas/IPAddress_address_family'
cidr:
description: Cidr Size for the IP Block created. Valid values depends on the operating system being provisioned. (28..32 for IPv4 addresses, 124..127 for IPv6 addresses)
example: 28
format: int32
type: integer
ip_reservations:
description: UUIDs of any IP reservations to use when assigning IPs
items:
type: string
type: array
public:
default: true
description: Address Type for IP Address
example: false
type: boolean
type: object
Partition:
example:
number: 3
size: size
label: label
properties:
label:
type: string
number:
format: int32
type: integer
size:
type: string
type: object
FacilityInput:
properties:
facility:
deprecated: true
description: 'The datacenter where the device should be created.
Either metro or facility must be provided.
The API will accept either a single facility `{ "facility": "f1" }`, or it can be instructed 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"] }` can be used to prioritize `f3` and then `f2` before accepting `any` facility. If none of the facilities provided have availability for the requested device the request will fail.'
example:
- sv15
items:
type: string
type: array
required:
- facility
type: object
Disk:
example:
partitions:
- number: 3
size: size
label: label
- number: 3
size: size
label: label
wipeTable: true
device: device
properties:
device:
type: string
wipeTable:
type: boolean
partitions:
items:
$ref: '#/components/schemas/Partition'
type: array
type: object
Storage:
example:
disks:
- partitions:
- number: 3
size: size
label: label
- number: 3
size: size
label: label
wipeTable: true
device: device
- partitions:
- number: 3
size: size
label: label
- number: 3
size: size
label: label
wipeTable: true
device: device
filesystems:
- mount:
format: format
options:
- options
- options
device: device
point: point
- mount:
format: format
options:
- options
- options
device: device
point: point
raid:
- devices:
- devices
- devices
level: level
name: name
- devices:
- devices
- devices
level: level
name: name
properties:
disks:
items:
$ref: '#/components/schemas/Disk'
type: array
raid:
items:
$ref: '#/components/schemas/Raid'
type: array
filesystems:
items:
$ref: '#/components/schemas/Filesystem'
type: array
type: object
SSHKeyInput:
example:
label: label
key: key
tags:
- tags
- tags
properties:
key:
type: string
label:
type: string
tags:
items:
type: string
type: array
type: object
InstancesBatchCreateInput:
example:
batches:
- null
- null
properties:
batches:
items:
$ref: '#/components/schemas/InstancesBatchCreateInput_batches_inner'
type: array
type: object
Filesystem:
example:
mount:
format: format
options:
- options
- options
device: device
point: point
properties:
mount:
$ref: '#/components/schemas/Mount'
type: object
DeviceCreateInput:
properties:
always_pxe:
default: false
description: 'When true, devices with a `custom_ipxe` OS will always boot to iPXE. The
default setting of false ensures that iPXE will be used on only the
first boot.'
type: boolean
billing_cycle:
$ref: '#/components/schemas/DeviceCreateInput_billing_cycle'
customdata:
additionalProperties: true
default: {}
description: 'Customdata is an arbitrary JSON value that can be accessed via the
metadata service.'
type: object
description:
description: 'Any description of the device or how it will be used. This may be used
to inform other API consumers with project access.'
type: string
features:
description: 'The features attribute allows you to optionally specify what features your server should have.
In the API shorthand syntax, all features listed are `required`:
```
{ "features": ["tpm"] }
```
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. The request will not fail if we have no servers with that feature in our inventory. The API offers an alternative syntax for mixing preferred and required features:
```
{ "features": { "tpm": "required", "raid": "preferred" } }
```
The request will only fail if there are no available servers matching the required `tpm` criteria.'
items:
type: string
type: array
hardware_reservation_id:
default: ''
description: 'The Hardware Reservation UUID to provision. Alternatively, `next-available` can be specified to select from any of the available hardware reservations. An error will be returned if the requested reservation option is not available.
See [Reserved Hardware](https://metal.equinix.com/developers/docs/deploy/reserved/) for more details.'
example: next-available
type: string
hostname:
description: The hostname to use within the operating system. The same hostname may be used on multiple devices within a project.
type: string
ip_addresses:
default:
- address_family: 4
public: true
- address_family: 4
public: false
- address_family: 6
public: true
description: 'The `ip_addresses attribute will allow you to specify the addresses you want created with your device.
The default value configures public IPv4, public IPv6, and private IPv4.
Private IPv4 address is required. When specifying `ip_addresses`, one of the array items must enable private IPv4.
Some operating systems require public IPv4 address. In those cases you will receive an error message if public IPv4 is not enabled.
For example, to only configure your server with a private IPv4 address, you can send `{ "ip_addresses": [{ "address_family": 4, "public": false }] }`.
It is possible to request a subnet size larger than a `/30` by assigning addresses using the UUID(s) of ip_reservations in your project.
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 proxy through another server in the project with public IPs enabled.'
items:
$ref: '#/components/schemas/IPAddress'
type: array
ipxe_script_url:
description: 'When set, the device will chainload an iPXE Script at boot fetched from the supplied URL.
See [Custom iPXE](https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/) for more details.'
externalDocs:
url: https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/
type: string
locked:
default: false
description: Whether the device should be locked, preventing accidental deletion.
type: boolean
network_frozen:
description: If true, this instance can not be converted to a different network type.
type: boolean
no_ssh_keys:
default: false
description: Overrides default behaviour of attaching all of the organization members ssh keys and project ssh keys to device if no specific keys specified
type: boolean
operating_system:
description: The slug of the operating system to provision. Check the Equinix Metal operating system documentation for rules that may be imposed per operating system, including restrictions on IP address options and device plans.
type: string
plan:
description: The slug of the device plan to provision.
example: c3.large.x86
type: string
private_ipv4_subnet_size:
default: 28
description: Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device.
format: int32
type: integer
x-deprecated: true
project_ssh_keys:
description: 'A list of UUIDs identifying the device parent project
that should be authorized to access this device (typically
via /root/.ssh/authorized_keys). These keys will also appear in the device metadata.
If no SSH keys are specified (`user_ssh_keys`, `project_ssh_keys`, and `ssh_keys` are all empty lists or omitted),
all parent project keys, parent project members keys and organization members keys will be included. This behaviour can
be changed with ''no_ssh_keys'' option to omit any SSH key being added.
'
items:
format: uuid
type: string
type: array
public_ipv4_subnet_size:
default: 31
description: Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device. Your project must have addresses available for a non-default request.
format: int32
type: integer
x-deprecated: true
spot_instance:
description: Create a spot instance. Spot instances are created with a maximum bid price. If the bid price is not met, the spot instance will be terminated as indicated by the `termination_time` field.
type: boolean
spot_price_max:
description: The maximum amount to bid for a spot instance.
example: 1.23
format: float
type: number
ssh_keys:
description: "A list of new or existing project ssh_keys\nthat should be authorized to access this device (typically\nvia /root/.ssh/authorized_keys). These keys will also\nappear in the device metadata.\n\nThese keys are added in addition to any keys defined by\n `project_ssh_keys` and `user_ssh_keys`.\n"
items:
$ref: '#/components/schemas/SSHKeyInput'
type: array
storage:
$ref: '#/components/schemas/Storage'
tags:
items:
type: string
type: array
termination_time:
description: 'When the device will be terminated. If you don''t supply timezone info, the timestamp is assumed to be in UTC.
This is commonly set in advance for
ephemeral spot market instances but this field may also be set with
on-demand and reservation instances to automatically delete the resource
at a given time. The termination time can also be used to release a
hardware reservation instance at a given time, keeping the reservation
open for other uses. On a spot market device, the termination time will
be set automatically when outbid.
'
example: 2021-09-03 16:32:00+03:00
format: date-time
type: string
user_ssh_keys:
description: 'A list of UUIDs identifying the users
that should be authorized to access this device (typically
via /root/.ssh/authorized_keys). These keys will also
appear in the device metadata.
The users must be members of the project or organization.
If no SSH keys are specified (`user_ssh_keys`, `project_ssh_keys`, and `ssh_keys` are all empty lists or omitted),
all parent project keys, parent project members keys and organization members keys will be included. This behaviour can
be changed with ''no_ssh_keys'' option to omit any SSH key being added.
'
items:
format: uuid
type: string
type: array
userdata:
description: 'The userdata presented in the metadata service for this device. Userdata is fetched and interpreted by the operating system installed on the device. Acceptable formats are determined by the operating system, with the exception of a special iPXE enabling syntax which is handled before the operating system starts.
See [Server User Data](https://metal.equinix.com/developers/docs/servers/user-data/) and [Provisioning with Custom iPXE](https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/#provisioning-with-custom-ipxe) for more details.'
externalDocs:
url: https://metal.equinix.com/developers/docs/servers/user-data/
type: string
required:
- operating_system
- plan
type: object
IPAddress_address_family:
description: Address Family for IP Address
enum:
- 4
- 6
example: 4
format: int32
type: integer
Batch:
example:
quantity: 0
updated_at: 2000-01-23 04:56:07+00:00
devices:
- href: href
- href: href
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: state
error_messages:
- error_messages
- error_messages
properties:
created_at:
format: date-time
type: string
devices:
items:
$ref: '#/components/schemas/Href'
type: array
error_messages:
items:
type: string
type: array
id:
format: uuid
type: string
project:
$ref: '#/components/schemas/Href'
quantity:
type: integer
state:
type: string
updated_at:
format: date-time
type: string
type: object
Href:
example:
href: href
properties:
href:
type: string
required:
- href
type: object
BatchesList:
example:
batches:
- quantity: 0
updated_at: 2000-01-23 04:56:07+00:00
devices:
- href: href
- href: href
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: state
error_messages:
- error_messages
- error_messages
- quantity: 0
updated_at: 2000-01-23 04:56:07+00:00
devices:
- href: href
- href: href
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: state
error_messages:
- error_messages
- error_messages
properties:
batches:
items:
$ref: '#/components/schemas/Batch'
type: array
type: object
Raid:
example:
devices:
- devices
- devices
level: level
name: name
properties:
devices:
items:
type: string
type: array
level:
type: string
name:
type: string
type: object
DeviceCreateInFacilityInput:
allOf:
- $ref: '#/components/schemas/FacilityInput'
- $ref: '#/components/schemas/DeviceCreateInput'
DeviceCreateInMetroInput:
allOf:
- $ref: '#/components/schemas/MetroInput'
- $ref: '#/components/schemas/DeviceCreateInput'
securitySchemes:
x_auth_token:
description: 'HTTP header containing the User or Project API key that will be used to authenticate the request.
'
in: header
name: X-Auth-Token
type: apiKey
x-displayName: X-Auth-Token
x-tagGroups:
- name: Accounts and Organization
tags:
- Authentication
- Emails
- Invitations
- Memberships
- Organizations
- OTPs
- PasswordResetTokens
- PaymentMethods
- Projects
- SSHKeys
- SupportRequest
- TransferRequests
- TwoFactorAuth
- Users
- UserVerificationTokens
- name: Services and Billing
tags:
- Events
- Facilities
- Incidents
- Invoices
- Licenses
- Metros
- Plans
- Usages
- name: Servers
tags:
- Devices
- Batches
- Capacity
- HardwareReservations
- OperatingSystems
- Ports
- SelfServiceReservations
- SpotMarket
- Userdata
- Volumes
- name: Networking
tags:
- BGP
- Interconnections
- IPAddresses
- MetalGateways
- VLANs
- VRFs