Skip to main content

Metal API (1.0.0)

Download OpenAPI specification:Download

Introduction

Equinix 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.

The API allows you to programmatically interact with all of your Equinix Metal resources, including devices, networks, addresses, organizations, projects, and your user account. Every feature of the Equinix Metal web interface is accessible through the API.

The API docs are generated from the Equinix Metal OpenAPI specification and are officially hosted at https://deploy.equinix.com/developers/api/metal/.

Common Parameters

The 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.

Pagination

Pagination 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.

The 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.

Sorting

Where 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).

Filtering

Filtering 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.

For example, to filter the IP list to only return public IPv4 addresses, you can filter by the type field, as in the following request:

curl -H 'X-Auth-Token: my_authentication_token' \
  https://api.equinix.com/metal/v1/projects/id/ips?type=public_ipv4

Only IP addresses with the type field set to public_ipv4 will be returned.

Searching

Searching 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.

To search resources you can use the search query parameter.

Include and Exclude

For 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.

{
  ...
  "project": {
    "href": "/metal/v1/projects/f3f131c8-f302-49ef-8c44-9405022dc6dd"
  }
}

If 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.

For example:

curl -H 'X-Auth-Token: my_authentication_token' \
  https://api.equinix.com/metal/v1/user?include=projects

The include parameter is generally accepted in GET, POST, PUT, and PATCH requests where href resources are presented.

To have multiple resources include, use a comma-separated list (e.g. ?include=emails,projects,memberships).

curl -H 'X-Auth-Token: my_authentication_token' \
  https://api.equinix.com/metal/v1/user?include=emails,projects,memberships

You may also include nested associations up to three levels deep using dot notation (?include=memberships.projects):

curl -H 'X-Auth-Token: my_authentication_token' \
  https://api.equinix.com/metal/v1/user?include=memberships.projects

To 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.

Authentication

Nearly all of the endpoints in the API require authentication. Authentication is performed by providing an authentication token (interchangeably referred to as an API key) in the X-Auth-Token HTTP request header.

X-Auth-Token

HTTP header containing the User or Project API key that will be used to authenticate the request.

Security Scheme Type: API Key
Header parameter name: X-Auth-Token

User API keys can be obtained by creating them in the Equinix Metal Portal or by using the Create a User API Key endpoint.

Project API keys can also be obtained by creating them in the Equinix Metal Portal or by using the Create a Project API Key endpoint. Project API keys are scoped to a single project and can only be used to access resources within that project.

For example, to use an authenticated API token, you would make a request like the following:

curl -H 'X-Auth-Token: my_authentication_token' \
  https://api.equinix.com/metal/v1/user/api-keys

Applications can take advantage of the Equinix Metal API and API keys to perform any of the actions that can be performed in the Equinix Metal Portal. For example, you can use the API to create and manage devices, projects, and other resources.

API keys can be deleted without affecting any of the resources created with them. Access to applications using the API can be revoked by deleting the API key used to authenticate the application.

Delete the API key

Deletes the API key.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

API Key UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve all API keys for the project.

Returns all API keys for a specific project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (AuthToken)
Array
created_at
string <date-time>
description
string

Available only for API keys

id
string <uuid>
object (AuthToken_project)

Available only for project tokens

read_only
boolean
token
string
updated_at
string <date-time>
object (AuthToken_user)

Available only for user tokens

Response samples

Content type
application/json
{
  • "api_keys": [
    ]
}

Create an API key for a project.

Creates an API key for a project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

API Key to create

description
string
read_only
boolean

Responses

Response Schema: application/json
created_at
string <date-time>
description
string

Available only for API keys

id
string <uuid>
object (AuthToken_project)

Available only for project tokens

backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
read_only
boolean
token
string
updated_at
string <date-time>
object (AuthToken_user)

Available only for user tokens

avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
Array
href
required
string
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "description": "string",
  • "read_only": true
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "read_only": true,
  • "token": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    }
}

Retrieve all user API keys

Returns all API keys for the current user.

Authorizations:
X-Auth-Token
query Parameters
search
string

Search by description

include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (AuthToken)
Array
created_at
string <date-time>
description
string

Available only for API keys

id
string <uuid>
object (AuthToken_project)

Available only for project tokens

read_only
boolean
token
string
updated_at
string <date-time>
object (AuthToken_user)

Available only for user tokens

Response samples

Content type
application/json
{
  • "api_keys": [
    ]
}

Create an API key

Creates a API key for the current user.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

API key to create

description
string
read_only
boolean

Responses

Response Schema: application/json
created_at
string <date-time>
description
string

Available only for API keys

id
string <uuid>
object (AuthToken_project)

Available only for project tokens

backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
read_only
boolean
token
string
updated_at
string <date-time>
object (AuthToken_user)

Available only for user tokens

avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
Array
href
required
string
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "description": "string",
  • "read_only": true
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "read_only": true,
  • "token": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    }
}

Delete the API key

Deletes the current user API key.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

API Key UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Emails

Email Management

Create an email Deprecated

Add a new email address to the current user.

Authorizations:
X-Auth-Token
Request Body schema: application/json
required

Email to create

address
required
string

Responses

Response Schema: application/json
address
string
default
boolean
href
string
id
string <uuid>
verified
boolean

Request samples

Content type
application/json
{
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "default": true,
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": true
}

Delete the email

Deletes the email.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Email UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve an email

Provides one of the user’s emails.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Email UUID

Responses

Response Schema: application/json
address
string
default
boolean
href
string
id
string <uuid>
verified
boolean

Response samples

Content type
application/json
{
  • "address": "string",
  • "default": true,
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": true
}

Update the email

Updates the email.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Email UUID

Request Body schema: application/json
required

email to update

default
boolean

Responses

Response Schema: application/json
address
string
default
boolean
href
string
id
string <uuid>
verified
boolean

Request samples

Content type
application/json
{
  • "default": true
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "default": true,
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": true
}

Invitations

Manage invitations. See project endpoints to create a new invitation. Check out the product docs to learn more about Invitations.

Decline an invitation

Decline an invitation.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Invitation UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

View an invitation

Returns a single invitation. (It include the invitable to maintain backward compatibility but will be removed soon)

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Invitation UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
object (Href)
href
required
string
invitee
string <email>
nonce
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
updated_at
string <date-time>
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitation": {
    },
  • "invited_by": {
    },
  • "invitee": "user@example.com",
  • "nonce": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "bound_roles": [
    ]
}

Accept an invitation

Accept an invitation.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Invitation UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
roles
Array of strings
updated_at
string <date-time>
object (Href)
href
required
string
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "bound_roles": [
    ]
}

Memberships

Membership Management (Project). Check out the product docs to learn more about Membership.

Delete the membership

Deletes the membership.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Membership UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a membership

Returns a single membership.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Membership UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
roles
Array of strings
updated_at
string <date-time>
object (Href)
href
required
string
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "bound_roles": [
    ]
}

Update the membership

Updates the membership.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Membership UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Membership to update

role
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
roles
Array of strings
updated_at
string <date-time>
object (Href)
href
required
string
bound_roles
Array of strings

Request samples

Content type
application/json
{
  • "role": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": {
    },
  • "bound_roles": [
    ]
}

Organizations

Organizations Management. Check out the product docs to learn more about Organizations.

Retrieve all organizations

Returns a list of organizations that are accessible to the current user.

Authorizations:
X-Auth-Token
query Parameters
personal
string
Enum: "include" "exclude" "only"

Include, exclude or show only personal organizations.

without_projects
string
Enum: "include" "exclude" "only"

Include, exclude or show only organizations that have no projects.

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer
Array of objects (Organization)
Array
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "organizations": [
    ]
}

Delete the organization

Deletes the organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve an organization's details

Returns a single organization's details, if the user is authorized to view it.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string

Response samples

Content type
application/json
{
  • "address": {
    },
  • "billing_address": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "credit_amount": 0.1,
  • "customdata": { },
  • "description": "string",
  • "enforce_2fa_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "logo": "string",
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "projects": [
    ],
  • "terms": 0,
  • "twitter": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "website": "string"
}

Update the organization

Updates the organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Organization to update

object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

name
string
twitter
string
website
string

Responses

Response Schema: application/json
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
latitude
string
longitude
string
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string

Request samples

Content type
application/json
{
  • "address": {
    },
  • "billing_address": {
    },
  • "customdata": { },
  • "description": "string",
  • "enforce_2fa_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "twitter": "string",
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "address": {
    },
  • "billing_address": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "credit_amount": 0.1,
  • "customdata": { },
  • "description": "string",
  • "enforce_2fa_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "logo": "string",
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "projects": [
    ],
  • "terms": 0,
  • "twitter": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "website": "string"
}

Retrieve the custom metadata of an organization

Provides the custom metadata stored for this organization in json format

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve organization invitations

Returns all invitations in an organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Membership)
Array
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
roles
Array of strings
updated_at
string <date-time>
object (Href)
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "invitations": [
    ]
}

Create an invitation for an organization

In order to add a user to an organization, they must first be invited. To invite to several projects the parameter projects_ids:[a,b,c] can be used

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Invitation to create

invitee
required
string <email>
message
string
organization_id
string <uuid>
projects_ids
Array of strings <uuid> [ items <uuid > ]
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
bound_roles
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
object (Href)
href
required
string
invitee
string <email>
nonce
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
updated_at
string <date-time>
bound_roles
Array of strings

Request samples

Content type
application/json
{
  • "invitee": "user@example.com",
  • "message": "string",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "projects_ids": [
    ],
  • "roles": [
    ],
  • "bound_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitation": {
    },
  • "invited_by": {
    },
  • "invitee": "user@example.com",
  • "nonce": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "bound_roles": [
    ]
}

Retrieve all operating systems visible by the organization

Returns a listing of available operating systems for the given organization

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (OperatingSystem)
Array
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Response samples

Content type
application/json
{
  • "operating_systems": [
    ]
}

Retrieve all payment methods of an organization

Returns all payment methods of an organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (PaymentMethod)
Array
object (PaymentMethodBillingAddress)
card_type
string
cardholder_name
string
created_at
string <date-time>
object (Href)
default
boolean
email
string
expiration_month
string
expiration_year
string
id
string <uuid>
name
string
object (Href)
Array of objects (Href)
type
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "payment_methods": [
    ]
}

Create a payment method for the given organization

Creates a payment method.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Payment Method to create

default
boolean
name
required
string
nonce
required
string

Responses

Response Schema: application/json
object (PaymentMethodBillingAddress)
country_code_alpha2
string
postal_code
string
street_address
string
card_type
string
cardholder_name
string
created_at
string <date-time>
object (Href)
href
required
string
default
boolean
email
string
expiration_month
string
expiration_year
string
id
string <uuid>
name
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
type
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "default": true,
  • "name": "string",
  • "nonce": "string"
}

Response samples

Content type
application/json
{
  • "billing_address": {
    },
  • "card_type": "string",
  • "cardholder_name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_user": {
    },
  • "default": true,
  • "email": "string",
  • "expiration_month": "string",
  • "expiration_year": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "type": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve all plans visible by the organization

Returns a listing of available plans for the given organization

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
Array of objects (Plan)
Array
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

Response samples

Content type
application/json
{
  • "plans": [
    ]
}

Retrieve all projects of an organization

Returns a collection of projects that belong to the organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
name
string

Filter results by name.

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer
Array of objects (Project)
Array
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "projects": [
    ]
}

Create a project for the organization

Creates a new project for the organization

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Project to create

customdata
object
name
required
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

payment_method_id
string <uuid>
type
string
Value: "default"

The type of the project. If no type is specified the project type will automatically be default

tags
Array of strings

Responses

Response Schema: application/json
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings

Request samples

Content type
application/json
{
  • "customdata": { },
  • "name": "string",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "type": "default",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "backend_transfer_enabled": true,
  • "bgp_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "devices": [
    ],
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitations": [
    ],
  • "max_devices": { },
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "network_status": { },
  • "organization": {
    },
  • "payment_method": {
    },
  • "ssh_keys": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "volumes": [
    ],
  • "type": "default",
  • "tags": [
    ]
}

Retrieve all project transfer requests from or to an organization

Provides a collection of project transfer requests from or to the organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (TransferRequest)
Array
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
object (Href)
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "transfers": [
    ]
}

Retrieve organization members

Get all Members of an Organization

Authorizations:
X-Auth-Token
path Parameters
organization_id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (Member)
Array
id
string <uuid>
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
projects_count
integer
bound_roles
Array of strings
object (Href)
object (Href)
Array of objects (Href)
href
string

Response samples

Content type
application/json
{
  • "members": [
    ]
}

Remove member from the organization

Authorizations:
X-Auth-Token
path Parameters
organization_id
required
string <uuid>

Organization UUID

id
required
string <uuid>

Member UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Update roles for an organization member

Update organization member by assigning roles that determine which actions they can perform within the organization.

Authorizations:
X-Auth-Token
path Parameters
organization_id
required
string <uuid>

Organization UUID

id
required
string <uuid>

Member UUID

Request Body schema: application/json

Organization to update

role
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"

Primary role for the user within the organization

bound_roles
Array of strings

Additional roles that can be bound to the user to grant extra permissions.

project_ids
Array of strings <uuid> [ items <uuid > ]

Project IDs the user should be able to access. This field is only required when role is set to collaborator or limited_collaborator.

Responses

Response Schema: application/json
id
string <uuid>
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
projects_count
integer
bound_roles
Array of strings
object (Href)
href
required
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
href
string

Request samples

Content type
application/json
{
  • "role": [
    ],
  • "bound_roles": [
    ],
  • "project_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "roles": [
    ],
  • "projects_count": 0,
  • "bound_roles": [
    ],
  • "user": {
    },
  • "organization": {
    },
  • "projects": [
    ],
  • "href": "string"
}

Reset current user password

Resets current user password.

Authorizations:
X-Auth-Token

Responses

Response Schema: application/json
new_password
string

Response samples

Content type
application/json
{
  • "new_password": "string"
}

Create a password reset token

Creates a password reset token

Authorizations:
X-Auth-Token
query Parameters
email
required
string

Email of user to create password reset token

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Delete the payment method

Deletes the payment method.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Payment Method UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a payment method

Returns a payment method

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Payment Method UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
object (PaymentMethodBillingAddress)
country_code_alpha2
string
postal_code
string
street_address
string
card_type
string
cardholder_name
string
created_at
string <date-time>
object (Href)
href
required
string
default
boolean
email
string
expiration_month
string
expiration_year
string
id
string <uuid>
name
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
type
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "billing_address": {
    },
  • "card_type": "string",
  • "cardholder_name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_user": {
    },
  • "default": true,
  • "email": "string",
  • "expiration_month": "string",
  • "expiration_year": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "type": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update the payment method

Updates the payment method.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Payment Method UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Payment Method to update

billing_address
object
cardholder_name
string
default
boolean
expiration_month
string
expiration_year
integer
name
string

Responses

Response Schema: application/json
object (PaymentMethodBillingAddress)
country_code_alpha2
string
postal_code
string
street_address
string
card_type
string
cardholder_name
string
created_at
string <date-time>
object (Href)
href
required
string
default
boolean
email
string
expiration_month
string
expiration_year
string
id
string <uuid>
name
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
type
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "billing_address": { },
  • "cardholder_name": "string",
  • "default": true,
  • "expiration_month": "string",
  • "expiration_year": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "billing_address": {
    },
  • "card_type": "string",
  • "cardholder_name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by_user": {
    },
  • "default": true,
  • "email": "string",
  • "expiration_month": "string",
  • "expiration_year": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "type": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Projects

Project Management. Check out the product docs to learn more about Projects.

Retrieve all projects

Returns a collection of projects that the current user is a member of.

Authorizations:
X-Auth-Token
query Parameters
name
string

Filter results by name.

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer
Array of objects (Project)
Array
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "projects": [
    ]
}

Create a project

Creates a new project for the user's default organization. If the user does not have a default organization, the API will look for a personal organization belonging to the user with the name "{User's Full Name} Projects" to associate the project with. If that organization does not exist a new organization named "{User's Full Name} Projects" will be created and the new project will be tied to that organization.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Project to create

customdata
object
name
required
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

organization_id
string <uuid>
payment_method_id
string <uuid>
type
string
Value: "default"

The type of the project. If no type is specified the project type will automatically be default

tags
Array of strings

Responses

Response Schema: application/json
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings

Request samples

Content type
application/json
{
  • "customdata": { },
  • "name": "string",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "type": "default",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "backend_transfer_enabled": true,
  • "bgp_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "devices": [
    ],
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitations": [
    ],
  • "max_devices": { },
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "network_status": { },
  • "organization": {
    },
  • "payment_method": {
    },
  • "ssh_keys": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "volumes": [
    ],
  • "type": "default",
  • "tags": [
    ]
}

Delete the project

Deletes the project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a project

Returns a single project if the user has access

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings

Response samples

Content type
application/json
{
  • "backend_transfer_enabled": true,
  • "bgp_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "devices": [
    ],
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitations": [
    ],
  • "max_devices": { },
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "network_status": { },
  • "organization": {
    },
  • "payment_method": {
    },
  • "ssh_keys": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "volumes": [
    ],
  • "type": "default",
  • "tags": [
    ]
}

Update the project

Updates the project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Project to update

backend_transfer_enabled
boolean
customdata
object
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

payment_method_id
string <uuid>
tags
Array of strings

Responses

Response Schema: application/json
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string
Array of objects (Href)
Array
href
required
string
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings

Request samples

Content type
application/json
{
  • "backend_transfer_enabled": true,
  • "customdata": { },
  • "name": "string",
  • "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "backend_transfer_enabled": true,
  • "bgp_config": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "devices": [
    ],
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitations": [
    ],
  • "max_devices": { },
  • "members": [
    ],
  • "memberships": [
    ],
  • "name": "string",
  • "network_status": { },
  • "organization": {
    },
  • "payment_method": {
    },
  • "ssh_keys": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "volumes": [
    ],
  • "type": "default",
  • "tags": [
    ]
}

Retrieve the custom metadata of a project

Provides the custom metadata stored for this project in json format

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Create a transfer request Deprecated

Organization owners can transfer their projects to other organizations.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

UUID of the project to be transferred

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Transfer Request to create

target_organization_id
string <uuid>

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
object (Href)
href
required
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "target_organization_id": "86e737fc-f10c-4261-bf49-58acf935bd4d"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "target_organization": {
    },
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve project invitations

Returns all invitations in a project.

Authorizations:
X-Auth-Token
path Parameters
project_id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Membership)
Array
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
roles
Array of strings
updated_at
string <date-time>
object (Href)
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "invitations": [
    ]
}

Create an invitation for a project

In order to add a user to a project, they must first be invited.

Authorizations:
X-Auth-Token
path Parameters
project_id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Invitation to create

invitee
required
string <email>
message
string
organization_id
string <uuid>
projects_ids
Array of strings <uuid> [ items <uuid > ]
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
bound_roles
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
object (Href)
href
required
string
invitee
string <email>
nonce
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
roles
Array of strings
Items Enum: "admin" "billing" "collaborator" "limited_collaborator"
updated_at
string <date-time>
bound_roles
Array of strings

Request samples

Content type
application/json
{
  • "invitee": "user@example.com",
  • "message": "string",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "projects_ids": [
    ],
  • "roles": [
    ],
  • "bound_roles": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invitation": {
    },
  • "invited_by": {
    },
  • "invitee": "user@example.com",
  • "nonce": "string",
  • "organization": {
    },
  • "projects": [
    ],
  • "roles": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "bound_roles": [
    ]
}

Retrieve the custom metadata of an IP Reservation

Provides the custom metadata stored for this IP Reservation in json format

Authorizations:
X-Auth-Token
path Parameters
project_id
required
string <uuid>

Project UUID

id
required
string <uuid>

Ip Reservation UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve project memberships

Returns all memberships in a project.

Authorizations:
X-Auth-Token
path Parameters
project_id
required
string <uuid>

Project UUID

query Parameters
search
string

Search by member full name, id and email.

include
Array of strings

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.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Membership)
Array
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
roles
Array of strings
updated_at
string <date-time>
object (Href)
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "memberships": [
    ]
}

Roles

List available roles

This list of roles can be used to update Members or new Invitations with additional permissions.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

Responses

Response Schema: application/json
roles
object

Response samples

Content type
application/json
{
  • "roles": { }
}

Get details about a specific role

Learn what actions are in each role.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

role_id
required
string

Role ID

Responses

Response Schema: application/json
id
string
name
string
actions
Array of strings

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "actions": [
    ]
}

SSHKeys

Manage SSH keys. See project endpoints to list and create project-level SSH keys.

Retrieve a device's ssh keys

Returns a collection of the device's ssh keys.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
Search string
string

Search by key, label, or fingerprint

include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (SSHKey)
Array
created_at
string <date-time>
object (Href)
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Response samples

Content type
application/json
{
  • "ssh_keys": [
    ]
}

Retrieve a project's ssh keys

Returns a collection of the project's ssh keys.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
query
string

Search by key, label, or fingerprint

include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (SSHKey)
Array
created_at
string <date-time>
object (Href)
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Response samples

Content type
application/json
{
  • "ssh_keys": [
    ]
}

Create a ssh key for the given project

Creates a ssh key.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

ssh key to create

instances_ids
Array of strings <uuid> [ items <uuid > ]

List of instance UUIDs to associate SSH key with, when empty array is sent all instances belonging to entity will be included

key
string
label
string
tags
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
object (Href)
href
required
string
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Request samples

Content type
application/json
{
  • "instances_ids": [
    ],
  • "key": "string",
  • "label": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "entity": {
    },
  • "fingerprint": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "string",
  • "label": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Retrieve all ssh keys

Returns a collection of the user’s ssh keys.

Authorizations:
X-Auth-Token
query Parameters
search
string

Search by key, label, or fingerprint

include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (SSHKey)
Array
created_at
string <date-time>
object (Href)
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Response samples

Content type
application/json
{
  • "ssh_keys": [
    ]
}

Create a ssh key for the current user

Creates a ssh key.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

ssh key to create

instances_ids
Array of strings <uuid> [ items <uuid > ]

List of instance UUIDs to associate SSH key with, when empty array is sent all instances belonging to entity will be included

key
string
label
string
tags
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
object (Href)
href
required
string
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Request samples

Content type
application/json
{
  • "instances_ids": [
    ],
  • "key": "string",
  • "label": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "entity": {
    },
  • "fingerprint": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "string",
  • "label": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Delete the ssh key

Deletes the ssh key.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

ssh key UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a ssh key

Returns a single ssh key if the user has access

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

SSH Key UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
object (Href)
href
required
string
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "entity": {
    },
  • "fingerprint": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "string",
  • "label": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Update the ssh key

Updates the ssh key.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

SSH Key UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

ssh key to update

key
string
label
string
tags
Array of strings

Responses

Response Schema: application/json
created_at
string <date-time>
object (Href)
href
required
string
fingerprint
string
href
string
id
string <uuid>
key
string
label
string
updated_at
string <date-time>
tags
Array of strings

Request samples

Content type
application/json
{
  • "key": "string",
  • "label": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "entity": {
    },
  • "fingerprint": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key": "string",
  • "label": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Create a support ticket

Support Ticket.

Authorizations:
X-Auth-Token
Request Body schema: application/json
required

Support Request to create

device_id
string
message
required
string
priority
string
Enum: "urgent" "high" "medium" "low"
project_id
string
subject
required
string

Responses

Request samples

Content type
application/json
{
  • "device_id": "string",
  • "message": "string",
  • "priority": "urgent",
  • "project_id": "string",
  • "subject": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Decline a transfer request

Decline a transfer request.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Transfer request UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

View a transfer request

Returns a single transfer request.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Transfer request UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
href
required
string
object (Href)
href
required
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "target_organization": {
    },
  • "updated_at": "2019-08-24T14:15:22Z"
}

Accept a transfer request

Accept a transfer request.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Transfer request UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

TwoFactorAuth

Two Factor Authentication Management. Check out the product docs to learn more about 2FA.

Disable two factor authentication

Disables two factor authentication.

Authorizations:
X-Auth-Token

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Enable two factor auth using app

Enables two factor authentication using authenticator app.

Authorizations:
X-Auth-Token

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve current user invitations

Returns all invitations in current user.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Membership)
Array
created_at
string <date-time>
href
string
id
string <uuid>
object (Href)
roles
Array of strings
updated_at
string <date-time>
object (Href)
bound_roles
Array of strings

Response samples

Content type
application/json
{
  • "invitations": [
    ]
}

Retrieve the current user

Returns the user object for the currently logged-in user.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
Array
href
required
string
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "avatar_thumb_url": "string",
  • "avatar_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "default_organization_id": "7498eaa8-62af-4757-81e0-959250fc9cd5",
  • "default_project_id": "1226a120-3a85-4fe0-bba2-cdfc7af0d81b",
  • "email": "string",
  • "emails": [
    ],
  • "first_name": "string",
  • "fraud_score": "string",
  • "full_name": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_name": "string",
  • "max_organizations": 0,
  • "max_projects": 0,
  • "phone_number": "string",
  • "short_id": "string",
  • "timezone": "string",
  • "two_factor_auth": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update the current user

Updates the currently logged-in user.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

User to update

customdata
object
first_name
string
last_name
string
password
string
phone_number
string
timezone
string

Responses

Response Schema: application/json
avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
Array
href
required
string
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "customdata": { },
  • "first_name": "string",
  • "last_name": "string",
  • "password": "string",
  • "phone_number": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "avatar_thumb_url": "string",
  • "avatar_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "default_organization_id": "7498eaa8-62af-4757-81e0-959250fc9cd5",
  • "default_project_id": "1226a120-3a85-4fe0-bba2-cdfc7af0d81b",
  • "email": "string",
  • "emails": [
    ],
  • "first_name": "string",
  • "fraud_score": "string",
  • "full_name": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_name": "string",
  • "max_organizations": 0,
  • "max_projects": 0,
  • "phone_number": "string",
  • "short_id": "string",
  • "timezone": "string",
  • "two_factor_auth": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve all users

Returns a list of users that the are accessible to the current user (all users in the current user’s projects, essentially).

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer
Array of objects (User)
Array
avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "users": [
    ]
}

Create a user

Creates a user.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

User to create

company_name
string
company_url
string
customdata
object
required
Array of objects (EmailInput)
Array
address
required
string
default
boolean
first_name
required
string
last_name
required
string
level
string
password
string
phone_number
string
social_accounts
object
timezone
string
title
string
two_factor_auth
string
verified_at
string <date-time>
invitation_id
string <uuid>
nonce
string

Responses

Request samples

Content type
application/json
{
  • "company_name": "string",
  • "company_url": "string",
  • "customdata": { },
  • "emails": [
    ],
  • "first_name": "string",
  • "last_name": "string",
  • "level": "string",
  • "password": "string",
  • "phone_number": "string",
  • "social_accounts": { },
  • "timezone": "string",
  • "title": "string",
  • "two_factor_auth": "string",
  • "verified_at": "2019-08-24T14:15:22Z",
  • "invitation_id": "a6e6785a-3ea9-406c-b873-17eaf2ed5fc9",
  • "nonce": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a user

Returns a single user if the user has access

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

User UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
avatar_thumb_url
string
avatar_url
string
created_at
string <date-time>
customdata
object
default_organization_id
string <uuid>
default_project_id
string <uuid>
email
string
Array of objects (Href)
Array
href
required
string
first_name
string
fraud_score
string
full_name
string
href
string
id
string <uuid>
last_login_at
string <date-time>
last_name
string
max_organizations
integer
max_projects
integer
phone_number
string
short_id
string
timezone
string
two_factor_auth
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "avatar_thumb_url": "string",
  • "avatar_url": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "customdata": { },
  • "default_organization_id": "7498eaa8-62af-4757-81e0-959250fc9cd5",
  • "default_project_id": "1226a120-3a85-4fe0-bba2-cdfc7af0d81b",
  • "email": "string",
  • "emails": [
    ],
  • "first_name": "string",
  • "fraud_score": "string",
  • "full_name": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "last_name": "string",
  • "max_organizations": 0,
  • "max_projects": 0,
  • "phone_number": "string",
  • "short_id": "string",
  • "timezone": "string",
  • "two_factor_auth": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve the custom metadata of a user

Provides the custom metadata stored for this user in json format

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

User UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Create an email verification request

Creates an email verification request

Authorizations:
X-Auth-Token
query Parameters
login
required
string

Email for verification request

include
Array of strings

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.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Verify a user using an email verification token

Consumes an email verification token and verifies the user associated with it.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

Email to create

user_token
required
string

User verification token

Responses

Request samples

Content type
application/json
{
  • "user_token": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Events

Event Management

Retrieve interconnection events

Returns a list of the interconnection events

Authorizations:
X-Auth-Token
path Parameters
connection_id
required
string <uuid>

Interconnection UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "meta": {
    }
}

Retrieve interconnection port events

Returns a list of the interconnection port events

Authorizations:
X-Auth-Token
path Parameters
connection_id
required
string <uuid>

Interconnection UUID

id
required
string <uuid>

Interconnection Port UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
Array
href
required
string
state
string
type
string
modified_by
object
ip
string

Response samples

Content type
application/json
{
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "interpolated": "string",
  • "relationships": [
    ],
  • "state": "string",
  • "type": "string",
  • "modified_by": { },
  • "ip": "string"
}

Retrieve device's events

Returns a list of events pertaining to a specific device

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "meta": {
    }
}

Retrieve current user's events

Returns a list of the current user’s events

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "meta": {
    }
}

Retrieve an event

Returns a single event if the user has access

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Event UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
Array
href
required
string
state
string
type
string
modified_by
object
ip
string

Response samples

Content type
application/json
{
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "interpolated": "string",
  • "relationships": [
    ],
  • "state": "string",
  • "type": "string",
  • "modified_by": { },
  • "ip": "string"
}

Retrieve organization's events

Returns a list of events for a single organization

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "meta": {
    }
}

Retrieve project's events

Returns a list of events for a single project

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "meta": {
    }
}

Retrieve VRF route events

Returns a list of the VRF route events

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

VRF Route UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
Array
href
required
string
state
string
type
string
modified_by
object
ip
string

Response samples

Content type
application/json
{
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "interpolated": "string",
  • "relationships": [
    ],
  • "state": "string",
  • "type": "string",
  • "modified_by": { },
  • "ip": "string"
}

Retrieve virtual circuit events

Returns a list of the virtual circuit events

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Virtual Circuit UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
Array
href
required
string
state
string
type
string
modified_by
object
ip
string

Response samples

Content type
application/json
{
  • "body": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "interpolated": "string",
  • "relationships": [
    ],
  • "state": "string",
  • "type": "string",
  • "modified_by": { },
  • "ip": "string"
}

Facilities

Facility Management. Check out the product docs to learn more about Facilities.

Retrieve the number of incidents

Retrieve the number of incidents.

Authorizations:
X-Auth-Token
query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Invoices

Retrieve an invoice

Returns the invoice identified by the provided id

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Invoice UUID

Responses

Response Schema: application/json
amount
number <float>
balance
number <float>
created_on
string <date>
credit_amount
number <float>
credits_applied
number <float>
currency
string
due_on
string <date>
id
string <uuid>
Array of objects (LineItem)
Array
amount
number <float>
currency
string
description
string
details
string
object (PlanIdName)
unit
string
unit_price
number <float>
hostname
string
location
string
item_type
string
service_id
string <uuid>
start_date
string <date>
end_date
string <date>
project_id
string <uuid>
plan_id
string <uuid>
object (ProjectIdName)
Array of objects (LineItemAdjustment)

Adjustments for the line item

number
string
object (ProjectIdName)
id
string <uuid>
name
string
reference_number
string
status
string
target_date
string <date>

Response samples

Content type
application/json
{
  • "amount": 0.1,
  • "balance": 0.1,
  • "created_on": "2019-08-24",
  • "credit_amount": 0.1,
  • "credits_applied": 0.1,
  • "currency": "USD",
  • "due_on": "2019-08-24",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "items": [
    ],
  • "number": "string",
  • "project": {
    },
  • "reference_number": "string",
  • "status": "string",
  • "target_date": "2019-08-24"
}

Retrieve all invoices for an organization

Returns all invoices for an organization

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
page
integer

page number

per_page
integer

per page

status
string

filter by status

Responses

Response Schema: application/json
Array of objects (Invoice)
Array
amount
number <float>
balance
number <float>
created_on
string <date>
credit_amount
number <float>
credits_applied
number <float>
currency
string
due_on
string <date>
id
string <uuid>
Array of objects (LineItem)
number
string
object (ProjectIdName)
reference_number
string
status
string
target_date
string <date>

Response samples

Content type
application/json
{
  • "invoices": [
    ]
}

Licenses

Manage licenses. See project endpoints to list and create licenses for a particular project.

Delete the license

Deletes a license.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

License UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a license

Returns a license

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

License UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
description
string
id
string <uuid>
license_key
string
object (Href)
href
required
string
object (Href)
href
required
string
size
number

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "license_key": "string",
  • "licensee_product": {
    },
  • "project": {
    },
  • "size": 0
}

Update the license

Updates the license.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

License UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

License to update

description
string
size
number

Responses

Response Schema: application/json
description
string
id
string <uuid>
license_key
string
object (Href)
href
required
string
object (Href)
href
required
string
size
number

Request samples

Content type
application/json
{
  • "description": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "license_key": "string",
  • "licensee_product": {
    },
  • "project": {
    },
  • "size": 0
}

Retrieve all licenses

Provides a collection of licenses for a given project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (License)
Array
description
string
id
string <uuid>
license_key
string
object (Href)
object (Href)
size
number

Response samples

Content type
application/json
{
  • "licenses": [
    ]
}

Create a License

Creates a new license for the given project

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

License to create

description
string
licensee_product_id
string
size
number

Responses

Response Schema: application/json
description
string
id
string <uuid>
license_key
string
object (Href)
href
required
string
object (Href)
href
required
string
size
number

Request samples

Content type
application/json
{
  • "description": "string",
  • "licensee_product_id": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "license_key": "string",
  • "licensee_product": {
    },
  • "project": {
    },
  • "size": 0
}

Metros

Metro Management. Check out the product docs to learn more about Metros.

Retrieve all metros

Provides a listing of available metros

Authorizations:
X-Auth-Token

Responses

Response Schema: application/json
Array of objects (Metro)
Array
code
string
country
string
id
string <uuid>
name
string

Response samples

Content type
application/json
{
  • "metros": [
    ]
}

Retrieve a specific Metro's details

Show the details for a metro, including name, code, and country.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Metro UUID

Responses

Response Schema: application/json
code
string
country
string
id
string <uuid>
name
string

Response samples

Content type
application/json
{
  • "code": "string",
  • "country": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string"
}

Plans

Plan Management (Device). Check out the product docs to learn more about Device Plans.

Retrieve all plans

Provides a listing of available plans to provision your device on.

Authorizations:
X-Auth-Token
query Parameters
categories[]
Array of strings
Items Enum: "compute" "storage" "legacy_gen" "current_gen"
Example: categories[]=compute

Filter plans by its category

type
string
Enum: "standard" "workload_optimized" "custom"
Example: type=standard

Filter plans by its plan type

slug
string
Example: slug=c3.small.x86

Filter plans by slug

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
Array of objects (Plan)
Array
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

Response samples

Content type
application/json
{
  • "plans": [
    ]
}

Retrieve all plans visible by the project

Returns a listing of available plans for the given project

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
Array of objects (Plan)
Array
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

Response samples

Content type
application/json
{
  • "plans": [
    ]
}

Retrieve all usages for device

Returns all usages for a device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
created[after]
string <datetime>

Filter usages created after this date

created[before]
string <datetime>

Filter usages created before this date

Responses

Response Schema: application/json
Array of objects (DeviceUsage)
Array
quantity
string
total
string
unit
string

Response samples

Content type
application/json
{
  • "usages": [
    ]
}

Retrieve all usages for project

Returns all usages for a project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
created[after]
string <datetime>

Filter usages created after this date

created[before]
string <datetime>

Filter usages created before this date

Responses

Response Schema: application/json
Array of objects (ProjectUsage)
Array
facility
string
name
string
plan
string
plan_version
string
price
string
quantity
string
total
string
type
string
unit
string

Response samples

Content type
application/json
{
  • "usages": [
    ]
}

Devices

Device Management. Check out the product docs to learn more about Server Devices.

Delete the device

Deletes a device and deprovisions it in our datacenter.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
force_delete
boolean

Force the deletion of the device, by detaching any storage volume still active.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a device

Type-specific options (such as facility for baremetal devices) will be included as part of the main data structure. State value can be one of: active inactive queued or provisioning

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

object (HardwareReservation)
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

device
object (Device) Recursive
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array
device
string
wipeTable
boolean
Array of objects (Partition)
Array of objects (Raid)
Array
devices
Array of strings
level
string
name
string
Array of objects (Filesystem)
Array
object (Mount)
device
string
format
string
point
string
options
Array of strings
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

Response samples

Content type
application/json
{
  • "always_pxe": true,
  • "billing_cycle": "string",
  • "bonding_mode": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "customdata": { },
  • "description": "string",
  • "facility": {
    },
  • "firmware_set_id": "bc3d90af-8405-43ae-8e5e-2f80a3bb0f88",
  • "hardware_reservation": {
    },
  • "hostname": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "image_url": "string",
  • "ip_addresses": [
    ],
  • "ipxe_script_url": "string",
  • "iqn": "string",
  • "locked": true,
  • "metro": {
    },
  • "network_frozen": true,
  • "network_ports": [
    ],
  • "operating_system": {
    },
  • "actions": [
    ],
  • "plan": {
    },
  • "project": {
    },
  • "project_lite": {
    },
  • "provisioning_events": [
    ],
  • "provisioning_percentage": 0.1,
  • "root_password": "string",
  • "short_id": "string",
  • "spot_instance": true,
  • "spot_price_max": 0.1,
  • "ssh_keys": [
    ],
  • "state": "queued",
  • "storage": {
    },
  • "switch_uuid": "string",
  • "tags": [
    ],
  • "termination_time": "2021-09-03T16:32:00+03:00",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": "string",
  • "userdata": "string",
  • "volumes": [
    ],
  • "sos": "string"
}

Update the device

Updates the device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Device to update

always_pxe
boolean
billing_cycle
string
object
Default: {}
property name*
additional property
any
description
string
hostname
string
firmware_set_id
string
ipxe_script_url
string
locked
boolean

Whether the device should be locked, preventing accidental deletion.

network_frozen
boolean

If true, this instance can not be converted to a different network type.

spot_instance
boolean

Can be set to false to convert a spot-market instance to on-demand.

tags
Array of strings
userdata
string

Responses

Response Schema: application/json
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

object (HardwareReservation)
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

device
object (Device) Recursive
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array
device
string
wipeTable
boolean
Array of objects (Partition)
Array of objects (Raid)
Array
devices
Array of strings
level
string
name
string
Array of objects (Filesystem)
Array
object (Mount)
device
string
format
string
point
string
options
Array of strings
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

Request samples

Content type
application/json
{
  • "always_pxe": true,
  • "billing_cycle": "string",
  • "customdata": { },
  • "description": "string",
  • "hostname": "string",
  • "firmware_set_id": "string",
  • "ipxe_script_url": "string",
  • "locked": true,
  • "network_frozen": true,
  • "spot_instance": true,
  • "tags": [
    ],
  • "userdata": "string"
}

Response samples

Content type
application/json
{
  • "always_pxe": true,
  • "billing_cycle": "string",
  • "bonding_mode": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "customdata": { },
  • "description": "string",
  • "facility": {
    },
  • "firmware_set_id": "bc3d90af-8405-43ae-8e5e-2f80a3bb0f88",
  • "hardware_reservation": {
    },
  • "hostname": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "image_url": "string",
  • "ip_addresses": [
    ],
  • "ipxe_script_url": "string",
  • "iqn": "string",
  • "locked": true,
  • "metro": {
    },
  • "network_frozen": true,
  • "network_ports": [
    ],
  • "operating_system": {
    },
  • "actions": [
    ],
  • "plan": {
    },
  • "project": {
    },
  • "project_lite": {
    },
  • "provisioning_events": [
    ],
  • "provisioning_percentage": 0.1,
  • "root_password": "string",
  • "short_id": "string",
  • "spot_instance": true,
  • "spot_price_max": 0.1,
  • "ssh_keys": [
    ],
  • "state": "queued",
  • "storage": {
    },
  • "switch_uuid": "string",
  • "tags": [
    ],
  • "termination_time": "2021-09-03T16:32:00+03:00",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": "string",
  • "userdata": "string",
  • "volumes": [
    ],
  • "sos": "string"
}

Perform an action

Performs an action for the given device. Possible actions include: power_on, power_off, reboot, reinstall, and rescue (reboot the device into rescue OS.)

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Request Body schema: application/json
required

Action to perform

type
required
string
Enum: "power_on" "power_off" "reboot" "rescue" "reinstall"

Action to perform. See Device.actions for possible actions.

force_delete
boolean

May be required to perform actions under certain conditions

deprovision_fast
boolean

When type is reinstall, enabling fast deprovisioning will bypass full disk wiping.

preserve_data
boolean

When type is reinstall, preserve the existing data on all disks except the operating-system disk.

operating_system
string

When type is reinstall, use this operating_system (defaults to the current operating system)

ipxe_script_url
string

When type is reinstall, use this ipxe_script_url (operating_system must be custom_ipxe, defaults to the current ipxe_script_url)

Responses

Request samples

Content type
application/json
{
  • "type": "power_on",
  • "force_delete": true,
  • "deprovision_fast": true,
  • "preserve_data": true,
  • "operating_system": "ubuntu_22_04",
  • "ipxe_script_url": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve an instance bandwidth

Retrieve an instance bandwidth for a given period of time.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
from
required
string

Timestamp from range

until
required
string

Timestamp to range

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve BGP neighbor data for this device

Provides a summary of the BGP neighbor data associated to the BGP sessions for this device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (BgpNeighborData)

A list of BGP session neighbor data

Array
address_family
integer <int32>

Address Family for IP Address. Accepted values are 4 or 6

customer_as
integer <int32>

The customer's ASN. In a local BGP deployment, this will be an internal ASN used to route within the data center. For a global BGP deployment, this will be the your own ASN, configured when you set up BGP for your project.

customer_ip
string

The device's IP address. For an IPv4 BGP session, this is typically the private bond0 address for the device.

md5_enabled
boolean

True if an MD5 password is configured for the project.

md5_password
string

The MD5 password configured for the project, if set.

multihop
boolean

True when the BGP session should be configured as multihop.

peer_as
integer <int32>

The Peer ASN to use when configuring BGP on your device.

peer_ips
Array of strings

A list of one or more IP addresses to use for the Peer IP section of your BGP configuration. For non-multihop sessions, this will typically be a single gateway address for the device. For multihop sessions, it will be a list of IPs.

Array of objects (BgpRoute)

A list of project subnets

Array of objects (BgpRoute)

A list of outgoing routes. Only populated if the BGP session has default route enabled.

Response samples

Content type
application/json
{
  • "bgp_neighbors": [
    ]
}

Retrieve all BGP sessions

Provides a listing of available BGP sessions for the device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (BgpSession)
Array
address_family
required
string
Enum: "ipv4" "ipv6"
created_at
string <date-time>
default_route
boolean
object (Href)
href
string
id
string <uuid>
learned_routes
Array of strings
status
string

The status of the BGP Session. Multiple status values may be reported when the device is connected to multiple switches, one value per switch. Each status will start with "unknown" and progress to "up" or "down" depending on the connected device. Subsequent "unknown" values indicate a problem acquiring status from the switch.

updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "bgp_sessions": [
    ]
}

Create a BGP session

Creates a BGP session.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

Request Body schema: application/json
required

BGP session to create

address_family
string
Enum: "ipv4" "ipv6"

Address family for BGP session.

default_route
boolean
Default: false

Set the default route policy.

Responses

Response Schema: application/json
address_family
required
string
Enum: "ipv4" "ipv6"
created_at
string <date-time>
default_route
boolean
object (Href)
href
required
string
href
string
id
string <uuid>
learned_routes
Array of strings
status
string

The status of the BGP Session. Multiple status values may be reported when the device is connected to multiple switches, one value per switch. Each status will start with "unknown" and progress to "up" or "down" depending on the connected device. Subsequent "unknown" values indicate a problem acquiring status from the switch.

updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "address_family": "ipv4",
  • "default_route": false
}

Response samples

Content type
application/json
{
  • "address_family": "ipv4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "default_route": true,
  • "device": {
    },
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "learned_routes": [
    ],
  • "status": "up,down",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve the custom metadata of an instance

Provides the custom metadata stored for this instance in json format

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Instance UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Get Device's Health Status

Returns the health rollup status of the device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Responses

Response Schema: application/json
health_rollup
string
Enum: "ok" "warning" "critical"

Health Status

updated_at
string <date-time>

Last update of health status.

Response samples

Content type
application/json
{
  • "health_rollup": "ok",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Device's associated Firmware Set

Returns the firmware set associated with the device. If a custom firmware set is associated with the device, then it is returned. Otherwise, if a default firmware set is available it is returned.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Responses

Response Schema: application/json
object (FirmwareSet)

Represents a Firmware Set

uuid
required
string <uuid>

Firmware Set UUID

name
required
string

Firmware Set Name

created_at
string <date-time>

Datetime when the block was created.

updated_at
string <date-time>

Datetime when the block was updated.

Array of objects (Attribute)

Represents a list of attributes

Array
namespace
string

Attribute namespace

created_at
string <date-time>

Datetime when the block was created.

updated_at
string <date-time>

Datetime when the block was updated.

object (AttributeData)
Array of objects (Component)

List of components versions

Array
uuid
string <uuid>

Component UUID

vendor
string

Component vendor

model
Array of strings

List of models where this component version can be applied

filename
string

name of the file

version
string

Version of the component

component
string

Component type

checksum
string

File checksum

upstream_url
string

Location of the file

repository_url
string

Location of the file in the repository

created_at
string <date-time>

Datetime when the block was created.

updated_at
string <date-time>

Datetime when the block was updated.

Response samples

Content type
application/json
{
  • "record": {
    }
}

Retrieve all ip assignments

Returns all ip assignments for a device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

Response samples

Content type
application/json
{
  • "ip_addresses": [
    ]
}

Create an ip assignment

Creates an ip assignment for a device.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

IPAssignment to create

address
required
string
customdata
object

Responses

Response Schema: application/json
address
string
address_family
integer
object (Href)
href
required
string
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

code
string
country
string
id
string <uuid>
name
string
netmask
string
network
string
object (ParentBlock)
cidr
integer
href
string
netmask
string
network
string
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

Request samples

Content type
application/json
{
  • "address": "string",
  • "customdata": { }
}

Response samples

Content type
application/json
{
  • "address": "string",
  • "address_family": 0,
  • "assigned_to": {
    },
  • "cidr": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "gateway": "string",
  • "global_ip": true,
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "manageable": true,
  • "management": true,
  • "metro": {
    },
  • "netmask": "string",
  • "network": "string",
  • "parent_block": {
    },
  • "public": true,
  • "state": "pending",
  • "next_hop": "192.168.0.1"
}

Retrieve metadata

Retrieve device metadata

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Responses

Response Schema: application/json
class
string
object
Default: {}
property name*
additional property
any
facility
string

The facility code of the instance

hostname
string
id
string <uuid>
iqn
string
metro
string

The metro code of the instance

object (Metadata_network)
addresses
Array of strings
interfaces
Array of objects
object (Metadata_network_network)
object (Metadata_network_network_bonding)
link_aggregation
string
mac
string
mode
integer
operating_system
object
plan
string

The plan slug of the instance

private_subnets
Array of strings

An array of the private subnets

reserved
boolean
specs
object

The specs of the plan version of the instance

ssh_keys
Array of strings
switch_short_id
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
tags
Array of strings
volumes
Array of strings

Response samples

Content type
application/json
{
  • "class": "string",
  • "customdata": { },
  • "facility": "string",
  • "hostname": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "iqn": "string",
  • "metro": "string",
  • "network": {
    },
  • "operating_system": { },
  • "plan": "string",
  • "private_subnets": [
    ],
  • "reserved": true,
  • "specs": { },
  • "ssh_keys": [
    ],
  • "switch_short_id": "string",
  • "state": "queued",
  • "tags": [
    ],
  • "volumes": [
    ]
}

Retrieve device traffic

Returns the total amount of inbound or outbound traffic for a specific device. The default time period is 1 hour.

Please note the results capture all network traffic for the server, but not all traffic may come from or be destined to the Internet and may be non-billable. Only Internet bound traffic is charged.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

query Parameters
direction
required
string
Enum: "inbound" "outbound"

Traffic direction

interval
string
Enum: "minute" "hour" "day" "week" "month" "year" "hour_of_day" "day_of_week" "day_of_month" "month_of_year"

Traffic interval

bucket
string
Enum: "internal" "external"

Traffic bucket

object (findTraffic_timeframe_parameter)

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve userdata

Retrieve device userdata

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Responses

Response Schema: application/json
userdata
string

Response samples

Content type
application/json
{
  • "userdata": "string"
}

Retrieve the custom metadata of an IP Assignment

Provides the custom metadata stored for this IP Assignment in json format

Authorizations:
X-Auth-Token
path Parameters
instance_id
required
string <uuid>

Instance UUID

id
required
string <uuid>

Ip Assignment UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve all devices of an organization

Provides a collection of devices for a given organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
search
string

Search by hostname, description, short_id, reservation short_id, tags, plan name, plan slug, facility code, facility name, operating system name, operating system slug, IP addresses.

categories
Array of strings
Items Enum: "compute" "storage" "legacy_gen" "current_gen"
Example: categories=compute

Filter by plan category

facility
string

Filter by device facility

hostname
string

Filter by partial hostname

reserved
boolean

Filter only reserved instances. When set to true, only include reserved instances. When set to false, only include on-demand instances.

tag
string

Filter by device tag

type
string

Filter by instance type (ondemand,spot,reserved)

has_termination_time
boolean

Filter only instances marked for termination. When set to true, only include instances that have a termination time. When set to false, only include instances that do not have a termination time.

mac_address
string

Filter by MAC address

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Device)
Array
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

object
Default: {}
description
string
object (Facility)
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

object (HardwareReservation)
hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

object (OperatingSystem)
Array of objects (Device_actions_inner)

Actions supported by the device instance.

object (Plan)
object (Project)
object (Device_project_lite)

Lite version of project object when included

Array of objects (Event)
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "meta": {
    }
}

Retrieve all devices of a project

Provides a collection of devices for a given project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
search
string

Search by hostname, description, short_id, reservation short_id, tags, plan name, plan slug, facility code, facility name, operating system name, operating system slug, IP addresses.

categories
Array of strings
Items Enum: "compute" "storage" "legacy_gen" "current_gen"
Example: categories=compute

Filter by plan category

facility
string

Filter by device facility

metro
string

Filter by device metro

hostname
string

Filter by partial hostname

reserved
boolean

Filter only reserved instances. When set to true, only include reserved instances. When set to false, only include on-demand instances.

tag
string

Filter by device tag

type
string

Filter by instance type (ondemand,spot,reserved)

has_termination_time
boolean

Filter only instances marked for termination. When set to true, only include instances that have a termination time. When set to false, only include instances that do not have a termination time.

mac_address
string

Filter by MAC address

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (Device)
Array
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

object
Default: {}
description
string
object (Facility)
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

object (HardwareReservation)
hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

object (OperatingSystem)
Array of objects (Device_actions_inner)

Actions supported by the device instance.

object (Plan)
object (Project)
object (Device_project_lite)

Lite version of project object when included

Array of objects (Event)
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "meta": {
    }
}

Create a device

Creates a new device and provisions it in the specified location.

Device type-specific options are accepted. For example, baremetal devices accept operating_system, hostname, and plan. These parameters may not be accepted for other device types. The default device type is baremetal.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Device to create

required
Array of strings or string (MetroInput_metro)

Metro code or ID of where the device should be provisioned in, or it can be instructed to create the device in the best available metro with { "metro": "any" }. The special metro value of any means anywhere, any metro. When any is chosen in the request, the metro location is picked per our scheduling algorithms that favor the following factors: hardware reservation location (if requesting reserved hardware), ip reservations, spot instances, etc. The any keyword does not optimize for cost, this means that usage costs (instance, transfer, other features dependent on location) will vary. Please check metro value in response to see where the device was created.

Additionally it is possible to set a prioritized location selection. For example { "metro": ["m3", "m2", "any"] } can be used to prioritize m3 and then m2 before accepting any metro. If none of the metros provided have availability for the requested device the request will fail. Either metro or facility must be provided.

Any of
Array
string
always_pxe
boolean
Default: false

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.

billing_cycle
string
Enum: "hourly" "daily" "monthly" "yearly"

The billing cycle of the device.

object
Default: {}

Customdata is an arbitrary JSON value that can be accessed via the metadata service.

property name*
additional property
any
description
string

Any description of the device or how it will be used. This may be used to inform other API consumers with project access.

features
Array of strings

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.

hardware_reservation_id
string
Default: ""

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 for more details.

hostname
string

The hostname to use within the operating system. The same hostname may be used on multiple devices within a project.

Array of objects (IPAddress)
Default: [{"address_family":4,"public":true},{"address_family":4,"public":false},{"address_family":6,"public":true}]

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.

Array
address_family
integer <int32>
Enum: 4 6

Address Family for IP Address

cidr
integer <int32>

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)

ip_reservations
Array of strings

UUIDs of any IP reservations to use when assigning IPs

public
boolean
Default: true

Address Type for IP Address

ipxe_script_url
string

When set, the device will chainload an iPXE Script at boot fetched from the supplied URL.

See Custom iPXE for more details.

locked
boolean
Default: false

Whether the device should be locked, preventing accidental deletion.

network_frozen
boolean

If true, this instance can not be converted to a different network type.

no_ssh_keys
boolean
Default: false

Overrides default behaviour of attaching all of the organization members ssh keys and project ssh keys to device if no specific keys specified

operating_system
required
string

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.

plan
required
string

The slug of the device plan to provision.

private_ipv4_subnet_size
integer <int32>

Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device.

project_ssh_keys
Array of strings <uuid> [ items <uuid > ]

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.

public_ipv4_subnet_size
integer <int32>

Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device. Your project must have addresses available for a non-default request.

spot_instance
boolean

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.

spot_price_max
number <float>

The maximum amount to bid for a spot instance.

Array of objects (SSHKeyInput)

A list of new or existing project ssh_keys that should be authorized to access this device (typically via /root/.ssh/authorized_keys). These keys will also appear in the device metadata.

These keys are added in addition to any keys defined by project_ssh_keys and user_ssh_keys.

Array
key
string
label
string
tags
Array of strings
object (Storage)
Array of objects (Disk)
Array
device
string
wipeTable
boolean
Array of objects (Partition)
Array of objects (Raid)
Array
devices
Array of strings
level
string
name
string
Array of objects (Filesystem)
Array
object (Mount)
device
string
format
string
point
string
options
Array of strings
tags
Array of strings
termination_time
string <date-time>

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.

user_ssh_keys
Array of strings <uuid> [ items <uuid > ]

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.

userdata
string

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 and Provisioning with Custom iPXE for more details.

Responses

Response Schema: application/json
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

object (HardwareReservation)
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

device
object (Device) Recursive
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array
device
string
wipeTable
boolean
Array of objects (Partition)
Array of objects (Raid)
Array
devices
Array of strings
level
string
name
string
Array of objects (Filesystem)
Array
object (Mount)
device
string
format
string
point
string
options
Array of strings
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

Request samples

Content type
application/json
{
  • "metro": [
    ],
  • "always_pxe": false,
  • "billing_cycle": "hourly",
  • "customdata": { },
  • "description": "string",
  • "features": [
    ],
  • "hardware_reservation_id": "next-available",
  • "hostname": "string",
  • "ip_addresses": [
    ],
  • "ipxe_script_url": "string",
  • "locked": false,
  • "network_frozen": true,
  • "no_ssh_keys": false,
  • "operating_system": "string",
  • "plan": "c3.large.x86",
  • "private_ipv4_subnet_size": 0,
  • "project_ssh_keys": [
    ],
  • "public_ipv4_subnet_size": 0,
  • "spot_instance": true,
  • "spot_price_max": 1.23,
  • "ssh_keys": [
    ],
  • "storage": {
    },
  • "tags": [
    ],
  • "termination_time": "2021-09-03T16:32:00+03:00",
  • "user_ssh_keys": [
    ],
  • "userdata": "string"
}

Response samples

Content type
application/json
{
  • "always_pxe": true,
  • "billing_cycle": "string",
  • "bonding_mode": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "customdata": { },
  • "description": "string",
  • "facility": {
    },
  • "firmware_set_id": "bc3d90af-8405-43ae-8e5e-2f80a3bb0f88",
  • "hardware_reservation": {
    },
  • "hostname": "string",
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "image_url": "string",
  • "ip_addresses": [
    ],
  • "ipxe_script_url": "string",
  • "iqn": "string",
  • "locked": true,
  • "metro": {
    },
  • "network_frozen": true,
  • "network_ports": [
    ],
  • "operating_system": {
    },
  • "actions": [
    ],
  • "plan": {
    },
  • "project": {
    },
  • "project_lite": {
    },
  • "provisioning_events": [
    ],
  • "provisioning_percentage": 0.1,
  • "root_password": "string",
  • "short_id": "string",
  • "spot_instance": true,
  • "spot_price_max": 0.1,
  • "ssh_keys": [
    ],
  • "state": "queued",
  • "storage": {
    },
  • "switch_uuid": "string",
  • "tags": [
    ],
  • "termination_time": "2021-09-03T16:32:00+03:00",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user": "string",
  • "userdata": "string",
  • "volumes": [
    ],
  • "sos": "string"
}

Batches

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

Delete the Batch

Deletes the Batch.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Batch UUID

query Parameters
remove_associated_instances
boolean
Default: false

Delete all instances created from this batch

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

Retrieve a Batch

Returns a Batch

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Batch UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
created_at
string <date-time>
Array of objects (Href)
Array
href
required
string
error_messages
Array of strings
id
string <uuid>
object (Href)
href
required
string
quantity
integer
state
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "devices": [
    ],
  • "error_messages": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project": {
    },
  • "quantity": 0,
  • "state": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve all batches by project

Returns all batches for the given project

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
include
Array of strings

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.

Responses

Response Schema: application/json
Array of objects (Batch)
Array
created_at
string <date-time>
Array of objects (Href)
error_messages
Array of strings
id
string <uuid>
object (Href)
quantity
integer
state
string
updated_at
string <date-time>

Response samples

Content type
application/json
{
  • "batches": [
    ]
}

Create a devices batch

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

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

Request Body schema: application/json
required

Batches to create

Array of objects (InstancesBatchCreateInput_batches_inner)
Array
hostnames
Array of strings
quantity
integer

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.

required
Array of strings or string (MetroInput_metro)

Metro code or ID of where the device should be provisioned in, or it can be instructed to create the device in the best available metro with { "metro": "any" }. The special metro value of any means anywhere, any metro. When any is chosen in the request, the metro location is picked per our scheduling algorithms that favor the following factors: hardware reservation location (if requesting reserved hardware), ip reservations, spot instances, etc. The any keyword does not optimize for cost, this means that usage costs (instance, transfer, other features dependent on location) will vary. Please check metro value in response to see where the device was created.

Additionally it is possible to set a prioritized location selection. For example { "metro": ["m3", "m2", "any"] } can be used to prioritize m3 and then m2 before accepting any metro. If none of the metros provided have availability for the requested device the request will fail. Either metro or facility must be provided.

always_pxe
boolean
Default: false

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.

billing_cycle
string
Enum: "hourly" "daily" "monthly" "yearly"

The billing cycle of the device.

object
Default: {}

Customdata is an arbitrary JSON value that can be accessed via the metadata service.

description
string

Any description of the device or how it will be used. This may be used to inform other API consumers with project access.

features
Array of strings

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.

hardware_reservation_id
string
Default: ""

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 for more details.

hostname
string

The hostname to use within the operating system. The same hostname may be used on multiple devices within a project.

Array of objects (IPAddress)
Default: [{"address_family":4,"public":true},{"address_family":4,"public":false},{"address_family":6,"public":true}]

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.

ipxe_script_url
string

When set, the device will chainload an iPXE Script at boot fetched from the supplied URL.

See Custom iPXE for more details.

locked
boolean
Default: false

Whether the device should be locked, preventing accidental deletion.

network_frozen
boolean

If true, this instance can not be converted to a different network type.

no_ssh_keys
boolean
Default: false

Overrides default behaviour of attaching all of the organization members ssh keys and project ssh keys to device if no specific keys specified

operating_system
required
string

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.

plan
required
string

The slug of the device plan to provision.

private_ipv4_subnet_size
integer <int32>

Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device.

project_ssh_keys
Array of strings <uuid> [ items <uuid > ]

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.

public_ipv4_subnet_size
integer <int32>

Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device. Your project must have addresses available for a non-default request.

spot_instance
boolean

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.

spot_price_max
number <float>

The maximum amount to bid for a spot instance.

Array of objects (SSHKeyInput)

A list of new or existing project ssh_keys that should be authorized to access this device (typically via /root/.ssh/authorized_keys). These keys will also appear in the device metadata.

These keys are added in addition to any keys defined by project_ssh_keys and user_ssh_keys.

object (Storage)
tags
Array of strings
termination_time
string <date-time>

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.

user_ssh_keys
Array of strings <uuid> [ items <uuid > ]

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.

userdata
string

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 and Provisioning with Custom iPXE for more details.

Responses

Response Schema: application/json
Array of objects (Batch)
Array
created_at
string <date-time>
Array of objects (Href)
error_messages
Array of strings
id
string <uuid>
object (Href)
quantity
integer
state
string
updated_at
string <date-time>

Request samples

Content type
application/json
{
  • "batches": [
    ]
}

Response samples

Content type
application/json
{
  • "batches": [
    ]
}

Capacity

Capacity Management. Check out the product docs to learn more about Capacity.

View capacity

Returns a list of facilities and plans with their current capacity.

Authorizations:
X-Auth-Token

Responses

Response Schema: application/json
object
additional property
object
additional property
object (CapacityLevelPerBaremetal)
level
string

Response samples

Content type
application/json
{
  • "capacity": {
    }
}

View capacity for metros

Returns a list of metros and plans with their current capacity.

Authorizations:
X-Auth-Token

Responses

Response Schema: application/json
object
additional property
object
additional property
object (CapacityLevelPerBaremetal)
level
string

Response samples

Content type
application/json
{
  • "capacity": {
    }
}

Check capacity for a metro

Validates if a deploy can be fulfilled in a metro.

Authorizations:
X-Auth-Token
Request Body schema: application/json
required

Metro to check capacity in

Array of objects (ServerInfo)
Array
metro
string

The metro ID or code to check the capacity in.

plan
string

The plan ID or slug to check the capacity of.

quantity
string

The number of servers to check the capacity of.

Responses

Response Schema: application/json
Array of objects (CapacityCheckPerMetroInfo)
Array
available
boolean

Returns true if there is enough capacity in the metro to fulfill the quantity set. Returns false if there is not enough.

metro
string

The metro ID or code sent to check capacity.

plan
string

The plan ID or slug sent to check capacity.

quantity
string

The number of servers sent to check capacity.

Request samples

Content type
application/json
{
  • "servers": [
    ]
}

Response samples

Content type
application/json
{
  • "servers": [
    ]
}

View available hardware plans per Metro for given organization

Returns a list of metros and plans with their current capacity.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

Responses

Response Schema: application/json
object
additional property
object
additional property
object (CapacityLevelPerBaremetal)
level
string

Response samples

Content type
application/json
{
  • "capacity": {
    }
}

ConsoleLogDetails

Console Log Details. Notice: This is a test feature currently under active development, and only available to certain users. Please contact Customer Success for more information.

captureScreenshot

Capture a screenshot from the device, if supported, via the BMC.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Device UUID

Responses

Response Schema: application/jpeg
string <binary>

Response samples

Content type
application/json
{
  • "error": "string",
  • "errors": [
    ]
}

FirmwareSets

Firmware Sets Management. Notice: Firmware Sets are a test feature currently under active development, and only available to certain users. Please contact Customer Success for more information.

Get Organization's Firmware Sets

Returns all firmware sets associated with the organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Organization UUID

query Parameters
page
integer

page number to return

per_page
integer

items returned per page.

Responses

Response Schema: application/json
page_size
integer

Max number of items returned in a page

page
integer

Page returned

page_count
integer

Items returned in current page

total_pages
integer

Total count of pages

total_record_count
integer

Total count of items

Array of objects (FirmwareSet)

Represents a list of FirmwareSets

Array
uuid
required
string <uuid>

Firmware Set UUID

name
required
string

Firmware Set Name

created_at
string <date-time>

Datetime when the block was created.

updated_at
string <date-time>

Datetime when the block was updated.

Array of objects (Attribute)

Represents a list of attributes

Array of objects (Component)

List of components versions

Response samples

Content type
application/json
{
  • "page_size": 0,
  • "page": 0,
  • "page_count": 0,
  • "total_pages": 0,
  • "total_record_count": 0,
  • "records": [
    ]
}

Get Project's Firmware Sets

Returns all firmware sets associated with the project or organization.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
page
integer

page number to return

per_page
integer

items returned per page.

Responses

Response Schema: application/json
page_size
integer

Max number of items returned in a page

page
integer

Page returned

page_count
integer

Items returned in current page

total_pages
integer

Total count of pages

total_record_count
integer

Total count of items

Array of objects (FirmwareSet)

Represents a list of FirmwareSets

Array
uuid
required
string <uuid>

Firmware Set UUID

name
required
string

Firmware Set Name

created_at
string <date-time>

Datetime when the block was created.

updated_at
string <date-time>

Datetime when the block was updated.

Array of objects (Attribute)

Represents a list of attributes

Array of objects (Component)

List of components versions

Response samples

Content type
application/json
{
  • "page_size": 0,
  • "page": 0,
  • "page_count": 0,
  • "total_pages": 0,
  • "total_record_count": 0,
  • "records": [
    ]
}

HardwareReservations

Hardware Reservation Management. Check out the product docs to learn more about Reserved Hardware.

Retrieve a hardware reservation

Returns a single hardware reservation

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

HardwareReservation UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Responses

Response Schema: application/json
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

object (Device)
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

hardware_reservation
object (HardwareReservation) Recursive
hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array of objects (Raid)
Array of objects (Filesystem)
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "custom_rate": 1050.5,
  • "device": {
    },
  • "facility": {
    },
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "need_of_service": true,
  • "plan": {
    },
  • "project": {
    },
  • "provisionable": true,
  • "short_id": "string",
  • "spare": true,
  • "switch_uuid": "string",
  • "termination_time": "2019-08-24T14:15:22Z"
}

Activate a spare hardware reservation

Activate a spare hardware reservation

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Hardware Reservation UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
optional

Note to attach to the reservation

description
string

Responses

Response Schema: application/json
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

object (Device)
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

hardware_reservation
object (HardwareReservation) Recursive
hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array of objects (Raid)
Array of objects (Filesystem)
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "custom_rate": 1050.5,
  • "device": {
    },
  • "facility": {
    },
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "need_of_service": true,
  • "plan": {
    },
  • "project": {
    },
  • "provisionable": true,
  • "short_id": "string",
  • "spare": true,
  • "switch_uuid": "string",
  • "termination_time": "2019-08-24T14:15:22Z"
}

Move a hardware reservation

Move a hardware reservation to another project

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Hardware Reservation UUID

query Parameters
include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

Request Body schema: application/json
required

Destination Project UUID

project_id
string <uuid>

Responses

Response Schema: application/json
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

object (Device)
always_pxe
boolean
billing_cycle
string
bonding_mode
integer
created_at
string <date-time>
object (Device_created_by)

The user that created the device.

avatar_thumb_url
string

Avatar thumbnail URL of the User

created_at
string <date-time>

When the user was created

email
string

Primary email address of the User

first_name
string

First name of the User

full_name
string

Full name of the User

href
string

API URL uniquely representing the User

id
required
string <uuid>

ID of the User

last_name
string

Last name of the User

short_id
required
string

Short ID of the User

updated_at
string <date-time>

When the user details were last updated

object
Default: {}
property name*
additional property
any
description
string
object (Facility)
object (Address)
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

name
string
firmware_set_id
string <uuid>

The UUID of the firmware set to associate with the device.

hardware_reservation
object (HardwareReservation) Recursive
hostname
string
href
string
id
string <uuid>
image_url
string
Array of objects (IPAssignment)
Array
address
string
address_family
integer
object (Href)
cidr
integer
created_at
string <date-time>
enabled
boolean
gateway
string
global_ip
boolean
href
string
id
string <uuid>
manageable
boolean
management
boolean
object (IPAssignment_metro)

The metro the IP address is in

netmask
string
network
string
object (ParentBlock)
public
boolean
state
string
Enum: "pending" "active" "deleting"

Only set when this is a Metal Gateway Elastic IP Assignment.

Describes the current configuration state of this IP on the network.

next_hop
string <ipv4>

Only set when this is a Metal Gateway Elastic IP Assignment.

The IP address within the Metal Gateway to which requests to the Elastic IP are forwarded.

ipxe_script_url
string
iqn
string
locked
boolean

Prevents accidental deletion of this resource when set to true.

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
network_frozen
boolean

Whether network mode changes such as converting to/from Layer2 or Layer3 networking, bonding or disbonding network interfaces are permitted for the device.

Array of objects (Port)

By default, servers at Equinix Metal are configured in a “bonded” mode using LACP (Link Aggregation Control Protocol). Each 2-NIC server is configured with a single bond (namely bond0) with both interfaces eth0 and eth1 as members of the bond in a default Layer 3 mode. Some device plans may have a different number of ports and bonds available.

Array
object (BondPortData)
object (PortData)
disbond_operation_supported
boolean

Indicates whether or not the bond can be broken on the port (when applicable).

href
string
id
string <uuid>
name
string
type
string
Enum: "NetworkPort" "NetworkBondPort"

Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports

network_type
string
Enum: "layer2-bonded" "layer2-individual" "layer3" "hybrid" "hybrid-bonded"

Composite network type of the bond

object (VirtualNetwork)
Array of objects (VirtualNetwork)
object (OperatingSystem)
build_date
string <date>

The date when Metal's current OS image was built and released.

deprecation_date
string <date>

The date when the OS is deprecated. This is the date set by the upstream operating system maintainer.

distro
string
distro_label
string
end_of_life_date
string <date>

The date when the Metal OS image no longer receives any updates and may be disabled at any time. Typically the same as the deprecation date set by the upstream OS maintainers.

end_of_service_date
string <date>

Metal-set date for when the OS is nearing end of life, typically 30 days before end of life.

id
string <uuid>
licensed
boolean

Indicates if the OS is licensed or not. Licensed operating systems are priced according to pricing property.

lifecycle_state
string

Where in the lifecycle the OS image is. Possible states are - "testing", "pre_release", "active", "deprecated", "end_of_service", or "end_of_life".

name
string
preinstallable
boolean

Indicates whether servers can be preinstalled with OS image in order to shorten provision time.

pricing
object

This object contains price per time unit and optional multiplier value if license price depends on hardware plan or components (e.g. number of cores).

provisionable_on
Array of strings
release_date
string <date>

The date the upstream operating system maintainer released this version of the OS.

release_notes
string

The current release notes for this OS image, typically in Markdown format.

slug
string
version
string
default_operating_system
boolean

Default operating system for the distro.

Array of objects (Device_actions_inner)

Actions supported by the device instance.

Array
type
string
name
string
object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
created_at
string <date-time>
customdata
object
Array of objects (Href)
href
string
id
string <uuid>
Array of objects (Href)
max_devices
object
Array of objects (Href)
Array of objects (Href)
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Href)
Array of objects (Href)
updated_at
string <date-time>
url
string
Array of objects (Href)
type
string
Value: "default"

The type of the project.

tags
Array of strings
object (Device_project_lite)

Lite version of project object when included

href
required
string
Array of objects (Event)
Array
body
string
created_at
string <date-time>
href
string
id
string <uuid>
interpolated
string
Array of objects (Href)
state
string
type
string
modified_by
object
ip
string
provisioning_percentage
number <float>

Only visible while device provisioning

root_password
string

Root password is automatically generated when server is provisioned and it is removed after 24 hours

short_id
string
spot_instance
boolean

Whether or not the device is a spot instance.

spot_price_max
number <float>

The maximum price per hour you are willing to pay to keep this spot instance. If you are outbid, the termination will be set allowing two minutes before shutdown.

Array of objects (Href)
Array
href
required
string
state
string
Enum: "queued" "provisioning" "deprovisioning" "reinstalling" "active" "inactive" "failed" "powering_on" "powering_off" "deleted"

The current state the instance is in.

  • When an instance is initially created it will be in the queued state until it is picked up by the provisioner.
  • Once provisioning has begun on the instance it's state will move to provisioning.
  • When an instance is deleted, it will move to deprovisioning state until the deprovision is completed and the instance state moves to deleted.
  • If an instance fails to provision or deprovision it will move to failed state.
  • Once an instance has completed provisioning it will move to active state.
  • If an instance is currently powering off or powering on it will move to powering_off or powering_on states respectively.
  • When the instance is powered off completely it will move to the inactive state.
  • When an instance is powered on completely it will move to the active state.
  • Using the reinstall action to install a new OS on the instance will cause the instance state to change to reinstalling.
  • When the reinstall action is complete the instance will move to active state.
object (Storage)
Array of objects (Disk)
Array of objects (Raid)
Array of objects (Filesystem)
switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

tags
Array of strings
termination_time
string <date-time>

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.

updated_at
string <date-time>
user
string
userdata
string
Array of objects (Href)
Array
href
required
string
sos
string

Hostname used to connect to the instance via the SOS (Serial over SSH) out-of-band console.

object (Facility)
object (Address)
address
required
string
address2
string
city
string
object (Coordinates)
country
required
string
state
string
zip_code
required
string
code
string
features
Array of strings
Items Enum: "baremetal" "backend_transfer" "layer_2" "global_ipv4" "ibx"
id
string <uuid>
ip_ranges
Array of strings

IP ranges registered in facility. Can be used for GeoIP location

object (Device_metro)

The metro the facility is in

code
string
country
string
id
string <uuid>
name
string
name
string
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
Array of objects (Plan_available_in_inner)

Shows which facilities the plan is available in, and the facility-based price if it is different from the default price.

Array
href
string

href to the Facility

object (Plan_available_in_inner_price)
Array of objects (Plan_available_in_metros_inner)

Shows which metros the plan is available in, and the metro-based price if it is different from the default price.

Array
href
string

href to the Metro

object (Plan_available_in_inner_price)
categories
Array of strings

Categories of the plan, like compute or storage. A Plan can belong to multiple categories.

class
string
description
string
deployment_types
Array of strings >= 0 items unique
Items Enum: "on_demand" "spot_market"
id
string <uuid>
legacy
boolean

Deprecated. Always return false

line
string
name
string
pricing
object
slug
string
object (Plan_specs)
Array of objects (Plan_specs_cpus_inner)
object (Plan_specs_memory)
Array of objects (Plan_specs_drives_inner)
Array of objects (Plan_specs_nics_inner)
object (Plan_specs_features)
type
string
Enum: "standard" "workload_optimized" "custom"

The plan type

object (Project)
backend_transfer_enabled
boolean
object (Href)
href
required
string
created_at
string <date-time>
customdata
object
Array of objects (Href)
Array
href
required
string
href
string
id
string <uuid>
Array of objects (Href)
Array
href
required
string
max_devices
object
Array of objects (Href)
Array
href
required
string
Array of objects (Href)
Array
href
required
string
name
string [ 1 .. 80 ] characters

The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.

network_status
object
object (Organization)
object (Address)
object (Address)
created_at
string <date-time>
credit_amount
number <float>
customdata
object
description
string
enforce_2fa_at
string <date-time>

Force to all members to have enabled the two factor authentication after that date, unless the value is null

href
string
id
string <uuid>
logo
string
Array of objects (Href)
Array of objects (Href)
name
string
Array of objects (Href)
terms
integer
twitter
string
updated_at
string <date-time>
website
string
object (Href)
href
required
string
Array of objects (Href)
Array
href
required
string
updated_at
string <date-time>
url
string
Array of objects (Href)
Array
href
required
string
type
string
Value: "default"

The type of the project.

tags
Array of strings
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

Request samples

Content type
application/json
{
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "custom_rate": 1050.5,
  • "device": {
    },
  • "facility": {
    },
  • "href": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "need_of_service": true,
  • "plan": {
    },
  • "project": {
    },
  • "provisionable": true,
  • "short_id": "string",
  • "spare": true,
  • "switch_uuid": "string",
  • "termination_time": "2019-08-24T14:15:22Z"
}

Retrieve all hardware reservations for a given project

Provides a collection of hardware reservations for a given project.

Authorizations:
X-Auth-Token
path Parameters
id
required
string <uuid>

Project UUID

query Parameters
query
string

Search by facility code, plan name, project name, reservation short ID or device hostname

state
string
Enum: "active" "spare" "need_of_service"

Filter by hardware reservation state

provisionable
string
Value: "only"

Filter hardware reservation that is provisionable

include
Array of strings

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.

exclude
Array of strings

Nested attributes to exclude. Excluded objects will return only the href attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply nested objects.

page
integer <int32> [ 1 .. 100000 ]
Default: 1

Page to return

per_page
integer <int32> [ 1 .. 1000 ]
Default: 10

Items returned per page

Responses

Response Schema: application/json
Array of objects (HardwareReservation)
Array
created_at
string <date-time>
custom_rate
number <float>

Amount that will be charged for every billing_cycle.

object (Device)
object (Facility)
href
string
id
string <uuid>
need_of_service
boolean

Whether this Device requires assistance from Equinix Metal.

object (Plan)
object (Project)
provisionable
boolean

Whether the reserved server is provisionable or not. Spare devices can't be provisioned unless they are activated first.

short_id
string <string>

Short version of the ID.

spare
boolean

Whether the Hardware Reservation is a spare. Spare Hardware Reservations are used when a Hardware Reservations requires service from Equinix Metal

switch_uuid
string

Switch short id. This can be used to determine if two devices are connected to the same switch, for example.

termination_time
string <date-time>

Expiration date for the reservation.

object (Meta)
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
object (Href)
href
required
string
total
integer
current_page
integer
last_page
integer

Response samples

Content type
application/json
{
  • "hardware_reservations": [