openapi: 3.1.0
info:
  title: 'Forward Networks: Networks API'
  description: Create, list, rename, or delete model networks
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /
security:
  - api_token: []
tags:
  - name: Networks
    description: Create, list, rename, or delete model networks
paths:
  /api/networks:
    get:
      tags:
        - Networks
      summary: Lists all networks
      operationId: getNetworksUsingGET
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Network'
    post:
      tags:
        - Networks
      summary: Creates a network
      operationId: createNetworkUsingPOST
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
  /api/networks/{networkId}:
    delete:
      tags:
        - Networks
      summary: Deletes a network
      operationId: deleteNetworkUsingDELETE
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
    patch:
      tags:
        - Networks
      summary: Updates a network
      description: All JSON properties in the request body are optional. Include only the properties you wish to change.
      operationId: updateNetworkUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkUpdate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
  /api/networks/{networkId}/workspaces:
    post:
      tags:
        - Networks
      summary: Creates a Workspace network
      description: A <a class="fn-external-link" target="_blank" href="/docs/enterprise/applications/change-mgmt/workspace_network/">Workspace network</a> is a network that collects from only a subset of the devices in a large “parent” network. This kind of network can be useful in time-sensitive situations like change management windows.
      operationId: createWorkspaceNetworkUsingPOST
      parameters:
        - name: networkId
          in: path
          description: The id of the parent network
          required: true
          schema:
            type: string
      requestBody:
        description: Information about the new Workspace network
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceNetworkRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
components:
  schemas:
    CreateWorkspaceNetworkRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          examples:
            - My Network - Workspace A
        note:
          type: string
          examples:
            - For change window 2021-10-30-ABC
        devices:
          type: array
          items:
            type: string
          description: Names of the devices to include (`ClassicDevice` names; see [Network Setup](#network-setup)). Can be omitted or empty if `cloudAccounts` or `vcenters` is nonempty.
          examples:
            - - nyc-dc01-tor01
              - nyc-dc01-rtr01
        cloudAccounts:
          type: array
          items:
            type: string
          description: Names of the cloud accounts (<a class="fn-external-link" target="_blank" href="docs/enterprise/getting_started/configure_collection/cloud/aws_setup/">AWS</a>), <a class="fn-external-link" target="_blank" href="docs/enterprise/getting_started/configure_collection/cloud/gcp_setup/">GCP</a>), or <a class="fn-external-link" target="_blank" href="docs/enterprise/getting_started/configure_collection/cloud/azure_setup/">Azure</a>) to include. Can be omitted or empty if `devices` or `vcenters` is nonempty.
          examples:
            - - my-aws-account
              - my-gcp-account
              - my-azure-account
        vcenters:
          type: array
          items:
            type: string
          description: Names of the <a class="fn-external-link" target="_blank" href="docs/enterprise/getting_started/configure_collection/VMware_account/">vCenters</a>) to include. Can be omitted or empty if `devices` or `cloudAccounts` is nonempty.
          examples:
            - - vcenter-01
        omissions:
          type: array
          items:
            type: string
            enum:
              - CUSTOM_COMMANDS
              - NQE_CHECKS
              - PREDEFINED_CHECKS
              - INTENT_CHECKS
          description: What to omit (not copy) from the parent network
          examples:
            - - CUSTOM_COMMANDS
              - NQE_CHECKS
        retentionDays:
          type: integer
          format: int32
          minimum: 1
          maximum: 365
          description: Number of days of inactivity after which the Workspace network will be deleted. If omitted, the value defaults to 7. If specified as null, this network will be considered permanent.
    Network:
      type: object
      required:
        - id
        - name
        - orgId
      properties:
        id:
          type: string
        parentId:
          type: string
          description: The network from which this Workspace network was created. Absent if this network is not a Workspace.
        name:
          type: string
          examples:
            - My Network
        orgId:
          type: string
        creator:
          type: string
          description: The username of the user who created the network, or null if the account was deleted
          examples:
            - mary
        creatorId:
          type: string
          description: The id of the user who created the network, or null if the account was deleted
          examples:
            - '123'
        createdAt:
          type: integer
          format: int64
          examples:
            - 1649277285118
        note:
          type: string
          description: An optional network description.
        retentionDays:
          type: integer
          format: int32
          minimum: 1
          maximum: 365
          description: The number of days without any use of this network after which it will be automatically deleted. Absent for parent networks and permanent Workspace networks.
        secondsToExpiry:
          type: integer
          format: int64
          description: Number of seconds without use before the network expires. Present for temporary Workspace networks only.
    NetworkUpdate:
      type: object
      properties:
        name:
          type: string
        note:
          type: string
        retentionDays:
          type: integer
          format: int32
  securitySchemes:
    api_token:
      type: http
      scheme: basic
