Equinix Interconnections API

openapi: 3.0.1
info:
  title: Equinix API Authentication Interconnections 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: 'Network Interconnections. See Instructions to create Network Interconnections at Check out the product docs to learn more about [Equinix Fabric](https://metal.equinix.com/developers/docs/networking/fabric/).

    '
  externalDocs:
    url: https://metal.equinix.com/developers/docs/equinix-interconnect/introduction/
  name: Interconnections
paths:
  /connections/{connection_id}:
    delete:
      description: Delete a interconnection, its associated ports and virtual circuits.
      operationId: deleteInterconnection
      parameters:
      - description: Interconnection UUID
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interconnection'
          description: accepted
        '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 interconnection
      tags:
      - Interconnections
    get:
      description: Get the details of a interconnection
      operationId: getInterconnection
      parameters:
      - description: Interconnection UUID
        in: path
        name: connection_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/Interconnection'
          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: Get interconnection
      tags:
      - Interconnections
    put:
      description: Update the details of a interconnection
      operationId: updateInterconnection
      parameters:
      - description: Interconnection UUID
        in: path
        name: connection_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/InterconnectionUpdateInput'
        description: Updated interconnection details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interconnection'
          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: Update interconnection
      tags:
      - Interconnections
  /connections/{connection_id}/ports:
    get:
      description: List the ports associated to an interconnection.
      operationId: listInterconnectionPorts
      parameters:
      - description: UUID of the interconnection
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterconnectionPortList'
          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: List a interconnection's ports
      tags:
      - Interconnections
  /connections/{connection_id}/virtual-circuits:
    get:
      description: List the virtual circuit record(s) associated with a particular interconnection id.
      operationId: listInterconnectionVirtualCircuits
      parameters:
      - description: UUID of the interconnection
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCircuitList'
          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: List a interconnection's virtual circuits
      tags:
      - Interconnections
  /connections/{connection_id}/ports/{id}:
    get:
      description: Get the details of an interconnection port.
      operationId: getInterconnectionPort
      parameters:
      - description: UUID of the interconnection
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      - 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
      - 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/InterconnectionPort'
          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: Get a interconnection port
      tags:
      - Interconnections
  /connections/{connection_id}/ports/{port_id}/virtual-circuits:
    get:
      description: List the virtual circuit record(s) associatiated with a particular interconnection port.
      operationId: listInterconnectionPortVirtualCircuits
      parameters:
      - description: UUID of the interconnection
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      - description: UUID of the interconnection port
        in: path
        name: port_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/VirtualCircuitList'
          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: List a interconnection port's virtual circuits
      tags:
      - Interconnections
    post:
      description: Create a new Virtual Circuit on a Dedicated Port. To create a regular Virtual Circuit, specify a Virtual Network record and an NNI VLAN value. To create a VRF-based Virtual Circuit, specify the VRF ID and subnet, along with the NNI VLAN value.
      operationId: createInterconnectionPortVirtualCircuit
      parameters:
      - description: UUID of the interconnection
        in: path
        name: connection_id
        required: true
        schema:
          format: uuid
          type: string
      - description: UUID of the interconnection port
        in: path
        name: port_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualCircuitCreateInput'
        description: Virtual Circuit details
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCircuit'
          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: Create a new Virtual Circuit
      tags:
      - Interconnections
  /organizations/{organization_id}/connections:
    get:
      description: List the connections belonging to the organization
      operationId: organizationListInterconnections
      parameters:
      - description: UUID of the organization
        in: path
        name: organization_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/InterconnectionList'
          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: List organization connections
      tags:
      - Interconnections
    post:
      description: Creates a new interconnection request. A Project ID must be specified in the request body for connections on shared ports.
      operationId: createOrganizationInterconnection
      parameters:
      - description: UUID of the organization
        in: path
        name: organization_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:
        $ref: '#/components/requestBodies/InterconnectionCreateInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interconnection'
          description: created
        '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: Request a new interconnection for the organization
      tags:
      - Interconnections
  /projects/{project_id}/connections:
    get:
      description: List the connections belonging to the project
      operationId: projectListInterconnections
      parameters:
      - description: UUID of the project
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      - description: Page to return
        in: query
        name: page
        schema:
          default: 1
          format: int32
          maximum: 100000
          minimum: 1
          type: integer
      - description: Items returned per page
        in: query
        name: per_page
        schema:
          default: 10
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterconnectionList'
          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: List project connections
      tags:
      - Interconnections
      x-equinix-metal-paginated-property: Interconnections
    post:
      description: Creates a new interconnection request
      operationId: createProjectInterconnection
      parameters:
      - description: UUID of the project
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      requestBody:
        $ref: '#/components/requestBodies/InterconnectionCreateInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interconnection'
          description: created
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Request a new interconnection for the project's organization
      tags:
      - Interconnections
  /virtual-circuits/{id}:
    delete:
      description: Delete a virtual circuit from a Dedicated Port.
      operationId: deleteVirtualCircuit
      parameters:
      - description: Virtual Circuit UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCircuit'
          description: accepted
        '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 a virtual circuit
      tags:
      - Interconnections
    get:
      description: Get the details of a virtual circuit
      operationId: getVirtualCircuit
      parameters:
      - description: Virtual Circuit 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/VirtualCircuit'
          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: Get a virtual circuit
      tags:
      - Interconnections
    put:
      description: Update the details of a virtual circuit.
      operationId: updateVirtualCircuit
      parameters:
      - description: Virtual Circuit 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/VirtualCircuitUpdateInput'
        description: Updated Virtual Circuit details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCircuit'
          description: ok
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualCircuit'
          description: accepted
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Update a virtual circuit
      tags:
      - Interconnections
components:
  schemas:
    VlanFabricVcCreateInput_service_token_type:
      description: Either 'a_side' or 'z_side'. Setting this field to 'a_side' will create an interconnection with Fabric VCs (Metal Billed). Setting this field to 'z_side' will create an interconnection with Fabric VCs (Fabric Billed). This is required when the 'type' is 'shared', but this is not applicable when the 'type' is 'dedicated'. This parameter is included in the specification as a developer preview and is generally unavailable. Please contact our Support team for more details.
      enum:
      - a_side
      - z_side
      example: a_side
      type: string
    VrfVirtualCircuit_status:
      description: The status changes of a VRF virtual circuit are generally the same as Virtual Circuits that aren't in a VRF. However, for VRF Virtual Circuits on Fabric VCs, the status will change to 'waiting_on_peering_details' once the Fabric service token associated with the virtual circuit has been redeemed on Fabric, and Metal has found the associated Fabric connection. At this point, users can update the subnet, MD5 password, customer IP and/or metal IP accordingly. For VRF Virtual Circuits on Dedicated Ports, we require all peering details to be set on creation of a VRF Virtual Circuit. The status will change to `changing_peering_details` whenever an active VRF Virtual Circuit has any of its peering details updated.
      enum:
      - pending
      - waiting_on_peering_details
      - activating
      - changing_peering_details
      - deactivating
      - deleting
      - active
      - expired
      - activation_failed
      - changing_peering_details_failed
      - deactivation_failed
      - delete_failed
      type: string
    VlanVirtualCircuit:
      properties:
        bill:
          default: false
          description: True if the Virtual Circuit is being billed. Currently, only Virtual Circuits of Fabric VCs (Metal Billed) will be billed. Usage will start the first time the Virtual Circuit becomes active, and will not stop until it is deleted from Metal.
          type: boolean
        description:
          type: string
        id:
          format: uuid
          type: string
        name:
          type: string
        nni_vlan:
          type: integer
        port:
          $ref: '#/components/schemas/Href'
        project:
          $ref: '#/components/schemas/Href'
        speed:
          description: For Virtual Circuits on shared and dedicated connections, this speed should match the one set on their Interconnection Ports. For Virtual Circuits on Fabric VCs (both Metal and Fabric Billed) that have found their corresponding Fabric connection, this is the actual speed of the interconnection that was configured when setting up the interconnection on the Fabric Portal. Details on Fabric VCs are included in the specification as a developer preview and is generally unavailable. Please contact our Support team for more details.
          type: integer
        status:
          $ref: '#/components/schemas/VlanVirtualCircuit_status'
        tags:
          items:
            type: string
          type: array
        type:
          $ref: '#/components/schemas/VlanVirtualCircuit_type'
        virtual_network:
          $ref: '#/components/schemas/Href'
        vnid:
          type: integer
        created_at:
          format: date-time
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    DedicatedPortCreateInput:
      properties:
        billing_account_name:
          description: The billing account name of the Equinix Fabric account.
          type: string
        contact_email:
          description: The preferred email used for communication and notifications about the Equinix Fabric interconnection. Required when using a Project API key. Optional and defaults to the primary user email address when using a User API key.
          format: email
          type: string
        description:
          type: string
        metro:
          description: A Metro ID or code. For interconnections with Dedicated Ports, this will be the location of the issued Dedicated Ports.
          type: string
        mode:
          $ref: '#/components/schemas/DedicatedPortCreateInput_mode'
        name:
          type: string
        project:
          type: string
        redundancy:
          description: Either 'primary' or 'redundant'.
          type: string
        speed:
          description: A interconnection speed, in bps, mbps, or gbps. For Dedicated Ports, this can be 10Gbps or 100Gbps.
          example: 10000000000
          type: integer
        tags:
          items:
            type: string
          type: array
        type:
          $ref: '#/components/schemas/DedicatedPortCreateInput_type'
        use_case:
          description: The intended use case of the dedicated port.
          type: string
      required:
      - metro
      - name
      - redundancy
      - type
      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
    VirtualCircuitUpdateInput:
      oneOf:
      - $ref: '#/components/schemas/VlanVirtualCircuitUpdate

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