Equinix Interconnections API

openapi: 3.2.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 Interconnections API
  version: 1.0.0
servers:
- url: https://api.equinix.com/metal/v1
security:
- x_auth_token: []
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:
    Address:
      example:
        country: country
        address: address
        address2: address2
        city: city
        coordinates:
          latitude: latitude
          longitude: longitude
        state: state
        zip_code: zip_code
      properties:
        address:
          type: string
        address2:
          type: string
        city:
          type: string
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        country:
          type: string
        state:
          type: string
        zip_code:
          type: string
      required:
      - address
      - country
      - zip_code
      type: object
    VlanVirtualCircuit_type:
      enum:
      - vlan
      type: string
    createOrganizationInterconnection_request:
      oneOf:
      - $ref: '#/components/schemas/DedicatedPortCreateInput'
      - $ref: '#/components/schemas/VlanFabricVcCreateInput'
      - $ref: '#/components/schemas/VrfFabricVcCreateInput'
    VirtualCircuitList:
      example:
        virtual_circuits:
        - null
        - null
      properties:
        virtual_circuits:
          items:
            $ref: '#/components/schemas/VirtualCircuit'
          type: array
      type: object
    InterconnectionUpdateInput:
      example:
        mode: standard
        name: name
        description: description
        redundancy: redundancy
        contact_email: contact_email
        tags:
        - tags
        - tags
      properties:
        contact_email:
          type: string
        description:
          type: string
        mode:
          $ref: '#/components/schemas/Interconnection_mode'
        name:
          type: string
        redundancy:
          description: Updating from 'redundant' to 'primary' will remove a secondary port, while updating from 'primary' to 'redundant' will add one.
          type: string
        tags:
          items:
            type: string
          type: array
      type: 

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