openapi: 3.2.0
info:
  title: 'Forward: L3VPNs API'
  summary: Model the provider L3VPNs connecting a network’s customer edge routers
  description: |-
    An L3VPN stands in for a provider’s core without collecting its PE and P routers. It is one kind of
    [synthetic device](https://docs.fwd.app/latest/application/sources/configure-collection/synthetic-devices/).
    Each customer edge router advertises the subnets it owns, and the VPN forwards only between connections in the same
    VRF. For the modeling details, see
    [L3 VPN](https://docs.fwd.app/latest/application/sources/configure-collection/synthetic-devices/reference/#l3-vpn).

    Changes to a network’s L3VPNs affect future Snapshots.
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: 26.8
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Collection Sources
    description: Specify the devices, endpoints, and other sources to collect from
  - name: Synthetic Devices
    description: Model a network’s internet connections, intranets, L2VPNs, L3VPNs, WAN circuits, and encryptors
    parent: Collection Sources
  - name: L3VPNs
    description: Model the provider L3VPNs connecting a network’s customer edge routers
    parent: Synthetic Devices
paths:
  /networks/{networkId}/l3-vpns:
    get:
      tags:
        - L3VPNs
      summary: Get a network’s L3VPNs
      operationId: getL3Vpns
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L3VpnList'
    put:
      tags:
        - L3VPNs
      summary: Replace all of a network’s L3VPNs
      operationId: putL3Vpns
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/L3VpnList'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /networks/{networkId}/l3-vpns/{l3VpnName}:
    get:
      tags:
        - L3VPNs
      summary: Get an L3VPN
      operationId: getL3Vpn
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L3Vpn'
    put:
      tags:
        - L3VPNs
      summary: Add or replace an L3VPN
      operationId: putL3Vpn
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/L3Vpn'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
    patch:
      tags:
        - L3VPNs
      summary: Update an L3VPN
      description: |-
        All JSON properties in the request body are optional. Include only the properties you wish to
        change.
      operationId: patchL3Vpn
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/L3VpnPatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L3Vpn'
    delete:
      tags:
        - L3VPNs
      summary: Remove an L3VPN
      operationId: deleteL3Vpn
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
  /networks/{networkId}/l3-vpns/{l3VpnName}/connections:
    get:
      tags:
        - L3VPNs
      summary: Get an L3VPN’s connections
      operationId: getL3VpnConnections
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
        - name: uplinkDevice
          in: query
          schema:
            type: string
        - name: uplinkPort
          in: query
          schema:
            type: string
        - name: gatewayDevice
          in: query
          schema:
            type: string
        - name: gatewayPort
          in: query
          schema:
            type: string
        - name: vlan
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L3SyntheticWanConnections'
    post:
      tags:
        - L3VPNs
      summary: Add a connection to an L3VPN
      operationId: addL3VpnConnection
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/L3SyntheticWanConnection'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
    delete:
      tags:
        - L3VPNs
      summary: Remove an L3VPN’s connections
      operationId: deleteL3VpnConnections
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: l3VpnName
          in: path
          required: true
          schema:
            type: string
        - name: uplinkDevice
          in: query
          schema:
            type: string
        - name: uplinkPort
          in: query
          schema:
            type: string
        - name: gatewayDevice
          in: query
          schema:
            type: string
        - name: gatewayPort
          in: query
          schema:
            type: string
        - name: vlan
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L3SyntheticWanConnections'
components:
  schemas:
    L3SyntheticWanConnection:
      type: object
      required:
        - uplinkPort
      properties:
        uplinkPort:
          $ref: '#/components/schemas/DevicePort'
          description: The physical uplink port on the edge device.
          examples:
            - device: nyc-rtr-01
              port: eth1/1
        gatewayPort:
          $ref: '#/components/schemas/DevicePort'
          description: The virtual gateway port, if different than `uplinkPort`.
          examples:
            - device: nyc-rtr-01
              port: vlan100
        vlan:
          type: integer
          format: int32
          description: The VLAN of traffic from `uplinkPort`, if tagged.
          examples:
            - 100
        name:
          type: string
          description: |-
            An optional name for this connection, which will be used as the interface name created on the synthetic
            device that links to the physical edge port.
        vrf:
          type: string
          description: An optional name for the VRF on the synthetic device under which this connection resides.
        site:
          type: string
          description: |-
            An optional name for the site in which this connection's gateway device resides. A site is a collection of
            devices that redistribute routes learned from the synthetic device to each other. Grouping connections
            together into a single site enables more accurate site subnet autodiscovery when using `IP_ROUTES` or
            `BGP_ROUTES`.
        subnets:
          type: array
          items:
            type: string
          description: |-
            Advertised subnets. Routes for these subnets are created on the synthetic device if received by another CE.
            Required (and must not be empty) if `subnetAutoDiscovery` is `NONE`.
          examples:
            - - 123.223.47.0/24
        subnetAutoDiscovery:
          $ref: '#/components/schemas/AutoDiscoverySource'
          description: |-
            The types of routes from which advertised subnets are automatically inferred in the gateway device’s routing
            table. Defaults to `NONE`. If `INTERFACE_ADDRESSES`, the gateway port’s IP address is used. If `IP_ROUTES`,
            subnets are inferred from the gateway device’s RIB. If `BGP_ROUTES`, subnets are inferred from the gateway
            device’s Adj-RIB-Out.

            Note: If not `NONE`, routes are created on the synthetic device for both autodiscovered subnets, as well any
            subnets specified in `subnets`, that are received by another CE.

            Note: Using `BGP_ROUTES` will automatically enable collection of Adj-RIB-Out from the gateway device in
            future network collections.
          examples:
            - NONE
        peerIps:
          type: array
          items:
            type: string
          description: |-
            IP addresses of BGP peers to which this connection’s site subnets are advertised. If empty, routes
            advertised to all BGP peers are examined.

            Note: This set is only used if `subnetAutoDiscovery` is `BGP_ROUTES`.
          examples:
            - - 1.1.1.1
        backdoorLinkPorts:
          type: array
          items:
            $ref: '#/components/schemas/DevicePort'
          description: L3 interfaces that provide backdoor connectivity between sites.
        advertisesDefaultRoute:
          type: boolean
          description: |-
            Whether the CE advertises the default route. Defaults to `false`.

            Note: This property is only used if `subnetAutoDiscovery` is `IP_ROUTES`, which should be the case when BGP
            collection is not enabled on the CE. If the Adj-RIB-Out is not collected, the RIB is examined and a default
            route forwarded out `gatewayPort` is skipped if this property is false.
    L3SyntheticWanConnections:
      type: object
      required:
        - connections
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/L3SyntheticWanConnection'
    L3Vpn:
      type: object
      required:
        - name
        - connections
      properties:
        name:
          type: string
          examples:
            - l3vpn
        connections:
          type: array
          items:
            $ref: '#/components/schemas/L3SyntheticWanConnection'
    L3VpnList:
      type: object
      required:
        - l3Vpns
      properties:
        l3Vpns:
          type: array
          items:
            $ref: '#/components/schemas/L3Vpn'
    L3VpnPatch:
      type: object
      properties:
        name:
          type: string
        connections:
          type: array
          items:
            $ref: '#/components/schemas/L3SyntheticWanConnection'
          description: If specified, this list will **replace** all existing connections on the L3 VPN node.
    DevicePort:
      type: object
      properties:
        device:
          type: string
        port:
          type: string
    AutoDiscoverySource:
      type: string
      enum:
        - NONE
        - IP_ROUTES
        - BGP_ROUTES
        - INTERFACE_ADDRESSES
  securitySchemes:
    api_token:
      type: http
      scheme: basic
