Packet Host MetalGateways API
Metal Gateway Management.Check out the product docs to learn more about [Metal Gateways](https://metal.equinix.com/developers/docs/networking/metal-gateway/).
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: support@equinixmetal.com
name: Equinix Metal API Team
description: "# Introduction\nEquinix Metal provides a RESTful HTTP API which can be reached at <https://api.equinix.com/metal/v1>. This document describes the API and how to use it.\n\nThe API allows you to programmatically interact with all\nof your Equinix Metal resources, including devices, networks, addresses, organizations,\nprojects, and your user account. Every feature of the Equinix Metal web interface is accessible through the API.\n\nThe API docs are generated from the Equinix Metal OpenAPI specification and are officially hosted at <https://metal.equinix.com/developers/api>.\n\n# Common Parameters\n\nThe Equinix Metal API uses a few methods to minimize network traffic and improve throughput. These parameters are not used in all API calls, but are used often enough to warrant their own section. Look for these parameters in the documentation for the API calls that support them.\n\n## Pagination\n\nPagination is used to limit the number of results returned in a single request. The API will return a maximum of 100 results per page. To retrieve additional results, you can use the `page` and `per_page` query parameters.\n\nThe `page` parameter is used to specify the page number. The first page is `1`. The `per_page` parameter is used to specify the number of results per page. The maximum number of results differs by resource type.\n\n## Sorting\n\nWhere offered, the API allows you to sort results by a specific field. To sort results use the `sort_by` query parameter with the root level field name as the value. The `sort_direction` parameter is used to specify the sort direction, either either `asc` (ascending) or `desc` (descending).\n\n## Filtering\n\nFiltering is used to limit the results returned in a single request. The API supports filtering by certain fields in the response. To filter results, you can use the field as a query parameter.\n\nFor example, to filter the IP list to only return public IPv4 addresses, you can filter by the `type` field, as in the following request:\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/projects/id/ips?type=public_ipv4\n```\n\nOnly IP addresses with the `type` field set to `public_ipv4` will be returned.\n\n## Searching\n\nSearching is used to find matching resources using multiple field comparissons. The API supports searching in resources that define this behavior. Currently the search parameter is only available on devices, ssh_keys, api_keys and memberships endpoints.\n\nTo search resources you can use the `search` query parameter.\n\n## Include and Exclude\n\nFor resources that contain references to other resources, sucha as a Device that refers to the Project it resides in, the Equinix Metal API will returns `href` values (API links) to the associated resource.\n\n```json\n{\n ...\n \"project\": {\n \"href\": \"/metal/v1/projects/f3f131c8-f302-49ef-8c44-9405022dc6dd\"\n }\n}\n```\n\nIf you're going need the project details, you can avoid a second API request. Specify the contained `href` resources and collections that you'd like to have included in the response using the `include` query parameter.\n\nFor example:\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=projects\n```\n\nThe `include` parameter is generally accepted in `GET`, `POST`, `PUT`, and `PATCH` requests where `href` resources are presented.\n\nTo have multiple resources include, use a comma-separated list (e.g. `?include=emails,projects,memberships`).\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=emails,projects,memberships\n```\n\nYou may also include nested associations up to three levels deep using dot notation (`?include=memberships.projects`):\n\n```sh\ncurl -H 'X-Auth-Token: my_authentication_token' \\\n https://api.equinix.com/metal/v1/user?include=memberships.projects\n```\n\nTo exclude resources, and optimize response delivery, use the `exclude` query parameter. The `exclude` parameter is generally accepted in `GET`, `POST`, `PUT`, and `PATCH` requests for fields with nested object responses. When excluded, these fields will be replaced with an object that contains only an `href` field.\n"
license:
name: Equinix Metal
url: https://metal.equinix.com/legal/
termsOfService: https://metal.equinix.com/legal/
title: Metal Authentication MetalGateways API
version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
tags:
- description: 'Metal Gateway Management.Check out the product docs to learn more about [Metal Gateways](https://metal.equinix.com/developers/docs/networking/metal-gateway/).
'
externalDocs:
url: https://metal.equinix.com/developers/docs/networking/metal-gateway/
name: MetalGateways
paths:
/metal-gateways/{id}:
delete:
description: Deletes a metal gateway and any elastic IP assignments associated with this metal gateway.
operationId: deleteMetalGateway
parameters:
- description: Metal Gateway UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/findMetalGatewayById_200_response'
description: accepted
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Deletes the metal gateway
tags:
- MetalGateways
get:
description: Returns a specific metal gateway
operationId: findMetalGatewayById
parameters:
- description: Metal Gateway UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/findMetalGatewayById_200_response'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Returns the metal gateway
tags:
- MetalGateways
/metal-gateways/{id}/ips:
get:
description: Returns the list of Elastic IPs assigned to this Metal Gateway
operationId: getMetalGatewayElasticIps
parameters:
- description: Metal Gateway UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/IPAssignmentList'
description: OK
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Not Found
summary: List Metal Gateway Elastic IPs
tags:
- MetalGateways
post:
description: 'Create a new Elastic IP on this Metal Gateway.
Assign an IPv4 range as an elastic IP to the Metal Gateway, with a specified next-hop address contained within the Metal Gateway.
Notice: Elastic IPs on Metal Gateways are a test feature currently under active development, and only available to certain users. Please contact Customer Success for more information.
'
operationId: createMetalGatewayElasticIp
parameters:
- description: Metal Gateway UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetalGatewayElasticIpCreateInput'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/IPAssignment'
description: Created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unprocessable entity
summary: Create a Metal Gateway Elastic IP
tags:
- MetalGateways
/projects/{project_id}/metal-gateways:
get:
description: Return all metal gateways for a project
operationId: findMetalGatewaysByProject
parameters:
- description: Project UUID
in: path
name: project_id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
- description: Page to return
in: query
name: page
schema:
default: 1
format: int32
maximum: 100000
minimum: 1
type: integer
- description: Items returned per page
in: query
name: per_page
schema:
default: 10
format: int32
maximum: 1000
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MetalGatewayList'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Returns all metal gateways for a project
tags:
- MetalGateways
x-equinix-metal-paginated-property: MetalGateways
post:
description: Create a metal gateway in a project
operationId: createMetalGateway
parameters:
- description: Project UUID
in: path
name: project_id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- description: '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.'
explode: false
in: query
name: exclude
schema:
items:
type: string
type: array
style: form
- description: Page to return
in: query
name: page
schema:
default: 1
format: int32
maximum: 100000
minimum: 1
type: integer
- description: Items returned per page
in: query
name: per_page
schema:
default: 10
format: int32
maximum: 1000
minimum: 1
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createMetalGateway_request'
description: Metal Gateway to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/findMetalGatewayById_200_response'
description: created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Create a metal gateway
tags:
- MetalGateways
components:
schemas:
MetalGatewayCreateInput:
properties:
ip_reservation_id:
description: The UUID of an IP reservation that belongs to the same project as where the metal gateway will be created in. This field is required unless the private IPv4 subnet size is specified.
format: uuid
type: string
private_ipv4_subnet_size:
description: "The subnet size (8, 16, 32, 64, or 128) of the private IPv4 reservation that will be created for the metal gateway. This field is required unless a project IP reservation was specified.\n Please keep in mind that the number of private metal gateway ranges are limited per project. If you would like to increase the limit per project, please contact support for assistance."
type: integer
virtual_network_id:
description: The UUID of a metro virtual network that belongs to the same project as where the metal gateway will be created in.
format: uuid
type: string
required:
- virtual_network_id
type: object
IPReservation_metro:
allOf:
- $ref: '#/components/schemas/Metro'
- description: The metro the IP reservation is in. As long as the IP reservation has a metro, it can be used on a metro level. Can be null if requesting an IP reservation in a facility that is not in a metro.
type: object
createMetalGateway_request:
oneOf:
- $ref: '#/components/schemas/MetalGatewayCreateInput'
- $ref: '#/components/schemas/VrfMetalGatewayCreateInput'
Project:
example:
devices:
- href: href
- href: href
volumes:
- href: href
- href: href
created_at: 2000-01-23 04:56:07+00:00
type: null
memberships:
- href: href
- href: href
bgp_config:
href: href
tags:
- tags
- tags
max_devices: '{}'
ssh_keys:
- href: href
- href: href
updated_at: 2000-01-23 04:56:07+00:00
invitations:
- href: href
- href: href
members:
- href: href
- href: href
organization:
website: website
address:
country: country
address: address
address2: address2
city: city
coordinates:
latitude: latitude
longitude: longitude
state: state
zip_code: zip_code
projects:
- href: href
- href: href
credit_amount: 1.4658129
created_at: 2000-01-23 04:56:07+00:00
description: description
billing_address:
country: country
address: address
address2: address2
city: city
coordinates:
latitude: latitude
longitude: longitude
state: state
zip_code: zip_code
memberships:
- href: href
- href: href
enforce_2fa_at: 2000-01-23 04:56:07+00:00
twitter: twitter
updated_at: 2000-01-23 04:56:07+00:00
terms: 5
members:
- href: href
- href: href
name: name
logo: logo
customdata: '{}'
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
name: name
network_status: '{}'
customdata: '{}'
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
payment_method:
href: href
properties:
bgp_config:
$ref: '#/components/schemas/Href'
created_at:
format: date-time
type: string
customdata:
type: object
devices:
items:
$ref: '#/components/schemas/Href'
type: array
href:
type: string
id:
format: uuid
type: string
invitations:
items:
$ref: '#/components/schemas/Href'
type: array
max_devices:
type: object
members:
items:
$ref: '#/components/schemas/Href'
type: array
memberships:
items:
$ref: '#/components/schemas/Href'
type: array
name:
description: The name of the project. Cannot contain characters encoded in greater than 3 bytes such as emojis.
maxLength: 80
minLength: 1
type: string
network_status:
type: object
organization:
$ref: '#/components/schemas/Organization'
payment_method:
$ref: '#/components/schemas/Href'
ssh_keys:
items:
$ref: '#/components/schemas/Href'
type: array
updated_at:
format: date-time
type: string
volumes:
items:
$ref: '#/components/schemas/Href'
type: array
type:
$ref: '#/components/schemas/Project_type'
tags:
items:
type: string
type: array
type: object
MetalGatewayList_metal_gateways_inner:
anyOf:
- $ref: '#/components/schemas/MetalGateway'
- $ref: '#/components/schemas/VrfMetalGateway'
IPAssignment:
example:
address: address
parent_block:
netmask: netmask
cidr: 2
href: href
network: network
created_at: 2000-01-23 04:56:07+00:00
type: null
enabled: true
manageable: true
network: network
address_family: 5
public: true
management: true
netmask: netmask
metro: null
next_hop: next_hop
cidr: 5
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: null
global_ip: true
gateway: gateway
assigned_to:
href: href
properties:
address:
type: string
address_family:
type: integer
assigned_to:
$ref: '#/components/schemas/Href'
cidr:
type: integer
created_at:
format: date-time
type: string
enabled:
type: boolean
gateway:
type: string
global_ip:
type: boolean
href:
type: string
id:
format: uuid
type: string
manageable:
type: boolean
management:
type: boolean
metro:
$ref: '#/components/schemas/IPAssignment_metro'
netmask:
type: string
network:
type: string
parent_block:
$ref: '#/components/schemas/ParentBlock'
public:
type: boolean
state:
$ref: '#/components/schemas/IPAssignment_state'
next_hop:
description: '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.
'
format: ipv4
type: string
type:
$ref: '#/components/schemas/IPAssignment_type'
type: object
VrfVirtualCircuit:
example:
subnet: 12.0.0.0/30
customer_ip: 12.0.0.2
description: description
project:
href: href
created_at: 2000-01-23 04:56:07+00:00
vrf: null
type: null
metal_ip: 12.0.0.1
speed: 9
tags:
- tags
- tags
nni_vlan: 2
updated_at: 2000-01-23 04:56:07+00:00
port:
href: href
name: name
peer_asn: 7
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
md5: md5
status: null
properties:
customer_ip:
description: An IP address from the subnet that will be used on the Customer side. This parameter is optional, but if supplied, we will use the other usable IP address in the subnet as the Metal IP. By default, the last usable IP address in the subnet will be used.
example: 12.0.0.2
type: string
description:
type: string
id:
format: uuid
type: string
md5:
description: The MD5 password for the BGP peering in plaintext (not a checksum).
type: string
metal_ip:
description: An IP address from the subnet that will be used on the Metal side. This parameter is optional, but if supplied, we will use the other usable IP address in the subnet as the Customer IP. By default, the first usable IP address in the subnet will be used.
example: 12.0.0.1
type: string
name:
type: string
port:
$ref: '#/components/schemas/Href'
nni_vlan:
type: integer
peer_asn:
description: The peer ASN that will be used with the VRF on the Virtual Circuit.
type: integer
project:
$ref: '#/components/schemas/Href'
speed:
description: integer representing bps speed
type: integer
status:
$ref: '#/components/schemas/VrfVirtualCircuit_status'
subnet:
description: The /30 or /31 subnet of one of the VRF IP Blocks that will be used with the VRF for the Virtual Circuit. This subnet does not have to be an existing VRF IP reservation, as we will create the VRF IP reservation on creation if it does not exist. The Metal IP and Customer IP must be IPs from this subnet. For /30 subnets, the network and broadcast IPs cannot be used as the Metal or Customer IP.
example: 12.0.0.0/30
type: string
tags:
items:
type: string
type: array
type:
$ref: '#/components/schemas/VrfIpReservation_type'
vrf:
$ref: '#/components/schemas/Vrf'
created_at:
format: date-time
type: string
updated_at:
format: date-time
type: string
required:
- vrf
type: object
findMetalGatewayById_200_response:
oneOf:
- $ref: '#/components/schemas/MetalGateway'
- $ref: '#/components/schemas/VrfMetalGateway'
Address:
example:
country: country
address: address
address2: address2
city: city
coordinates:
latitude: latitude
longitude: longitude
state: state
zip_code: zip_code
properties:
address:
type: string
address2:
type: string
city:
type: string
coordinates:
$ref: '#/components/schemas/Coordinates'
country:
type: string
state:
type: string
zip_code:
type: string
required:
- address
- country
- zip_code
type: object
Error:
description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
properties:
error:
description: A description of the error that caused the request to fail.
type: string
errors:
description: A list of errors that contributed to the request failing.
items:
description: An error message that contributed to the request failing.
type: string
type: array
type: object
MetalGateway_state:
description: The current state of the Metal Gateway. 'Ready' indicates the gateway record has been configured, but is currently not active on the network. 'Active' indicates the gateway has been configured on the network. 'Deleting' is a temporary state used to indicate that the gateway is in the process of being un-configured from the network, after which the gateway record will be deleted.
enum:
- ready
- active
- deleting
type: string
Meta:
example:
next:
href: href
total: 0
last:
href: href
previous:
href: href
last_page: 1
self:
href: href
first:
href: href
current_page: 6
properties:
first:
$ref: '#/components/schemas/Href'
last:
$ref: '#/components/schemas/Href'
next:
$ref: '#/components/schemas/Href'
previous:
$ref: '#/components/schemas/Href'
self:
$ref: '#/components/schemas/Href'
total:
type: integer
current_page:
type: integer
last_page:
type: integer
type: object
VirtualNetwork:
example:
vxlan: 4
instances:
- href: href
- href: href
description: description
created_at: 2000-01-23 04:56:07+00:00
assigned_to_virtual_circuit: true
tags:
- tags
- tags
metal_gateways:
- gateway_address: 10.1.2.1/27
updated_at: 2000-01-23 04:56:07+00:00
vlan: 1001
created_at: 2000-01-23 04:56:07+00:00
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: null
- gateway_address: 10.1.2.1/27
updated_at: 2000-01-23 04:56:07+00:00
vlan: 1001
created_at: 2000-01-23 04:56:07+00:00
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: null
metro_code: metro_code
metro:
href: href
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
facility:
href: href
assigned_to:
href: href
properties:
assigned_to:
$ref: '#/components/schemas/Href'
assigned_to_virtual_circuit:
description: True if the virtual network is attached to a virtual circuit. False if not.
type: boolean
description:
type: string
facility:
$ref: '#/components/schemas/Href'
href:
type: string
created_at:
format: date-time
type: string
id:
format: uuid
type: string
instances:
description: A list of instances with ports currently associated to this Virtual Network.
items:
$ref: '#/components/schemas/Href'
type: array
metal_gateways:
description: A list of metal gateways currently associated to this Virtual Network.
items:
$ref: '#/components/schemas/MetalGatewayLite'
type: array
metro:
$ref: '#/components/schemas/Href'
metro_code:
description: The Metro code of the metro in which this Virtual Network is defined.
type: string
vxlan:
type: integer
tags:
items:
type: string
type: array
type: object
ParentBlock:
example:
netmask: netmask
cidr: 2
href: href
network: network
properties:
cidr:
type: integer
href:
type: string
netmask:
type: string
network:
type: string
type: object
VrfMetalGateway:
example:
virtual_network:
vxlan: 4
instances:
- href: href
- href: href
description: desc
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/packet-host/refs/heads/main/openapi/packet-host-metalgateways-api-openapi.yml