Equinix Ports API

openapi: 3.0.1
info:
  title: Equinix API Authentication Ports API
  description: 'Equinix APIs use the OAuth 2.0 for authentication and authorization. Equinix supports the resource owner password and the client credentials flow.

    To begin, obtain OAuth 2.0 client credentials from the Equinix Developer Console under "My Apps". Then your client application  requests an access token from the Equinix API Authorization endpoint, extracts the access_token from the response, and sends the Bearer token to the API that you want to access'
  termsOfService: https://www.equinix.com/about/legal/terms
  contact:
    name: Equinix API Support
    url: https://docs.equinix.com/api-support.htm
  version: '1.2'
servers:
- url: https://api.equinix.com
tags:
- description: 'Port ManagementCheck out the product docs to learn more about [Port configurations](https://metal.equinix.com/developers/docs/layer2-networking/overview/).

    '
  externalDocs:
    url: https://metal.equinix.com/developers/docs/layer2-networking/overview/
  name: Ports
paths:
  /ports/{id}:
    get:
      description: Returns a port
      operationId: findPortById
      parameters:
      - description: Port 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/Port'
          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 a port
      tags:
      - Ports
  /ports/{id}/assign:
    post:
      description: Assign a hardware port to a virtual network.
      operationId: assignPort
      parameters:
      - description: Port 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:
        $ref: '#/components/requestBodies/PortAssignInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Assign a port to virtual network
      tags:
      - Ports
  /ports/{id}/bond:
    post:
      description: Enabling bonding for one or all ports
      operationId: bondPort
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: enable both ports
        in: query
        name: bulk_enable
        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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Enabling bonding
      tags:
      - Ports
  /ports/{id}/convert/layer-2:
    post:
      description: Converts a bond port to Layer 2. IP assignments of the port will be removed.
      operationId: convertLayer2
      parameters:
      - description: Port 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:
        $ref: '#/components/requestBodies/PortAssignInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Convert to Layer 2
      tags:
      - Ports
  /ports/{id}/convert/layer-3:
    post:
      description: Converts a bond port to Layer 3. VLANs must first be unassigned.
      operationId: convertLayer3
      parameters:
      - description: Port 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/PortConvertLayer3Input'
        description: IPs to request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Convert to Layer 3
      tags:
      - Ports
  /ports/{id}/disbond:
    post:
      description: Disabling bonding for one or all ports
      operationId: disbondPort
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: disable both ports
        in: query
        name: bulk_disable
        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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Disabling bonding
      tags:
      - Ports
  /ports/{id}/native-vlan:
    delete:
      description: Removes the native VLAN from this port
      operationId: deleteNativeVlan
      parameters:
      - description: Port 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/Port'
          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: Remove native VLAN
      tags:
      - Ports
    post:
      description: Sets a virtual network on this port as a "native VLAN". The VLAN must have already been assigned using the using the "Assign a port to a virtual network" operation.
      operationId: assignNativeVlan
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Virtual Network ID. May be the UUID of the Virtual Network record, or the VLAN value itself (ex: ''1001'').'
        in: query
        name: vnid
        required: true
        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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Assign a native VLAN
      tags:
      - Ports
  /ports/{id}/unassign:
    post:
      description: Unassign a port for a hardware.
      operationId: unassignPort
      parameters:
      - description: Port 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:
        $ref: '#/components/requestBodies/PortAssignInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port'
          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: Unassign a port
      tags:
      - Ports
  /ports/{id}/vlan-assignments:
    get:
      description: Show the port's current VLAN assignments, including if this VLAN is set as native, and the current state of the assignment (ex. 'assigned' or 'unassigning')
      operationId: findPortVlanAssignments
      parameters:
      - description: Port 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.
        in: query
        name: include
        schema:
          default:
          - port
          - virtual_network
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortVlanAssignmentList'
          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: List Current VLAN assignments for a port
      tags:
      - Ports
  /ports/{id}/vlan-assignments/{assignment_id}:
    get:
      description: Show the details of a specific Port-VLAN assignment, including the current state and if the VLAN is set as native.
      operationId: findPortVlanAssignmentByPortIdAndAssignmentId
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Assignment ID
        in: path
        name: assignment_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.
        in: query
        name: include
        schema:
          default:
          - port
          - virtual_network
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortVlanAssignment'
          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: Show a particular Port VLAN assignment's details
      tags:
      - Ports
  /ports/{id}/vlan-assignments/batches:
    get:
      description: Show all the VLAN assignment batches that have been created for managing this port's VLAN assignments
      operationId: findPortVlanAssignmentBatches
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortVlanAssignmentBatchList'
          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: List the VLAN Assignment Batches for a port
      tags:
      - Ports
    post:
      description: Create a new asynchronous batch request which handles adding and/or removing the VLANs to which the port is assigned.
      operationId: createPortVlanAssignmentBatch
      parameters:
      - description: Port 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/PortVlanAssignmentBatchCreateInput'
        description: VLAN Assignment batch details
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortVlanAssignmentBatch'
          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 new Port-VLAN Assignment management batch
      tags:
      - Ports
  /ports/{id}/vlan-assignments/batches/{batch_id}:
    get:
      description: Returns the details of an existing Port-VLAN Assignment batch, including the list of VLANs to assign or unassign, and the current state of the batch.
      operationId: findPortVlanAssignmentBatchByPortIdAndBatchId
      parameters:
      - description: Port UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Batch ID
        in: path
        name: batch_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/PortVlanAssignmentBatch'
          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 VLAN Assignment Batch's details
      tags:
      - Ports
  /fabric/v4/ports:
    get:
      tags:
      - Ports
      summary: Get All Ports
      description: Get All Ports returns details of all assigned and available ports for the specified user credentials. The metro attribute in the response shows the origin of the proposed connection.
      operationId: getPorts
      parameters:
      - name: name
        in: query
        description: port name to be provided if specific port(s) to be retrieved
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllPortsResponse'
              examples:
                portExample:
                  $ref: '#/components/examples/ports'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/403'
        '500':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                portExample:
                  $ref: '#/components/examples/ports-500'
                userFailureExample:
                  $ref: '#/components/examples/ports-500-user-failure'
    post:
      tags:
      - Ports
      summary: Create Port
      description: Creates Equinix Fabric? Port.
      operationId: createPort
      parameters:
      - name: dryRun
        in: query
        description: option to verify that API calls will succeed
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortRequest'
            examples:
              COLOSinglePortNonLag:
                $ref: '#/components/examples/coloSinglePortNonLag'
              COLOSinglePortLag:
                $ref: '#/components/examples/coloSinglePortLag'
              COLOUnlimitedPlusPortLag:
                $ref: '#/components/examples/coloUnlimitedPlusPortLag'
              COLOLagPortNewGroup:
                $ref: '#/components/examples/coloLagPortNewGroup'
              COLOAddSecondaryPort:
                $ref: '#/components/examples/coloAddSecondaryPort'
              COLOSinglePortNonLagDryRun:
                $ref: '#/components/examples/COLOSinglePortNonLagCreateDryRun'
              COLOSinglePortLagDryRun:
                $ref: '#/components/examples/COLOSinglePortLagCreateDryRun'
              REMOTESinglePortLag:
                $ref: '#/components/examples/remoteSinglePortNewGroupLagRequest'
              BMMRSinglePortLag:
                $ref: '#/components/examples/bmmrSinglePortLag'
              BMMRSinglePortNoLag:
                $ref: '#/components/examples/bmmrSinglePortNoLag'
              BMMRAddSecondaryPort:
                $ref: '#/components/examples/bmmrAddSecondaryPort'
              BMMRLagPortNewGroup:
                $ref: '#/components/examples/bmmrLagPortNewGroup'
              IXPublicPrivatePeeringPort:
                $ref: '#/components/examples/createIXPublicPrivatePeeringPortRequest'
              IXPublicPeeringPort:
                $ref: '#/components/examples/createIXPublicPeeringPortRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port_2'
              examples:
                portDryRunExample:
                  $ref: '#/components/examples/PortCreateDryRunResponse'
                bmmrPortDryRunExample:
                  $ref: '#/components/examples/bmmrSinglePortCreateDryRunResponse'
                remotePortDryRunExample:
                  $ref: '#/components/examples/remoteSinglePortCreateDryRunResponse'
        '202':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Port_2'
              examples:
                COLOSinglePortNonLag:
                  $ref: '#/components/examples/coloSinglePortNonLagResponse'
                BMMRSinglePortLag:
                  $ref: '#/components/examples/bmmrSinglePortLagResponse'
                REMOTESinglePortLag:
                  $ref: '#/components/examples/remoteSinglePortLagResponse'
                REMOTESinglePortLagWithOrderExemption:
                  $ref: '#/components/examples/remoteSinglePortLagWithPurchaseOrderExemption'
                IXPublicPrivatePeeringPort:
                  $ref: '#/components/examples/createIXPublicPrivatePeeringPortResponse'
                IXPublicPeeringPort:
                  $ref: '#/components/examples/createIXPublicPeeringPortResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                validationError:
                  $ref: '#/components/examples/port-400'
                badRequest:
                  $ref: '#/components/examples/createPortBadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/401'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/port-500'
  /fabric/v4/ports/{portId}/physicalPorts/bulk:
    post:
      tags:
      - Ports
      summary: Add to Lag
      description: Add Physical Ports to Virtual Port.<font color="red"> <sup color='red'>Preview</sup></font>
      operationId: addToLag
      parameters:
      - name: portId
        in: path
        description: Port UUID
        required: true
        schema:
          $ref: '#/components/schemas/PortUUID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPhysicalPort'
            examples:
              COLOAddToLag:
                $ref: '#/components/examples/coloAddToLag'
              REMOTEAddToLag:
                $ref: '#/components/examples/remoteAddToLag'
              BMMRAddToLag:
                $ref: '#/components/examples/bmmrAddToLag'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllPhysicalPortsResponse'
              examples:
                COLOAddToLag:
                  $ref: '#/components/examples/coloAddToLagResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/port-400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                example:
                  $ref: '#/components/examples/404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: 

# --- truncated at 32 KB (169 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/equinix/refs/heads/main/openapi/equinix-ports-api-openapi.yml