Packet Host Projects API
Project Management. Check out the product docs to learn more about [Projects](https://metal.equinix.com/developers/docs/accounts/projects/).
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 Projects API
version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
tags:
- description: 'Project Management. Check out the product docs to learn more about [Projects](https://metal.equinix.com/developers/docs/accounts/projects/).
'
externalDocs:
url: https://metal.equinix.com/developers/docs/accounts/projects/
name: Projects
paths:
/projects:
get:
description: Returns a collection of projects that the current user is a member of.
operationId: findProjects
parameters:
- description: Filter results by name.
in: query
name: name
schema:
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/ProjectList'
description: ok
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
summary: Retrieve all projects
tags:
- Projects
x-equinix-metal-paginated-property: Projects
post:
description: Creates a new project for the user default organization. If the user don't have an organization, a new one will be created.
operationId: createProject
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/ProjectCreateFromRootInput'
description: Project to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
description: created
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unauthorized
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Create a project
tags:
- Projects
/projects/{id}:
delete:
description: Deletes the project.
operationId: deleteProject
parameters:
- description: Project UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
'204':
description: no content
'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: Delete the project
tags:
- Projects
get:
description: Returns a single project if the user has access
operationId: findProjectById
parameters:
- description: Project UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- 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/Project'
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 project
tags:
- Projects
put:
description: Updates the project.
operationId: updateProject
parameters:
- description: Project UUID
in: path
name: id
required: true
schema:
format: uuid
type: string
- description: 'Nested attributes to include. Included objects will return their full
attributes. Attribute names can be dotted (up to 3 levels) to included deeply
nested objects.'
explode: false
in: query
name: include
schema:
items:
type: string
type: array
style: form
- 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/ProjectUpdateInput'
description: Project to update
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
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
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: unprocessable entity
summary: Update the project
tags:
- Projects
/projects/{id}/customdata:
get:
description: Provides the custom metadata stored for this project in json format
operationId: findProjectCustomdata
parameters:
- description: Project 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 project
tags:
- Projects
/projects/{id}/transfers:
post:
deprecated: true
description: Organization owners can transfer their projects to other organizations.
operationId: createTransferRequest
parameters:
- description: UUID of the project to be transferred
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequestInput'
description: Transfer Request to create
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequest'
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 transfer request
tags:
- Projects
/projects/{project_id}/invitations:
get:
description: Returns all invitations in a project.
operationId: findProjectInvitations
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
- description: Project UUID
in: path
name: project_id
required: true
schema:
format: uuid
type: string
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 project invitations
tags:
- Projects
post:
description: In order to add a user to a project, they must first be invited.
operationId: createProjectInvitation
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
requestBody:
$ref: '#/components/requestBodies/InvitationInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
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 an invitation for a project
tags:
- Projects
/projects/{project_id}/ips/{id}/customdata:
get:
description: Provides the custom metadata stored for this IP Reservation in json format
operationId: findIPReservationCustomdata
parameters:
- description: Project UUID
in: path
name: project_id
required: true
schema:
format: uuid
type: string
- description: Ip Reservation 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 an IP Reservation
tags:
- Projects
/projects/{project_id}/memberships:
get:
description: Returns all memberships in a project.
operationId: findProjectMemberships
parameters:
- description: Search by member full name, id and email.
in: query
name: search
schema:
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: 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
- description: Project UUID
in: path
name: project_id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipList'
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 project memberships
tags:
- Projects
components:
schemas:
ProjectCreateFromRootInput_type:
description: The type of the project. If no type is specified the project type will automatically be `default` Projects of type 'vmce' are part of an in development feature and not available to all customers.
enum:
- default
- vmce
type: string
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
Invitation_roles_inner:
enum:
- admin
- billing
- collaborator
- limited_collaborator
type: string
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
Invitation:
example:
projects:
- href: href
- href: href
updated_at: 2000-01-23 04:56:07+00:00
invitation:
href: href
organization:
href: href
roles:
- null
- null
created_at: 2000-01-23 04:56:07+00:00
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
invited_by:
href: href
nonce: nonce
invitee: invitee
properties:
created_at:
format: date-time
type: string
href:
type: string
id:
format: uuid
type: string
invitation:
$ref: '#/components/schemas/Href'
invited_by:
$ref: '#/components/schemas/Href'
invitee:
format: email
type: string
nonce:
type: string
organization:
$ref: '#/components/schemas/Href'
projects:
items:
$ref: '#/components/schemas/Href'
type: array
roles:
items:
$ref: '#/components/schemas/Invitation_roles_inner'
type: array
updated_at:
format: date-time
type: string
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
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
TransferRequest:
example:
updated_at: 2000-01-23 04:56:07+00:00
target_organization:
href: href
created_at: 2000-01-23 04:56:07+00:00
project:
href: href
href: href
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
properties:
created_at:
format: date-time
type: string
href:
type: string
id:
format: uuid
type: string
project:
$ref: '#/components/schemas/Href'
target_organization:
$ref: '#/components/schemas/Href'
updated_at:
format: date-time
type: string
type: object
ProjectCreateFromRootInput:
example:
payment_method_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
name: name
customdata: '{}'
type: null
tags:
- tags
- tags
properties:
customdata:
type: object
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
organization_id:
format: uuid
type: string
payment_method_id:
format: uuid
type: string
type:
$ref: '#/components/schemas/ProjectCreateFromRootInput_type'
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/packet-host/refs/heads/main/openapi/packet-host-projects-api-openapi.yml