Packet Host Devices API

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 Devices API
  version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
tags:
- description: 'Device Management. Check out the product docs to learn more about [Server Devices](https://metal.equinix.com/developers/docs/servers/).

    '
  externalDocs:
    url: https://metal.equinix.com/developers/docs/deploy/on-demand/
  name: Devices
paths:
  /devices/{id}:
    delete:
      description: Deletes a device and deprovisions it in our datacenter.
      operationId: deleteDevice
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Force the deletion of the device, by detaching any storage volume still active.
        in: query
        name: force_delete
        schema:
          type: boolean
      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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Delete the device
      tags:
      - Devices
    get:
      description: "Type-specific options (such as facility for baremetal devices) will be included as part of the main data structure.\n                         State value can be one of: active inactive queued or provisioning"
      operationId: findDeviceById
      parameters:
      - description: Device 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/Device'
          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 device
      tags:
      - Devices
    put:
      description: Updates the device.
      operationId: updateDevice
      parameters:
      - description: Device 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/DeviceUpdateInput'
        description: Device to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
          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 device
      tags:
      - Devices
  /devices/{id}/actions:
    post:
      description: 'Performs an action for the given device.  Possible actions include: power_on, power_off, reboot, reinstall, and rescue (reboot the device into rescue OS.)'
      operationId: performAction
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceActionInput'
        description: Action to perform
        required: true
      responses:
        '202':
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Perform an action
      tags:
      - Devices
  /devices/{id}/bandwidth:
    get:
      description: Retrieve an instance bandwidth for a given period of time.
      operationId: findInstanceBandwidth
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Timestamp from range
        in: query
        name: from
        required: true
        schema:
          type: string
      - description: Timestamp to range
        in: query
        name: until
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
        '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 an instance bandwidth
      tags:
      - Devices
  /devices/{id}/bgp/neighbors:
    get:
      description: Provides a summary of the BGP neighbor data associated to the BGP sessions for this device.
      operationId: getBgpNeighborData
      parameters:
      - description: Device 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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BgpSessionNeighbors'
          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 BGP neighbor data for this device
      tags:
      - Devices
  /devices/{id}/bgp/sessions:
    get:
      description: Provides a listing of available BGP sessions for the device.
      operationId: findBgpSessions
      parameters:
      - description: Device 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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BgpSessionList'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
      summary: Retrieve all BGP sessions
      tags:
      - Devices
    post:
      description: Creates a BGP session.
      operationId: createBgpSession
      parameters:
      - description: Device 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BGPSessionInput'
        description: BGP session to create
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BgpSession'
          description: created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Create a BGP session
      tags:
      - Devices
  /devices/{id}/customdata:
    get:
      description: Provides the custom metadata stored for this instance in json format
      operationId: findDeviceCustomdata
      parameters:
      - description: Instance 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 instance
      tags:
      - Devices
  /devices/{id}/diagnostics/health/rollup:
    get:
      description: Returns the health rollup status of the device.
      operationId: getDeviceHealthRollup
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceHealthRollup'
          description: Successful operation
        '401':
          description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
        '404':
          description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      summary: Get Device's Health Status
      tags:
      - Devices
  /devices/{id}/firmware-sets:
    get:
      description: 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.
      operationId: getDeviceFirmwareSets
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmwareSetResponse'
          description: Successful operation
        '401':
          description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
        '404':
          description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error
      summary: Get Device's associated Firmware Set
      tags:
      - Devices
  /devices/{id}/ips:
    get:
      description: Returns all ip assignments for a device.
      operationId: findIPAssignments
      parameters:
      - description: Device 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: Retrieve all ip assignments
      tags:
      - Devices
    post:
      description: Creates an ip assignment for a device.
      operationId: createIPAssignment
      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: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IPAssignmentInput'
        description: IPAssignment to create
        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
        '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 ip assignment
      tags:
      - Devices
  /devices/{id}/metadata:
    get:
      description: Retrieve device metadata
      operationId: findDeviceMetadataByID
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Retrieve metadata
      tags:
      - Devices
  /devices/{id}/traffic:
    get:
      description: Returns traffic for a specific device.
      operationId: findTraffic
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Traffic direction
        in: query
        name: direction
        required: true
        schema:
          $ref: '#/components/schemas/findTraffic_direction_parameter'
      - description: Traffic interval
        in: query
        name: interval
        schema:
          $ref: '#/components/schemas/findTraffic_interval_parameter'
      - description: Traffic bucket
        in: query
        name: bucket
        schema:
          $ref: '#/components/schemas/findTraffic_bucket_parameter'
      - explode: true
        in: query
        name: timeframe
        schema:
          $ref: '#/components/schemas/findTraffic_timeframe_parameter'
        style: deepObject
      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 device traffic
      tags:
      - Devices
  /devices/{id}/userdata:
    get:
      description: Retrieve device userdata
      operationId: findDeviceUserdataByID
      parameters:
      - description: Device UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Userdata'
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Retrieve userdata
      tags:
      - Devices
  /devices/{instance_id}/ips/{id}/customdata:
    get:
      description: Provides the custom metadata stored for this IP Assignment in json format
      operationId: findIPAssignmentCustomdata
      parameters:
      - description: Instance UUID
        in: path
        name: instance_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Ip Assignment 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 Assignment
      tags:
      - Devices
  /organizations/{id}/devices:
    get:
      description: Provides a collection of devices for a given organization.
      operationId: findOrganizationDevices
      parameters:
      - description: Organization UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 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.
        in: query
        name: search
        schema:
          type: string
      - description: Filter by plan category
        in: query
        name: categories
        schema:
          items:
            $ref: '#/components/schemas/findOrganizationDevices_categories_parameter_inner'
          type: array
      - description: Filter by device facility
        in: query
        name: facility
        schema:
          type: string
      - description: Filter by partial hostname
        in: query
        name: hostname
        schema:
          type: string
      - description: Filter only reserved instances. When set to true, only include reserved instances. When set to false, only include on-demand instances.
        in: query
        name: reserved
        schema:
          type: boolean
      - description: Filter by device tag
        in: query
        name: tag
        schema:
          type: string
      - description: Filter by instance type (ondemand,spot,reserved)
        in: query
        name: type
        schema:
          type: string
      - description: 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.
        in: query
        name: has_termination_time
        schema:
          type: boolean
      - 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/DeviceList'
          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:
 

# --- truncated at 32 KB (173 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/packet-host/refs/heads/main/openapi/packet-host-devices-api-openapi.yml