Metal API (1.0.0)

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

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

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

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.

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.

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.

Email Management

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