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 Users API
version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
tags:
- description: 'User Management
'
externalDocs:
url: https://metal.equinix.com/developers/docs/accounts/users/
name: Users
paths:
/invitations:
get:
description: Returns all invitations in current user.
operationId: findInvitations
parameters:
- 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: 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/InvitationList'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Retrieve current user invitations
tags:
- Users
/user:
get:
description: Returns the user object for the currently logged-in user.
operationId: findCurrentUser
parameters:
- 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/User'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
summary: Retrieve the current user
tags:
- Users
put:
description: Updates the currently logged-in user.
operationId: updateCurrentUser
parameters:
- 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/UserUpdateInput'
description: User to update
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Update the current user
tags:
- Users
/users:
get:
description: Returns a list of users that the are accessible to the current user (all users in the current user’s projects, essentially).
operationId: findUsers
parameters:
- 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/UserList'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
summary: Retrieve all users
tags:
- Users
x-equinix-metal-paginated-property: Users
post:
description: Creates a user.
operationId: createUser
parameters:
- 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/UserCreateInput'
description: User to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'422':
content:
application/json:
example:
errors:
- Email address username@example.com has already been taken
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Create a user
tags:
- Users
/users/{id}:
get:
description: Returns a single user if the user has access
operationId: findUserById
parameters:
- description: User 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/User'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Retrieve a user
tags:
- Users
/users/{id}/customdata:
get:
description: Provides the custom metadata stored for this user in json format
operationId: findUserCustomdata
parameters:
- description: User UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
'200':
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: not found
summary: Retrieve the custom metadata of a user
tags:
- Users
components:
schemas:
User:
example:
avatar_thumb_url: avatar_thumb_url
last_login_at: 2000-01-23 04:56:07+00:00
max_projects: 2
timezone: timezone
default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
created_at: 2000-01-23 04:56:07+00:00
last_name: last_name
short_id: short_id
fraud_score: fraud_score
emails:
- href: href
- href: href
default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
full_name: full_name
avatar_url: avatar_url
updated_at: 2000-01-23 04:56:07+00:00
phone_number: phone_number
customdata: '{}'
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
first_name: first_name
max_organizations: 3
two_factor_auth: two_factor_auth
email: email
properties:
avatar_thumb_url:
type: string
avatar_url:
type: string
created_at:
format: date-time
type: string
customdata:
type: object
default_organization_id:
format: uuid
type: string
default_project_id:
format: uuid
type: string
email:
type: string
emails:
items:
$ref: '#/components/schemas/Href'
type: array
first_name:
type: string
fraud_score:
type: string
full_name:
type: string
href:
type: string
id:
format: uuid
type: string
last_login_at:
format: date-time
type: string
last_name:
type: string
max_organizations:
type: integer
max_projects:
type: integer
phone_number:
type: string
short_id:
type: string
timezone:
type: string
two_factor_auth:
type: string
updated_at:
format: date-time
type: string
type: object
Href:
example:
href: href
properties:
href:
type: string
required:
- href
type: object
UserCreateInput:
example:
invitation_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
level: level
timezone: timezone
last_name: last_name
avatar: ''
title: title
nonce: nonce
emails:
- default: true
address: address
- default: true
address: address
social_accounts: '{}'
password: password
verified_at: 2000-01-23 04:56:07+00:00
company_name: company_name
company_url: company_url
phone_number: phone_number
customdata: '{}'
first_name: first_name
two_factor_auth: two_factor_auth
properties:
avatar:
format: binary
type: string
company_name:
type: string
company_url:
type: string
customdata:
type: object
emails:
items:
$ref: '#/components/schemas/EmailInput'
type: array
first_name:
type: string
last_name:
type: string
level:
type: string
password:
type: string
phone_number:
type: string
social_accounts:
type: object
timezone:
type: string
title:
type: string
two_factor_auth:
type: string
verified_at:
format: date-time
type: string
invitation_id:
format: uuid
type: string
nonce:
type: string
required:
- emails
- first_name
- last_name
type: object
InvitationList:
example:
invitations:
- updated_at: 2000-01-23 04:56:07+00:00
roles:
- roles
- roles
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
user:
href: href
- updated_at: 2000-01-23 04:56:07+00:00
roles:
- roles
- roles
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
user:
href: href
properties:
invitations:
items:
$ref: '#/components/schemas/Membership'
type: array
type: object
UserUpdateInput:
example:
password: password
timezone: timezone
last_name: last_name
phone_number: phone_number
customdata: '{}'
first_name: first_name
properties:
customdata:
type: object
first_name:
type: string
last_name:
type: string
password:
type: string
phone_number:
type: string
timezone:
type: string
type: object
UserList:
example:
meta:
next:
href: href
total: 0
last:
href: href
previous:
href: href
last_page: 1
self:
href: href
first:
href: href
current_page: 6
users:
- avatar_thumb_url: avatar_thumb_url
last_login_at: 2000-01-23 04:56:07+00:00
max_projects: 2
timezone: timezone
default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
created_at: 2000-01-23 04:56:07+00:00
last_name: last_name
short_id: short_id
fraud_score: fraud_score
emails:
- href: href
- href: href
default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
full_name: full_name
avatar_url: avatar_url
updated_at: 2000-01-23 04:56:07+00:00
phone_number: phone_number
customdata: '{}'
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
first_name: first_name
max_organizations: 3
two_factor_auth: two_factor_auth
email: email
- avatar_thumb_url: avatar_thumb_url
last_login_at: 2000-01-23 04:56:07+00:00
max_projects: 2
timezone: timezone
default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
created_at: 2000-01-23 04:56:07+00:00
last_name: last_name
short_id: short_id
fraud_score: fraud_score
emails:
- href: href
- href: href
default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
full_name: full_name
avatar_url: avatar_url
updated_at: 2000-01-23 04:56:07+00:00
phone_number: phone_number
customdata: '{}'
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
first_name: first_name
max_organizations: 3
two_factor_auth: two_factor_auth
email: email
properties:
meta:
$ref: '#/components/schemas/Meta'
users:
items:
$ref: '#/components/schemas/User'
type: array
type: object
EmailInput:
example:
default: true
address: address
properties:
address:
type: string
default:
type: boolean
required:
- address
type: object
Membership:
example:
updated_at: 2000-01-23 04:56:07+00:00
roles:
- roles
- roles
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
user:
href: href
properties:
created_at:
format: date-time
type: string
href:
type: string
id:
format: uuid
type: string
project:
$ref: '#/components/schemas/Href'
roles:
items:
type: string
type: array
updated_at:
format: date-time
type: string
user:
$ref: '#/components/schemas/Href'
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
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
securitySchemes:
x_auth_token:
description: 'HTTP header containing the User or Project API key that will be used to authenticate the request.
'
in: header
name: X-Auth-Token
type: apiKey
x-displayName: X-Auth-Token
x-tagGroups:
- name: Accounts and Organization
tags:
- Authentication
- Emails
- Invitations
- Memberships
- Organizations
- OTPs
- PasswordResetTokens
- PaymentMethods
- Projects
- SSHKeys
- SupportRequest
- TransferRequests
- TwoFactorAuth
- Users
- UserVerificationTokens
- name: Services and Billing
tags:
- Events
- Facilities
- Incidents
- Invoices
- Licenses
- Metros
- Plans
- Usages
- name: Servers
tags:
- Devices
- Batches
- Capacity
- HardwareReservations
- OperatingSystems
- Ports
- SelfServiceReservations
- SpotMarket
- Userdata
- Volumes
- name: Networking
tags:
- BGP
- Interconnections
- IPAddresses
- MetalGateways
- VLANs
- VRFs