openapi: 3.1.0
info:
  title: NetFoundry Core Management
  description: NetFoundry Core Management API
  version: 0.6.0
servers:
  - url: https://gateway.production.netfoundry.io/core
security:
  - bearerAuth: []
tags:
  - name: Regions
    description: Retrieves Regions
  - name: Host Sizes
    description: Retrieves Host Sizes
  - name: Network Assemblies
    description: Retrieve a Network as an assembly or create a new Network from an assembly
  - name: Software Deployment States
    description: Retrieves or updates SoftwareDeploymentStates
  - name: Host Addresses
    description: Manages Host addresses
  - name: Container Sizes
    description: Retrieves Container Sizes
  - name: Network Groups
    description: Manage Network Groups
  - name: Dns Zones
    description: Manage DnsZone resources
  - name: Edge Routers
    description: Manages Edge Routers
  - name: Edge Router Registrations
    description: Manages Edge Router Registrations
  - name: Network Controller Upgrades
    description: Handles upgrades of Network Controllers
  - name: Edge Router Upgrades
    description: Handles upgrades of Edge Routers
  - name: Network Upgrades
    description: Handles upgrades of a Network
  - name: Stored Secrets
    description: Manage StoredSecret resources
  - name: Clusters
    description: Manage Cluster resources
  - name: Cloud Providers
    description: Retrieves Cloud Providers
  - name: NetworkJwtSets
    description: Retrieves NetworkJwtSets
  - name: Hosts
    description: Retrieves Hosts
  - name: Executions
    description: Manage Execution resources
  - name: Networks
    description: Manage Network resources
  - name: Containers
    description: Retrieves Containers
  - name: Network Controllers
    description: Manage Network Controller resources
  - name: Network Versions
    description: Retrieves Network Versions
paths:
  /v3/networks/{id}/suspend:
    put:
      tags:
        - Networks
      summary: Suspend Network
      description: >
        Suspend the specified Network. This will stop all of the controllers on
        the Network from running without deleting them.

        The operation is asynchronous and returns the updated Network resource
        with related links.

        The caller must have the update-suspend permission on the specified
        Network.
      operationId: suspendNetwork_1
      parameters:
        - name: id
          in: path
          description: Id of the Network to suspend
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "e99603ba-70c3-4886-99a3-2936f88aefed",
                      "ownerIdentityId" : "8b823d48-ca03-4e92-ba85-19187f3bb6c1",
                      "createdBy" : "8b823d48-ca03-4e92-ba85-19187f3bb6c1",
                      "createdAt" : "2025-12-05T15:19:42.705537Z",
                      "updatedAt" : "2025-12-05T15:19:42.782645Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "suspend-test-v3",
                      "networkGroupId" : "e37e2a44-4784-4c64-a3d5-3e276126c260",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/e99603ba-70c3-4886-99a3-2936f88aefed",
                          "title" : "suspend-test-v3"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/e37e2a44-4784-4c64-a3d5-3e276126c260",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Suspend Network
      description: >
        Suspend the specified Network. This will stop all of the controllers on
        the Network from running without deleting them.

        The operation is asynchronous and returns the updated Network resource
        with related links.

        The caller must have the update-suspend permission on the specified
        Network.
      operationId: suspendNetwork
      parameters:
        - name: id
          in: path
          description: Id of the Network to suspend
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "e99603ba-70c3-4886-99a3-2936f88aefed",
                      "ownerIdentityId" : "8b823d48-ca03-4e92-ba85-19187f3bb6c1",
                      "createdBy" : "8b823d48-ca03-4e92-ba85-19187f3bb6c1",
                      "createdAt" : "2025-12-05T15:19:42.705537Z",
                      "updatedAt" : "2025-12-05T15:19:42.782645Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "suspend-test-v3",
                      "networkGroupId" : "e37e2a44-4784-4c64-a3d5-3e276126c260",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/e99603ba-70c3-4886-99a3-2936f88aefed",
                          "title" : "suspend-test-v3"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/e37e2a44-4784-4c64-a3d5-3e276126c260",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/resume:
    put:
      tags:
        - Networks
      summary: Resume Network
      description: >
        Resume the specified Network. This will restart all of the suspended
        controllers on the Network.

        The operation is asynchronous and returns the updated Network resource
        with related links.

        The caller must have the update-resume permission on the specified
        Network.
      operationId: resumeNetwork_1
      parameters:
        - name: id
          in: path
          description: Id of the Network to resume
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "019af781-ac45-4a60-b843-1efe4775ddd7",
                      "ownerIdentityId" : "74d34147-a204-4a66-a1c9-0bd25a25c80e",
                      "createdBy" : "74d34147-a204-4a66-a1c9-0bd25a25c80e",
                      "createdAt" : "2025-12-05T15:19:42.226612Z",
                      "updatedAt" : "2025-12-05T15:19:42.336787Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "resume-test-v3",
                      "networkGroupId" : "23471914-5628-47bc-b498-325a4853998f",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/019af781-ac45-4a60-b843-1efe4775ddd7",
                          "title" : "resume-test-v3"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/23471914-5628-47bc-b498-325a4853998f",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Resume Network
      description: >
        Resume the specified Network. This will restart all of the suspended
        controllers on the Network.

        The operation is asynchronous and returns the updated Network resource
        with related links.

        The caller must have the update-resume permission on the specified
        Network.
      operationId: resumeNetwork
      parameters:
        - name: id
          in: path
          description: Id of the Network to resume
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "019af781-ac45-4a60-b843-1efe4775ddd7",
                      "ownerIdentityId" : "74d34147-a204-4a66-a1c9-0bd25a25c80e",
                      "createdBy" : "74d34147-a204-4a66-a1c9-0bd25a25c80e",
                      "createdAt" : "2025-12-05T15:19:42.226612Z",
                      "updatedAt" : "2025-12-05T15:19:42.336787Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "resume-test-v3",
                      "networkGroupId" : "23471914-5628-47bc-b498-325a4853998f",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/019af781-ac45-4a60-b843-1efe4775ddd7",
                          "title" : "resume-test-v3"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/23471914-5628-47bc-b498-325a4853998f",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/process/restart:
    put:
      tags:
        - Networks
      summary: Restart network controller processes
      description: >
        Restart all controller processes for the specified Network. Optionally
        restart controller services concurrently.

        The caller must have the update-heal permission on the specified
        Network.
      operationId: restartNetworkProcess_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Options for restarting processes. If omitted, defaults are applied.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestartOptions'
            examples:
              default:
                description: default
                value:
                  concurrentControllerRestart: false
              concurrent:
                description: concurrent
                value:
                  concurrentControllerRestart: true
        required: true
      responses:
        '202':
          description: Accepted. Network process restart has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "f6a203e8-a6c6-4350-b983-5295cf899935",
                      "ownerIdentityId" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                      "createdBy" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                      "createdAt" : "2025-11-17T16:24:56.099409Z",
                      "updatedAt" : "2025-11-17T16:24:56.145494Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-351",
                      "networkGroupId" : "83e45c77-c4e3-4c49-b42b-1c3ba034f209",
                      "size" : "small",
                      "productVersion" : "7.4.16",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : true,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "networkController" : {
                        "id" : "f878bd1f-47d0-4ac3-a13a-b801a1499fe6",
                        "ownerIdentityId" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                        "networkId" : "f6a203e8-a6c6-4350-b983-5295cf899935",
                        "domainName" : "f878bd1f-47d0-4ac3-a13a-b801a1499fe6.nf.io",
                        "alternateDomainName" : null,
                        "port" : 443,
                        "name" : "network-351-nc",
                        "productVersion" : "7.4.16",
                        "hostId" : "0a81eae5-a6b0-4481-ba54-06013cb57e86",
                        "status" : "PROVISIONED",
                        "createdAt" : "2025-11-17T16:24:56.108395Z",
                        "updatedAt" : "2025-11-17T16:24:56.119536Z",
                        "deletedAt" : null,
                        "createdBy" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                        "deletedBy" : null,
                        "softwareDeploymentStateId" : "c5d461ea-60e9-45d7-a9ac-50180ec16190",
                        "haPrimaryNode" : true
                      },
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-groups/83e45c77-c4e3-4c49-b42b-1c3ba034f209",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/f6a203e8-a6c6-4350-b983-5295cf899935",
                          "title" : "network-351"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Restart network controller processes
      description: >
        Restart all controller processes for the specified Network. Optionally
        restart controller services concurrently.

        The caller must have the update-heal permission on the specified
        Network.
      operationId: restartNetworkProcess
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Options for restarting processes. If omitted, defaults are applied.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestartOptions'
            examples:
              default:
                description: default
                value:
                  concurrentControllerRestart: false
              concurrent:
                description: concurrent
                value:
                  concurrentControllerRestart: true
        required: true
      responses:
        '202':
          description: Accepted. Network process restart has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "f6a203e8-a6c6-4350-b983-5295cf899935",
                      "ownerIdentityId" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                      "createdBy" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                      "createdAt" : "2025-11-17T16:24:56.099409Z",
                      "updatedAt" : "2025-11-17T16:24:56.145494Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-351",
                      "networkGroupId" : "83e45c77-c4e3-4c49-b42b-1c3ba034f209",
                      "size" : "small",
                      "productVersion" : "7.4.16",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : true,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "networkController" : {
                        "id" : "f878bd1f-47d0-4ac3-a13a-b801a1499fe6",
                        "ownerIdentityId" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                        "networkId" : "f6a203e8-a6c6-4350-b983-5295cf899935",
                        "domainName" : "f878bd1f-47d0-4ac3-a13a-b801a1499fe6.nf.io",
                        "alternateDomainName" : null,
                        "port" : 443,
                        "name" : "network-351-nc",
                        "productVersion" : "7.4.16",
                        "hostId" : "0a81eae5-a6b0-4481-ba54-06013cb57e86",
                        "status" : "PROVISIONED",
                        "createdAt" : "2025-11-17T16:24:56.108395Z",
                        "updatedAt" : "2025-11-17T16:24:56.119536Z",
                        "deletedAt" : null,
                        "createdBy" : "75a5f6f0-5faa-470e-82dc-aa31d4d666c1",
                        "deletedBy" : null,
                        "softwareDeploymentStateId" : "c5d461ea-60e9-45d7-a9ac-50180ec16190",
                        "haPrimaryNode" : true
                      },
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-groups/83e45c77-c4e3-4c49-b42b-1c3ba034f209",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/f6a203e8-a6c6-4350-b983-5295cf899935",
                          "title" : "network-351"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/host/restart:
    put:
      tags:
        - Networks
      summary: Restart network controller hosts
      description: >
        Restart all controller hosts for the specified Network. Optionally
        restart controller services concurrently.

        The caller must have the update-heal permission on the specified
        Network.
      operationId: restartNetworkHost_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Options for restarting hosts. If omitted, defaults are applied.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestartOptions'
            examples:
              default:
                description: default
                value:
                  concurrentControllerRestart: false
              concurrent:
                description: concurrent
                value:
                  concurrentControllerRestart: true
        required: true
      responses:
        '202':
          description: Accepted. Network host restart has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "1edbcee5-14d3-4919-bcf9-65974afb9998",
                      "ownerIdentityId" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                      "createdBy" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                      "createdAt" : "2025-11-17T16:24:55.722276Z",
                      "updatedAt" : "2025-11-17T16:24:55.775181Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-334",
                      "networkGroupId" : "38d007e0-7b4c-409d-b4d0-18ec1da20bde",
                      "size" : "small",
                      "productVersion" : "7.4.16",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : true,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "networkController" : {
                        "id" : "5cf90e8d-c86a-4ff0-ba3b-5cc0a0c03fc6",
                        "ownerIdentityId" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                        "networkId" : "1edbcee5-14d3-4919-bcf9-65974afb9998",
                        "domainName" : "5cf90e8d-c86a-4ff0-ba3b-5cc0a0c03fc6.nf.io",
                        "alternateDomainName" : null,
                        "port" : 443,
                        "name" : "network-334-nc",
                        "productVersion" : "7.4.16",
                        "hostId" : "9f461f88-2d7b-4a3e-bcaf-ce6a630881b7",
                        "status" : "PROVISIONED",
                        "createdAt" : "2025-11-17T16:24:55.730847Z",
                        "updatedAt" : "2025-11-17T16:24:55.741246Z",
                        "deletedAt" : null,
                        "createdBy" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                        "deletedBy" : null,
                        "softwareDeploymentStateId" : "d4ba6464-1c2b-4d4a-8db2-db3491254938",
                        "haPrimaryNode" : true
                      },
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-groups/38d007e0-7b4c-409d-b4d0-18ec1da20bde",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/1edbcee5-14d3-4919-bcf9-65974afb9998",
                          "title" : "network-334"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Restart network controller hosts
      description: >
        Restart all controller hosts for the specified Network. Optionally
        restart controller services concurrently.

        The caller must have the update-heal permission on the specified
        Network.
      operationId: restartNetworkHost
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Options for restarting hosts. If omitted, defaults are applied.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestartOptions'
            examples:
              default:
                description: default
                value:
                  concurrentControllerRestart: false
              concurrent:
                description: concurrent
                value:
                  concurrentControllerRestart: true
        required: true
      responses:
        '202':
          description: Accepted. Network host restart has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "1edbcee5-14d3-4919-bcf9-65974afb9998",
                      "ownerIdentityId" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                      "createdBy" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                      "createdAt" : "2025-11-17T16:24:55.722276Z",
                      "updatedAt" : "2025-11-17T16:24:55.775181Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-334",
                      "networkGroupId" : "38d007e0-7b4c-409d-b4d0-18ec1da20bde",
                      "size" : "small",
                      "productVersion" : "7.4.16",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : true,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "networkController" : {
                        "id" : "5cf90e8d-c86a-4ff0-ba3b-5cc0a0c03fc6",
                        "ownerIdentityId" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                        "networkId" : "1edbcee5-14d3-4919-bcf9-65974afb9998",
                        "domainName" : "5cf90e8d-c86a-4ff0-ba3b-5cc0a0c03fc6.nf.io",
                        "alternateDomainName" : null,
                        "port" : 443,
                        "name" : "network-334-nc",
                        "productVersion" : "7.4.16",
                        "hostId" : "9f461f88-2d7b-4a3e-bcaf-ce6a630881b7",
                        "status" : "PROVISIONED",
                        "createdAt" : "2025-11-17T16:24:55.730847Z",
                        "updatedAt" : "2025-11-17T16:24:55.741246Z",
                        "deletedAt" : null,
                        "createdBy" : "f2d3f2c4-bf1b-4186-a8aa-119c168d8f6a",
                        "deletedBy" : null,
                        "softwareDeploymentStateId" : "d4ba6464-1c2b-4d4a-8db2-db3491254938",
                        "haPrimaryNode" : true
                      },
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-groups/38d007e0-7b4c-409d-b4d0-18ec1da20bde",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/1edbcee5-14d3-4919-bcf9-65974afb9998",
                          "title" : "network-334"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/suspend:
    put:
      tags:
        - Network Controllers
      summary: Suspend Network Controller
      description: >
        Suspend the specified Network Controller. This will stop the controller
        from running without deleting it.

        The operation is asynchronous and returns the updated Network Controller
        resource with related links.

        The caller must have the update-suspend permission on the specified
        Network Controller.
      operationId: suspendNetworkController_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to suspend
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network Controller suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "34357c00-b3d5-4055-85b0-23cc63bc765f",
                      "ownerIdentityId" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "networkId" : "dd64a3e3-1342-4006-9d67-93c06a8c462b",
                      "domainName" : "34357c00-b3d5-4055-85b0-23cc63bc765f.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-v3-controller-test-nc",
                      "productVersion" : "8.0.43",
                      "hostId" : "6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce",
                      "status" : "UPDATING",
                      "createdAt" : "2025-12-05T15:18:36.128508Z",
                      "updatedAt" : "2025-12-05T15:18:38.469882Z",
                      "deletedAt" : null,
                      "createdBy" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "65f080c8-4c5c-4663-9086-76de7149ea47",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f",
                          "title" : "networkcontroller-v3-controller-test-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/65f080c8-4c5c-4663-9086-76de7149ea47"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/dd64a3e3-1342-4006-9d67-93c06a8c462b",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Suspend Network Controller
      description: >
        Suspend the specified Network Controller. This will stop the controller
        from running without deleting it.

        The operation is asynchronous and returns the updated Network Controller
        resource with related links.

        The caller must have the update-suspend permission on the specified
        Network Controller.
      operationId: suspendNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to suspend
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network Controller suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "34357c00-b3d5-4055-85b0-23cc63bc765f",
                      "ownerIdentityId" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "networkId" : "dd64a3e3-1342-4006-9d67-93c06a8c462b",
                      "domainName" : "34357c00-b3d5-4055-85b0-23cc63bc765f.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-v3-controller-test-nc",
                      "productVersion" : "8.0.43",
                      "hostId" : "6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce",
                      "status" : "UPDATING",
                      "createdAt" : "2025-12-05T15:18:36.128508Z",
                      "updatedAt" : "2025-12-05T15:18:38.469882Z",
                      "deletedAt" : null,
                      "createdBy" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "65f080c8-4c5c-4663-9086-76de7149ea47",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f",
                          "title" : "networkcontroller-v3-controller-test-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/65f080c8-4c5c-4663-9086-76de7149ea47"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/dd64a3e3-1342-4006-9d67-93c06a8c462b",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/resume:
    put:
      tags:
        - Network Controllers
      summary: Resume Network Controller
      description: >
        Resume the specified Network Controller. This restarts the controller
        service if it is suspended.

        The operation is asynchronous and returns the updated Network Controller
        resource with related links.

        The caller must have the update-resume permission on the specified
        Network Controller.
      operationId: resumeNetworkController_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to resume
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network Controller resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "34357c00-b3d5-4055-85b0-23cc63bc765f",
                      "ownerIdentityId" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "networkId" : "dd64a3e3-1342-4006-9d67-93c06a8c462b",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-v3-controller-test-nc",
                      "productVersion" : "8.0.43",
                      "hostId" : "ed7a96b0-f9fa-44b5-bd17-ec5b530408e7",
                      "status" : "UPDATING",
                      "createdAt" : "2025-12-05T15:18:36.128508Z",
                      "updatedAt" : "2025-12-05T15:18:44.516251Z",
                      "deletedAt" : null,
                      "createdBy" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "d81a2d55-3636-4728-aec8-a064519dd024",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f",
                          "title" : "networkcontroller-v3-controller-test-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/d81a2d55-3636-4728-aec8-a064519dd024"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ed7a96b0-f9fa-44b5-bd17-ec5b530408e7"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/dd64a3e3-1342-4006-9d67-93c06a8c462b",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Resume Network Controller
      description: >
        Resume the specified Network Controller. This restarts the controller
        service if it is suspended.

        The operation is asynchronous and returns the updated Network Controller
        resource with related links.

        The caller must have the update-resume permission on the specified
        Network Controller.
      operationId: resumeNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to resume
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network Controller resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "34357c00-b3d5-4055-85b0-23cc63bc765f",
                      "ownerIdentityId" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "networkId" : "dd64a3e3-1342-4006-9d67-93c06a8c462b",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-v3-controller-test-nc",
                      "productVersion" : "8.0.43",
                      "hostId" : "ed7a96b0-f9fa-44b5-bd17-ec5b530408e7",
                      "status" : "UPDATING",
                      "createdAt" : "2025-12-05T15:18:36.128508Z",
                      "updatedAt" : "2025-12-05T15:18:44.516251Z",
                      "deletedAt" : null,
                      "createdBy" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "d81a2d55-3636-4728-aec8-a064519dd024",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f",
                          "title" : "networkcontroller-v3-controller-test-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/d81a2d55-3636-4728-aec8-a064519dd024"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ed7a96b0-f9fa-44b5-bd17-ec5b530408e7"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/dd64a3e3-1342-4006-9d67-93c06a8c462b",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/process/restart:
    put:
      tags:
        - Network Controllers
      summary: Restart Network Controller process
      description: >
        Restart the Network Controller application process on its host. This
        schedules a restart operation and returns the controller resource.

        The operation is asynchronous; check the returned resource for execution
        links or poll the controller to see updated status.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: restartNetworkControllerProcess_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to restart
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: >-
            Accepted. The restart of the Network Controller process has been
            scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Restart process accepted response
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "1acd4a72-a185-4242-ab06-c7b106214117.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:16.834932Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "2b152768-fe70-4861-89e1-c7e5ca4353e4",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/2b152768-fe70-4861-89e1-c7e5ca4353e4"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "networkcontroller-controller-test-nc"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Restart Network Controller process
      description: >
        Restart the Network Controller application process on its host. This
        schedules a restart operation and returns the controller resource.

        The operation is asynchronous; check the returned resource for execution
        links or poll the controller to see updated status.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: restartNetworkControllerProcess
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to restart
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: >-
            Accepted. The restart of the Network Controller process has been
            scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Restart process accepted response
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "1acd4a72-a185-4242-ab06-c7b106214117.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:16.834932Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "2b152768-fe70-4861-89e1-c7e5ca4353e4",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/2b152768-fe70-4861-89e1-c7e5ca4353e4"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "networkcontroller-controller-test-nc"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/move:
    put:
      tags:
        - Network Controllers
      summary: Move Network Controller host
      description: >
        Move the Network Controller host to a different cloud provider/region or
        within the same provider/region.

        When moving within the same provider and region, you may either request
        a new IP to be assigned or specify a previously allocated IP address.

        The caller must have the update-move permission on the specified Network
        Controller.
      operationId: moveNetworkController_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to move
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Move request describing target provider/region and optional IP
          assignment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveHost'
            examples:
              move-within-provider-assign-new-ip:
                description: Move within the same provider/region and assign a new IP
                value:
                  provider: AWS
                  region: us-east-1
                  assignNewIp: true
              move-with-specified-ip:
                description: Move and specify a previously allocated IP address
                value:
                  provider: AWS
                  region: us-west-2
                  ipAddress: 203.0.113.10
        required: true
      responses:
        '202':
          description: Accepted. Network Controller move has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                network-controller:
                  description: Example Network Controller response with links
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "1acd4a72-a185-4242-ab06-c7b106214117.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:20.521306Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "37b620fc-b7b9-4ea2-884e-f610c1d672bd",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/37b620fc-b7b9-4ea2-884e-f610c1d672bd"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "networkcontroller-controller-test-nc"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/37b620fc-b7b9-4ea2-884e-f610c1d672bd",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Move Network Controller host
      description: >
        Move the Network Controller host to a different cloud provider/region or
        within the same provider/region.

        When moving within the same provider and region, you may either request
        a new IP to be assigned or specify a previously allocated IP address.

        The caller must have the update-move permission on the specified Network
        Controller.
      operationId: moveNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to move
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Move request describing target provider/region and optional IP
          assignment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveHost'
            examples:
              move-within-provider-assign-new-ip:
                description: Move within the same provider/region and assign a new IP
                value:
                  provider: AWS
                  region: us-east-1
                  assignNewIp: true
              move-with-specified-ip:
                description: Move and specify a previously allocated IP address
                value:
                  provider: AWS
                  region: us-west-2
                  ipAddress: 203.0.113.10
        required: true
      responses:
        '202':
          description: Accepted. Network Controller move has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                network-controller:
                  description: Example Network Controller response with links
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "1acd4a72-a185-4242-ab06-c7b106214117.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:20.521306Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "37b620fc-b7b9-4ea2-884e-f610c1d672bd",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/c8f00e8e-2109-4c3c-a5b4-b7e62f1d69e3"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/37b620fc-b7b9-4ea2-884e-f610c1d672bd"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "networkcontroller-controller-test-nc"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/37b620fc-b7b9-4ea2-884e-f610c1d672bd",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/host/restart:
    put:
      tags:
        - Network Controllers
      summary: Restart Network Controller host
      description: >
        Restart the underlying host (VM) for the specified Network Controller.
        This schedules a host restart operation and returns the controller
        resource.

        The operation is asynchronous; check the returned resource for execution
        links or poll the controller to see updated status.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: restartNetworkControllerHost_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller whose host will be restarted
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: >-
            Accepted. The restart of the Network Controller host has been
            scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Restart host accepted response
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:20.934223Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6b36c604-3cf1-4f34-964f-3f11633ba637",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6b36c604-3cf1-4f34-964f-3f11633ba637"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Restart Network Controller host
      description: >
        Restart the underlying host (VM) for the specified Network Controller.
        This schedules a host restart operation and returns the controller
        resource.

        The operation is asynchronous; check the returned resource for execution
        links or poll the controller to see updated status.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: restartNetworkControllerHost
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller whose host will be restarted
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: >-
            Accepted. The restart of the Network Controller host has been
            scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Restart host accepted response
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:20.934223Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6b36c604-3cf1-4f34-964f-3f11633ba637",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6b36c604-3cf1-4f34-964f-3f11633ba637"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/host/resize:
    put:
      tags:
        - Network Controllers
      summary: Resize Network Controller host
      description: >
        Resize the underlying host instance for the specified Network
        Controller.

        Provide the desired deployment size identifier in the request body.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: resizeNetworkControllerHost_1
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to resize
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Resize host request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeHost'
            examples:
              small:
                description: Resize the host to a small deployment size
                value:
                  size: small
              medium:
                description: Resize the host to a medium deployment size
                value:
                  size: medium
        required: true
      responses:
        '202':
          description: Accepted. Network Controller host resize has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "5c729904-3077-4ee5-bff9-209e15231112",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "f53bc7b8-81b8-4077-b559-9acc25ce7348",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:20.813642Z",
                      "updatedAt" : "2025-11-17T16:28:23.444550Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "151624c3-80e8-44ba-a13a-9bf4d4add652",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/f53bc7b8-81b8-4077-b559-9acc25ce7348"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/151624c3-80e8-44ba-a13a-9bf4d4add652"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/5c729904-3077-4ee5-bff9-209e15231112",
                          "title" : "networkcontroller-controller-test-nc"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Resize Network Controller host
      description: >
        Resize the underlying host instance for the specified Network
        Controller.

        Provide the desired deployment size identifier in the request body.

        The caller must have the update-heal permission on the specified Network
        Controller.
      operationId: resizeNetworkControllerHost
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller to resize
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Resize host request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeHost'
            examples:
              small:
                description: Resize the host to a small deployment size
                value:
                  size: small
              medium:
                description: Resize the host to a medium deployment size
                value:
                  size: medium
        required: true
      responses:
        '202':
          description: Accepted. Network Controller host resize has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "5c729904-3077-4ee5-bff9-209e15231112",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller-test-nc",
                      "productVersion" : "7.4.5",
                      "hostId" : "f53bc7b8-81b8-4077-b559-9acc25ce7348",
                      "status" : "UPDATING",
                      "createdAt" : "2025-11-17T16:28:20.813642Z",
                      "updatedAt" : "2025-11-17T16:28:23.444550Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "151624c3-80e8-44ba-a13a-9bf4d4add652",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/f53bc7b8-81b8-4077-b559-9acc25ce7348"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/151624c3-80e8-44ba-a13a-9bf4d4add652"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/5c729904-3077-4ee5-bff9-209e15231112",
                          "title" : "networkcontroller-controller-test-nc"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/executions/{id}/cancel:
    put:
      tags:
        - Executions
      summary: Cancel an Execution
      description: >-
        Cancel a running or pending Execution by ID. If the underlying process
        is still active, the service attempts to cancel it and returns the
        updated Execution resource.
      operationId: cancelExecution_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Execution to cancel.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: >-
            OK. Returns the updated Execution resource reflecting its canceled
            state when applicable.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get execution response
                  value: |-
                    {
                      "id" : "c5e80418-a4ff-4eea-aab3-0438c391a21e",
                      "networkId" : "12b04999-4903-41eb-b781-79df991fc3b4",
                      "processId" : "e7590fc8-5edc-4ab0-95bc-eb7d832b4ea9",
                      "name" : "CreateEndpointProcess",
                      "description" : "Create Endpoint",
                      "resourceType" : "component",
                      "resourceId" : "e57d6e0d-29c1-489e-8608-b549a85febb1",
                      "startedAt" : "2025-12-05T15:18:13.347396Z",
                      "finishedAt" : "2025-12-05T15:18:13.407543Z",
                      "traceId" : "trace1",
                      "status" : "CANCELED",
                      "initiatingIdentityId" : "54263e60-3c9e-4193-9bbd-eb3accc5880f",
                      "createdAt" : "2025-12-05T15:18:13.348219Z",
                      "updatedAt" : "2025-12-05T15:18:13.409966Z",
                      "actions" : [ ],
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/12b04999-4903-41eb-b781-79df991fc3b4",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/c5e80418-a4ff-4eea-aab3-0438c391a21e",
                          "title" : "CreateEndpointProcess"
                        }
                      }
                    }
          links:
            self:
              operationId: getExecution
              parameters:
                id: $request.path.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Executions
      summary: Cancel an Execution
      description: >-
        Cancel a running or pending Execution by ID. If the underlying process
        is still active, the service attempts to cancel it and returns the
        updated Execution resource.
      operationId: cancelExecution
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Execution to cancel.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: >-
            OK. Returns the updated Execution resource reflecting its canceled
            state when applicable.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get execution response
                  value: |-
                    {
                      "id" : "c5e80418-a4ff-4eea-aab3-0438c391a21e",
                      "networkId" : "12b04999-4903-41eb-b781-79df991fc3b4",
                      "processId" : "e7590fc8-5edc-4ab0-95bc-eb7d832b4ea9",
                      "name" : "CreateEndpointProcess",
                      "description" : "Create Endpoint",
                      "resourceType" : "component",
                      "resourceId" : "e57d6e0d-29c1-489e-8608-b549a85febb1",
                      "startedAt" : "2025-12-05T15:18:13.347396Z",
                      "finishedAt" : "2025-12-05T15:18:13.407543Z",
                      "traceId" : "trace1",
                      "status" : "CANCELED",
                      "initiatingIdentityId" : "54263e60-3c9e-4193-9bbd-eb3accc5880f",
                      "createdAt" : "2025-12-05T15:18:13.348219Z",
                      "updatedAt" : "2025-12-05T15:18:13.409966Z",
                      "actions" : [ ],
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/12b04999-4903-41eb-b781-79df991fc3b4",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/c5e80418-a4ff-4eea-aab3-0438c391a21e",
                          "title" : "CreateEndpointProcess"
                        }
                      }
                    }
          links:
            self:
              operationId: getExecution
              parameters:
                id: $request.path.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/suspend:
    put:
      tags:
        - Edge Routers
      summary: Suspend Edge Router
      description: >
        Suspend the specified Edge Router. This will stop the edge router from
        running without deleting it.

        The operation is asynchronous and returns the updated Edge Router
        resource with related links.

        The caller must have the update-suspend permission on the specified Edge
        Router.
      operationId: suspendEdgeRouter_1
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to suspend
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Edge Router suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                      "hostId" : "ff2bba00-eeb9-498c-bb5b-ac43e27c3354",
                      "ownerIdentityId" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdBy" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdAt" : "2025-12-05T15:20:19.793074Z",
                      "updatedAt" : "2025-12-05T15:20:19.857932Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1204",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e-p.fake.netfoundry.io",
                      "name" : "er-test-1203",
                      "productVersion" : "8.0.43",
                      "networkId" : "116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                          "title" : "er-test-1203"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ff2bba00-eeb9-498c-bb5b-ac43e27c3354"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Suspend Edge Router
      description: >
        Suspend the specified Edge Router. This will stop the edge router from
        running without deleting it.

        The operation is asynchronous and returns the updated Edge Router
        resource with related links.

        The caller must have the update-suspend permission on the specified Edge
        Router.
      operationId: suspendEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to suspend
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Edge Router suspend has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                      "hostId" : "ff2bba00-eeb9-498c-bb5b-ac43e27c3354",
                      "ownerIdentityId" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdBy" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdAt" : "2025-12-05T15:20:19.793074Z",
                      "updatedAt" : "2025-12-05T15:20:19.857932Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1204",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e-p.fake.netfoundry.io",
                      "name" : "er-test-1203",
                      "productVersion" : "8.0.43",
                      "networkId" : "116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                          "title" : "er-test-1203"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ff2bba00-eeb9-498c-bb5b-ac43e27c3354"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/resume:
    put:
      tags:
        - Edge Routers
      summary: Resume Edge Router
      description: >
        Resume the specified Edge Router. This restarts the edge router host if
        it is suspended.

        The operation is asynchronous and returns the updated Edge Router
        resource with related links.

        The caller must have the update-resume permission on the specified Edge
        Router.
      operationId: resumeEdgeRouter_1
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to resume
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Edge Router resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "47cdb694-884f-4a4f-903e-9ff3e1f45512",
                      "hostId" : "35c82219-3193-4b48-a871-d0da13dd0f3b",
                      "ownerIdentityId" : "4cc4d242-c7aa-4d18-acd7-e91300e5d6d6",
                      "createdBy" : "4cc4d242-c7aa-4d18-acd7-e91300e5d6d6",
                      "createdAt" : "2025-12-05T15:20:26.618658Z",
                      "updatedAt" : "2025-12-05T15:20:26.680386Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1669",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "47cdb694-884f-4a4f-903e-9ff3e1f45512-p.fake.netfoundry.io",
                      "name" : "er-test-1668",
                      "productVersion" : "8.0.43",
                      "networkId" : "b8d7c7cc-24f8-47aa-a4d2-7e41b981c797",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/47cdb694-884f-4a4f-903e-9ff3e1f45512",
                          "title" : "er-test-1668"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b8d7c7cc-24f8-47aa-a4d2-7e41b981c797",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/35c82219-3193-4b48-a871-d0da13dd0f3b"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Resume Edge Router
      description: >
        Resume the specified Edge Router. This restarts the edge router host if
        it is suspended.

        The operation is asynchronous and returns the updated Edge Router
        resource with related links.

        The caller must have the update-resume permission on the specified Edge
        Router.
      operationId: resumeEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to resume
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Edge Router resume has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "47cdb694-884f-4a4f-903e-9ff3e1f45512",
                      "hostId" : "35c82219-3193-4b48-a871-d0da13dd0f3b",
                      "ownerIdentityId" : "4cc4d242-c7aa-4d18-acd7-e91300e5d6d6",
                      "createdBy" : "4cc4d242-c7aa-4d18-acd7-e91300e5d6d6",
                      "createdAt" : "2025-12-05T15:20:26.618658Z",
                      "updatedAt" : "2025-12-05T15:20:26.680386Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1669",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "47cdb694-884f-4a4f-903e-9ff3e1f45512-p.fake.netfoundry.io",
                      "name" : "er-test-1668",
                      "productVersion" : "8.0.43",
                      "networkId" : "b8d7c7cc-24f8-47aa-a4d2-7e41b981c797",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/47cdb694-884f-4a4f-903e-9ff3e1f45512",
                          "title" : "er-test-1668"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b8d7c7cc-24f8-47aa-a4d2-7e41b981c797",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/35c82219-3193-4b48-a871-d0da13dd0f3b"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/c90b7e0b-e7b9-4c60-8d19-89f6d4f506d8",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/process/restart:
    put:
      tags:
        - Edge Routers
      summary: Restart Edge Router Process
      description: >
        Schedules a restart of the Edge Router application process on the
        underlying host.

        The caller must have the update-heal permission on the Edge Router
        resource.
      operationId: restartEdgeRouterProcess_1
      parameters:
        - name: id
          in: path
          description: >-
            The unique identifier of the Edge Router whose process should be
            restarted.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '202':
          description: Restart scheduled; returns the Edge Router resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample restart process response
                  value: |-
                    {
                      "id" : "0b849af9-5cc3-40cd-a28a-2628ff204259",
                      "hostId" : "0fc1038b-f971-477e-ae43-e189e99b6100",
                      "ownerIdentityId" : "9b37397b-c843-42b2-8841-76a310c64bc2",
                      "createdBy" : "9b37397b-c843-42b2-8841-76a310c64bc2",
                      "createdAt" : "2025-12-05T15:20:21.895580Z",
                      "updatedAt" : "2025-12-05T15:20:21.950843Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1525",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "0b849af9-5cc3-40cd-a28a-2628ff204259-p.fake.netfoundry.io",
                      "name" : "er-test-1524",
                      "productVersion" : "8.0.43",
                      "networkId" : "df1218f4-503f-4c25-81d4-610623f464bb",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "7b0fc820-2ffe-4123-8811-0153803934c0",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/0b849af9-5cc3-40cd-a28a-2628ff204259",
                          "title" : "er-test-1524"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/7b0fc820-2ffe-4123-8811-0153803934c0"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/df1218f4-503f-4c25-81d4-610623f464bb",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/0fc1038b-f971-477e-ae43-e189e99b6100"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/7b0fc820-2ffe-4123-8811-0153803934c0",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Restart Edge Router Process
      description: >
        Schedules a restart of the Edge Router application process on the
        underlying host.

        The caller must have the update-heal permission on the Edge Router
        resource.
      operationId: restartEdgeRouterProcess
      parameters:
        - name: id
          in: path
          description: >-
            The unique identifier of the Edge Router whose process should be
            restarted.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '202':
          description: Restart scheduled; returns the Edge Router resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample restart process response
                  value: |-
                    {
                      "id" : "0b849af9-5cc3-40cd-a28a-2628ff204259",
                      "hostId" : "0fc1038b-f971-477e-ae43-e189e99b6100",
                      "ownerIdentityId" : "9b37397b-c843-42b2-8841-76a310c64bc2",
                      "createdBy" : "9b37397b-c843-42b2-8841-76a310c64bc2",
                      "createdAt" : "2025-12-05T15:20:21.895580Z",
                      "updatedAt" : "2025-12-05T15:20:21.950843Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1525",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "0b849af9-5cc3-40cd-a28a-2628ff204259-p.fake.netfoundry.io",
                      "name" : "er-test-1524",
                      "productVersion" : "8.0.43",
                      "networkId" : "df1218f4-503f-4c25-81d4-610623f464bb",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "7b0fc820-2ffe-4123-8811-0153803934c0",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/0b849af9-5cc3-40cd-a28a-2628ff204259",
                          "title" : "er-test-1524"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/7b0fc820-2ffe-4123-8811-0153803934c0"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/df1218f4-503f-4c25-81d4-610623f464bb",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/0fc1038b-f971-477e-ae43-e189e99b6100"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/7b0fc820-2ffe-4123-8811-0153803934c0",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/move:
    put:
      tags:
        - Edge Routers
      summary: Move Edge Router host
      description: >
        Move the Edge Router host to a different cloud provider/region or within
        the same provider/region.

        When moving within the same provider and region, you may either request
        a new IP to be assigned or specify a previously allocated IP address.

        The caller must have the update-move permission on the specified Edge
        Router.
      operationId: moveEdgeRouter_1
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to move
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Move request describing target provider/region and optional IP
          assignment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveHost'
            examples:
              move-within-provider-assign-new-ip:
                description: Move within the same provider/region and assign a new IP
                value:
                  provider: AWS
                  region: us-east-1
                  assignNewIp: true
              move-with-specified-ip:
                description: Move and specify a previously allocated IP address
                value:
                  provider: AWS
                  region: us-west-2
                  ipAddress: 203.0.113.10
        required: true
      responses:
        '202':
          description: Accepted. Edge Router move has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response with links
                  value: |-
                    {
                      "id" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                      "hostId" : "ff2bba00-eeb9-498c-bb5b-ac43e27c3354",
                      "ownerIdentityId" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdBy" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdAt" : "2025-12-05T15:20:19.793074Z",
                      "updatedAt" : "2025-12-05T15:20:19.857932Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1204",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e-p.fake.netfoundry.io",
                      "name" : "er-test-1203",
                      "productVersion" : "8.0.43",
                      "networkId" : "116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                          "title" : "er-test-1203"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ff2bba00-eeb9-498c-bb5b-ac43e27c3354"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Move Edge Router host
      description: >
        Move the Edge Router host to a different cloud provider/region or within
        the same provider/region.

        When moving within the same provider and region, you may either request
        a new IP to be assigned or specify a previously allocated IP address.

        The caller must have the update-move permission on the specified Edge
        Router.
      operationId: moveEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to move
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Move request describing target provider/region and optional IP
          assignment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveHost'
            examples:
              move-within-provider-assign-new-ip:
                description: Move within the same provider/region and assign a new IP
                value:
                  provider: AWS
                  region: us-east-1
                  assignNewIp: true
              move-with-specified-ip:
                description: Move and specify a previously allocated IP address
                value:
                  provider: AWS
                  region: us-west-2
                  ipAddress: 203.0.113.10
        required: true
      responses:
        '202':
          description: Accepted. Edge Router move has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response with links
                  value: |-
                    {
                      "id" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                      "hostId" : "ff2bba00-eeb9-498c-bb5b-ac43e27c3354",
                      "ownerIdentityId" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdBy" : "a937e803-2fdb-428a-9ff1-b83e91f9fc5b",
                      "createdAt" : "2025-12-05T15:20:19.793074Z",
                      "updatedAt" : "2025-12-05T15:20:19.857932Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1204",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "c5a14b20-5311-4a7a-85d1-fa9b072a194e-p.fake.netfoundry.io",
                      "name" : "er-test-1203",
                      "productVersion" : "8.0.43",
                      "networkId" : "116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/c5a14b20-5311-4a7a-85d1-fa9b072a194e",
                          "title" : "er-test-1203"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/116df4d4-5b1c-43ee-bbfa-731fc3b5794f",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/ff2bba00-eeb9-498c-bb5b-ac43e27c3354"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/499a1b3c-c2ca-4a0e-a05c-d27cde3d030f",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/host/restart:
    put:
      tags:
        - Edge Routers
      summary: Restart Edge Router Host
      description: >
        Schedules a restart of the Edge Router underlying host.

        The caller must have the update-heal permission on the Edge Router
        resource.
      operationId: restartEdgeRouterHost_1
      parameters:
        - name: id
          in: path
          description: >-
            The unique identifier of the Edge Router whose process should be
            restarted.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '202':
          description: Restart scheduled; returns the Edge Router resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample restart process response
                  value: |-
                    {
                      "id" : "2a874e05-eb13-4fe4-b088-1c5745e3bb88",
                      "hostId" : "74ba4881-65c1-4dbf-8ded-5164ad1c4897",
                      "ownerIdentityId" : "05d04d91-0d9a-4183-8d09-396431407500",
                      "createdBy" : "05d04d91-0d9a-4183-8d09-396431407500",
                      "createdAt" : "2025-12-05T15:20:17.661120Z",
                      "updatedAt" : "2025-12-05T15:20:18.083279Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1069",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "2a874e05-eb13-4fe4-b088-1c5745e3bb88-p.fake.netfoundry.io",
                      "name" : "er-test-1068",
                      "productVersion" : "8.0.43",
                      "networkId" : "b6a5a80c-3d1a-48a9-94af-89032cee34a9",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "46c08964-8c5d-465d-a675-5b4de57987a7",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/2a874e05-eb13-4fe4-b088-1c5745e3bb88",
                          "title" : "er-test-1068"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/46c08964-8c5d-465d-a675-5b4de57987a7"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b6a5a80c-3d1a-48a9-94af-89032cee34a9",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/74ba4881-65c1-4dbf-8ded-5164ad1c4897"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/46c08964-8c5d-465d-a675-5b4de57987a7",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Restart Edge Router Host
      description: >
        Schedules a restart of the Edge Router underlying host.

        The caller must have the update-heal permission on the Edge Router
        resource.
      operationId: restartEdgeRouterHost
      parameters:
        - name: id
          in: path
          description: >-
            The unique identifier of the Edge Router whose process should be
            restarted.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '202':
          description: Restart scheduled; returns the Edge Router resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample restart process response
                  value: |-
                    {
                      "id" : "2a874e05-eb13-4fe4-b088-1c5745e3bb88",
                      "hostId" : "74ba4881-65c1-4dbf-8ded-5164ad1c4897",
                      "ownerIdentityId" : "05d04d91-0d9a-4183-8d09-396431407500",
                      "createdBy" : "05d04d91-0d9a-4183-8d09-396431407500",
                      "createdAt" : "2025-12-05T15:20:17.661120Z",
                      "updatedAt" : "2025-12-05T15:20:18.083279Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1069",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "2a874e05-eb13-4fe4-b088-1c5745e3bb88-p.fake.netfoundry.io",
                      "name" : "er-test-1068",
                      "productVersion" : "8.0.43",
                      "networkId" : "b6a5a80c-3d1a-48a9-94af-89032cee34a9",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "46c08964-8c5d-465d-a675-5b4de57987a7",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/2a874e05-eb13-4fe4-b088-1c5745e3bb88",
                          "title" : "er-test-1068"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/46c08964-8c5d-465d-a675-5b4de57987a7"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b6a5a80c-3d1a-48a9-94af-89032cee34a9",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/74ba4881-65c1-4dbf-8ded-5164ad1c4897"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/46c08964-8c5d-465d-a675-5b4de57987a7",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/host/resize:
    put:
      tags:
        - Edge Routers
      summary: Resize Edge Router host
      description: >
        Resize the underlying host instance for the specified Edge Router.

        Provide the desired deployment size identifier in the request body.

        The caller must have the update-heal permission on the specified Edge
        Router.
      operationId: resizeEdgeRouterHost_1
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to resize
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Resize host request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeHost'
            examples:
              small:
                description: Resize the host to a small deployment size
                value:
                  size: small
              medium:
                description: Resize the host to a medium deployment size
                value:
                  size: medium
        required: true
      responses:
        '202':
          description: Accepted. Edge Router host resize has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "ab2e408d-6971-46dd-a82b-d8d4242a6ddf",
                      "hostId" : "90b51d64-4850-415d-8d2e-5312ab8a620b",
                      "ownerIdentityId" : "a67e4b4b-dcc9-42cf-9f3b-40ac76320169",
                      "createdBy" : "a67e4b4b-dcc9-42cf-9f3b-40ac76320169",
                      "createdAt" : "2025-12-05T15:20:18.922210Z",
                      "updatedAt" : "2025-12-05T15:20:19.028037Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1096",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "ab2e408d-6971-46dd-a82b-d8d4242a6ddf-p.fake.netfoundry.io",
                      "name" : "er-test-1095",
                      "productVersion" : "8.0.43",
                      "networkId" : "14089cd9-32ec-420c-8738-47f7db9bd18d",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "a3a6a660-727c-46ea-b75a-862446d176c8",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/ab2e408d-6971-46dd-a82b-d8d4242a6ddf",
                          "title" : "er-test-1095"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a3a6a660-727c-46ea-b75a-862446d176c8"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/14089cd9-32ec-420c-8738-47f7db9bd18d",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/90b51d64-4850-415d-8d2e-5312ab8a620b"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a3a6a660-727c-46ea-b75a-862446d176c8",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Resize Edge Router host
      description: >
        Resize the underlying host instance for the specified Edge Router.

        Provide the desired deployment size identifier in the request body.

        The caller must have the update-heal permission on the specified Edge
        Router.
      operationId: resizeEdgeRouterHost
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to resize
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Resize host request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeHost'
            examples:
              small:
                description: Resize the host to a small deployment size
                value:
                  size: small
              medium:
                description: Resize the host to a medium deployment size
                value:
                  size: medium
        required: true
      responses:
        '202':
          description: Accepted. Edge Router host resize has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "ab2e408d-6971-46dd-a82b-d8d4242a6ddf",
                      "hostId" : "90b51d64-4850-415d-8d2e-5312ab8a620b",
                      "ownerIdentityId" : "a67e4b4b-dcc9-42cf-9f3b-40ac76320169",
                      "createdBy" : "a67e4b4b-dcc9-42cf-9f3b-40ac76320169",
                      "createdAt" : "2025-12-05T15:20:18.922210Z",
                      "updatedAt" : "2025-12-05T15:20:19.028037Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1096",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "ab2e408d-6971-46dd-a82b-d8d4242a6ddf-p.fake.netfoundry.io",
                      "name" : "er-test-1095",
                      "productVersion" : "8.0.43",
                      "networkId" : "14089cd9-32ec-420c-8738-47f7db9bd18d",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "UPDATING",
                      "softwareDeploymentStateId" : "a3a6a660-727c-46ea-b75a-862446d176c8",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/ab2e408d-6971-46dd-a82b-d8d4242a6ddf",
                          "title" : "er-test-1095"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a3a6a660-727c-46ea-b75a-862446d176c8"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/14089cd9-32ec-420c-8738-47f7db9bd18d",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/90b51d64-4850-415d-8d2e-5312ab8a620b"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a3a6a660-727c-46ea-b75a-862446d176c8",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}:
    get:
      tags:
        - Networks
      summary: Retrieve a Network
      description: |
        Retrieve a single Network resource by its ID.
        The caller must have the read permission on the specified Network.
      operationId: getNetwork
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: embed
          in: query
          description: >-
            Embed related resources in the result. Allowed: all | executions |
            network-controllers | hosts | network-jwt-sets | edge-routers.
          schema:
            type: array
            items:
              type: string
              enum:
                - all
                - executions
                - network-controllers
                - hosts
                - network-jwt-sets
                - edge-routers
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * zitiVersion: Return the Ziti version information
          schema:
            type: array
            items:
              type: string
              enum:
                - zitiVersion
      responses:
        '200':
          description: The requested Network resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get network response
                  value: |-
                    {
                      "id" : "238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a",
                      "ownerIdentityId" : "0ae9effc-22d8-45b6-b328-724f944c0c0e",
                      "createdBy" : "0ae9effc-22d8-45b6-b328-724f944c0c0e",
                      "createdAt" : "2025-12-05T15:19:14.824653Z",
                      "updatedAt" : "2025-12-05T15:19:14.826967Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-617",
                      "networkGroupId" : "1b29c5ab-1a40-4405-9a1e-c3fe27b7e7ed",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a",
                          "title" : "network-617"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/1b29c5ab-1a40-4405-9a1e-c3fe27b7e7ed",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Networks
      summary: Update a Network
      description: >
        Update mutable properties of a Network such as name, owner identity, HA
        setting, and additional network controllers.

        The caller must have the update permission on the specified Network.
      operationId: updateNetwork
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Fields to update on the Network. Omitted fields are left unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetwork'
            examples:
              default:
                description: default
                value: >-
                  {"name":"test12345","publicCertEnabled":null,"networkControllers":[],"edgeRouters":[],"edgeRouterPolicies":[],"serviceEdgeRouterPolicies":[],"servicePolicies":[],"services":[],"certificateAuthorities":[],"endpoints":[],"appWans":[],"postureChecks":[]}
        required: true
      responses:
        '202':
          description: Accepted. Network update has been scheduled/applied.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "6ba21b2d-a46e-4430-aaa9-592cef187f04",
                      "ownerIdentityId" : "46bf130c-f3af-4fdc-ab60-d6e2008fbb07",
                      "createdBy" : "46bf130c-f3af-4fdc-ab60-d6e2008fbb07",
                      "createdAt" : "2025-12-05T15:19:43.186794Z",
                      "updatedAt" : "2025-12-05T15:19:43.259689Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test12345",
                      "networkGroupId" : "8356ad13-1e16-41f1-bb91-5b9341abfa28",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/6ba21b2d-a46e-4430-aaa9-592cef187f04",
                          "title" : "test12345"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/8356ad13-1e16-41f1-bb91-5b9341abfa28",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Networks
      summary: Delete a Network
      description: >
        Delete a Network by ID if it is in an allowed state(PROVISIONED, ERROR,
        SUSPENDED, DELETED, OFFILINE).

        The caller must have the delete permission on the specified Network.
      operationId: deleteNetwork
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
      responses:
        '202':
          description: >-
            Deletion accepted. Returns the Network resource reflecting its
            updated state.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample delete network response
                  value: |-
                    {
                      "id" : "5e45791b-9d93-4910-996b-fd3239f7b0ce",
                      "ownerIdentityId" : "eda7bd03-a337-44e2-9585-682336a405c0",
                      "createdBy" : "eda7bd03-a337-44e2-9585-682336a405c0",
                      "createdAt" : "2025-12-05T15:19:13.628228Z",
                      "updatedAt" : "2025-12-05T15:19:13.699639Z",
                      "deletedBy" : "b2f42a21-6eb2-457d-b730-e8758dc8cfc8",
                      "deletedAt" : null,
                      "name" : "network-569",
                      "networkGroupId" : "793ee764-0ba0-4ea1-a369-e5f857e96986",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "DELETING",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/5e45791b-9d93-4910-996b-fd3239f7b0ce",
                          "title" : "network-569"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/793ee764-0ba0-4ea1-a369-e5f857e96986",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=5e45791b-9d93-4910-996b-fd3239f7b0ce"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Networks
      summary: Update a Network
      description: >
        Update mutable properties of a Network such as name, owner identity, HA
        setting, and additional network controllers.

        The caller must have the update permission on the specified Network.
      operationId: updateNetwork_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Fields to update on the Network. Omitted fields are left unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetwork'
            examples:
              default:
                description: default
                value: >-
                  {"name":"test12345","publicCertEnabled":null,"networkControllers":[],"edgeRouters":[],"edgeRouterPolicies":[],"serviceEdgeRouterPolicies":[],"servicePolicies":[],"services":[],"certificateAuthorities":[],"endpoints":[],"appWans":[],"postureChecks":[]}
        required: true
      responses:
        '202':
          description: Accepted. Network update has been scheduled/applied.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "6ba21b2d-a46e-4430-aaa9-592cef187f04",
                      "ownerIdentityId" : "46bf130c-f3af-4fdc-ab60-d6e2008fbb07",
                      "createdBy" : "46bf130c-f3af-4fdc-ab60-d6e2008fbb07",
                      "createdAt" : "2025-12-05T15:19:43.186794Z",
                      "updatedAt" : "2025-12-05T15:19:43.259689Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test12345",
                      "networkGroupId" : "8356ad13-1e16-41f1-bb91-5b9341abfa28",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/6ba21b2d-a46e-4430-aaa9-592cef187f04",
                          "title" : "test12345"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/8356ad13-1e16-41f1-bb91-5b9341abfa28",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=6ba21b2d-a46e-4430-aaa9-592cef187f04"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/replay:
    put:
      tags:
        - Networks
      summary: Replay the creation of a Network
      description: >
        Replay the creation of a Network. This is useful if the original
        creation process failed.

        If the original payload is no longer cached, the request will fail.
      operationId: replayCreateNetwork
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network creation has been re-submitted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "892a3e37-dfc0-4785-9172-169d292afd8f",
                      "ownerIdentityId" : "62c3b79f-4d6f-4e98-8754-074fcd807f46",
                      "createdBy" : "62c3b79f-4d6f-4e98-8754-074fcd807f46",
                      "createdAt" : "2025-12-05T15:19:19.380504Z",
                      "updatedAt" : "2025-12-05T15:19:19.407457Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test-network-722",
                      "networkGroupId" : "5b8b50cb-719e-42c0-b93e-3b78434b8cf9",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/892a3e37-dfc0-4785-9172-169d292afd8f",
                          "title" : "test-network-722"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/5b8b50cb-719e-42c0-b93e-3b78434b8cf9",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Networks
      summary: Replay the creation of a Network
      description: >
        Replay the creation of a Network. This is useful if the original
        creation process failed.

        If the original payload is no longer cached, the request will fail.
      operationId: replayCreateNetwork_1
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network creation has been re-submitted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "892a3e37-dfc0-4785-9172-169d292afd8f",
                      "ownerIdentityId" : "62c3b79f-4d6f-4e98-8754-074fcd807f46",
                      "createdBy" : "62c3b79f-4d6f-4e98-8754-074fcd807f46",
                      "createdAt" : "2025-12-05T15:19:19.380504Z",
                      "updatedAt" : "2025-12-05T15:19:19.407457Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test-network-722",
                      "networkGroupId" : "5b8b50cb-719e-42c0-b93e-3b78434b8cf9",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONING",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/892a3e37-dfc0-4785-9172-169d292afd8f",
                          "title" : "test-network-722"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/5b8b50cb-719e-42c0-b93e-3b78434b8cf9",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=892a3e37-dfc0-4785-9172-169d292afd8f"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/stored-secrets/{id}:
    get:
      tags:
        - Stored Secrets
      summary: Get a Stored Secret
      description: >
        Retrieve a single StoredSecret resource by its ID. The value of the
        secret is not returned by this endpoint.

        To retrieve the value, call the includeValue=true variant which requires
        additional authorization.

        The caller must have read permission on the StoredSecret.
      operationId: getStoredSecret
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested Stored Secret resource (value not included).
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret response
                  value: |-
                    {
                      "id" : "6e005edc-171b-4bee-b427-48324a40a03b",
                      "createdBy" : "815f7f5d-cf8b-4c4b-a567-f6ee1e4cb6d3",
                      "createdAt" : "2025-12-05T15:20:07.057665Z",
                      "updatedAt" : "2025-12-05T15:20:07.057665Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test-v2",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "0156165e-c9d9-4b9c-bbd2-4e613df2237d",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/6e005edc-171b-4bee-b427-48324a40a03b"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/0156165e-c9d9-4b9c-bbd2-4e613df2237d"
                        }
                      }
                    }
          links:
            self:
              operationId: getStoredSecret
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Stored Secrets
      summary: Update a Stored Secret
      description: >
        Update mutable properties of a Stored Secret such as its human-friendly
        name and/or the secret value.

        Omit fields to leave them unchanged. When the secret type is PRIVATE_KEY
        and a value is supplied, it must be a PEM-formatted private key.

        To update the value via a one-time token (OTT) without normal auth, use
        the text/plain OTT variant on the same path with the 'token' query
        parameter.

        The caller must have update permission on the StoredSecret.
      operationId: updateStoredSecret
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Stored Secret.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Fields to update on the Stored Secret. Omitted fields remain
          unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoredSecret'
            examples:
              rename-only:
                description: Change only the secret's name; value remains unchanged.
                value:
                  name: my-ssh-key-updated
              update-value-private-key:
                description: >-
                  Update only the value for a PRIVATE_KEY secret using a PEM
                  formatted key.
                value:
                  value: |-
                    -----BEGIN PRIVATE KEY-----
                    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                    -----END PRIVATE KEY-----
              rename-and-value:
                description: Change the name and update the value in a single request.
                value:
                  name: prod-ssh-key
                  value: s3cr3t-v4lu3
        required: true
      responses:
        '200':
          description: >-
            Returns the updated Stored Secret resource (value is never
            returned).
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret response
                  value: |-
                    {
                      "id" : "4fd7d146-0136-4d51-a146-37a958e0a708",
                      "createdBy" : "098e27a2-aa8d-4bd0-b92e-f314c3cedce8",
                      "createdAt" : "2025-12-05T15:20:06.719569Z",
                      "updatedAt" : "2025-12-05T15:20:06.737183Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "Test Name vZzplt3Kj75lE_B-1n17E",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "517a3bf6-0680-4e10-81be-cf52551df3bf",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/517a3bf6-0680-4e10-81be-cf52551df3bf",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/4fd7d146-0136-4d51-a146-37a958e0a708",
                          "title" : "Test Name vZzplt3Kj75lE_B-1n17E"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/cb79b0b3-9c5b-4adf-8c38-4fae63d16b25",
                          "title" : "Update StoredSecret",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Stored Secrets
      summary: Delete a Stored Secret
      description: >
        Delete a Stored Secret by ID. Deletion fails if the secret is referenced
        by any Host (e.g., as an SSH private key).

        The caller must have delete permission on the Stored Secret.
      operationId: deleteStoredSecret
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Stored Secret.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: >-
            Returns the deleted Stored Secret resource (value is never
            returned).
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret response
                  value: |-
                    {
                      "id" : "969bb79d-ae5d-481a-88f0-5e52056924d0",
                      "createdBy" : "8b34df73-d3fc-46f4-9f87-d9506b1b32ff",
                      "createdAt" : "2025-12-05T15:20:06.649493Z",
                      "updatedAt" : "2025-12-05T15:20:06.649493Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test-v2",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "de0bd342-ebb2-406e-bcf0-950dc2e890ab",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/de0bd342-ebb2-406e-bcf0-950dc2e890ab",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/969bb79d-ae5d-481a-88f0-5e52056924d0",
                          "title" : "test-v2"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/b64e81ef-879e-426d-aa8f-283aa88ebdb1",
                          "title" : "Delete StoredSecret",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Stored Secrets
      summary: Update a Stored Secret
      description: >
        Update mutable properties of a Stored Secret such as its human-friendly
        name and/or the secret value.

        Omit fields to leave them unchanged. When the secret type is PRIVATE_KEY
        and a value is supplied, it must be a PEM-formatted private key.

        To update the value via a one-time token (OTT) without normal auth, use
        the text/plain OTT variant on the same path with the 'token' query
        parameter.

        The caller must have update permission on the StoredSecret.
      operationId: updateStoredSecret_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Stored Secret.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Fields to update on the Stored Secret. Omitted fields remain
          unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStoredSecret'
            examples:
              rename-only:
                description: Change only the secret's name; value remains unchanged.
                value:
                  name: my-ssh-key-updated
              update-value-private-key:
                description: >-
                  Update only the value for a PRIVATE_KEY secret using a PEM
                  formatted key.
                value:
                  value: |-
                    -----BEGIN PRIVATE KEY-----
                    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                    -----END PRIVATE KEY-----
              rename-and-value:
                description: Change the name and update the value in a single request.
                value:
                  name: prod-ssh-key
                  value: s3cr3t-v4lu3
        required: true
      responses:
        '200':
          description: >-
            Returns the updated Stored Secret resource (value is never
            returned).
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret response
                  value: |-
                    {
                      "id" : "4fd7d146-0136-4d51-a146-37a958e0a708",
                      "createdBy" : "098e27a2-aa8d-4bd0-b92e-f314c3cedce8",
                      "createdAt" : "2025-12-05T15:20:06.719569Z",
                      "updatedAt" : "2025-12-05T15:20:06.737183Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "Test Name vZzplt3Kj75lE_B-1n17E",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "517a3bf6-0680-4e10-81be-cf52551df3bf",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/517a3bf6-0680-4e10-81be-cf52551df3bf",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/4fd7d146-0136-4d51-a146-37a958e0a708",
                          "title" : "Test Name vZzplt3Kj75lE_B-1n17E"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/cb79b0b3-9c5b-4adf-8c38-4fae63d16b25",
                          "title" : "Update StoredSecret",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/software-deployment-states/{id}:
    get:
      tags:
        - Software Deployment States
      summary: Get Software Deployment State
      description: >
        Returns a single SoftwareDeploymentState by its unique identifier.

        The caller must have read permissions on the SoftwareDeploymentState
        resource.
      operationId: getSoftwareDeploymentState
      parameters:
        - name: id
          in: path
          description: The unique identifier of the SoftwareDeploymentState.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: SoftwareDeploymentState retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get SoftwareDeploymentState response
                  value: |-
                    {
                      "id" : "2366279d-8745-41bf-b1ad-eb48b756fddc",
                      "networkId" : "f065c214-ff0c-4c1a-947d-373cf94ef5f3",
                      "resourceId" : "7624dcae-8d19-4ec7-8103-4c44243aadd2",
                      "resourceType" : "NETWORK_CONTROLLER",
                      "enabled" : false,
                      "online" : false,
                      "lastOnlineAt" : null,
                      "softwareConfigurationPortEnabled" : true,
                      "lastCheckedAt" : "2025-11-17T16:25:56.128330Z",
                      "nextCheckAt" : "2025-11-17T17:35:56.128340Z",
                      "createdBy" : "dbb3e5d7-7cc4-444c-a5e0-4f101316a174",
                      "createdAt" : "2025-11-17T16:35:56.133808Z",
                      "updatedAt" : "2025-11-17T16:35:56.133808Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/f065c214-ff0c-4c1a-947d-373cf94ef5f3",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/2366279d-8745-41bf-b1ad-eb48b756fddc"
                        },
                        "network-controller" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/7624dcae-8d19-4ec7-8103-4c44243aadd2",
                          "title" : "parent"
                        }
                      }
                    }
          links:
            network-controller:
              operationId: getNetworkController
              parameters:
                id: $response.body#/resourceId
            edge-router:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/resourceId
            self:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Software Deployment States
      summary: Update Software Deployment State
      description: >
        Updates mutable fields of a SoftwareDeploymentState. Currently supports
        toggling software configuration management flags.

        The caller must have update-software-configuration-port permission on
        the SoftwareDeploymentState resource.
      operationId: patchSoftwareDeploymentState
      parameters:
        - name: id
          in: path
          description: The unique identifier of the SoftwareDeploymentState.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: SoftwareDeploymentState update payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSoftwareDeploymentState'
            examples:
              enable-config-port:
                description: enable-config-port
                value:
                  softwareConfigurationPortEnabled: true
        required: true
      responses:
        '202':
          description: >-
            Update accepted; returns the updated SoftwareDeploymentState with
            standard HAL links.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample patch SoftwareDeploymentState response
                  value: |-
                    {
                      "id" : "304eb566-41f9-4425-ab43-933190ac3812",
                      "networkId" : "bfbf82ff-2a93-4a4c-a989-7a0b8e6908b8",
                      "resourceId" : "bb7420e5-b6fc-4c1a-9909-5190c14699cc",
                      "resourceType" : "NETWORK_CONTROLLER",
                      "enabled" : true,
                      "online" : true,
                      "lastOnlineAt" : "2025-12-05T15:12:35.971797Z",
                      "softwareConfigurationPortEnabled" : true,
                      "lastCheckedAt" : "2025-12-05T15:12:35.971797Z",
                      "nextCheckAt" : "2025-12-05T16:22:35.971805Z",
                      "createdBy" : "c40c82a8-75d3-4b38-80f5-9b400fe5ecc9",
                      "createdAt" : "2025-12-05T15:22:35.971541Z",
                      "updatedAt" : "2025-12-05T15:22:35.971541Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/bfbf82ff-2a93-4a4c-a989-7a0b8e6908b8",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/304eb566-41f9-4425-ab43-933190ac3812"
                        },
                        "network-controller" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/bb7420e5-b6fc-4c1a-9909-5190c14699cc",
                          "title" : "parent"
                        }
                      }
                    }
          links:
            network-controller:
              operationId: getNetworkController
              parameters:
                id: $response.body#/resourceId
            edge-router:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/resourceId
            self:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Software Deployment States
      summary: Update Software Deployment State
      description: >
        Updates mutable fields of a SoftwareDeploymentState. Currently supports
        toggling software configuration management flags.

        The caller must have update-software-configuration-port permission on
        the SoftwareDeploymentState resource.
      operationId: patchSoftwareDeploymentState_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the SoftwareDeploymentState.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: SoftwareDeploymentState update payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSoftwareDeploymentState'
            examples:
              enable-config-port:
                description: enable-config-port
                value:
                  softwareConfigurationPortEnabled: true
        required: true
      responses:
        '202':
          description: >-
            Update accepted; returns the updated SoftwareDeploymentState with
            standard HAL links.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample patch SoftwareDeploymentState response
                  value: |-
                    {
                      "id" : "304eb566-41f9-4425-ab43-933190ac3812",
                      "networkId" : "bfbf82ff-2a93-4a4c-a989-7a0b8e6908b8",
                      "resourceId" : "bb7420e5-b6fc-4c1a-9909-5190c14699cc",
                      "resourceType" : "NETWORK_CONTROLLER",
                      "enabled" : true,
                      "online" : true,
                      "lastOnlineAt" : "2025-12-05T15:12:35.971797Z",
                      "softwareConfigurationPortEnabled" : true,
                      "lastCheckedAt" : "2025-12-05T15:12:35.971797Z",
                      "nextCheckAt" : "2025-12-05T16:22:35.971805Z",
                      "createdBy" : "c40c82a8-75d3-4b38-80f5-9b400fe5ecc9",
                      "createdAt" : "2025-12-05T15:22:35.971541Z",
                      "updatedAt" : "2025-12-05T15:22:35.971541Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/bfbf82ff-2a93-4a4c-a989-7a0b8e6908b8",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/304eb566-41f9-4425-ab43-933190ac3812"
                        },
                        "network-controller" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/bb7420e5-b6fc-4c1a-9909-5190c14699cc",
                          "title" : "parent"
                        }
                      }
                    }
          links:
            network-controller:
              operationId: getNetworkController
              parameters:
                id: $response.body#/resourceId
            edge-router:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/resourceId
            self:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-groups/{id}:
    get:
      tags:
        - Network Groups
      summary: Get a Network Group by ID
      description: |
        Returns a single Network Group by its unique identifier.
        The caller must have read permission on the NetworkGroup resource.
      operationId: getNetworkGroup
      parameters:
        - name: id
          in: path
          description: The unique identifier of the NetworkGroup.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: embed
          in: query
          description: >-
            Embed related resources in the result. Allowed: all | networks |
            dns-zones.
          schema:
            type: array
            items:
              type: string
              enum:
                - all
                - networks
                - dns-zones
      responses:
        '200':
          description: Network Group retrieved
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get network group response
                  value: |-
                    {
                      "id" : "deeb86cd-4321-4cb3-a047-cda66dcc9aa0",
                      "name" : "Test-NG",
                      "shortName" : "nw-7741",
                      "billingAccountId" : "6fbabe55-82c4-4670-b19e-1c256e491a22",
                      "ownerIdentityId" : "69f5a9e3-0cab-48cd-9cb5-6a79ba75717f",
                      "createdBy" : "9d274476-2abf-4644-80b1-484841034446",
                      "createdAt" : "2025-11-17T16:26:00.134545Z",
                      "updatedAt" : "2025-11-17T16:26:00.134545Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/deeb86cd-4321-4cb3-a047-cda66dcc9aa0",
                          "title" : "Test-NG"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=deeb86cd-4321-4cb3-a047-cda66dcc9aa0"
                        },
                        "dns-zones" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=deeb86cd-4321-4cb3-a047-cda66dcc9aa0"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Network Groups
      summary: Update a Network Group
      description: >
        Updates mutable fields of a Network Group. Only provided fields will be
        changed.

        The caller must have update permission on the NetworkGroup resource.
      operationId: updateNetworkGroup
      parameters:
        - name: id
          in: path
          description: The unique identifier of the NetworkGroup.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Group update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkGroup'
            examples:
              rename:
                description: rename
                value:
                  name: eng-platform
        required: true
      responses:
        '200':
          description: Network Group updated
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample update network group response
                  value: |-
                    {
                      "id" : "cc99d3d0-8254-4749-af29-58086fe5623e",
                      "name" : "Updated NG Name-767",
                      "shortName" : "nw-7691",
                      "billingAccountId" : "39e0a8de-bf1c-4ec7-b0ab-bb32759ffdf8",
                      "ownerIdentityId" : "50ddbd4b-4d84-48c1-8c7d-740184987c81",
                      "createdBy" : "55e0291e-cc12-4458-a9ee-6d3e9ba49f79",
                      "createdAt" : "2025-11-17T16:25:59.929869Z",
                      "updatedAt" : "2025-11-17T16:25:59.948231Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/cc99d3d0-8254-4749-af29-58086fe5623e",
                          "title" : "Updated NG Name-767"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/776e1758-10c7-41cc-a280-dd2472e07a85",
                          "title" : "Update NetworkGroup",
                          "profile" : "meta"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                        },
                        "dns-zones" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            self:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Network Groups
      summary: Delete a Network Group
      description: >
        Deletes a Network Group and returns the deleted resource with execution
        metadata if available.

        The caller must have delete permission on the NetworkGroup resource.
      operationId: deleteNetworkGroup
      parameters:
        - name: id
          in: path
          description: The unique identifier of the NetworkGroup.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: Network Group deleted
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample delete network group response
                  value: |-
                    {
                      "id" : "a89ad72d-af65-41cb-a2ec-cca9e747ddac",
                      "name" : "Test-NG",
                      "shortName" : "nw-7661",
                      "billingAccountId" : "188111b9-9407-4286-ac6f-286c1491b65e",
                      "ownerIdentityId" : "47705e07-9adf-4069-bddf-24cc1e50e6ef",
                      "createdBy" : "4846c4fa-924f-4a96-bb98-43e6b6358112",
                      "createdAt" : "2025-11-17T16:25:59.878599Z",
                      "updatedAt" : "2025-11-17T16:25:59.889243Z",
                      "deletedBy" : "5bb7d738-2f86-4118-82aa-9d4ea20f6e64",
                      "deletedAt" : "2025-11-17T16:25:59.889Z",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/a89ad72d-af65-41cb-a2ec-cca9e747ddac",
                          "title" : "Test-NG"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/da6cc486-ac67-4a93-a6e4-36b59f29398a",
                          "title" : "Delete NetworkGroup",
                          "profile" : "meta"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=a89ad72d-af65-41cb-a2ec-cca9e747ddac"
                        },
                        "dns-zones" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=a89ad72d-af65-41cb-a2ec-cca9e747ddac"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            self:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Network Groups
      summary: Update a Network Group
      description: >
        Updates mutable fields of a Network Group. Only provided fields will be
        changed.

        The caller must have update permission on the NetworkGroup resource.
      operationId: updateNetworkGroup_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the NetworkGroup.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Group update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkGroup'
            examples:
              rename:
                description: rename
                value:
                  name: eng-platform
        required: true
      responses:
        '200':
          description: Network Group updated
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample update network group response
                  value: |-
                    {
                      "id" : "cc99d3d0-8254-4749-af29-58086fe5623e",
                      "name" : "Updated NG Name-767",
                      "shortName" : "nw-7691",
                      "billingAccountId" : "39e0a8de-bf1c-4ec7-b0ab-bb32759ffdf8",
                      "ownerIdentityId" : "50ddbd4b-4d84-48c1-8c7d-740184987c81",
                      "createdBy" : "55e0291e-cc12-4458-a9ee-6d3e9ba49f79",
                      "createdAt" : "2025-11-17T16:25:59.929869Z",
                      "updatedAt" : "2025-11-17T16:25:59.948231Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/cc99d3d0-8254-4749-af29-58086fe5623e",
                          "title" : "Updated NG Name-767"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/776e1758-10c7-41cc-a280-dd2472e07a85",
                          "title" : "Update NetworkGroup",
                          "profile" : "meta"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                        },
                        "dns-zones" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            self:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/replay:
    put:
      tags:
        - Network Controllers
      summary: Replay the creation of a Network Controller
      description: >
        Replay the creation of a Network Controller. This is useful if the
        original creation process failed.

        If the original payload is no longer cached, the request will fail.
      operationId: replayCreateNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network Controller creation has been re-submitted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "275e5594-a52c-4ee8-a8a9-7ab7d511158a",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "275e5594-a52c-4ee8-a8a9-7ab7d511158a.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "secondary-controller-1",
                      "productVersion" : "7.4.5",
                      "hostId" : "9c6f133c-c96b-486e-908e-67229a7e9d77",
                      "status" : "PROVISIONING",
                      "createdAt" : "2025-11-17T16:28:21.466970Z",
                      "updatedAt" : "2025-11-17T16:28:21.508796Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : null,
                      "haPrimaryNode" : false,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/9c6f133c-c96b-486e-908e-67229a7e9d77"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/275e5594-a52c-4ee8-a8a9-7ab7d511158a",
                          "title" : "secondary-controller-1"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Network Controllers
      summary: Replay the creation of a Network Controller
      description: >
        Replay the creation of a Network Controller. This is useful if the
        original creation process failed.

        If the original payload is no longer cached, the request will fail.
      operationId: replayCreateNetworkController_1
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Accepted. Network Controller creation has been re-submitted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "275e5594-a52c-4ee8-a8a9-7ab7d511158a",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "275e5594-a52c-4ee8-a8a9-7ab7d511158a.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "secondary-controller-1",
                      "productVersion" : "7.4.5",
                      "hostId" : "9c6f133c-c96b-486e-908e-67229a7e9d77",
                      "status" : "PROVISIONING",
                      "createdAt" : "2025-11-17T16:28:21.466970Z",
                      "updatedAt" : "2025-11-17T16:28:21.508796Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : null,
                      "haPrimaryNode" : false,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/9c6f133c-c96b-486e-908e-67229a7e9d77"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/275e5594-a52c-4ee8-a8a9-7ab7d511158a",
                          "title" : "secondary-controller-1"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}:
    get:
      tags:
        - Network Controllers
      summary: Retrieve a Network Controller
      description: Retrieve a single Network Controller by its ID.
      operationId: getNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: embed
          in: query
          description: >-
            Embed related resources in the result. Allowed: all | host |
            software-deployment-state.
          schema:
            type: array
            items:
              type: string
              enum:
                - all
                - host
                - software-deployment-state
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * zitiVersion: Return the Ziti version information
               * zitiManagementIdentity: Returns the hybrid Ziti Management identity details (hybrid Network Controller only)
               * inspect(inspection): Invoke the Ziti inspect operation with the specified inspection parameter see below (not all applicable to all configurations):
                   * metrics
                   * config
                   * cluster-config
                   * connected-routers
                   * connected-peers
                   * links
                   * sdk-terminators
      responses:
        '200':
          description: The requested Network Controller.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Retrieve a Network Controller by ID
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "PROVISIONED",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:21.692088Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6306a463-1c49-4134-9257-6b80993cd50c",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Network Controllers
      summary: Update a Network Controller
      description: >
        Update a Network Controller.

        The caller must have the update permission on the specified Network
        Controller.
      operationId: updateNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Controller update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkController'
            examples:
              default:
                description: default
                value: '{"name":"updatedControllerName-2177"}'
        required: true
      responses:
        '202':
          description: Accepted. Network Controller update has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "PROVISIONED",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:21.692088Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6306a463-1c49-4134-9257-6b80993cd50c",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Network Controllers
      summary: Delete a Network Controller
      description: >
        Delete a Network Controller by its ID.

        You cannot delete the primary network controller for a network.

        The caller must have the delete permission on the specified Network
        Controller.
      operationId: deleteNetworkController
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
          example: bdf1b7c1-5a33-4b2c-9b3d-9c7d3f8a4e21
      responses:
        '202':
          description: Accepted. Network Controller deletion has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "29eb83d9-6ed2-4eb3-b1c7-c67f9f0538c3",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "29eb83d9-6ed2-4eb3-b1c7-c67f9f0538c3.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-controller2-test-nc",
                      "productVersion" : "7.3.37",
                      "hostId" : "7c06dd21-9a76-4d67-9f23-9e64ff4f131b",
                      "status" : "DELETING",
                      "createdAt" : "2025-11-17T16:28:23.220419Z",
                      "updatedAt" : "2025-11-17T16:28:23.241288Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : null,
                      "haPrimaryNode" : false,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/7c06dd21-9a76-4d67-9f23-9e64ff4f131b"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/29eb83d9-6ed2-4eb3-b1c7-c67f9f0538c3",
                          "title" : "networkcontroller-controller2-test-nc"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Network Controllers
      summary: Update a Network Controller
      description: >
        Update a Network Controller.

        The caller must have the update permission on the specified Network
        Controller.
      operationId: updateNetworkController_1
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Controller update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkController'
            examples:
              default:
                description: default
                value: '{"name":"updatedControllerName-2177"}'
        required: true
      responses:
        '202':
          description: Accepted. Network Controller update has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "PROVISIONED",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:21.692088Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6306a463-1c49-4134-9257-6b80993cd50c",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/dns-zones/{id}:
    get:
      tags:
        - Dns Zones
      summary: Get DnsZone
      description: |
        Returns a single DnsZone by its unique identifier.
        The caller must have read permission on the DnsZone resource.
      operationId: getDnsZone
      parameters:
        - name: id
          in: path
          description: The unique identifier of the DnsZone.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: DnsZone retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get DnsZone response
                  value: |-
                    {
                      "id" : "7b63d2c4-2f7c-462d-bf71-f8bd4752455a",
                      "networkGroupId" : "2dd67abf-abdf-46ea-a0c5-5aeef81f5447",
                      "name" : "test-v3-domain.com",
                      "route53ZoneId" : "zoneId-1911",
                      "domain" : "domain.io.",
                      "validated" : false,
                      "createdBy" : "47ad074f-2f7d-4066-bd94-f320e86bdda2",
                      "createdAt" : "2025-12-05T15:21:16.828933Z",
                      "updatedAt" : "2025-12-05T15:21:16.828933Z",
                      "deletedAt" : null,
                      "deletedBy" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/7b63d2c4-2f7c-462d-bf71-f8bd4752455a",
                          "title" : "test-v3-domain.com"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/2dd67abf-abdf-46ea-a0c5-5aeef81f5447",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            networkGroup:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/networkGroupId
            self:
              operationId: getDnsZone
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Dns Zones
      summary: Update DnsZone
      description: >
        Updates mutable fields of a DnsZone. Currently only the name is
        supported.

        The caller must have update permission on the DnsZone resource.
      operationId: updateDnsZone
      parameters:
        - name: id
          in: path
          description: The unique identifier of the DnsZone.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: DnsZone update payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDnsZone'
            examples:
              rename:
                description: rename
                value:
                  name: corp-zone-renamed
        required: true
      responses:
        '200':
          description: DnsZone updated.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample update DnsZone response
                  value: |-
                    {
                      "id" : "98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                      "networkGroupId" : "892632d0-0be5-49e9-86d2-19a45dfad558",
                      "name" : "updated-1921",
                      "route53ZoneId" : "zoneId-1920",
                      "domain" : "domain.io.",
                      "validated" : false,
                      "createdBy" : "e059f248-8100-451a-b497-50ecb25fcd11",
                      "createdAt" : "2025-12-05T15:21:16.944558Z",
                      "updatedAt" : "2025-12-05T15:21:16.960957Z",
                      "deletedAt" : null,
                      "deletedBy" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                          "title" : "updated-1921"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/892632d0-0be5-49e9-86d2-19a45dfad558",
                          "profile" : "parent"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/4fc9f009-f3e9-45bc-85c1-ae209abd2986",
                          "title" : "Update DnsZone",
                          "profile" : "meta"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            networkGroup:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/networkGroupId
            self:
              operationId: getDnsZone
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Dns Zones
      summary: Delete DnsZone
      description: >-
        Deletes a DnsZone by ID after ensuring it is not referenced by any
        Network. Requires delete permission on the DnsZone resource.
      operationId: deleteDnsZone
      parameters:
        - name: id
          in: path
          description: The unique identifier of the DnsZone to delete.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: DnsZone deleted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample delete DnsZone response
                  value: |-
                    {
                      "id" : "2005d176-eb73-4531-936e-953078e61f3e",
                      "networkGroupId" : "304e6164-8186-40d4-90fc-bb191161f2de",
                      "name" : "toDelete",
                      "route53ZoneId" : "zoneId-1947",
                      "domain" : "domain.io.",
                      "validated" : false,
                      "createdBy" : "ebda3917-48c8-43ef-91e6-9991a8107b67",
                      "createdAt" : "2025-12-05T15:21:17.378379Z",
                      "updatedAt" : "2025-12-05T15:21:17.404725Z",
                      "deletedAt" : "2025-12-05T15:21:17.405Z",
                      "deletedBy" : "e9443adf-45cd-4444-8cc1-2d44fd0095d6",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/2005d176-eb73-4531-936e-953078e61f3e",
                          "title" : "toDelete"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/304e6164-8186-40d4-90fc-bb191161f2de",
                          "profile" : "parent"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/c9a24cd2-f21f-4e13-9f41-f776f5090acd",
                          "title" : "Delete DnsZone",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            networkGroup:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/networkGroupId
            self:
              operationId: getDnsZone
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Dns Zones
      summary: Update DnsZone
      description: >
        Updates mutable fields of a DnsZone. Currently only the name is
        supported.

        The caller must have update permission on the DnsZone resource.
      operationId: updateDnsZone_1
      parameters:
        - name: id
          in: path
          description: The unique identifier of the DnsZone.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: DnsZone update payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDnsZone'
            examples:
              rename:
                description: rename
                value:
                  name: corp-zone-renamed
        required: true
      responses:
        '200':
          description: DnsZone updated.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample update DnsZone response
                  value: |-
                    {
                      "id" : "98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                      "networkGroupId" : "892632d0-0be5-49e9-86d2-19a45dfad558",
                      "name" : "updated-1921",
                      "route53ZoneId" : "zoneId-1920",
                      "domain" : "domain.io.",
                      "validated" : false,
                      "createdBy" : "e059f248-8100-451a-b497-50ecb25fcd11",
                      "createdAt" : "2025-12-05T15:21:16.944558Z",
                      "updatedAt" : "2025-12-05T15:21:16.960957Z",
                      "deletedAt" : null,
                      "deletedBy" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                          "title" : "updated-1921"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/892632d0-0be5-49e9-86d2-19a45dfad558",
                          "profile" : "parent"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/4fc9f009-f3e9-45bc-85c1-ae209abd2986",
                          "title" : "Update DnsZone",
                          "profile" : "meta"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            networkGroup:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/networkGroupId
            self:
              operationId: getDnsZone
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/clusters/{id}:
    get:
      tags:
        - Clusters
      summary: Retrieve a single Cluster
      description: >
        Retrieve a single Cluster resource by its ID. The platform creates the
        Cluster resource automatically when the network is enabled for HA.

        The network version must support cluster operations and the caller must
        have read permissions on the Cluster resource.
      operationId: getCluster
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested Cluster.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Cluster'
              examples:
                default:
                  description: Retrieve a cluster by ID
                  value: |-
                    {
                      "id" : "f7a48c07-0d1d-4433-b52a-a24db68ea2d4",
                      "networkId" : "4df7faa8-b2fc-4cda-b72d-c3d99c7b6d44",
                      "leaderId" : "1d4761f1-26d6-4f11-bb6e-ff13adab3ddd",
                      "createdAt" : "2025-11-17T16:30:43.929097Z",
                      "updatedAt" : "2025-11-17T16:30:43.929097Z",
                      "deletedAt" : null,
                      "readOnly" : false,
                      "partitioned" : false,
                      "leaderMemberInfos" : [ {
                        "id" : "1d4761f1-26d6-4f11-bb6e-ff13adab3ddd",
                        "address" : "1d4761f1-26d6-4f11-bb6e-ff13adab3ddd",
                        "voter" : true,
                        "leader" : true,
                        "version" : null,
                        "connected" : true,
                        "readOnly" : false
                      } ],
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/4df7faa8-b2fc-4cda-b72d-c3d99c7b6d44",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/clusters/f7a48c07-0d1d-4433-b52a-a24db68ea2d4"
                        },
                        "leader" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1d4761f1-26d6-4f11-bb6e-ff13adab3ddd"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Cluster belongs.
            leader:
              operationId: getNetworkController
              parameters:
                id: $response.body.leaderId
              description: The Network Controller that leads this Cluster.
            self:
              operationId: getCluster
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Clusters
      summary: Set the leader of a Cluster
      description: >
        Set the leader of a cluster to the specified network controller. The
        network controller must be a member of the network.

        The caller must have update permissions on the Cluster resource.
      operationId: setClusterLeader
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: The details of the update, including the ID of the new leader.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCluster'
            examples:
              patch/put:
                description: Sample update cluster request
                value: '{"leaderId":"3aa2d402-7e9e-454e-b496-d218911d3065"}'
        required: true
      responses:
        '200':
          description: The updated Cluster.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Cluster'
              examples: {}
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Cluster belongs.
            leader:
              operationId: getNetworkController
              parameters:
                id: $response.body.leaderId
              description: The Network Controller that leads this Cluster.
            self:
              operationId: getCluster
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Clusters
      summary: Set the leader of a Cluster
      description: >
        Set the leader of a cluster to the specified network controller. The
        network controller must be a member of the network.

        The caller must have update permissions on the Cluster resource.
      operationId: setClusterLeader_1
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: The details of the update, including the ID of the new leader.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCluster'
            examples:
              patch/put:
                description: Sample update cluster request
                value: '{"leaderId":"3aa2d402-7e9e-454e-b496-d218911d3065"}'
        required: true
      responses:
        '200':
          description: The updated Cluster.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Cluster'
              examples: {}
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Cluster belongs.
            leader:
              operationId: getNetworkController
              parameters:
                id: $response.body.leaderId
              description: The Network Controller that leads this Cluster.
            self:
              operationId: getCluster
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/stored-secrets/{idUsingOtt}:
    put:
      tags:
        - Stored Secrets
      summary: Update a Stored Secret value using a one-time token (OTT)
      description: >
        Update the value of a Stored Secret using a one-time token (OTT) without
        normal authentication.

        Provide the token as a query parameter and the new value as a text/plain
        request body.

        When the secret type is PRIVATE_KEY, the body must contain a PEM
        formatted private key.

        This operation returns 200 OK with no response body.
      operationId: updateStoredSecretUsingOtt_1
      parameters:
        - name: idUsingOtt
          in: path
          description: The unique identifier of the Stored Secret to update.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: token
          in: query
          description: The one-time token (OTT) that authorizes this update.
          example: abc123de
      requestBody:
        description: >-
          The new secret value to store, sent as text/plain. For PRIVATE_KEY
          secrets, must be a PEM formatted key.
        content:
          text/plain:
            schema:
              type: string
            examples:
              opaque:
                description: Update an opaque/GENERIC secret value
                value: s3cr3t-v4lu3
              private-key:
                description: Update a PRIVATE_KEY secret with PEM formatted private key
                value: |-
                  -----BEGIN PRIVATE KEY-----
                  MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                  -----END PRIVATE KEY-----
        required: true
      responses:
        '200':
          description: OK. Secret value updated. No response body is returned.
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $request.path.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Stored Secrets
      summary: Update a Stored Secret value using a one-time token (OTT)
      description: >
        Update the value of a Stored Secret using a one-time token (OTT) without
        normal authentication.

        Provide the token as a query parameter and the new value as a text/plain
        request body.

        When the secret type is PRIVATE_KEY, the body must contain a PEM
        formatted private key.

        This operation returns 200 OK with no response body.
      operationId: updateStoredSecretUsingOtt
      parameters:
        - name: idUsingOtt
          in: path
          description: The unique identifier of the Stored Secret to update.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: token
          in: query
          description: The one-time token (OTT) that authorizes this update.
          example: abc123de
      requestBody:
        description: >-
          The new secret value to store, sent as text/plain. For PRIVATE_KEY
          secrets, must be a PEM formatted key.
        content:
          text/plain:
            schema:
              type: string
            examples:
              opaque:
                description: Update an opaque/GENERIC secret value
                value: s3cr3t-v4lu3
              private-key:
                description: Update a PRIVATE_KEY secret with PEM formatted private key
                value: |-
                  -----BEGIN PRIVATE KEY-----
                  MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                  -----END PRIVATE KEY-----
        required: true
      responses:
        '200':
          description: OK. Secret value updated. No response body is returned.
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $request.path.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Stored Secrets
      summary: Update a Stored Secret value using a one-time token (OTT)
      description: >
        Update the value of a Stored Secret using a one-time token (OTT) without
        normal authentication.

        Provide the token as a query parameter and the new value as a text/plain
        request body.

        When the secret type is PRIVATE_KEY, the body must contain a PEM
        formatted private key.

        This operation returns 200 OK with no response body.
      operationId: updateStoredSecretUsingOtt_2
      parameters:
        - name: idUsingOtt
          in: path
          description: The unique identifier of the Stored Secret to update.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: token
          in: query
          description: The one-time token (OTT) that authorizes this update.
          example: abc123de
      requestBody:
        description: >-
          The new secret value to store, sent as text/plain. For PRIVATE_KEY
          secrets, must be a PEM formatted key.
        content:
          text/plain:
            schema:
              type: string
            examples:
              opaque:
                description: Update an opaque/GENERIC secret value
                value: s3cr3t-v4lu3
              private-key:
                description: Update a PRIVATE_KEY secret with PEM formatted private key
                value: |-
                  -----BEGIN PRIVATE KEY-----
                  MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                  -----END PRIVATE KEY-----
        required: true
      responses:
        '200':
          description: OK. Secret value updated. No response body is returned.
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $request.path.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-assemblies/{id}:
    get:
      tags:
        - Network Assemblies
      summary: Export a Network Assembly
      description: >
        Export a composite of the specified network including Ziti controller
        data and hosting information.

        Optionally filter which entities to include via the 'entities' query
        parameter.
      operationId: getNetworkAssembly
      parameters:
        - name: id
          in: path
          description: The Network ID (UUID). The network must exist and be PROVISIONED.
          required: true
          schema:
            type: string
            format: uuid
          example: 8d4a9f4d-9f64-4f24-9a6a-6a7a2bc4b6c1
        - name: entities
          in: query
          description: >-
            Filter the entities to include. Allowed: all | network-controller |
            ca/certificate-authority | identity | edge-router | service | config
            | config-type | service-policy | edge-router-policy |
            service-edge-router-policy | external-jwt-signer | auth-policy |
            posture-check.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - all
                - network-controller
                - ca
                - certificate-authority
                - identity
                - edge-router
                - service
                - config
                - config-type
                - service-policy
                - edge-router-policy
                - service-edge-router-policy
                - external-jwt-signer
                - auth-policy
                - posture-check
          examples:
            all:
              description: all
              value: all
            subset:
              description: subset
              value: identity,service,edge-router
      responses:
        '200':
          description: The exported Network Assembly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkAssembly'
              examples:
                default:
                  description: Example Get Network Assembly response
                  value: |-
                    {
                      "name" : "export-test-0",
                      "version" : "8.1.4",
                      "zitiVersion" : null,
                      "identities" : [ {
                        "authPolicy" : "@NetFoundry Console Integration Auth Policy",
                        "disabled" : false,
                        "edgeRouterConnectionStatus" : "offline",
                        "externalId" : "5f854c49-b5fd-44a1-b14f-a9c4aa5a7eba",
                        "isAdmin" : true,
                        "isDefaultAdmin" : false,
                        "isMfaEnabled" : false,
                        "name" : "NF User Identity(managed from 5f854c49-b5fd-44a1-b14f-a9c4aa5a7eba)",
                        "roleAttributes" : [ ],
                        "tags" : {
                          "nf-identity-id" : "5f854c49-b5fd-44a1-b14f-a9c4aa5a7eba"
                        },
                        "typeId" : "Default"
                      }, {
                        "authPolicy" : "@NetFoundry Console Integration Auth Policy",
                        "disabled" : false,
                        "edgeRouterConnectionStatus" : "offline",
                        "externalId" : "0ed768fa-7214-4404-8335-c715156dff45",
                        "isAdmin" : true,
                        "isDefaultAdmin" : false,
                        "isMfaEnabled" : false,
                        "name" : "MOP Ziti Metrics Processor Service(managed from ced768fa-7214-4404-8335-a715156dff45)",
                        "roleAttributes" : [ ],
                        "tags" : {
                          "nf-identity-id" : "0ed768fa-7214-4404-8335-a715156dff45"
                        },
                        "typeId" : "Default"
                      } ],
                      "edgeRouters" : [ {
                        "appData" : { },
                        "disabled" : false,
                        "hostname" : "281f0ea3-33c2-4354-8c01-e1c0835bba4f-p.sandbox.netfoundry.io",
                        "isTunnelerEnabled" : false,
                        "name" : "test-2",
                        "noTraversal" : false,
                        "roleAttributes" : [ ],
                        "tags" : { },
                        "unverifiedCertPem" : null,
                        "unverifiedFingerprint" : null
                      }, {
                        "appData" : { },
                        "disabled" : false,
                        "hostname" : "cf7149f6-d634-4402-9cbc-a132280bae84-p.sandbox.netfoundry.io",
                        "isTunnelerEnabled" : false,
                        "name" : "test-1",
                        "noTraversal" : false,
                        "roleAttributes" : [ ],
                        "tags" : { },
                        "unverifiedCertPem" : null,
                        "unverifiedFingerprint" : null
                      } ],
                      "services" : [ ],
                      "configs" : null,
                      "configTypes" : null,
                      "servicePolicies" : [ ],
                      "serviceEdgeRouterPolicies" : [ {
                        "edgeRouterRoles" : [ "#all" ],
                        "name" : "Default Policy",
                        "semantic" : "AnyOf",
                        "serviceRoles" : [ "#all" ],
                        "tags" : {
                          "network-id" : "d5cb7263-116f-4ae9-9591-5f657d0c960a",
                          "resource-id" : "509af4d1-d1fc-40d7-b739-5dc41259c200"
                        }
                      } ],
                      "edgeRouterPolicies" : [ ],
                      "authPolicies" : [ {
                        "name" : "NetFoundry Console Integration Auth Policy",
                        "primary" : {
                          "cert" : {
                            "allowExpiredCerts" : false,
                            "allowed" : false
                          },
                          "extJwt" : {
                            "allowed" : true,
                            "allowedSigners" : [ "@NetFoundry Console Integration External JWT Signer" ]
                          },
                          "updb" : {
                            "allowed" : false,
                            "lockoutDurationMinutes" : 0,
                            "maxAttempts" : 0,
                            "minPasswordLength" : 5,
                            "requireMixedCase" : false,
                            "requireNumberChar" : false,
                            "requireSpecialChar" : false
                          }
                        },
                        "secondary" : {
                          "requireTotp" : false
                        },
                        "tags" : {
                          "network-id" : "d5cb7263-116f-4ae9-9591-5f657d0c960a",
                          "resource-id" : "24d5cc4b-3094-4762-a8b7-2b03bc3f55b9"
                        }
                      } ],
                      "certificateAuthorities" : null,
                      "externalJwtSigners" : [ {
                        "audience" : "https://gateway.sandbox.netfoundry.io/d5cb7263-116f-4ae9-9591-5f657d0c960a",
                        "certPem" : null,
                        "claimsProperty" : "sub",
                        "clientId" : null,
                        "enabled" : true,
                        "externalAuthUrl" : null,
                        "fingerprint" : null,
                        "issuer" : "https://netfoundry.io/jwt/Swuq_ZYGeVHSZcSnjf-GQ",
                        "jwksEndpoint" : "https://2qy82qhbz8xe.in.staging.zrok.io/network-auth/v1/public/.well-known/Swuq_ZYGeVHSZcSnjf-GQ/jwks.json",
                        "kid" : null,
                        "name" : "NetFoundry Console Integration External JWT Signer",
                        "scopes" : null,
                        "tags" : { },
                        "targetToken" : null,
                        "useExternalId" : false
                      } ],
                      "postureChecks" : null,
                      "hosting" : {
                        "networkControllers" : [ {
                          "name" : "test-nc-2",
                          "provider" : "AWS",
                          "region" : "us-east-1",
                          "size" : "small",
                          "productVersion" : "7.3.37",
                          "haPrimaryNode" : true
                        }, {
                          "name" : "export-test-0-nc",
                          "provider" : "AWS",
                          "region" : "us-east-1",
                          "size" : "small",
                          "productVersion" : "8.1.4",
                          "haPrimaryNode" : true
                        } ],
                        "edgeRouters" : [ {
                          "name" : "test-2",
                          "provider" : "AWS",
                          "region" : "us-east-1",
                          "size" : "small",
                          "alternateDomainName" : null
                        }, {
                          "name" : "test-1",
                          "provider" : "AWS",
                          "region" : "us-east-1",
                          "size" : "small",
                          "alternateDomainName" : null
                        } ]
                      },
                      "haEnabled" : false
                    }
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Network Assemblies
      summary: Import a Network Assembly into an existing Network
      description: >-
        Import a Network Assembly into an existing Network. This process updates
        the network, imports the specified Ziti entities, and creates hosting
        for any new edge routers.
      operationId: importFromNetworkAssembly
      parameters:
        - name: id
          in: path
          description: Id of the resource
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          A Network Assembly object that defines the components to import into
          the network.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNetworkAssembly'
            examples:
              default:
                description: default
                value: >-
                  {"name":"test-network-assembly","haEnabled":false,"productVersion":null,"customerProviderDetails":null,"entities":[],"hosting":{"networkControllers":[{"name":"test-controller","provider":"AWS","region":"us-east-1","size":"medium","productVersion":"8.0.43","alternateDomainName":null,"haPrimaryNode":null}],"edgeRouters":null},"dnsZoneId":null,"networkGroupId":"38570e26-c378-4829-b5ad-7685fa99a80a"}
        required: true
      responses:
        '202':
          description: The request to import the network assembly is accepted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "076c27fa-6fd9-4538-9759-44772332ce26",
                      "ownerIdentityId" : "dc616281-4ba0-4a4f-b860-c593bfb2adfb",
                      "createdBy" : "dc616281-4ba0-4a4f-b860-c593bfb2adfb",
                      "createdAt" : "2025-12-18T22:57:05.315760Z",
                      "updatedAt" : "2025-12-18T22:57:05.323967Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-assembly-test-30",
                      "networkGroupId" : "38570e26-c378-4829-b5ad-7685fa99a80a",
                      "size" : "small",
                      "productVersion" : "8.1.4",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/38570e26-c378-4829-b5ad-7685fa99a80a",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/076c27fa-6fd9-4538-9759-44772332ce26",
                          "title" : "network-assembly-test-30"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/076c27fa-6fd9-4538-9759-44772332ce26"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=076c27fa-6fd9-4538-9759-44772332ce26"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=076c27fa-6fd9-4538-9759-44772332ce26"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=076c27fa-6fd9-4538-9759-44772332ce26"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=076c27fa-6fd9-4538-9759-44772332ce26"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}:
    get:
      tags:
        - Edge Routers
      summary: Get Edge Router
      description: >-
        Returns a single Edge Router by its unique identifier. The caller must
        have read permission on the Edge Router resource.
      operationId: getEdgeRouter
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Edge Router.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: embed
          in: query
          description: >-
            Embed related resources in the result. Allowed: all | host |
            software-deployment-state.
          schema:
            type: array
            items:
              type: string
              enum:
                - all
                - host
                - software-deployment-state
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * ziti: Query Ziti for the Ziti definition of the edge-router
               * inspect(inspection): Invoke the Ziti inspect operation with the specified inspection parameter see below (not all applicable to all configurations):
                   * metrics
                   * config
                   * connected-routers
                   * connected-peers
                   * links
                   * sdk-terminators
                   * router-messaging
                   * router-data-model
                   * router-controllers
      responses:
        '200':
          description: Edge Router retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get edge router response
                  value: |-
                    {
                      "id" : "f9ab1547-bb1f-487a-a481-4f81105b5fe8",
                      "hostId" : "a69ed55f-e5b4-4696-8bab-01dd4c3f7d29",
                      "ownerIdentityId" : "a1ef42e5-b510-4924-84f3-888e6f8cbca8",
                      "createdBy" : "a1ef42e5-b510-4924-84f3-888e6f8cbca8",
                      "createdAt" : "2025-12-05T15:20:47.541889Z",
                      "updatedAt" : "2025-12-05T15:20:47.549017Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1806",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "f9ab1547-bb1f-487a-a481-4f81105b5fe8-p.fake.netfoundry.io",
                      "name" : "er-test-1805",
                      "productVersion" : "8.0.43",
                      "networkId" : "feb03672-34e7-4bba-86c9-e5ed4aacc462",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "PROVISIONED",
                      "softwareDeploymentStateId" : "1adde1e7-fcee-4f61-b3b5-a9839dd3c975",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/f9ab1547-bb1f-487a-a481-4f81105b5fe8",
                          "title" : "er-test-1805"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/1adde1e7-fcee-4f61-b3b5-a9839dd3c975"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/feb03672-34e7-4bba-86c9-e5ed4aacc462",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/a69ed55f-e5b4-4696-8bab-01dd4c3f7d29"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/1adde1e7-fcee-4f61-b3b5-a9839dd3c975",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    put:
      tags:
        - Edge Routers
      summary: Update Edge Router (complete)
      description: >
        Updates an existing Edge Router. The operation is asynchronous and
        returns the Edge Router resource with related links.

        The caller must have the update permission on the specified Edge Router.
      operationId: putUpdateEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to update
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      requestBody:
        description: Update Edge Router payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEdgeRouter'
            examples:
              rename:
                description: rename
                value:
                  name: er-nyc-02
              toggle-link-listener:
                description: Only supported for NetFoundry-hosted Edge Routers.
                value:
                  linkListener: true
        required: true
      responses:
        '202':
          description: Accepted. Edge Router update has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "72263f05-4122-480f-a156-4c81fce51331",
                      "hostId" : "0f3aac12-3626-45c2-9326-abad8bd18eee",
                      "ownerIdentityId" : "1cd2d754-8e36-4fb6-ae05-e6527ba24f96",
                      "createdBy" : "1cd2d754-8e36-4fb6-ae05-e6527ba24f96",
                      "createdAt" : "2025-12-05T15:20:19.290463Z",
                      "updatedAt" : "2025-12-05T15:20:19.451347Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1150",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "72263f05-4122-480f-a156-4c81fce51331-p.fake.netfoundry.io",
                      "name" : "Updated name",
                      "productVersion" : "8.0.43",
                      "networkId" : "2319c918-9cae-4fff-a860-ccd8cd35521a",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "PROVISIONED",
                      "softwareDeploymentStateId" : "1f4f4666-d8d2-4564-840b-72200fd59d09",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/72263f05-4122-480f-a156-4c81fce51331",
                          "title" : "Updated name"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/1f4f4666-d8d2-4564-840b-72200fd59d09"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/2319c918-9cae-4fff-a860-ccd8cd35521a",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/0f3aac12-3626-45c2-9326-abad8bd18eee"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/1f4f4666-d8d2-4564-840b-72200fd59d09",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Edge Routers
      summary: Delete Edge Router
      description: >-
        Deletes an Edge Router by ID after validating it is not hosting a
        service and that the owning Network is provisioned. Requires delete
        permission on the Edge Router resource.
      operationId: deleteEdgeRouter
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Edge Router to delete.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: Edge Router deleted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample delete Edge Router response
                  value: |-
                    {
                      "id" : "59ab7370-45ae-438b-a3cd-28930dd194e9",
                      "hostId" : "aa8e3ae7-df8e-49f6-8dfb-9adfcbeac0d0",
                      "ownerIdentityId" : "1883994e-781a-4bce-b6fd-2631959e273e",
                      "createdBy" : "1883994e-781a-4bce-b6fd-2631959e273e",
                      "createdAt" : "2025-12-05T15:20:20.005413Z",
                      "updatedAt" : "2025-12-05T15:20:20.066511Z",
                      "deletedBy" : "54f126ba-32c0-4157-995b-b941de40b8a2",
                      "deletedAt" : null,
                      "zitiId" : "zitiId",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "59ab7370-45ae-438b-a3cd-28930dd194e9-p.fake.netfoundry.io",
                      "name" : "er-test-1233",
                      "productVersion" : "8.0.43",
                      "networkId" : "bc22559c-3d25-4b56-8ada-9fe5c47aa000",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "DELETING",
                      "softwareDeploymentStateId" : null,
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/59ab7370-45ae-438b-a3cd-28930dd194e9",
                          "title" : "er-test-1233"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/bc22559c-3d25-4b56-8ada-9fe5c47aa000",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/aa8e3ae7-df8e-49f6-8dfb-9adfcbeac0d0"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    patch:
      tags:
        - Edge Routers
      summary: Update Edge Router (partial)
      description: >
        Partially updates an existing Edge Router. Only the provided fields are
        modified.

        The operation is asynchronous and returns the Edge Router resource with
        related links.

        The caller must have the update permission on the specified Edge Router.
      operationId: patchUpdateEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to update
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      requestBody:
        description: Partial Update Edge Router payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEdgeRouter'
            examples:
              rename:
                description: rename
                value:
                  name: er-nyc-02
              toggle-link-listener:
                description: Only supported for NetFoundry-hosted Edge Routers.
                value:
                  linkListener: true
        required: true
      responses:
        '202':
          description: Accepted. Edge Router update has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "dbfe6af6-fe51-4c58-809f-8b26a7bf803d",
                      "hostId" : "0700afc8-5602-48c7-aae5-b6b69f8415ff",
                      "ownerIdentityId" : "8cac4e88-e239-4054-9d06-1ec8bac2e2cb",
                      "createdBy" : "8cac4e88-e239-4054-9d06-1ec8bac2e2cb",
                      "createdAt" : "2025-12-05T15:20:20.715009Z",
                      "updatedAt" : "2025-12-05T15:20:20.777324Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1315",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "dbfe6af6-fe51-4c58-809f-8b26a7bf803d-p.fake.netfoundry.io",
                      "name" : "Updated name",
                      "productVersion" : "8.0.43",
                      "networkId" : "edc8ab85-5e44-4fd3-bc3a-87a3987e4fa7",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : true,
                      "status" : "PROVISIONED",
                      "softwareDeploymentStateId" : "2f5dc97e-66f1-42ce-8071-622163c606b6",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/dbfe6af6-fe51-4c58-809f-8b26a7bf803d",
                          "title" : "Updated name"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/2f5dc97e-66f1-42ce-8071-622163c606b6"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/edc8ab85-5e44-4fd3-bc3a-87a3987e4fa7",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/0700afc8-5602-48c7-aae5-b6b69f8415ff"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/2f5dc97e-66f1-42ce-8071-622163c606b6",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/registrations/share:
    post:
      tags:
        - registration-controller
      operationId: share
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateRegistration'
            examples: {}
        required: true
      responses:
        '202':
          description: Accepted
  /v3/networks:
    get:
      tags:
        - Networks
      summary: Find all Networks that match the specified criteria
      description: >
        Find all Network instances that match the specified search criteria.

        The endpoint removes from the results any instances for which you do not
        have read authorization.

        As a side effect, this endpoint never returns a 403 or 404 error.
        Instead, it returns an empty list.
      operationId: findNetworks
      parameters:
        - name: id
          in: query
          description: Filter by Network ID.
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: name
          in: query
          description: Filter by Network name.
          example: My Network
        - name: networkGroupId
          in: query
          description: Filter by Network Group ID.
          example: 11111111-2222-3333-4444-555555555555
        - name: productVersion
          in: query
          description: Filter by product version.
          examples:
            2.3.1:
              description: 2.3.1
              value: 2.3.1
            3.0.0:
              description: 3.0.0
              value: 3.0.0
        - name: status
          in: query
          description: Filter by Network status.
          examples:
            running:
              description: running
              value: RUNNING
            suspended:
              description: suspended
              value: SUSPENDED
        - name: publicCertEnabled
          in: query
          description: Filter by whether public certificate is enabled.
          examples:
            'true':
              description: 'true'
              value: true
            'false':
              description: 'false'
              value: false
        - name: dnsZoneId
          in: query
          description: Filter by DNS Zone ID.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: ownerIdentityId
          in: query
          description: Filter by owner identity ID.
          example: aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb
        - name: createdBy
          in: query
          description: Filter by creator identity ID.
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID.
          example: cccccccc-1111-2222-3333-dddddddddddd
        - name: haEnabled
          in: query
          description: Filter by High Availability (HA) flag.
          examples:
            'true':
              description: 'true'
              value: true
            'false':
              description: 'false'
              value: false
        - name: createdAt
          in: query
          description: >-
            Filter by createdAt with comparison operators. Supports >, >=, <,
            <=, =, !=
          examples:
            created-after:
              description: created-after
              value: '>2025-01-01T00:00:00Z'
            created-before:
              description: created-before
              value: <2025-12-31T23:59:59Z
        - name: updatedAt
          in: query
          description: Filter by updatedAt with comparison operators.
          example: '>=2025-01-01T00:00:00Z'
        - name: deletedAt
          in: query
          description: Filter by deletedAt with comparison operators.
          example: '=2025-05-10T13:37:00Z'
        - name: page
          in: query
          description: Zero-based page index.
          example: 0
        - name: size
          in: query
          description: The size of the page to be returned.
          example: 20
        - name: sort
          in: query
          description: >-
            Sorting criteria in the format: property,(asc|desc). Multiple sort
            params are supported.
          examples:
            name-asc:
              description: name-asc
              value: name,asc
            createdAt-desc:
              description: createdAt-desc
              value: createdAt,desc
        - name: network.size
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            uniqueItems: true
        - name: findByName
          in: query
          required: false
          deprecated: true
          schema:
            type: string
        - name: findByNetworkGroupId
          in: query
          required: false
          deprecated: true
          schema:
            type: string
            format: uuid
        - name: region
          in: query
          required: false
          deprecated: true
          schema:
            type: string
        - name: locationCode
          in: query
          required: false
          deprecated: true
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of Networks.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find networks request
                  value: |-
                    {
                      "_embedded" : {
                        "networkList" : [ {
                          "id" : "cd89f366-605d-490f-ad6b-ede1c8587c57",
                          "ownerIdentityId" : "28a64561-d998-4867-b5a1-56cedd554010",
                          "createdBy" : "28a64561-d998-4867-b5a1-56cedd554010",
                          "createdAt" : "2026-01-14T16:32:02.972391Z",
                          "updatedAt" : "2026-01-14T16:32:02.977500Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "name" : "network-6",
                          "networkGroupId" : "cf87629d-158e-4ef1-bd1e-90819c6dbd05",
                          "size" : "small",
                          "productVersion" : "8.0.43",
                          "region" : "us-east-1",
                          "status" : "PROVISIONED",
                          "publicCertEnabled" : true,
                          "haEnabled" : false,
                          "dnsZoneId" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks/cd89f366-605d-490f-ad6b-ede1c8587c57",
                              "title" : "network-6"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/cf87629d-158e-4ef1-bd1e-90819c6dbd05",
                              "profile" : "parent"
                            },
                            "networks" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                              "profile" : "parent"
                            },
                            "network-jwt-sets" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/cd89f366-605d-490f-ad6b-ede1c8587c57"
                            },
                            "network-controllers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=cd89f366-605d-490f-ad6b-ede1c8587c57"
                            },
                            "executions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=cd89f366-605d-490f-ad6b-ede1c8587c57"
                            },
                            "edge-routers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=cd89f366-605d-490f-ad6b-ede1c8587c57"
                            },
                            "hosts" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=cd89f366-605d-490f-ad6b-ede1c8587c57"
                            }
                          }
                        }, {
                          "id" : "f8095468-5dd4-428c-bd12-fdcd301faae5",
                          "ownerIdentityId" : "3709ae8f-1016-41b0-80e7-a7bbd1a4ac37",
                          "createdBy" : "3709ae8f-1016-41b0-80e7-a7bbd1a4ac37",
                          "createdAt" : "2026-01-14T16:32:02.888714Z",
                          "updatedAt" : "2026-01-14T16:32:02.903532Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "name" : "network-2",
                          "networkGroupId" : "f3a55921-1fb1-4638-b3f4-f374f322f0a8",
                          "size" : "small",
                          "productVersion" : "8.0.43",
                          "region" : "us-east-1",
                          "status" : "PROVISIONED",
                          "publicCertEnabled" : true,
                          "haEnabled" : true,
                          "dnsZoneId" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks/f8095468-5dd4-428c-bd12-fdcd301faae5",
                              "title" : "network-2"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/f3a55921-1fb1-4638-b3f4-f374f322f0a8",
                              "profile" : "parent"
                            },
                            "networks" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                              "profile" : "parent"
                            },
                            "network-jwt-sets" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/f8095468-5dd4-428c-bd12-fdcd301faae5"
                            },
                            "network-controllers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=f8095468-5dd4-428c-bd12-fdcd301faae5"
                            },
                            "executions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=f8095468-5dd4-428c-bd12-fdcd301faae5"
                            },
                            "edge-routers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=f8095468-5dd4-428c-bd12-fdcd301faae5"
                            },
                            "hosts" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=f8095468-5dd4-428c-bd12-fdcd301faae5"
                            },
                            "clusters" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=f8095468-5dd4-428c-bd12-fdcd301faae5"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 2,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Create a new Network
      description: >
        Create a new Network resource. The `provider` field determines if
        NetFoundry or the customer hosts the network.

        The caller must have create permission on Network resources. If the
        provider is `CUSTOMER`, the caller must also have
        `create-customer-hosted` authorization.
      operationId: createNetwork
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: The network to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetwork'
            examples:
              default:
                description: default
                value: >-
                  {"networkGroupId":"0230661b-0992-4394-9c3e-84ae4a487ff4","size":"small","name":"Create
                  Test
                  Network-512","productVersion":"8.0.43","provider":"AWS","region":"us-east-1","publicCertEnabled":false,"haEnabled":false}
        required: true
      responses:
        '202':
          description: Accepts the request to create the network.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf",
                      "ownerIdentityId" : "dcfc5dc3-8df0-4b33-aba3-77cb1d775af5",
                      "createdBy" : "dcfc5dc3-8df0-4b33-aba3-77cb1d775af5",
                      "createdAt" : "2025-12-05T15:18:57.733573Z",
                      "updatedAt" : "2025-12-05T15:18:57.733573Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "Create Test Network-512",
                      "networkGroupId" : "0230661b-0992-4394-9c3e-84ae4a487ff4",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONING",
                      "publicCertEnabled" : true,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf",
                          "title" : "Create Test Network-512"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/0230661b-0992-4394-9c3e-84ae4a487ff4",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=b0979ff1-0f49-45c3-ba21-ea2bd2ff30cf"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/repair:
    post:
      tags:
        - Networks
      summary: Repair management access for a Network
      description: |2
         Attempt to repair management access for the specified Network. This operation can be used when management access
         to the Network's controllers has been lost or degraded. The repair is asynchronous and the response contains the
         Network resource with related links. The caller must have the update permission on the specified Network.
         The caller must have the update permission on the specified Network.
      operationId: repairManagementAccess
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
      responses:
        '202':
          description: Accepted. Network management access repair has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a",
                      "ownerIdentityId" : "0ae9effc-22d8-45b6-b328-724f944c0c0e",
                      "createdBy" : "0ae9effc-22d8-45b6-b328-724f944c0c0e",
                      "createdAt" : "2025-12-05T15:19:14.824653Z",
                      "updatedAt" : "2025-12-05T15:19:14.826967Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-617",
                      "networkGroupId" : "1b29c5ab-1a40-4405-9a1e-c3fe27b7e7ed",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a",
                          "title" : "network-617"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/1b29c5ab-1a40-4405-9a1e-c3fe27b7e7ed",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=238829e4-c6d0-4ff7-abf8-a3a82c0d5a6a"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/exchange:
    post:
      tags:
        - Networks
      summary: Exchange Core API auth for a Ziti token
      description: >
        Exchange the caller's authenticated Core API context for a Ziti token
        usable against the Network's Ziti Edge Management API.

        If no body is provided or the type is omitted, a SESSION token is
        returned by default.

        The caller must have the update permission on the specified Network.
      operationId: exchangeZitiToken
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
      requestBody:
        description: Specify the token type to return. Defaults to SESSION when omitted.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRequest'
            examples:
              auto-default:
                description: Auto detect what token (body omitted) should be returned
                value: '{"type":"AUTO"}'
              session:
                description: Request a SESSION token
                value: '{"type":"SESSION"}'
              bearer:
                description: Request a BEARER JWT instead of a Ziti session token
                value: '{"type":"BEARER"}'
      responses:
        '200':
          description: >-
            OK. Returns a HAL resource wrapping details of the exchanged Ziti
            token.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                ziti-bearer-token:
                  description: Example CloudZitiToken response
                  value: |-
                    {
                      "type" : "BEARER",
                      "value" : "mock-ziti-session-token-7f759d36-9f81-493f-aab7-d443ff86b8fa",
                      "expiresAt" : "2025-12-05T15:29:14.504+00:00",
                      "networkControllerUrl" : "https://d1d576e9-bde8-4089-af3d-9cd776d743a1-p.nf.io:443/edge/management/v1",
                      "networkControllerHost" : "d1d576e9-bde8-4089-af3d-9cd776d743a1-p.nf.io",
                      "networkControllerPort" : 443,
                      "zitiVersion" : "0.25.3",
                      "networkId" : "12a97d72-c9b7-49c8-a49a-6b9adc5bb44e",
                      "tunnelerAccess" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/12a97d72-c9b7-49c8-a49a-6b9adc5bb44e/exchange"
                        },
                        "parent" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/12a97d72-c9b7-49c8-a49a-6b9adc5bb44e"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            self:
              operationId: exchangeZitiToken
              parameters:
                id: $request.path.id/exchange
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-assemblies:
    post:
      tags:
        - Network Assemblies
      summary: Create a Network from a Network Assembly
      description: >-
        Create a new Network and its components from the provided Network
        Assembly. This process includes creating the network, all specified Ziti
        entities, and the hosting infrastructure for network controllers and
        edge routers.
      operationId: createFromNetworkAssembly
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: A Network Assembly object that defines the network to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetworkAssembly'
            examples:
              default:
                description: default
                value: >-
                  {"name":"test-network-assembly","haEnabled":false,"productVersion":null,"customerProviderDetails":null,"entities":["network-controllers","services"],"hosting":{"networkControllers":[{"name":"test-network-controller","provider":"AWS","region":"us-east-1","size":"large","productVersion":"8.0.43","alternateDomainName":null,"haPrimaryNode":null}],"edgeRouters":null},"dnsZoneId":null,"networkGroupId":"8a8fbe1d-ffca-4a31-a4f6-02411fb9b8ff"}
        required: true
      responses:
        '202':
          description: The request to create the network is accepted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "3860b7c5-25a0-43b2-96ed-cf33cbb063b6",
                      "ownerIdentityId" : "b7248771-6f41-417e-9ee0-fc654546bb06",
                      "createdBy" : "b7248771-6f41-417e-9ee0-fc654546bb06",
                      "createdAt" : "2025-12-18T22:57:04.772590Z",
                      "updatedAt" : "2025-12-18T22:57:04.782874Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-assembly-test-15",
                      "networkGroupId" : "8a8fbe1d-ffca-4a31-a4f6-02411fb9b8ff",
                      "size" : "small",
                      "productVersion" : "8.1.4",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/8a8fbe1d-ffca-4a31-a4f6-02411fb9b8ff",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/3860b7c5-25a0-43b2-96ed-cf33cbb063b6",
                          "title" : "network-assembly-test-15"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/3860b7c5-25a0-43b2-96ed-cf33cbb063b6"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=3860b7c5-25a0-43b2-96ed-cf33cbb063b6"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=3860b7c5-25a0-43b2-96ed-cf33cbb063b6"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=3860b7c5-25a0-43b2-96ed-cf33cbb063b6"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=3860b7c5-25a0-43b2-96ed-cf33cbb063b6"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.body.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers:
    get:
      tags:
        - Edge Routers
      summary: Find Edge Routers
      description: >-
        Returns Edge Routers matching the provided filters. Results are limited
        to resources the caller may read. Supports standard paging and sorting.
      operationId: findEdgeRouters
      parameters:
        - name: id
          in: query
          description: Filter by Edge Router ID.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: name
          in: query
          description: Filter by Edge Router name.
          example: er-nyc-01
        - name: networkId
          in: query
          description: Filter by Network ID.
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: zitiId
          in: query
          description: Filter by Ziti ID.
          example: zi:er:abcd1234
        - name: provider
          in: query
          description: Filter by hosting provider.
          examples:
            customer:
              description: customer
              value: CUSTOMER
            aws:
              description: aws
              value: AWS
        - name: linkListener
          in: query
          description: Filter by whether linkListener is enabled.
          example: true
        - name: wssListener
          in: query
          description: Filter by whether wssListener is enabled.
          example: true
        - name: hostId
          in: query
          description: Filter by Host ID.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: status
          in: query
          description: Filter by status.
          examples:
            provisioned:
              description: provisioned
              value: PROVISIONED
            suspended:
              description: suspended
              value: SUSPENDED
        - name: attribute
          in: query
          description: >-
            Filter by attribute expression. When used, exactly one networkId
            must also be provided.
          example: key=value
        - name: createdAt
          in: query
          description: >-
            Filter by createddAt with comparison operators. Supports >, >=, <,
            <=, =, != (e.g., createdAt=>=2025-01-01T00:00:00Z)
          examples:
            created-after:
              description: created-after
              value: '>2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Filter by updatedAt with comparison operators.
          example: <2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Filter by deletedAt with comparison operators.
          example: '>2025-05-10T13:37:00Z'
        - name: page
          in: query
          description: Zero-based page index.
          example: 0
        - name: size
          in: query
          description: The size of the page to be returned.
          example: 20
        - name: sort
          in: query
          description: >-
            Sorting criteria in the format: property,(asc|desc). Multiple sort
            params are supported.
          examples:
            name-asc:
              description: name-asc
              value: name,asc
            createdAt-desc:
              description: createdAt-desc
              value: createdAt,desc
      responses:
        '200':
          description: A paginated list of Edge Routers.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
          links:
            self:
              operationId: findEdgeRouters
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Edge Routers
      summary: Create Edge Router
      description: >-
        Creates a managed Edge Router within the specified Network. For
        NF-hosted providers, a host is provisioned in the given cloud region.
        The operation is asynchronous and returns the Edge Router resource with
        related links.
      operationId: createEdgeRouter
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Create Edge Router payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEdgeRouter'
            examples:
              nf-hosted-aws:
                description: NF-hosted Edge Router in AWS us-east-1
                value:
                  networkId: 11111111-2222-3333-4444-555555555555
                  zitiId: abcd1234
                  provider: AWS
                  region: us-east-1
                  hostSize: SMALL
                  linkListener: true
                  wssListener: true
                  alternateDomainName: er1.example.net
              customer-hosted:
                description: Customer-hosted Edge Router (region ignored)
                value:
                  networkId: 11111111-2222-3333-4444-555555555555
                  zitiId: efgh5678
                  provider: CUSTOMER
        required: true
      responses:
        '202':
          description: Accepted. Edge Router creation has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Edge Router response
                  value: |-
                    {
                      "id" : "efe8c328-1a4e-4936-bf74-fd2db21f32e2",
                      "hostId" : null,
                      "ownerIdentityId" : "96797e44-e206-44f0-a835-2f9a4547de04",
                      "createdBy" : "96797e44-e206-44f0-a835-2f9a4547de04",
                      "createdAt" : "2025-12-05T15:20:47.830888Z",
                      "updatedAt" : "2025-12-05T15:20:47.843093Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "zitiId",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "name" : "NtiHk-0TO7hjJxhEUe7CU",
                      "productVersion" : "8.0.43",
                      "networkId" : "e50ad80e-7f3a-4e9c-8a4a-3f8b0fb14205",
                      "jwt" : null,
                      "linkListener" : false,
                      "online" : false,
                      "verified" : false,
                      "status" : "PROVISIONING",
                      "softwareDeploymentStateId" : "a278363d-0f24-40c2-b54e-9aab8f525984",
                      "provider" : null,
                      "region" : null,
                      "hostSize" : null,
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/efe8c328-1a4e-4936-bf74-fd2db21f32e2",
                          "title" : "NtiHk-0TO7hjJxhEUe7CU"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a278363d-0f24-40c2-b54e-9aab8f525984"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/e50ad80e-7f3a-4e9c-8a4a-3f8b0fb14205",
                          "profile" : "parent"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/a278363d-0f24-40c2-b54e-9aab8f525984",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-router-registrations:
    post:
      tags:
        - Edge Router Registrations
      summary: Create Edge Router Registration Key
      description: >
        Creates (or fetches if one already exists) a short-lived registration
        key for an Edge Router identified by

        Ziti ID within the specified Network. The Network must be provisioned
        and the Edge Router must not already

        be provisioned. Caller must have update permissions on the Network
        resource.
      operationId: createEdgeRouterRegistrationKey
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Registration key request payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegistrationKey'
            examples:
              default:
                description: >-
                  Create or fetch a registration key for an unprovisioned Edge
                  Router.
                value:
                  networkId: 11111111-2222-3333-4444-555555555555
                  zitiId: abcd1234
        required: true
      responses:
        '200':
          description: Registration key created or returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeRouterRegistrationKeyResponse'
              examples:
                default:
                  description: Example registration key response
                  value: |-
                    {
                      "registrationKey" : "TEST8BN5WKIOTZM",
                      "expiresAt" : "2025-12-08T15:22:23.744Z"
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            network:
              operationId: getNetwork
              parameters:
                id: $request.body#/networkId
              description: The Network for which this registration key applies.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-router-registrations/{registrationKey}:
    post:
      tags:
        - Edge Router Registrations
      summary: Retrieve Edge Router registration bundle
      description: >
        Used by Edge Router registration scripts. Given a valid, unexpired
        registration key, returns the registration payload

        including the Edge Router resource, the Network Controller host,
        configuration template content, and expiration.

        Each key has a limited number of retrievals and will automatically be
        deleted after attempts are exhausted.

        Fails if the key is invalid/expired or if the Edge Router is already
        provisioned.
      operationId: edgeRouterRegistrationFromKey
      parameters:
        - name: registrationKey
          in: path
          description: >-
            Short-lived registration key obtained from
            createEdgeRouterRegistrationKey.
          required: true
          schema:
            type: string
          example: YIFKR39HBG
      responses:
        '200':
          description: Registration payload returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeRouterRegistrationResponse'
              examples:
                valid:
                  description: Example registration response for a valid key.
                  value: |-
                    {
                      "edgeRouter" : {
                        "id" : "a38370ae-7f59-40cd-a7e4-90897b409c73",
                        "hostId" : "5a8eb397-378a-4c3f-bba7-b246e9d50bba",
                        "ownerIdentityId" : null,
                        "createdBy" : null,
                        "createdAt" : "2025-12-05T15:22:24.213160Z",
                        "updatedAt" : "2025-12-05T15:22:24.228428Z",
                        "deletedBy" : null,
                        "deletedAt" : null,
                        "zitiId" : "gordTXCEwjtMYamVZfEw5",
                        "domainName" : null,
                        "alternateDomainName" : null,
                        "name" : "UasnDHoNtCNmF4BrcKuXy",
                        "productVersion" : "7.3.37",
                        "networkId" : "27382385-ae39-4fe1-9725-78ba0513476f",
                        "jwt" : "2gsYnj0OI_m4yTzahuwYr",
                        "linkListener" : false,
                        "wssListener" : false,
                        "tunnelerEnabled" : false,
                        "noTraversal" : false,
                        "online" : false,
                        "verified" : false,
                        "enabled" : true,
                        "status" : "NEW",
                        "softwareDeploymentStateId" : "c3cd5413-386f-4f26-b0a3-9b0263e05293",
                        "provider" : "CUSTOMER",
                        "region" : null,
                        "hostSize" : null,
                        "attributes" : [ ],
                        "registration" : null
                      },
                      "networkControllerHost" : "26e29db2-6412-4bd4-b29c-b9c65f2ea162.nf.io",
                      "template" : "v: 3\n\n# (required) The certificates, ca chains, and private key used to represent this routers identity\n#\n# If the 'edge\" section is enabled and enrollment is run, the files in this section will be written to with the results.\n# The \"key\" value can be provided through any of the support private key engines (file, etc.).\n#\n# If the 'key' value is a file and that file exists; it is expected to a pre-generated private key. It will be used for\n# the  enrollment process and it will back the certificates generated during enrollment. If the file does not exist, it\n# will be generated.\n#\n# The 'cert', 'server_cert', and 'ca' files will be overwritten with the results of the enrollment process.\n#\n# When running the ziti-router the files/values in this section will be read and used. The 'cert' value will be used\n# as the client certificate to connect to the controller. The 'server_cert' is used for all servers/listeners. The\n# 'ca' value is used to populate an internally Trusted CA pool.\n\nidentity:\n  cert:        \"certs/client.cert.pem\"\n  server_cert: \"certs/server.cert.pem\"\n  key:         \"certs/client.key.pem\"\n  ca:          \"certs/intermediate-chain.pem\"\n\n\n#trace:\n# path:                 001.trace\n\n#profile:\n#  memory:\n#    path:               001.memprof\n#  cpu:\n#    path:               001.cpuprof\n\nctrl:\n  endpoint: \"tls:{{ controller_ip }}:80\"\n\n\nlink:\n  dialers:\n    - binding:          transport\n{% if link_listener %}    \n  listeners:\n    - binding:          transport\n      bind:             tls:0.0.0.0:80\n      advertise:        tls:{{ advertise_value }}:80 \n      options:\n        outQueueSize:   16\n{%- endif %}\n{% if fabric_link_listener %}    \n  listeners:\n    - binding:          transport\n      bind:             tls:0.0.0.0:80\n      advertise:        tls:{{ fabric_value }}:80 \n      options:\n        outQueueSize:   16\n{%- endif %} \n\n# By having an 'edge' section defined, the ziti-router will attempt to parse the edge configuration. Removing this\n# section, commenting out, or altering the name of the section will cause the router to no longer operate as an Edge\n# Router.\n\nedge:\n  # (required) Information used to generate the initial registration CSR. For documentation on these fields please\n  # refer to the openssl documentation. These values MUST be supplied and have no defaults.\n  csr:\n    country: US\n    province: NC\n    locality: Charlotte\n    organization: NetFoundry\n    organizationalUnit: Ziti\n    # (required) SANs that this Gateways certs should contain. At least one IP or DNS SAN should be defined that matches\n    # the edge listeners \"advertise\" value from the \"listeners\" section.\n    sans:\n      {% if type == \"ip\" -%}\n      ip:\n        - 127.0.0.1\n        - {{ advertise_value }}\n      {%- endif %}\n      {%- if type == \"dns\" -%}\n      dns:\n        - localhost\n        - {{ advertise_value }}\n      {%- endif %}\n     {%- if manual_configuration -%}\n      {% if ip -%}\n      ip:\n        - 127.0.0.1\n        {%- for ip in ip_list %}\n        - {{ ip }}\n        {%- endfor -%}\n      {%- endif %}\n      {% if dns -%}\n      dns:\n        - localhost\n        {%- for dns in dns_list %}\n        - {{ dns }}\n        {%- endfor -%}\n      {%- endif -%}\n     {%- endif %}\n\nlisteners:\n  - binding: edge\n    address: tls:0.0.0.0:443\n    options:\n      # (required) The public hostname and port combination that Ziti SDKs should connect on. Previously this was in the chanIngress section.\n      advertise: {{ advertise_value }}:443 \n \n  {% if salt -%}\n  # Netfoundry SaltStack 4505\n  - binding:            proxy\n    address:            tcp:127.0.0.1:4505\n    service:            salt4505\n  # NetFoundry SaltStack 4506\n  - binding:            proxy\n    address:            tcp:127.0.0.1:4506\n    service:            salt4506\n  {%- endif -%}\n",
                      "expiresAt" : "2025-12-05T15:24:24.195799Z",
                      "productVersion" : "7.3.37",
                      "productMetadata" : {
                        "active" : true,
                        "version" : {
                          "type" : "STRICT",
                          "build" : null,
                          "major" : 7,
                          "minor" : 3,
                          "patch" : 37,
                          "value" : "7.3.37",
                          "stable" : true,
                          "suffixTokens" : [ ],
                          "originalValue" : "7.3.37"
                        },
                        "zitiVersion" : {
                          "type" : "STRICT",
                          "build" : null,
                          "major" : 0,
                          "minor" : 24,
                          "patch" : 14,
                          "value" : "0.24.14",
                          "stable" : false,
                          "suffixTokens" : [ ],
                          "originalValue" : "0.24.14"
                        },
                        "defaultVersion" : false
                      },
                      "haEnabled" : false
                    }
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Edge Router Registrations
      summary: Acknowledge Edge Router registration result
      description: >
        Used by Edge Router registration scripts to report the outcome of a
        registration attempt. A status of 0 indicates success;

        any non-zero value indicates an error. The registration key is
        short-lived and may become invalid after use.
      operationId: edgeRouterRegistrationRegistered
      parameters:
        - name: registrationKey
          in: path
          description: >-
            Short-lived registration key obtained from
            createEdgeRouterRegistrationKey.
          required: true
          schema:
            type: string
          example: YIFKR39HBG
      requestBody:
        description: Result payload posted by the registering Edge Router.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredEdgeRouter'
            examples:
              success:
                description: success
                value:
                  status: 0
                  message: Successful
              error:
                description: Non-zero status indicates an error.
                value:
                  status: 2
                  message: Certificate install failed
        required: true
      responses:
        '202':
          description: Accepted. Registration result has been processed.
          links:
            registration:
              operationId: edgeRouterRegistrationFromKey
              parameters:
                registrationKey: $request.path.registrationKey
              description: >-
                Retrieve the registration bundle associated with this key (may
                be invalid after use).
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/stored-secrets/{id}/share:
    post:
      tags:
        - Stored Secrets
      summary: Share a Stored Secret for OTT update
      description: >
        Generate a one-time token (OTT) and share URL for updating the Stored
        Secret's value without normal authentication.

        The response contains the Stored Secret metadata (unwrapped) and a URL
        that includes the OTT as a query parameter.

        Use this URL with a text/plain body to POST/PUT/PATCH the new value.

        The caller must have update permission on the StoredSecret.
      operationId: shareStoredSecret
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Stored Secret to share.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: >-
            Returns the Stored Secret metadata and an OTT URL to set/update the
            secret value.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample share stored secret response including the OTT URL
                  value:
                    id: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
                    name: my-ssh-key
                    type: PRIVATE_KEY
                    networkGroupId: 11111111-2222-3333-4444-555555555555
                    createdAt: '2025-10-09T12:34:56Z'
                    updatedAt: '2025-10-09T12:40:00Z'
                    url: >-
                      https://gateway.production.netfoundry.io/core/v2/stored-secrets/8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b?token=abc123de
                    _links:
                      self:
                        href: >-
                          https://gateway.production.netfoundry.io/core/v2/stored-secrets/8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
                      network-group:
                        href: >-
                          https://gateway.production.netfoundry.io/core/v2/network-groups/11111111-2222-3333-4444-555555555555
          links:
            self:
              operationId: getStoredSecret
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/stored-secrets:
    get:
      tags:
        - Stored Secrets
      summary: Find Stored Secrets
      description: >-
        Find all StoredSecret instances that match the specified search
        criteria. Results exclude resources the caller is not authorized to
        read; therefore this endpoint never returns 403/404, only an empty list
        when no authorized results are found.
      operationId: findStoredSecrets
      parameters:
        - name: id
          in: query
          description: Filter by Stored Secret ID.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: name
          in: query
          description: Filter by Stored Secret name.
          example: my-ssh-key
        - name: parameterName
          in: query
          description: Filter by backing parameter name (internal identifier).
          example: ssm:/netfoundry/ng-1111/ssh-key
        - name: networkGroupId
          in: query
          description: Filter by Network Group ID that owns the secret.
          example: 11111111-2222-3333-4444-555555555555
        - name: createdBy
          in: query
          description: Filter by creator identity ID.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID.
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: createdAt
          in: query
          description: >-
            Filter by createdAt with comparison operators. Supports >, >=, <,
            <=, =, !=
          examples:
            created-after:
              description: created-after
              value: '>2025-01-01T00:00:00Z'
            created-before:
              description: created-before
              value: <2025-12-31T23:59:59Z
        - name: updatedAt
          in: query
          description: Filter by updatedAt with comparison operators.
          example: '>=2025-01-01T00:00:00Z'
        - name: deletedAt
          in: query
          description: Filter by deletedAt with comparison operators.
          example: '=2025-05-10T13:37:00Z'
        - name: page
          in: query
          description: Zero-based page index.
          example: 0
        - name: size
          in: query
          description: The size of the page to be returned.
          example: 20
        - name: sort
          in: query
          description: >-
            Sorting criteria in the format: property,(asc|desc). Multiple sort
            params are supported.
          examples:
            name-asc:
              description: name-asc
              value: name,asc
            createdAt-desc:
              description: createdAt-desc
              value: createdAt,desc
      responses:
        '200':
          description: A paginated list of Stored Secrets.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
          links:
            self:
              operationId: findStoredSecrets
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Stored Secrets
      summary: Create a Stored Secret
      description: >
        Create a new Stored Secret within a Network Group.

        The caller must have create permission for StoredSecret resources in the
        specified Network Group.

        If a value is provided, it is stored immediately; otherwise the secret
        metadata is created and the

        value can be set later via the one-time token (OTT) flow.
      operationId: createStoredSecret
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Details of the Stored Secret to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStoredSecret'
            examples:
              generic-no-value:
                description: >-
                  Create a GENERIC secret without an initial value (value can be
                  set later via OTT).
                value:
                  networkGroupId: 11111111-2222-3333-4444-555555555555
                  name: my-ssh-key
              private-key-with-value:
                description: >-
                  Create a PRIVATE_KEY secret providing a PEM-formatted private
                  key value.
                value:
                  networkGroupId: 11111111-2222-3333-4444-555555555555
                  name: my-ssh-key
                  type: PRIVATE_KEY
                  value: |-
                    -----BEGIN PRIVATE KEY-----
                    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
                    -----END PRIVATE KEY-----
        required: true
      responses:
        '200':
          description: >
            Returns the created Stored Secret resource (value is never
            returned).

            The caller must have create permission on the StoredSecret resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret response
                  value: |-
                    {
                      "id" : "c4ca3def-4c2f-4ad4-8187-3d67a18f4bbc",
                      "createdBy" : "73bd5ded-62ac-4194-857a-bf650ea01be0",
                      "createdAt" : "2025-12-05T15:20:06.019921Z",
                      "updatedAt" : "2025-12-05T15:20:06.019921Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "Test Name H4rMP5b9TxlqeGBSoZjzU",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "b7560740-0100-4c32-8e12-34d10d2782ba",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "_links" : {
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/b7560740-0100-4c32-8e12-34d10d2782ba",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/c4ca3def-4c2f-4ad4-8187-3d67a18f4bbc",
                          "title" : "Test Name H4rMP5b9TxlqeGBSoZjzU"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/ac6e9e71-2a35-477c-9d80-f6ee051bc27d",
                          "title" : "Create StoredSecret",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getStoredSecret
              parameters:
                id: $response.body#/id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/software-deployment-states/{id}/refresh:
    post:
      tags:
        - Software Deployment States
      summary: Refresh Software State
      description: >
        Schedules a background refresh of Software Deployment State for the
        specified resource.

        The caller must have update permission on the SoftwareDeploymentState
        resource.
      operationId: refreshSoftwareState
      parameters:
        - name: id
          in: path
          description: The unique identifier of the SoftwareDeploymentState to refresh.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '204':
          description: Refresh scheduled; no content returned.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/software-deployment-states/refresh:
    post:
      tags:
        - Software Deployment States
      summary: Refresh Software State in Network
      description: >
        Schedules a background refresh of Software Deployment State for all
        resources in the specified Network.

        The caller must have update permission on the Network resource.
      operationId: refreshSoftwareStateInNetwork
      parameters:
        - name: networkId
          in: query
          description: >-
            The unique identifier of the Network whose software state should be
            refreshed.
          required: true
          schema:
            type: string
            format: uuid
          example: 11111111-2222-3333-4444-555555555555
      responses:
        '204':
          description: Refresh scheduled; no content returned.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/upgrade:
    post:
      tags:
        - Network Upgrades
      summary: Upgrade a Network
      description: >-
        Initiates an upgrade for a network and its components. The behavior of
        the upgrade is determined by the `UpgradeNetwork` object in the request
        body.
      operationId: upgradeNetwork
      parameters:
        - name: id
          in: path
          description: The ID of the Network to upgrade.
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Specifies the details of the network upgrade.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeNetwork'
            examples:
              Full Upgrade:
                description: >-
                  Upgrade the network controllers and all edge routers to
                  version 8.3.0.
                value:
                  target: 8.3.0
                  upgradeMode: FULL
              Edge Routers Only:
                description: Upgrade only the edge routers to the latest version.
                value:
                  upgradeMode: EDGE_ROUTERS_ONLY
              Concurrent Controller Upgrade:
                description: Upgrade all network controllers concurrently.
                value:
                  target: 8.3.0
                  upgradeMode: CONTROLLERS_ONLY
                  concurrentControllerUpgrades: true
        required: true
      responses:
        '202':
          description: The upgrade request has been accepted and is in progress.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Network'
              examples:
                default:
                  description: Example Network Upgrade response
                  value: |-
                    {
                      "id" : "80ee8155-1e94-4238-b63b-6af81c332a51",
                      "ownerIdentityId" : "9caccc42-dfea-409b-ab0b-820ff0251d13",
                      "createdBy" : "9caccc42-dfea-409b-ab0b-820ff0251d13",
                      "createdAt" : "2025-11-13T23:56:36.713181Z",
                      "updatedAt" : "2025-11-13T23:56:36.724485Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "upgrade-network-0",
                      "networkGroupId" : "1e6f7f03-3f7d-4b23-a1a0-9509edc5d99b",
                      "size" : "small",
                      "productVersion" : "8.0.90",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : false,
                      "haEnabled" : false,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/80ee8155-1e94-4238-b63b-6af81c332a51",
                          "title" : "upgrade-network-0"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/1e6f7f03-3f7d-4b23-a1a0-9509edc5d99b",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "service-policies" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/service-policies?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "certificate-authorities" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/certificate-authorities?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "services" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/services?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "service-edge-router-policies" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/service-edge-router-policies?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "edge-router-policies" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-router-policies?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "app-wans" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/app-wans?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "process-executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/process-executions?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "configs" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/configs?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "endpoints" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/endpoints?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "terminators" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/terminators?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "config-types" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/config-types?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        },
                        "posture-checks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/posture-checks?networkId=80ee8155-1e94-4238-b63b-6af81c332a51"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/restore:
    post:
      tags:
        - Networks
      summary: Restore a backup from a file in S3
      description: >
        Restore a backup from a file in S3. If you specify 'latest' for the
        filename, this endpoint restores the latest backup.

        Note for HA networks, all controllers in the network will be updated to
        the specified backup version.

        The caller must have the update-restore permission on the specified
        Network.
      operationId: restoreNetworkFromBackup
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          Payload specifying the backup file to restore. If omitted or fileName
          is null/empty, the latest backup will be restored.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreBackup'
            examples:
              file-by-name:
                description: Restore a specific backup file
                value:
                  fileName: backup-2025-10-01T12-00-00Z.tar.gz
              latest:
                description: Restore the latest backup by omitting fileName
                value: {}
        required: true
      responses:
        '202':
          description: Accepted. Network restore from backup has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "1c9f20d0-5f14-4880-aa17-0794651a8243",
                      "ownerIdentityId" : "e1e06406-f9cc-4756-a532-25284b5c575e",
                      "createdBy" : "e1e06406-f9cc-4756-a532-25284b5c575e",
                      "createdAt" : "2025-12-05T15:19:41.871093Z",
                      "updatedAt" : "2025-12-05T15:19:42.065909Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-764",
                      "networkGroupId" : "b45b8e8f-f2a8-4f50-93b6-44d159ecf878",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "UPDATING",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/1c9f20d0-5f14-4880-aa17-0794651a8243",
                          "title" : "network-764"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/b45b8e8f-f2a8-4f50-93b6-44d159ecf878",
                          "profile" : "parent"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks",
                          "profile" : "parent"
                        },
                        "network-jwt-sets" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-jwt-sets/1c9f20d0-5f14-4880-aa17-0794651a8243"
                        },
                        "edge-routers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers?networkId=1c9f20d0-5f14-4880-aa17-0794651a8243"
                        },
                        "hosts" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts?networkId=1c9f20d0-5f14-4880-aa17-0794651a8243"
                        },
                        "network-controllers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers?networkId=1c9f20d0-5f14-4880-aa17-0794651a8243"
                        },
                        "executions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions?networkId=1c9f20d0-5f14-4880-aa17-0794651a8243"
                        },
                        "clusters" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/clusters?networkId=1c9f20d0-5f14-4880-aa17-0794651a8243"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/backups:
    get:
      tags:
        - Networks
      summary: List existing backups for the network
      description: List all existing backups for the specified Network.
      operationId: getNetworkBackups
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Backup'
              examples:
                backups:
                  description: Example list of backups
                  value: |-
                    {
                      "_embedded" : {
                        "backupList" : [ {
                          "name" : "217dc953-0c07-46c7-b82b-90d20033465c/5323924c-975b-4886-ad00-e0097fceddaa/file.1.gpg",
                          "lastModified" : "2025-12-05T15:19:17.443600Z",
                          "size" : 123
                        } ]
                      },
                      "_links" : {
                        "parent" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/217dc953-0c07-46c7-b82b-90d20033465c"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $request.path.id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Networks
      summary: Create a backup for all controllers in the network
      description: >
        Create a backup for all controllers in the specified Network. The
        operation is asynchronous and returns the Network resource with related
        links.

        The caller must have the update-backup permission on the specified
        Network.
      operationId: createNetworkBackup
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network backup has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Network response
                  value: |-
                    {
                      "id" : "f40d685c-88ee-4540-802c-f22c04658ead",
                      "ownerIdentityId" : "a956eb82-b8cc-4389-9e95-61d58bc61abe",
                      "createdBy" : "a956eb82-b8cc-4389-9e95-61d58bc61abe",
                      "createdAt" : "2025-12-05T15:18:54.275017Z",
                      "updatedAt" : "2025-12-05T15:18:54.291470Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "network-482",
                      "networkGroupId" : "47093983-fbe9-49ee-81bd-3f87e7623ee8",
                      "size" : "small",
                      "productVersion" : "8.0.43",
                      "region" : "us-east-1",
                      "status" : "PROVISIONED",
                      "publicCertEnabled" : true,
                      "haEnabled" : true,
                      "dnsZoneId" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/f40d685c-88ee-4540-802c-f22c04658ead",
                          "title" : "network-482"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/47093983-fbe9-49ee-81bd-3f87e7623ee8",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-groups:
    get:
      tags:
        - Network Groups
      summary: Find Network Groups
      description: >
        Returns Network Groups matching the optional query parameters. Results
        are filtered to only include resources the caller may read.
      operationId: findNetworkGroups
      parameters:
        - name: id
          in: query
          description: Filter by Network Group ID(s). Repeat to specify multiple.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: name
          in: query
          description: Filter by exact name(s). Repeat to specify multiple.
          example: engineering-networks
        - name: shortName
          in: query
          description: Filter by short name(s).
          example: eng123
        - name: billingAccountId
          in: query
          description: Filter by Billing Account ID(s).
          example: 11111111-2222-3333-4444-555555555555
        - name: ownerIdentityId
          in: query
          description: Filter by Owner Identity ID(s).
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: createdBy
          in: query
          description: Filter by creator identity ID(s).
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID(s).
          example: dddddddd-eeee-ffff-1111-222222222222
        - name: createdAt
          in: query
          description: >-
            Created-at filter expressions. Supports >, >=, <, <=, =, != (e.g.,
            createdAt=>=2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Deleted-at filter expressions.
          example: '>2025-10-01T00:00:00Z'
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., name,updatedAt,desc.
          example: name,asc
      responses:
        '200':
          description: A paginated list of network groups.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find network groups response
                  value: |-
                    {
                      "_embedded" : {
                        "networkGroupList" : [ {
                          "id" : "50deab14-9dc9-49b2-8ad3-fcb9c332f10c",
                          "name" : "Test-NG",
                          "shortName" : "nw-7641",
                          "billingAccountId" : "a8d8e318-22e9-40e5-8b28-3077a5e60a27",
                          "ownerIdentityId" : "db041d3e-aa20-45a7-aede-503dc2d6c13b",
                          "createdBy" : "c61829f9-1949-42cf-8660-ea688af61481",
                          "createdAt" : "2025-11-17T16:25:59.766564Z",
                          "updatedAt" : "2025-11-17T16:25:59.805406Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/50deab14-9dc9-49b2-8ad3-fcb9c332f10c",
                              "title" : "Test-NG"
                            },
                            "networks" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=50deab14-9dc9-49b2-8ad3-fcb9c332f10c"
                            },
                            "dns-zones" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=50deab14-9dc9-49b2-8ad3-fcb9c332f10c"
                            }
                          }
                        }, {
                          "id" : "abb73aa1-649e-4ff2-b82d-7dbaa7cdb7ba",
                          "name" : "Test-NG",
                          "shortName" : "nw-7721",
                          "billingAccountId" : "4286e3bd-83a4-4a74-9ea6-df43a0ad7648",
                          "ownerIdentityId" : "aa0e33c5-9526-457d-8c14-5d41d0284e7b",
                          "createdBy" : "ebb82001-fdb1-4a1d-a9da-30d7747607de",
                          "createdAt" : "2025-11-17T16:26:00.082643Z",
                          "updatedAt" : "2025-11-17T16:26:00.082643Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/abb73aa1-649e-4ff2-b82d-7dbaa7cdb7ba",
                              "title" : "Test-NG"
                            },
                            "networks" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=abb73aa1-649e-4ff2-b82d-7dbaa7cdb7ba"
                            },
                            "dns-zones" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=abb73aa1-649e-4ff2-b82d-7dbaa7cdb7ba"
                            }
                          }
                        }, {
                          "id" : "cc99d3d0-8254-4749-af29-58086fe5623e",
                          "name" : "Updated NG Name-767",
                          "shortName" : "nw-7691",
                          "billingAccountId" : "39e0a8de-bf1c-4ec7-b0ab-bb32759ffdf8",
                          "ownerIdentityId" : "50ddbd4b-4d84-48c1-8c7d-740184987c81",
                          "createdBy" : "55e0291e-cc12-4458-a9ee-6d3e9ba49f79",
                          "createdAt" : "2025-11-17T16:25:59.929869Z",
                          "updatedAt" : "2025-11-17T16:25:59.948231Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/cc99d3d0-8254-4749-af29-58086fe5623e",
                              "title" : "Updated NG Name-767"
                            },
                            "networks" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                            },
                            "dns-zones" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=cc99d3d0-8254-4749-af29-58086fe5623e"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 3,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
          links:
            self:
              operationId: findNetworkGroups
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Groups
      summary: Create a Network Group
      description: >-
        Creates a new Network Group. Requires the caller to have create
        NetworkGroup permission.
      operationId: createNetworkGroup
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Group creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetworkGroup'
            examples:
              basic:
                description: basic
                value:
                  name: engineering-networks
                  billingAccountId: 11111111-2222-3333-4444-555555555555
                  ownerIdentityId: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        required: true
      responses:
        '200':
          description: Network Group created
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample create network group response
                  value: |-
                    {
                      "id" : "8916be5a-e9fc-4e69-8b45-366529c60356",
                      "name" : "New NG",
                      "shortName" : "NEWNG",
                      "billingAccountId" : "6a528dd4-e082-4e7e-9598-1851662c5150",
                      "ownerIdentityId" : "c028edcc-f537-429e-862d-f6ea14863a89",
                      "createdBy" : "811b10d1-c77a-46ac-96f9-165a43bf359e",
                      "createdAt" : "2025-11-17T16:26:00.180419Z",
                      "updatedAt" : "2025-11-17T16:26:00.180419Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/8916be5a-e9fc-4e69-8b45-366529c60356",
                          "title" : "New NG"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/681ea7c7-dbc5-4531-90bf-a981efcc146d",
                          "title" : "Create NetworkGroup",
                          "profile" : "meta"
                        },
                        "networks" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks?networkGroupId=8916be5a-e9fc-4e69-8b45-366529c60356"
                        },
                        "dns-zones" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones?networkGroupId=8916be5a-e9fc-4e69-8b45-366529c60356"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            self:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/upgrade:
    post:
      tags:
        - Network Controller Upgrades
      summary: Upgrade a Network Controller
      description: >-
        Initiates an upgrade for a specific Network Controller. The target
        version must be provided in the request body.
      operationId: upgradeNetworkController
      parameters:
        - name: id
          in: path
          description: The ID of the Network Controller to upgrade.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Specifies the target version for the upgrade.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeNetworkController'
            examples:
              Specific Version:
                description: Specific Version
                value:
                  target: 8.3.0
        required: true
      responses:
        '202':
          description: The upgrade has been accepted and is in progress.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller Upgrade response
                  value: |-
                    {
                      "id" : "b358be3f-f32a-4ece-8c8a-3fccca61a2fe",
                      "ownerIdentityId" : "8140fe43-9786-41ee-a2f7-8f75bca0062b",
                      "networkId" : "b44db455-a09a-4b18-adf7-fe3a5cc5872c",
                      "domainName" : "b358be3f-f32a-4ece-8c8a-3fccca61a2fe.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "network-2029-nc",
                      "productVersion" : "8.0.14",
                      "hostId" : "da87223e-e1cd-44c0-85e1-330d6a500930",
                      "status" : "PROVISIONED",
                      "createdAt" : "2025-12-05T15:22:03.852640Z",
                      "updatedAt" : "2025-12-05T15:22:03.865111Z",
                      "deletedAt" : null,
                      "createdBy" : "8140fe43-9786-41ee-a2f7-8f75bca0062b",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "cad3e691-62d0-4b2d-b970-9b7541029971",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/b358be3f-f32a-4ece-8c8a-3fccca61a2fe",
                          "title" : "network-2029-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/cad3e691-62d0-4b2d-b970-9b7541029971"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/da87223e-e1cd-44c0-85e1-330d6a500930"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/b44db455-a09a-4b18-adf7-fe3a5cc5872c",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/restore:
    post:
      tags:
        - Network Controllers
      summary: Restore a backup for the network controller
      description: >
        Restore a network controller from a backup file in S3. If you specify
        'latest' for the filename, this endpoint restores the latest backup.

        The caller must have the update-restore permission on the specified
        Network Controller
      operationId: restoreNetworkControllerFromBackup
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreBackup'
            examples: {}
        required: true
      responses:
        '202':
          description: Accepted. Network Controller restore from backup has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: Example Network Controller response
                  value: |-
                    {
                      "id" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "ownerIdentityId" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : "new-domain.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "updatedControllerName-2177",
                      "productVersion" : "7.4.5",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "status" : "PROVISIONED",
                      "createdAt" : "2025-11-17T16:28:15.654202Z",
                      "updatedAt" : "2025-11-17T16:28:21.692088Z",
                      "deletedAt" : null,
                      "createdBy" : "fd4855dd-6ead-4095-88bd-13a2e881751e",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "6306a463-1c49-4134-9257-6b80993cd50c",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/hosts/0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117",
                          "title" : "updatedControllerName-2177"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6306a463-1c49-4134-9257-6b80993cd50c",
                          "deprecation" : "Use software-deployment-state link instead"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/backups:
    get:
      tags:
        - Network Controllers
      summary: List existing backups for the network controller
      description: >
        List all existing backups for the specified network controller.

        The caller must have the update-backup permission on the specified
        Network Controller.
      operationId: listNetworkControllerBackups
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller
          required: true
          schema:
            type: string
            format: uuid
          examples:
            example-id:
              description: example-id
              value: 2f1b4a2e-9a2b-4c53-9e6c-9f1e8b6a7c21
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Backup'
              examples:
                backups:
                  description: Example list of backups
                  value:
                    - name: backup-2025-10-01T12-00-00Z.tar.gz
                      lastModified: '2025-10-01T12:00:10Z'
                      size: 10485760
                    - name: backup-2025-10-02T12-00-00Z.tar.gz
                      lastModified: '2025-10-02T12:00:05Z'
                      size: 15728640
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Create a backup for the network controller
      description: >
        Create a backup for the network controller and store the backup file in
        S3.

        The caller must have the update-backup permission on the specified
        Network Controller.
      operationId: createNetworkControllerBackup
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller
          required: true
          schema:
            type: string
            format: uuid
        - name: nf-validate
          in: header
          schema:
            type: string
      responses:
        '202':
          description: Accepted. Network Controller create backup has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                network-controller:
                  description: Example Network Controller response with links
                  value: |-
                    {
                      "id" : "34357c00-b3d5-4055-85b0-23cc63bc765f",
                      "ownerIdentityId" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "networkId" : "dd64a3e3-1342-4006-9d67-93c06a8c462b",
                      "domainName" : "34357c00-b3d5-4055-85b0-23cc63bc765f.nf.io",
                      "alternateDomainName" : null,
                      "port" : 443,
                      "name" : "networkcontroller-v3-controller-test-nc",
                      "productVersion" : "8.0.43",
                      "hostId" : "6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce",
                      "status" : "UPDATING",
                      "createdAt" : "2025-12-05T15:18:36.128508Z",
                      "updatedAt" : "2025-12-05T15:18:39.176349Z",
                      "deletedAt" : null,
                      "createdBy" : "bbd3174d-5c9c-41e2-b0bd-ca520896d3d1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : "fc1d78d3-117b-4cb9-bb99-a33ba5518cda",
                      "haPrimaryNode" : true,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f",
                          "title" : "networkcontroller-v3-controller-test-nc"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/fc1d78d3-117b-4cb9-bb99-a33ba5518cda"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/6f9a22fa-03c0-41cf-98c2-8c9ddb37f7ce"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/dd64a3e3-1342-4006-9d67-93c06a8c462b",
                          "profile" : "parent"
                        },
                        "softwareDeploymentState" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/fc1d78d3-117b-4cb9-bb99-a33ba5518cda",
                          "deprecation" : "Use software-deployment-state link instead"
                        },
                        "parent" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-controllers/34357c00-b3d5-4055-85b0-23cc63bc765f"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers:
    get:
      tags:
        - Network Controllers
      summary: Find Network Controllers
      description: >
        Find all Network Controllers that match the specified criteria.

        Instances that the API client does not have authorization to read will
        be removed from the results.

        As a side effect, this endpoint never returns a 403 or 404 error.
        Instead, it returns an empty list.
      operationId: findNetworkControllers
      parameters:
        - name: id
          in: query
          description: Filter by Network Controller ID.
          schema:
            type: string
            format: uuid
        - name: name
          in: query
          description: Filter by name.
          schema:
            type: string
        - name: networkId
          in: query
          description: Filter by Network ID.
          schema:
            type: string
            format: uuid
        - name: productVersion
          in: query
          description: Filter by product version.
          schema:
            type: string
        - name: hostId
          in: query
          description: Filter by Host ID.
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          description: Filter by controller status.
          schema:
            type: string
            description: >-
              Enumerates lifecycle and operational states for Core resources
              (e.g., Edge Routers, Network Controllers, Networks). Useful for
              clients to track long-running operations and final states.
            enum:
              - NEW
              - PROVISIONING
              - PROVISIONED
              - ERROR
              - UPDATING
              - SUSPENDED
              - REPLACING
              - DELETING
              - DELETED
              - OFFLINE
            example: PROVISIONED
        - name: domainName
          in: query
          description: Filter by domain name.
          schema:
            type: string
        - name: alternateDomainName
          in: query
          description: Filter by alternate domain name.
          schema:
            type: string
        - name: port
          in: query
          description: Filter by port.
          schema:
            type: integer
        - name: ownerIdentityId
          in: query
          description: Filter by owner identity ID.
          schema:
            type: string
            format: uuid
        - name: createdBy
          in: query
          description: Filter by creator identity ID.
          schema:
            type: string
            format: uuid
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID.
          schema:
            type: string
            format: uuid
        - name: publicCertEnabled
          in: query
          description: Filter by whether public certificates are enabled.
          schema:
            type: boolean
        - name: createdAt
          in: query
          description: >-
            Filter by creation timestamp using InstantFilter syntax, e.g.,
            >2025-01-01T00:00:00Z.
          schema:
            type: string
        - name: updatedAt
          in: query
          description: Filter by update timestamp using InstantFilter syntax.
          schema:
            type: string
        - name: deletedAt
          in: query
          description: Filter by deletion timestamp using InstantFilter syntax.
          schema:
            type: string
        - name: page
          in: query
          description: Zero-based page index.
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: size
          in: query
          description: The number of resources returned per page.
          schema:
            type: integer
            default: 20
            minimum: 1
        - name: sort
          in: query
          description: 'Sorting criteria in the format: property,(asc|desc).'
          schema:
            type: string
        - name: isDeleted
          in: query
          required: false
          deprecated: true
          schema:
            type: boolean
      responses:
        '200':
          description: A paginated list of Network Controllers.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Network Controllers
      summary: Create a Network Controller
      description: >
        Create a new Network Controller. The `provider` field determines if
        NetFoundry or the customer hosts the controller.

        The caller must have create permission on Network resources. If the
        provider is `CUSTOMER`, the caller must also have
        `create-customer-hosted` authorization.
      operationId: createNetworkController
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Network Controller creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetworkController'
            examples:
              default:
                description: default
                value: >-
                  {"networkId":"80caaf72-e1bd-4dee-8db2-efda13114dd1","name":"createNetworkController-2142","hostSize":"small","provider":"AWS","region":"us-east-1","haVotingMember":false}
        required: true
      responses:
        '202':
          description: Accepted. Network Controller creation has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NetworkController'
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "id" : "cd3f367e-4baa-4610-9d80-9852d84eca7b",
                      "ownerIdentityId" : "8612b1d6-dea0-471b-a1ed-b0ecf63c09f1",
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "port" : 8443,
                      "name" : "createNetworkController-2142",
                      "productVersion" : "7.4.5",
                      "hostId" : null,
                      "status" : "PROVISIONING",
                      "createdAt" : "2025-11-17T16:28:20.008782Z",
                      "updatedAt" : "2025-11-17T16:28:20.008782Z",
                      "deletedAt" : null,
                      "createdBy" : "8612b1d6-dea0-471b-a1ed-b0ecf63c09f1",
                      "deletedBy" : null,
                      "softwareDeploymentStateId" : null,
                      "haPrimaryNode" : false,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/cd3f367e-4baa-4610-9d80-9852d84eca7b",
                          "title" : "createNetworkController-2142"
                        }
                      }
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: >-
                The SoftwareDeploymentState resource for this Network
                Controller.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Network Controller.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/host-addresses:
    get:
      tags:
        - Host Addresses
      summary: Find Cloud Addresses
      description: >-
        Returns reserved Host addresses within the specified Network, optionally
        filtered by cloud provider and region. Results are filtered to only
        include resources the caller may read.
      operationId: findCloudAddresses
      parameters:
        - name: provider
          in: query
          description: Filter to cloud provider(s). Repeat to specify multiple.
          required: false
          schema:
            type: array
            items:
              type: string
              description: >-
                Enumerates supported cloud provider keys used throughout the
                API.
              enum:
                - AWS
                - AZURE
                - GCP
                - OCI
                - CUSTOMER
              example: AWS
          example: AWS
        - name: networkId
          in: query
          description: Network ID to scope the search.
          required: true
          schema:
            type: string
            format: uuid
          example: 11111111-2222-3333-4444-555555555555
        - name: region
          in: query
          description: Filter by cloud region code.
          required: false
          schema:
            type: string
          example: us-east-1
      responses:
        '200':
          description: A collection of HostAddress resources within the Network.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find cloud addresses response
                  value: |-
                    {
                      "_embedded" : {
                        "hostAddressList" : [ {
                          "ip" : "1.2.3.4",
                          "networkId" : "b941e6b5-209a-4075-9a0f-9abcabc83107",
                          "provider" : "AWS",
                          "region" : "us-east-1",
                          "createdAt" : "2025-11-17T16:33:16.416805Z",
                          "expiresAt" : "2025-11-27T16:33:16.416806Z",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses/1.2.3.4"
                            },
                            "addresses" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=b941e6b5-209a-4075-9a0f-9abcabc83107"
                            }
                          }
                        }, {
                          "ip" : "2.3.4.5",
                          "networkId" : "b941e6b5-209a-4075-9a0f-9abcabc83107",
                          "provider" : "GCP",
                          "region" : "us-east1",
                          "createdAt" : "2025-11-17T16:33:16.416816Z",
                          "expiresAt" : "2025-11-27T16:33:16.416816Z",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses/2.3.4.5"
                            },
                            "addresses" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=b941e6b5-209a-4075-9a0f-9abcabc83107"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=b941e6b5-209a-4075-9a0f-9abcabc83107"
                        }
                      },
                      "page" : {
                        "size" : 2,
                        "totalElements" : 2,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
          links:
            self:
              operationId: findCloudAddresses
              parameters:
                networkId: $request.query#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Host Addresses
      summary: Allocate Cloud Address
      description: >
        Reserves a public IP address with the specified cloud provider and
        region within the given Network.

        The caller must have create permission for Networks.
      operationId: allocateCloudAddress
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: Cloud address allocation payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocateCloudAddress'
            examples:
              aws-east-1:
                description: aws-east-1
                value:
                  provider: AWS
                  networkId: 11111111-2222-3333-4444-555555555555
                  region: us-east-1
        required: true
      responses:
        '200':
          description: Cloud address allocated.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample allocate cloud address response
                  value: |-
                    {
                      "ip" : "1.2.3.4",
                      "networkId" : "ec4c4313-4818-4385-88cd-9ad2f24f00b6",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "createdAt" : "2025-11-17T16:33:15.894872Z",
                      "expiresAt" : "2025-11-27T16:33:15.894883Z",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses/1.2.3.4"
                        },
                        "addresses" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=ec4c4313-4818-4385-88cd-9ad2f24f00b6"
                        }
                      }
                    }
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
                uniqueItems: true
              examples: {}
          links:
            addresses:
              operationId: findCloudAddresses
              parameters:
                networkId: $response.body#/networkId
            self:
              operationId: getCloudAddress
              parameters:
                ip: $response.body#/ip
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/upgrade:
    post:
      tags:
        - Edge Router Upgrades
      summary: Upgrade an Edge Router
      description: >-
        Initiates an upgrade process for a specific edge router. You can specify
        the target version in the request body. If you omit the version, the
        edge router will be upgraded to the latest version available for the
        network.
      operationId: upgradeEdgeRouter
      parameters:
        - name: id
          in: path
          description: The ID of the Edge Router to upgrade.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: >-
          Specifies the target version for the upgrade. If omitted, the edge
          router will be upgraded to the latest version available for the
          network.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeEdgeRouter'
            examples:
              Specific Version:
                description: Specific Version
                value:
                  target: 8.3.0
      responses:
        '202':
          description: The upgrade has been accepted and is in progress.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EdgeRouter'
              examples:
                default:
                  description: Example Edge Router Upgrade response
                  value: |-
                    {
                      "id" : "444d4fb9-dd4c-47f7-909d-afcf14bc1c86",
                      "hostId" : "8a57ea2d-e715-40b0-a9f1-e034d7f82b98",
                      "ownerIdentityId" : "9c78234e-700b-4c2c-b1ad-0e26d09b165e",
                      "createdBy" : "9c78234e-700b-4c2c-b1ad-0e26d09b165e",
                      "createdAt" : "2025-12-05T15:22:14.561735Z",
                      "updatedAt" : "2025-12-05T15:22:15.423833Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-2060",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "444d4fb9-dd4c-47f7-909d-afcf14bc1c86-p.fake.netfoundry.io",
                      "name" : "edgerouter-2061",
                      "productVersion" : "8.4.1",
                      "networkId" : "c767548f-8b2e-47fe-877d-1a1b3148999c",
                      "jwt" : null,
                      "linkListener" : true,
                      "online" : false,
                      "verified" : false,
                      "status" : "PROVISIONED",
                      "softwareDeploymentStateId" : "25950230-8682-41f0-8449-65e99ae79cf6",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/444d4fb9-dd4c-47f7-909d-afcf14bc1c86",
                          "title" : "edgerouter-2061"
                        },
                        "software-deployment-state" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/software-deployment-states/25950230-8682-41f0-8449-65e99ae79cf6"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/c767548f-8b2e-47fe-877d-1a1b3148999c",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/8a57ea2d-e715-40b0-a9f1-e034d7f82b98"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body#/softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body#/hostId
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/reissue:
    post:
      tags:
        - Edge Routers
      summary: Reissue Edge Router certificate or enrollment
      description: >
        Reissues the Edge Router's certificate or re-enrolls the Edge Router,
        depending on network features and current verification state.

        The operation is asynchronous and returns the Edge Router resource with
        related links.

        The caller must have update permissions sufficient to create an Edge
        Router certificate (create on Edge Router within the Network).
      operationId: reissueEdgeRouter
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router to reissue
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '202':
          description: Accepted. Edge Router reissue has been scheduled.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                re-enroll:
                  description: >-
                    Example Edge Router response when re-enrolling a verified,
                    customer-hosted router
                  value: |-
                    {
                      "id" : "584bd777-9e6b-4929-89da-221358d527b8",
                      "hostId" : "d60f945b-0ecf-44ae-9079-8fd181bd9cd1",
                      "ownerIdentityId" : "418c1479-99df-4622-8a3c-ac554c6b0745",
                      "createdBy" : "418c1479-99df-4622-8a3c-ac554c6b0745",
                      "createdAt" : "2025-12-05T15:20:26.868188Z",
                      "updatedAt" : "2025-12-05T15:20:26.905964Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "zitiId" : "ziti-id-1714",
                      "domainName" : null,
                      "alternateDomainName" : null,
                      "publicDomainName" : "584bd777-9e6b-4929-89da-221358d527b8-p.fake.netfoundry.io",
                      "name" : "edgerouter-1715",
                      "productVersion" : "7.3.69",
                      "networkId" : "21a4480c-9344-4432-8cb5-142c6469c547",
                      "jwt" : null,
                      "linkListener" : true,
                      "tunnelerEnabled" : true,
                      "noTraversal" : false,
                      "online" : false,
                      "verified" : false,
                      "status" : "PROVISIONED",
                      "softwareDeploymentStateId" : null,
                      "provider" : "CUSTOMER",
                      "region" : "us-east-1",
                      "hostSize" : "small",
                      "attributes" : [ ],
                      "registration" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/584bd777-9e6b-4929-89da-221358d527b8",
                          "title" : "edgerouter-1715"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/21a4480c-9344-4432-8cb5-142c6469c547",
                          "profile" : "parent"
                        },
                        "host" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/d60f945b-0ecf-44ae-9079-8fd181bd9cd1"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/d4289831-4a4f-40c1-9d8b-48f18fb473e4",
                          "title" : "Update EdgeRouter",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
            software-deployment-state:
              operationId: getSoftwareDeploymentState
              parameters:
                id: $response.body.softwareDeploymentStateId
              description: The SoftwareDeploymentState resource for this Edge Router.
            host:
              operationId: getHost
              parameters:
                id: $response.body.hostId
              description: The Host resource for this Edge Router.
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/dns-zones/{id}/validate:
    post:
      tags:
        - Dns Zones
      summary: Validate DnsZone
      description: >
        Validates the DNS Zone by comparing public DNS TXT records against the
        provider's hosted zone records.

        Returns a validation result indicating success or the failure reason.

        The caller must have update permission on the DnsZone resource.
      operationId: validateDnsZone
      parameters:
        - name: id
          in: path
          description: The unique identifier of the DnsZone to validate.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: DnsZone validation result returned.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample validate DnsZone response
                  value: |-
                    {
                      "valid" : false,
                      "failureMessage" : "No public txt record found"
                    }
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/dns-zones:
    get:
      tags:
        - Dns Zones
      summary: Find DnsZones
      description: >-
        Returns DnsZones matching the optional query parameters. Results are
        filtered to only include resources the caller may read.
      operationId: findDnsZones
      parameters:
        - name: id
          in: query
          description: Filter by DnsZone ID(s).
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: networkGroupId
          in: query
          description: Filter by Network Group ID(s).
          example: 11111111-2222-3333-4444-555555555555
        - name: name
          in: query
          description: Filter by DnsZone name(s).
          example: corp-zone
        - name: route53ZoneId
          in: query
          description: Filter by provider hosted zone identifier(s).
          example: Z04008363AMXYS4T3J7OB
        - name: domain
          in: query
          description: Filter by root domain(s). Supports % wildcard.
          example: example.com
        - name: validated
          in: query
          description: Filter by validation status.
          example: true
        - name: createdBy
          in: query
          description: Filter by creator identity ID(s).
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID(s).
          example: dddddddd-eeee-ffff-1111-222222222222
        - name: createdAt
          in: query
          description: >-
            Created-at filter expressions. Supports >, >=, <, <=, =, != (e.g.,
            createdAt=>=2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Deleted-at filter expressions.
          example: '>2025-10-01T00:00:00Z'
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., name,updatedAt,desc.
          example: name,asc
      responses:
        '200':
          description: A paginated list of DnsZones.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find DnsZones response
                  value: |-
                    {
                      "_embedded" : {
                        "dnsZoneList" : [ {
                          "id" : "2d1c33ec-e98d-4074-bbcd-4e2b6b451945",
                          "networkGroupId" : "d744a5e9-387c-4cbc-a303-cb6af4b772e7",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1942",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "d202f524-7f3b-4c35-ae13-e030202c0c6b",
                          "createdAt" : "2025-12-05T15:21:17.308445Z",
                          "updatedAt" : "2025-12-05T15:21:17.308445Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/2d1c33ec-e98d-4074-bbcd-4e2b6b451945",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/d744a5e9-387c-4cbc-a303-cb6af4b772e7",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "459a527a-6de6-4d3f-a3fd-b2538ccc0f29",
                          "networkGroupId" : "99c27478-ae51-4535-b9a9-74289881bc43",
                          "name" : "firstName-1931",
                          "route53ZoneId" : "zoneId-1932",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "185a9c85-afb7-431b-b6b0-5793b2fe8039",
                          "createdAt" : "2025-12-05T15:21:17.141968Z",
                          "updatedAt" : "2025-12-05T15:21:17.141968Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/459a527a-6de6-4d3f-a3fd-b2538ccc0f29",
                              "title" : "firstName-1931"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/99c27478-ae51-4535-b9a9-74289881bc43",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "4dcbe027-c3bb-4c1e-8f51-f0bf750cc74a",
                          "networkGroupId" : "fa7ab687-e791-47fd-a239-28e1383b00ac",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1938",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "e65ff7ae-b96e-4572-be67-4e9f05fd3791",
                          "createdAt" : "2025-12-05T15:21:17.195446Z",
                          "updatedAt" : "2025-12-05T15:21:17.195446Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/4dcbe027-c3bb-4c1e-8f51-f0bf750cc74a",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/fa7ab687-e791-47fd-a239-28e1383b00ac",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "73c2040e-4e9c-4123-9d96-2c2ec3aeb330",
                          "networkGroupId" : "19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1925",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "ed206c83-7e8b-492e-9ee8-9fe5ef4f50a7",
                          "createdAt" : "2025-12-05T15:21:17.011654Z",
                          "updatedAt" : "2025-12-05T15:21:17.011654Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/73c2040e-4e9c-4123-9d96-2c2ec3aeb330",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "7b63d2c4-2f7c-462d-bf71-f8bd4752455a",
                          "networkGroupId" : "2dd67abf-abdf-46ea-a0c5-5aeef81f5447",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1911",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "47ad074f-2f7d-4066-bd94-f320e86bdda2",
                          "createdAt" : "2025-12-05T15:21:16.828933Z",
                          "updatedAt" : "2025-12-05T15:21:16.828933Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/7b63d2c4-2f7c-462d-bf71-f8bd4752455a",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/2dd67abf-abdf-46ea-a0c5-5aeef81f5447",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "877b756d-8d9d-47b6-bddb-a9c561c758f9",
                          "networkGroupId" : "99c27478-ae51-4535-b9a9-74289881bc43",
                          "name" : "toUpdate-1933",
                          "route53ZoneId" : "zoneId-1934",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "704536cb-958a-444d-ad4e-a5aa34049c58",
                          "createdAt" : "2025-12-05T15:21:17.145112Z",
                          "updatedAt" : "2025-12-05T15:21:17.145112Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/877b756d-8d9d-47b6-bddb-a9c561c758f9",
                              "title" : "toUpdate-1933"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/99c27478-ae51-4535-b9a9-74289881bc43",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "8a48d038-24d9-4ece-bc79-fe96d0134fc6",
                          "networkGroupId" : "892632d0-0be5-49e9-86d2-19a45dfad558",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1919",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "c084599a-1a54-489a-882f-7528a79da399",
                          "createdAt" : "2025-12-05T15:21:16.940432Z",
                          "updatedAt" : "2025-12-05T15:21:16.940432Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/8a48d038-24d9-4ece-bc79-fe96d0134fc6",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/892632d0-0be5-49e9-86d2-19a45dfad558",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                          "networkGroupId" : "892632d0-0be5-49e9-86d2-19a45dfad558",
                          "name" : "updated-1921",
                          "route53ZoneId" : "zoneId-1920",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "e059f248-8100-451a-b497-50ecb25fcd11",
                          "createdAt" : "2025-12-05T15:21:16.944558Z",
                          "updatedAt" : "2025-12-05T15:21:16.960957Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/98467000-bcc6-438c-b9ea-af3c0a39f8ae",
                              "title" : "updated-1921"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/892632d0-0be5-49e9-86d2-19a45dfad558",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "b0d319c6-fa33-450b-97c0-d2d7036e4b3e",
                          "networkGroupId" : "19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                          "name" : "testName-1926",
                          "route53ZoneId" : "zoneId",
                          "domain" : "domainResult",
                          "validated" : false,
                          "createdBy" : "0f5c462c-15e1-4f12-82f3-157005463650",
                          "createdAt" : "2025-12-05T15:21:17.092608Z",
                          "updatedAt" : "2025-12-05T15:21:17.092608Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/b0d319c6-fa33-450b-97c0-d2d7036e4b3e",
                              "title" : "testName-1926"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "b3109e9a-d3c7-4533-a7fa-246428cae463",
                          "networkGroupId" : "99c27478-ae51-4535-b9a9-74289881bc43",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1930",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "3fe67d80-4af0-4be8-8846-c267827d166f",
                          "createdAt" : "2025-12-05T15:21:17.137648Z",
                          "updatedAt" : "2025-12-05T15:21:17.137648Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/b3109e9a-d3c7-4533-a7fa-246428cae463",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/99c27478-ae51-4535-b9a9-74289881bc43",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "bf677e32-2d29-4da4-98e3-c326b4aed67e",
                          "networkGroupId" : "b544cfa0-4afb-45b3-bdc5-14025f497f1e",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1915",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "baeebb83-d599-40e6-8d71-8847f90300c0",
                          "createdAt" : "2025-12-05T15:21:16.908829Z",
                          "updatedAt" : "2025-12-05T15:21:16.908829Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/bf677e32-2d29-4da4-98e3-c326b4aed67e",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/b544cfa0-4afb-45b3-bdc5-14025f497f1e",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "c80e3d84-d198-4ce1-b813-8b36d6be191b",
                          "networkGroupId" : "d5e197e1-cf93-4ead-a417-9de94b8c1260",
                          "name" : "updated-1907",
                          "route53ZoneId" : "zoneId-1906",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "4fad044c-6630-4664-8bba-4ce9815680a8",
                          "createdAt" : "2025-12-05T15:21:15.586661Z",
                          "updatedAt" : "2025-12-05T15:21:16.298798Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/c80e3d84-d198-4ce1-b813-8b36d6be191b",
                              "title" : "updated-1907"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/d5e197e1-cf93-4ead-a417-9de94b8c1260",
                              "profile" : "parent"
                            }
                          }
                        }, {
                          "id" : "ca90728e-7ace-4145-b0a8-2bca2422a2a4",
                          "networkGroupId" : "d5e197e1-cf93-4ead-a417-9de94b8c1260",
                          "name" : "test-v3-domain.com",
                          "route53ZoneId" : "zoneId-1905",
                          "domain" : "domain.io.",
                          "validated" : false,
                          "createdBy" : "e9f2a4bc-4e0d-4b1b-b945-c5d81213bc98",
                          "createdAt" : "2025-12-05T15:21:15.570172Z",
                          "updatedAt" : "2025-12-05T15:21:15.570172Z",
                          "deletedAt" : null,
                          "deletedBy" : null,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/ca90728e-7ace-4145-b0a8-2bca2422a2a4",
                              "title" : "test-v3-domain.com"
                            },
                            "network-group" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/d5e197e1-cf93-4ead-a417-9de94b8c1260",
                              "profile" : "parent"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 13,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
          links:
            self:
              operationId: findDnsZones
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    post:
      tags:
        - Dns Zones
      summary: Create DnsZone
      description: >-
        Creates a new DnsZone within a Network Group. Exactly one of
        route53ZoneId or domain must be provided. Requires create permission on
        DnsZone in the specified Network Group.
      operationId: createDnsZone
      parameters:
        - name: nf-validate
          in: header
          schema:
            type: string
      requestBody:
        description: >-
          DnsZone creation payload. Provide either a Route53 hosted zone ID to
          reference an existing hosted zone, or a root domain to request
          creation/association.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDnsZone'
            examples:
              reference-existing-hosted-zone:
                description: reference-existing-hosted-zone
                value:
                  networkGroupId: 11111111-2222-3333-4444-555555555555
                  name: corp-zone
                  route53ZoneId: Z04008363AMXYS4T3J7OB
              create-by-domain:
                description: create-by-domain
                value:
                  networkGroupId: 11111111-2222-3333-4444-555555555555
                  name: corp-zone
                  domain: example.com
        required: true
      responses:
        '200':
          description: DnsZone created.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample create DnsZone response
                  value: |-
                    {
                      "id" : "b0d319c6-fa33-450b-97c0-d2d7036e4b3e",
                      "networkGroupId" : "19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                      "name" : "testName-1926",
                      "route53ZoneId" : "zoneId",
                      "domain" : "domainResult",
                      "validated" : false,
                      "createdBy" : "0f5c462c-15e1-4f12-82f3-157005463650",
                      "createdAt" : "2025-12-05T15:21:17.092608Z",
                      "updatedAt" : "2025-12-05T15:21:17.092608Z",
                      "deletedAt" : null,
                      "deletedBy" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/dns-zones/b0d319c6-fa33-450b-97c0-d2d7036e4b3e",
                          "title" : "testName-1926"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/19055a09-cac4-4770-9cb4-c3bf2aebbd73",
                          "profile" : "parent"
                        },
                        "execution" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/executions/37362758-2ed4-477d-b2da-46b38b518c04",
                          "title" : "Create DnsZone",
                          "profile" : "meta"
                        }
                      }
                    }
          links:
            execution:
              operationId: getExecution
              parameters:
                id: ''
            networkGroup:
              operationId: getNetworkGroup
              parameters:
                id: $response.body#/networkGroupId
            self:
              operationId: getDnsZone
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/networks/{id}/ping:
    get:
      tags:
        - Networks
      summary: Ping the Network Ziti Controller
      description: >
        Retrieves the ziti version as a way to check if the controller is
        online.

        The caller must have the read permission on the specified Network.
      operationId: pingNetwork
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network.
          required: true
          schema:
            type: string
            format: uuid
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
      responses:
        '200':
          description: Ziti Controller version.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Example Ziti Version response
                  value: |-
                    {
                      "networkId" : "08db8d6a-5485-4b7b-91cf-94898e70fd70",
                      "buildDate" : "2025-12-05T15:19:17.972853Z",
                      "runtimeVersion" : "v0.25.3",
                      "revision" : "v0.25.3",
                      "version" : "v0.25.3",
                      "semanticVersion" : "0.25.3",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/08db8d6a-5485-4b7b-91cf-94898e70fd70/ping"
                        },
                        "parent" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/08db8d6a-5485-4b7b-91cf-94898e70fd70"
                        }
                      }
                    }
          links:
            self:
              operationId: getNetwork
              parameters:
                id: $response.body.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.path.networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/host-sizes:
    get:
      tags:
        - Host Sizes
      summary: Find Host Sizes
      description: >-
        Returns host sizes aggregated across the selected cloud providers and
        optional host type filter. If no provider is specified, all providers
        are included. If no type is specified, both NC and ER sizes are
        returned.
      operationId: findHostSizes
      parameters:
        - name: provider
          in: query
          description: Filter to cloud provider(s). Repeat to specify multiple.
          required: false
          schema:
            type: array
            items:
              type: string
              description: >-
                Enumerates supported cloud provider keys used throughout the
                API.
              enum:
                - AWS
                - AZURE
                - GCP
                - OCI
                - CUSTOMER
              example: AWS
          example: AWS
        - name: type
          in: query
          description: Host type filter. Accepts NC (NetworkController) or ER (EdgeRouter).
          required: false
          schema:
            type: string
          example: ER
      responses:
        '200':
          description: A collection of HostSize resources.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CollectionModel'
              examples:
                default:
                  description: Sample find host sizes response
                  value: |-
                    [ {
                      "name" : "small",
                      "hostType" : "ER",
                      "providers" : [ "GCP", "OCI", "AWS", "AZURE" ],
                      "description" : [ ],
                      "default" : true
                    }, {
                      "name" : "medium",
                      "hostType" : "ER",
                      "providers" : [ "GCP", "OCI", "AWS", "AZURE" ],
                      "description" : [ ],
                      "default" : false
                    }, {
                      "name" : "small",
                      "hostType" : "NC",
                      "providers" : [ "AWS" ],
                      "description" : [ ],
                      "default" : true
                    }, {
                      "name" : "medium",
                      "hostType" : "NC",
                      "providers" : [ "AWS" ],
                      "description" : [ ],
                      "default" : false
                    } ]
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/edge-routers/{id}/compare-host:
    get:
      tags:
        - Edge Routers
      summary: Compare an Edge Router's host with its definition
      description: >
        Compare the actual Edge Router host in the cloud provider with the
        desired definition stored in NetFoundry.

        Useful for troubleshooting and support. The caller must have read
        permission on the specified Edge Router.
      operationId: compareEdgeRouterHost
      parameters:
        - name: id
          in: path
          description: Id of the Edge Router
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: OK. Comparison between the desired definition and the actual host.
          content:
            application/hal+json:
              schema:
                type: string
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/edge-routers/db7c7777-ecad-457e-be30-2949ffe8f062"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/6a2ce648-1638-4631-9bba-7d1cc671420e"
                        }
                      },
                      "matches" : true,
                      "checks" : [ {
                        "type" : "EXIST",
                        "matches" : true
                      }, {
                        "type" : "STATE",
                        "matches" : true,
                        "expected" : "RUNNING",
                        "actual" : "RUNNING"
                      }, {
                        "type" : "IP",
                        "matches" : true,
                        "expected" : "0.0.1.156",
                        "actual" : "0.0.1.156"
                      }, {
                        "type" : "INSTANCE_TYPE",
                        "matches" : true,
                        "expected" : [ "t2.small", "t3.small" ],
                        "actual" : "t2.small"
                      } ],
                      "networkId" : "6a2ce648-1638-4631-9bba-7d1cc671420e",
                      "edgeRouterId" : "db7c7777-ecad-457e-be30-2949ffe8f062",
                      "hostId" : "44fa4fb9-18c1-49aa-8714-f6099351d547",
                      "provider" : "AWS",
                      "providerInstanceId" : "e7b70555-9f21-4c30-93d4-c9764170da39"
                    }
          links:
            self:
              operationId: getEdgeRouter
              parameters:
                id: $response.body#/edgeRouterId
            network:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Edge Router belongs.
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/stored-secrets/{idWithValue}:
    get:
      tags:
        - Stored Secrets
      summary: Get a Stored Secret with value
      description: >
        Retrieve a single StoredSecret resource by its ID including its secret
        value.

        This variant requires the 'read-secret' authorization.

        Use the non-includeValue variant if you do not need the secret value.
      operationId: getStoredSecretWithValue
      parameters:
        - name: idWithValue
          in: path
          description: The unique identifier of the Stored Secret.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: The requested Stored Secret resource including the value.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get stored secret with value response
                  value: |-
                    {
                      "id" : "2288a3f7-03d7-4493-8246-c2b152368a91",
                      "createdBy" : "60f4ea06-2c2c-45a5-988d-7e1828e2606c",
                      "createdAt" : "2025-12-05T15:20:06.990746Z",
                      "updatedAt" : "2025-12-05T15:20:06.990746Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "name" : "test-v2",
                      "type" : "PRIVATE_KEY",
                      "networkGroupId" : "dc08718c-b84c-45e7-a274-43f43ac59a57",
                      "ott" : null,
                      "ottCreatedAt" : null,
                      "value" : "aiqpkvyYen3bC3Pg6NAr-",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/stored-secrets/2288a3f7-03d7-4493-8246-c2b152368a91"
                        },
                        "network-group" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-groups/dc08718c-b84c-45e7-a274-43f43ac59a57"
                        }
                      }
                    }
          links:
            self:
              operationId: getStoredSecretWithValue
              parameters:
                id: $request.path.id
            network-group:
              operationId: getNetworkGroup
              parameters:
                id: $response.path.networkGroupId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/software-deployment-states:
    get:
      tags:
        - Software Deployment States
      summary: Find Software Deployment States
      description: >-
        Returns SoftwareDeploymentStates matching the optional query parameters.
        Results are filtered to only include resources the caller may read.
      operationId: findSoftwareDeploymentStates
      parameters:
        - name: id
          in: query
          description: Filter by SoftwareDeploymentState ID(s). Repeat to specify multiple.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: networkId
          in: query
          description: Filter by Network ID(s).
          example: 11111111-2222-3333-4444-555555555555
        - name: resourceId
          in: query
          description: >-
            Filter by resource ID(s) the state applies to (Edge Router or
            Network Controller).
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: resourceType
          in: query
          description: Filter by resource type.
          example: EDGE_ROUTER
        - name: createdBy
          in: query
          description: Filter by creator identity ID(s).
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID(s).
          example: dddddddd-eeee-ffff-1111-222222222222
        - name: enabled
          in: query
          description: Filter by whether software management is enabled.
          example: true
        - name: online
          in: query
          description: Filter by current online status.
          example: true
        - name: softwareConfigurationPortEnabled
          in: query
          description: Filter by whether the software configuration port is enabled.
          example: false
        - name: lastCheckedAt
          in: query
          description: >-
            Last-checked-at filter expressions. Supports >, >=, <, <=, =, !=
            (e.g., lastCheckedAt=>=2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: nextCheckAt
          in: query
          description: Next-check-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: createdAt
          in: query
          description: Created-at filter expressions.
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Deleted-at filter expressions.
          example: '>2025-10-01T00:00:00Z'
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., resourceType,updatedAt,desc.
          example: updatedAt,desc
      responses:
        '200':
          description: A paginated list of SoftwareDeploymentStates.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find SoftwareDeploymentStates response
                  value: |-
                    {
                      "_embedded" : {
                        "softwareDeploymentStateList" : [ {
                          "id" : "10df1c9f-fd6e-4985-9007-8aafaca6eef8",
                          "networkId" : "09e18668-7c9e-445e-a046-7a4f539bfb8d",
                          "resourceId" : "41f006a0-6b1e-4097-b457-8337962cd983",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:55.221599Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:55.221599Z",
                          "nextCheckAt" : "2025-11-17T17:35:55.221643Z",
                          "createdBy" : "4f3c8e5b-bcfa-4015-8bdd-572a2d3b292b",
                          "createdAt" : "2025-11-17T16:35:55.268968Z",
                          "updatedAt" : "2025-11-17T16:35:55.268968Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/09e18668-7c9e-445e-a046-7a4f539bfb8d",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/10df1c9f-fd6e-4985-9007-8aafaca6eef8"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/41f006a0-6b1e-4097-b457-8337962cd983",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "2366279d-8745-41bf-b1ad-eb48b756fddc",
                          "networkId" : "f065c214-ff0c-4c1a-947d-373cf94ef5f3",
                          "resourceId" : "7624dcae-8d19-4ec7-8103-4c44243aadd2",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:56.128330Z",
                          "nextCheckAt" : "2025-11-17T17:35:56.128340Z",
                          "createdBy" : "dbb3e5d7-7cc4-444c-a5e0-4f101316a174",
                          "createdAt" : "2025-11-17T16:35:56.133808Z",
                          "updatedAt" : "2025-11-17T16:35:56.133808Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/f065c214-ff0c-4c1a-947d-373cf94ef5f3",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/2366279d-8745-41bf-b1ad-eb48b756fddc"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/7624dcae-8d19-4ec7-8103-4c44243aadd2",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "3e4b767b-e2dd-4e95-b57d-a6816b23899b",
                          "networkId" : "a9af388f-6867-4183-a4d2-b5df6988dce9",
                          "resourceId" : "49015156-d5df-49be-94dc-82010bc2ee3f",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:58.062047Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:58.062047Z",
                          "nextCheckAt" : "2025-11-17T17:35:58.062056Z",
                          "createdBy" : "8aed7e2b-6770-4b56-8dba-7d207f1c31e8",
                          "createdAt" : "2025-11-17T16:35:58.065808Z",
                          "updatedAt" : "2025-11-17T16:35:58.065808Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/a9af388f-6867-4183-a4d2-b5df6988dce9",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/3e4b767b-e2dd-4e95-b57d-a6816b23899b"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/49015156-d5df-49be-94dc-82010bc2ee3f",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "45f1eab5-3239-455d-adeb-6c4d66561018",
                          "networkId" : "3e6dd1c9-d69a-4395-90d5-58692967fdb9",
                          "resourceId" : "9945a75a-a160-43ed-a003-ba3979ed31e7",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:59.443847Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:59.443847Z",
                          "nextCheckAt" : "2025-11-17T17:35:59.443858Z",
                          "createdBy" : "6ceb2c1a-f3d4-4dac-bac9-1023272811b4",
                          "createdAt" : "2025-11-17T16:35:59.449676Z",
                          "updatedAt" : "2025-11-17T16:35:59.449676Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/3e6dd1c9-d69a-4395-90d5-58692967fdb9",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/45f1eab5-3239-455d-adeb-6c4d66561018"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/9945a75a-a160-43ed-a003-ba3979ed31e7",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "6dafdfba-e24c-48af-8b32-c357c987e9f2",
                          "networkId" : "485b22c0-1c30-493d-8c13-faacfdd9f3a4",
                          "resourceId" : "5592b4b6-053a-458b-9f88-f8c19109612f",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:56.458501Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:56.458501Z",
                          "nextCheckAt" : "2025-11-17T17:35:56.458511Z",
                          "createdBy" : "3269161b-ac37-4806-bbb4-1a08b3a1e95b",
                          "createdAt" : "2025-11-17T16:35:56.460339Z",
                          "updatedAt" : "2025-11-17T16:35:56.460339Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/485b22c0-1c30-493d-8c13-faacfdd9f3a4",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/6dafdfba-e24c-48af-8b32-c357c987e9f2"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/5592b4b6-053a-458b-9f88-f8c19109612f",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "73ab54a5-0f61-4eb5-b230-33665b3ba1c0",
                          "networkId" : "466e4c84-d83f-41f0-a7e6-09f6aee32adc",
                          "resourceId" : "febc4c8b-9df5-40c1-87a6-f2d4db854171",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:59.697542Z",
                          "nextCheckAt" : "2025-11-17T17:35:59.697554Z",
                          "createdBy" : "0b3de52f-cc41-43fb-bbe5-26e6fb88ede2",
                          "createdAt" : "2025-11-17T16:35:59.705123Z",
                          "updatedAt" : "2025-11-17T16:35:59.705123Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/466e4c84-d83f-41f0-a7e6-09f6aee32adc",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/73ab54a5-0f61-4eb5-b230-33665b3ba1c0"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/febc4c8b-9df5-40c1-87a6-f2d4db854171",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "8476e791-2db1-46f3-89a2-41d123620646",
                          "networkId" : "4cade0a1-7fc6-418f-bbf8-3a79b58bf01d",
                          "resourceId" : "1c55c967-2057-46b7-80c3-21777717c378",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : false,
                          "lastCheckedAt" : "2025-11-17T16:25:57.104927Z",
                          "nextCheckAt" : "2025-11-17T17:35:57.104936Z",
                          "createdBy" : "eeb98584-2444-46bd-a106-5413b66e916b",
                          "createdAt" : "2025-11-17T16:35:57.108225Z",
                          "updatedAt" : "2025-11-17T16:35:57.682245Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/4cade0a1-7fc6-418f-bbf8-3a79b58bf01d",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/8476e791-2db1-46f3-89a2-41d123620646"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1c55c967-2057-46b7-80c3-21777717c378",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "94b9264f-f32b-4ee0-acd4-fa8598179050",
                          "networkId" : "333be85e-a7a1-4c41-9c0d-a82ae5aebe8a",
                          "resourceId" : "fa571a49-7839-455c-98e8-8dc8681ed108",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:30:55.457425Z",
                          "nextCheckAt" : "2025-11-17T16:37:25.556570Z",
                          "createdBy" : "bc73a8be-0a38-4b2f-9d4d-bfb66e7a833c",
                          "createdAt" : "2025-11-17T16:35:55.434725Z",
                          "updatedAt" : "2025-11-17T16:35:55.561278Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/333be85e-a7a1-4c41-9c0d-a82ae5aebe8a",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/94b9264f-f32b-4ee0-acd4-fa8598179050"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/fa571a49-7839-455c-98e8-8dc8681ed108",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "c95c8cb3-1069-4ce1-83a2-c8089bc1e9fe",
                          "networkId" : "f4983204-3ffc-4ada-82f5-dacfb4f2d517",
                          "resourceId" : "9ac442db-a3fe-4161-b541-bce1a4c39d76",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:56.631497Z",
                          "nextCheckAt" : "2025-11-17T17:35:56.631506Z",
                          "createdBy" : "56809872-17fa-41f5-b9fd-80c59df5ee43",
                          "createdAt" : "2025-11-17T16:35:56.633333Z",
                          "updatedAt" : "2025-11-17T16:35:56.633333Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/f4983204-3ffc-4ada-82f5-dacfb4f2d517",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/c95c8cb3-1069-4ce1-83a2-c8089bc1e9fe"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/9ac442db-a3fe-4161-b541-bce1a4c39d76",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "cf38286c-e132-4249-b876-a1a560938f69",
                          "networkId" : "d473542d-f893-45d0-9809-296e590928c0",
                          "resourceId" : "57b2afe1-60bc-412a-a8e7-0f30998f8cc0",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:55.960830Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:55.960830Z",
                          "nextCheckAt" : "2025-11-17T17:35:55.960838Z",
                          "createdBy" : "ba99319d-02a8-4287-824a-ade7a28e6ad6",
                          "createdAt" : "2025-11-17T16:35:55.964203Z",
                          "updatedAt" : "2025-11-17T16:35:55.964203Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/d473542d-f893-45d0-9809-296e590928c0",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/cf38286c-e132-4249-b876-a1a560938f69"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/57b2afe1-60bc-412a-a8e7-0f30998f8cc0",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "d0105f4c-4e61-440d-a47d-291a54209cee",
                          "networkId" : "2da780b4-2cab-4dc0-a5f9-97da10c5dec8",
                          "resourceId" : "dd857c98-903d-44ff-9684-b5bb1e005902",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:30:59.147702Z",
                          "nextCheckAt" : "2025-11-17T16:37:29.223028Z",
                          "createdBy" : "cd03b940-615c-43bd-ab24-93b8aa9da036",
                          "createdAt" : "2025-11-17T16:35:59.131674Z",
                          "updatedAt" : "2025-11-17T16:35:59.223851Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/2da780b4-2cab-4dc0-a5f9-97da10c5dec8",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/d0105f4c-4e61-440d-a47d-291a54209cee"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/dd857c98-903d-44ff-9684-b5bb1e005902",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "d27860a8-99cf-4a96-9b8f-13d7ee20d0a6",
                          "networkId" : "ec5dc045-74a3-4250-b8b4-74dbb96ebb95",
                          "resourceId" : "d81b5558-03da-4bc0-aa88-2da9f021ac8c",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:58.916975Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:58.916975Z",
                          "nextCheckAt" : "2025-11-17T17:35:58.916983Z",
                          "createdBy" : "48213ca0-7f5c-42de-a416-45acfcd46c1d",
                          "createdAt" : "2025-11-17T16:35:58.921207Z",
                          "updatedAt" : "2025-11-17T16:35:58.921207Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/ec5dc045-74a3-4250-b8b4-74dbb96ebb95",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/d27860a8-99cf-4a96-9b8f-13d7ee20d0a6"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/d81b5558-03da-4bc0-aa88-2da9f021ac8c",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "f966cb01-903c-43d2-8d5f-8e72a4196ff4",
                          "networkId" : "9b32247f-ecc9-4107-ae6d-00b947c4cc9c",
                          "resourceId" : "d45eef7b-d4ee-45b9-a6cd-d3a78d59dd17",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : true,
                          "online" : true,
                          "lastOnlineAt" : "2025-11-17T16:25:56.956513Z",
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:56.956513Z",
                          "nextCheckAt" : "2025-11-17T17:35:56.956523Z",
                          "createdBy" : "8e3649a4-476e-41cc-b41f-320467060420",
                          "createdAt" : "2025-11-17T16:35:56.960350Z",
                          "updatedAt" : "2025-11-17T16:35:56.960350Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/9b32247f-ecc9-4107-ae6d-00b947c4cc9c",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/f966cb01-903c-43d2-8d5f-8e72a4196ff4"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/d45eef7b-d4ee-45b9-a6cd-d3a78d59dd17",
                              "title" : "parent"
                            }
                          }
                        }, {
                          "id" : "fb364da6-9fb5-472c-9476-a815f5b61b63",
                          "networkId" : "e6254b59-b1e6-446d-ab27-8558d63b6700",
                          "resourceId" : "17274d32-8048-4104-afef-4a4284c8486a",
                          "resourceType" : "NETWORK_CONTROLLER",
                          "enabled" : false,
                          "online" : false,
                          "lastOnlineAt" : null,
                          "softwareConfigurationPortEnabled" : true,
                          "lastCheckedAt" : "2025-11-17T16:25:58.229324Z",
                          "nextCheckAt" : "2025-11-17T17:35:58.229333Z",
                          "createdBy" : "45e40de9-d8f4-4d2b-a4d1-efabb0d3e988",
                          "createdAt" : "2025-11-17T16:35:58.233963Z",
                          "updatedAt" : "2025-11-17T16:35:58.233963Z",
                          "deletedBy" : null,
                          "deletedAt" : null,
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/e6254b59-b1e6-446d-ab27-8558d63b6700",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states/fb364da6-9fb5-472c-9476-a815f5b61b63"
                            },
                            "network-controller" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/17274d32-8048-4104-afef-4a4284c8486a",
                              "title" : "parent"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/software-deployment-states"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 14,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
          links:
            self:
              operationId: findSoftwareDeploymentStates
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/regions/{provider}/{locationCode}:
    get:
      tags:
        - Regions
      summary: Get Region
      description: Returns a single Region by cloud provider and location code.
      operationId: getRegion
      parameters:
        - name: provider
          in: path
          description: Cloud provider key.
          required: true
          schema:
            type: string
            description: Enumerates supported cloud provider keys used throughout the API.
            enum:
              - AWS
              - AZURE
              - GCP
              - OCI
              - CUSTOMER
            example: AWS
          example: AWS
        - name: locationCode
          in: path
          description: Unique region location code for the provider.
          required: true
          schema:
            type: string
          example: us-east-1
      responses:
        '200':
          description: Region retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get region response
                  value: |-
                    {
                      "locationCode" : "oci-us-east-1",
                      "name" : "us-east-1",
                      "provider" : "OCI",
                      "latitude" : 25.0,
                      "longitude" : 25.0,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/regions/OCI/oci-us-east-1"
                        },
                        "regions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=OCI"
                        },
                        "provider" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/OCI"
                        },
                        "providers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                        }
                      }
                    }
          links:
            regions:
              operationId: findRegions
              parameters:
                provider: $response.body#/provider
            provider:
              operationId: getCloudProvider
              parameters:
                cloudProvider: $response.body#/provider
            self:
              operationId: getRegion
              parameters:
                provider: $response.body#/provider
                locationCode: $response.body#/locationCode
            providers:
              operationId: listCloudProviders
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/regions:
    get:
      tags:
        - Regions
      summary: Find Regions
      description: >-
        Returns cloud regions aggregated across the selected provider(s).
        Optionally provide latitude and longitude to sort by proximity and
        include distance metadata. If no provider is specified, all providers
        are included.
      operationId: findRegions
      parameters:
        - name: provider
          in: query
          description: Filter to cloud provider(s). Repeat to specify multiple.
          required: false
          schema:
            type: array
            items:
              type: string
              description: >-
                Enumerates supported cloud provider keys used throughout the
                API.
              enum:
                - AWS
                - AZURE
                - GCP
                - OCI
                - CUSTOMER
              example: AWS
          example: AWS
        - name: latitude
          in: query
          description: Latitude to compute distance and sort results by proximity.
          required: false
          schema:
            type: number
            format: double
          example: 37.7749
        - name: longitude
          in: query
          description: Longitude to compute distance and sort results by proximity.
          required: false
          schema:
            type: number
            format: double
          example: -122.4194
      responses:
        '200':
          description: A collection of Region resources.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CollectionModel'
              examples:
                default:
                  description: Sample find regions response
                  value: |-
                    {
                      "_embedded" : {
                        "regionList" : [ {
                          "locationCode" : "gcp-us-east-1",
                          "name" : "us-east-1",
                          "provider" : "GCP",
                          "latitude" : 50.0,
                          "longitude" : 55.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/GCP/gcp-us-east-1"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=GCP"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/GCP"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "gcp-us-east-2",
                          "name" : "us-east-2",
                          "provider" : "GCP",
                          "latitude" : 55.0,
                          "longitude" : 50.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/GCP/gcp-us-east-2"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=GCP"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/GCP"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "oci-us-east-1",
                          "name" : "us-east-1",
                          "provider" : "OCI",
                          "latitude" : 25.0,
                          "longitude" : 25.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/OCI/oci-us-east-1"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=OCI"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/OCI"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "oci-us-east-2",
                          "name" : "us-east-2",
                          "provider" : "OCI",
                          "latitude" : 22.0,
                          "longitude" : 22.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/OCI/oci-us-east-2"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=OCI"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/OCI"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "aws-us-east-1",
                          "name" : "us-east-1",
                          "provider" : "AWS",
                          "latitude" : 50.0,
                          "longitude" : 50.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/AWS/aws-us-east-1"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=AWS"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/AWS"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "aws-us-east-2",
                          "name" : "us-east-2",
                          "provider" : "AWS",
                          "latitude" : 45.0,
                          "longitude" : 45.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/AWS/aws-us-east-2"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=AWS"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/AWS"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "azure-us-east-1",
                          "name" : "us-east-1",
                          "provider" : "AZURE",
                          "latitude" : 51.0,
                          "longitude" : 51.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/AZURE/azure-us-east-1"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=AZURE"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/AZURE"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        }, {
                          "locationCode" : "azure-us-east-2",
                          "name" : "us-east-2",
                          "provider" : "AZURE",
                          "latitude" : 48.0,
                          "longitude" : 48.0,
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions/AZURE/azure-us-east-2"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/regions?provider=AZURE"
                            },
                            "provider" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers/AZURE"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/regions"
                        },
                        "providers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/cloud-providers"
                        }
                      }
                    }
          links:
            self:
              operationId: findRegions
            providers:
              operationId: listCloudProviders
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-versions/{id}:
    get:
      tags:
        - Network Versions
      summary: Get Network Version
      description: >-
        Returns a single Network Version by its unique identifier. Results are
        public and not authorization-filtered.
      operationId: getNetworkVersion
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Network Version.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
      responses:
        '200':
          description: Network Version retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get network version response
                  value: |-
                    {
                      "id" : "d4a9d45a-703f-40f9-94cd-2dfc98169984",
                      "networkVersion" : "8.4.1",
                      "zitiVersion" : "1.4.1",
                      "minimumNetworkVersionForUpgrade" : null,
                      "minimumEdgeRouterVersionForUpgrade" : null,
                      "active" : true,
                      "default" : false,
                      "jsonNode" : {
                        "active" : true,
                        "version" : {
                          "type" : "STRICT",
                          "build" : null,
                          "major" : 8,
                          "minor" : 4,
                          "patch" : 1,
                          "value" : "8.4.1",
                          "stable" : true,
                          "suffixTokens" : [ ],
                          "originalValue" : "8.4.1"
                        },
                        "zitiVersion" : {
                          "type" : "STRICT",
                          "build" : null,
                          "major" : 1,
                          "minor" : 4,
                          "patch" : 1,
                          "value" : "1.4.1",
                          "stable" : true,
                          "suffixTokens" : [ ],
                          "originalValue" : "1.4.1"
                        },
                        "defaultVersion" : false
                      },
                      "createdAt" : "2025-11-17T16:36:45.508066Z",
                      "updatedAt" : "2025-11-17T16:36:45.508066Z",
                      "recommended" : false,
                      "platformFeatures" : [ {
                        "displayName" : "service.advanced-tunneler-to-endpoint",
                        "removedAt" : null,
                        "introducedAt" : "7.3.25",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "browzer",
                        "removedAt" : null,
                        "introducedAt" : "7.3.90",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "service.advanced-tunneler-to-endpoint.source-ip-transparency",
                        "removedAt" : null,
                        "introducedAt" : "7.3.32",
                        "deprecatedAt" : null
                      } ],
                      "zitiFeatures" : [ {
                        "displayName" : "enrollment.refresh",
                        "removedAt" : null,
                        "introducedAt" : "0.25.9",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "authenticator",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity.mfa",
                        "removedAt" : null,
                        "introducedAt" : "0.18.5",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "posture-check",
                        "removedAt" : null,
                        "introducedAt" : "0.16.5",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "authenticators.list.authenticators",
                        "removedAt" : null,
                        "introducedAt" : "0.22.10",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "enrollment.create.delete",
                        "removedAt" : null,
                        "introducedAt" : "0.25.9",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge-router-policy",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "config",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "posture-check.mfa",
                        "removedAt" : null,
                        "introducedAt" : "0.18.5",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "cas",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "auth-policy",
                        "removedAt" : null,
                        "introducedAt" : "0.25.4",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge-router.no-traversal",
                        "removedAt" : null,
                        "introducedAt" : "0.24.13",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "service",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "posture-check.process",
                        "removedAt" : null,
                        "introducedAt" : "0.16.5",
                        "deprecatedAt" : "0.20.0"
                      }, {
                        "displayName" : "transit-router",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "session",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "terminator",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "posture-check.multi-process",
                        "removedAt" : null,
                        "introducedAt" : "0.20.2",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge-router.is-tunneler-enabled",
                        "removedAt" : null,
                        "introducedAt" : "0.20.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge.router.enabled",
                        "removedAt" : null,
                        "introducedAt" : "0.27.6",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "authenticators.re.enroll",
                        "removedAt" : null,
                        "introducedAt" : "0.25.10",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity-type",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge-router.wss-listener",
                        "removedAt" : null,
                        "introducedAt" : "0.26.5",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity.external-id",
                        "removedAt" : null,
                        "introducedAt" : "0.25.4",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "posture-check.mfa.timeout-seconds",
                        "removedAt" : null,
                        "introducedAt" : "0.20.14",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge-router",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "config-type.intercept-v1",
                        "removedAt" : null,
                        "introducedAt" : "0.19.11",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "edge.routers.re.enroll",
                        "removedAt" : null,
                        "introducedAt" : "0.25.10",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity.disabled",
                        "removedAt" : null,
                        "introducedAt" : "0.25.4",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "service-policy",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "config-type",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "service-edge-router-policy",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "config-type.host-v1",
                        "removedAt" : null,
                        "introducedAt" : "0.19.11",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity.list.enrollments",
                        "removedAt" : null,
                        "introducedAt" : "0.25.11",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "policy-advice",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "identity",
                        "removedAt" : null,
                        "introducedAt" : "0.0.0",
                        "deprecatedAt" : null
                      }, {
                        "displayName" : "browzer",
                        "removedAt" : null,
                        "introducedAt" : "0.26.5",
                        "deprecatedAt" : null
                      } ],
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-versions/d4a9d45a-703f-40f9-94cd-2dfc98169984"
                        },
                        "versions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/network-versions",
                          "profile" : "parent"
                        }
                      }
                    }
          links:
            versions:
              operationId: findNetworkVersions
            self:
              operationId: getNetworkVersion
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-versions:
    get:
      tags:
        - Network Versions
      summary: Find Network Versions
      description: >-
        Returns Network Versions matching the optional query parameters. Results
        are public and not authorization-filtered.
      operationId: findNetworkVersions
      parameters:
        - name: id
          in: query
          description: Filter by Network Version ID(s). Repeat to specify multiple.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: name
          in: query
          description: >-
            Filter by semantic version of the Network (alias of networkVersion).
            Supports % wildcard.
          example: 8.5.%
        - name: networkVersion
          in: query
          description: Filter by semantic version of the Network. Supports % wildcard.
          example: 8.5.%
        - name: zitiVersion
          in: query
          description: >-
            Filter by semantic version of the bundled Ziti platform. Supports %
            wildcard.
          example: 1.0.%
        - name: minimumNetworkVersionRequiredForUpgrade
          in: query
          description: Filter by minimum Network version required for upgrade.
          deprecated: true
          example: 8.2.0
        - name: minimumEdgeRouterVersionRequiredForUpgrade
          in: query
          description: Filter by minimum Edge Router version required for upgrade.
          deprecated: true
          example: 1.1.0
        - name: active
          in: query
          description: Filter by active flag (available for new installs).
          example: true
        - name: default
          in: query
          description: Filter by default recommended version.
          example: true
        - name: createdAt
          in: query
          description: >-
            Created-at filter expression. Supports >, >=, <, <=, =, != (e.g.,
            createdAt=>2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expression.
          example: <=2025-12-31T23:59:59Z
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., networkVersion,updatedAt,desc.
          example: networkVersion,desc
      responses:
        '200':
          description: A paginated list of Network Versions.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
          links:
            self:
              operationId: findNetworkVersions
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-jwt-sets/{networkId}:
    get:
      tags:
        - NetworkJwtSets
      summary: Get Network JWT Set
      description: >-
        Returns the set of JWT descriptors issued by the specified Network. The
        result may be empty if none exist.
      operationId: getNetworkJwtSet
      parameters:
        - name: networkId
          in: path
          description: The unique identifier of the Network whose JWT set is requested.
          required: true
          schema:
            type: string
            format: uuid
          example: 11111111-2222-3333-4444-555555555555
      responses:
        '200':
          description: Network JWT Set retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get Network JWT Set response
                  value: |-
                    {
                      "networkId" : "bd6a117f-6f1e-40e7-ad45-095b215b9433",
                      "zitiNetworkJwts" : [ {
                        "name" : "mock-network-jwt",
                        "token" : "token-value"
                      } ],
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/bd6a117f-6f1e-40e7-ad45-095b215b9433"
                        }
                      }
                    }
          links:
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/network-controllers/{id}/compare-host:
    get:
      tags:
        - Network Controllers
      summary: Compare a Network Controller's host with its definition
      description: >
        Compare a Network Controller's host with its definition. This is useful
        for debugging and support.

        The caller must have the read permission on the specified Network
        Controller.
      operationId: compareNetworkControllerHost
      parameters:
        - name: id
          in: path
          description: Id of the Network Controller
          required: true
          schema:
            type: string
            format: uuid
          example: bdf1b7c1-5a33-4b2c-9b3d-9c7d3f8a4e21
      responses:
        '200':
          description: OK. Comparison between the desired definition and the actual host.
          content:
            application/hal+json:
              schema:
                type: string
              examples:
                default:
                  description: default
                  value: |-
                    {
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/1acd4a72-a185-4242-ab06-c7b106214117"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/80caaf72-e1bd-4dee-8db2-efda13114dd1"
                        }
                      },
                      "matches" : true,
                      "checks" : [ {
                        "type" : "EXIST",
                        "matches" : true
                      }, {
                        "type" : "STATE",
                        "matches" : true,
                        "expected" : "RUNNING",
                        "actual" : "RUNNING"
                      }, {
                        "type" : "IP",
                        "matches" : true,
                        "expected" : "4.3.2.1",
                        "actual" : "4.3.2.1"
                      }, {
                        "type" : "INSTANCE_TYPE",
                        "matches" : true,
                        "expected" : [ "t2.medium", "t3.medium" ],
                        "actual" : "t2.medium"
                      } ],
                      "networkId" : "80caaf72-e1bd-4dee-8db2-efda13114dd1",
                      "networkControllerId" : "1acd4a72-a185-4242-ab06-c7b106214117",
                      "hostId" : "0b8dd0f1-f48f-4397-85f9-f7eec2a9b63e",
                      "provider" : "AWS",
                      "providerInstanceId" : "i-testncinstance"
                    }
          links:
            parent:
              operationId: getNetwork
              parameters:
                id: $response.body.networkId
              description: The Network to which this Network Controller belongs.
            self:
              operationId: getNetworkController
              parameters:
                id: $response.body#/networkControllerId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/hosts/{id}:
    get:
      tags:
        - Hosts
      summary: Get Host
      description: >-
        Returns a single Host by its unique identifier. Results are filtered to
        only include resources the caller may read.
      operationId: getHost
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Host.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * describeCloudHost: Return detailed cloud host data
          schema:
            type: array
            items:
              type: string
              enum:
                - describeCloudHost
      responses:
        '200':
          description: Host retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get host response
                  value: |-
                    {
                      "id" : "fde28f76-9b7e-4f63-8e90-994b5156849a",
                      "networkId" : "05f40cf1-8f54-4175-a762-9cbc350cdb70",
                      "ownerIdentityId" : "3ce688c9-b4be-4c22-8065-498fb351fc11",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "ipAddress" : "0.0.5.33",
                      "sshPort" : 22,
                      "sshPrivateKeyStoredSecretId" : null,
                      "providerInstanceId" : "be057ede-642d-4f37-b4e9-7bfad18254be",
                      "size" : "small",
                      "userData" : null,
                      "createdBy" : null,
                      "createdAt" : "2025-11-17T16:32:24.030264Z",
                      "updatedAt" : "2025-11-17T16:32:24.030264Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/05f40cf1-8f54-4175-a762-9cbc350cdb70",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/hosts/fde28f76-9b7e-4f63-8e90-994b5156849a"
                        },
                        "provider" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/AWS"
                        },
                        "region" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/regions/AWS/us-east-1"
                        }
                      }
                    }
          links:
            provider:
              operationId: getCloudProvider
              parameters:
                cloudProvider: $response.body#/provider
            self:
              operationId: getHost
              parameters:
                id: $response.body#/id
            region:
              operationId: getRegion
              parameters:
                provider: $response.body#/provider
                locationCode: $response.body#/region
            network:
              operationId: getNetwork
              parameters:
                networkId: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/hosts:
    get:
      tags:
        - Hosts
      summary: Find Hosts
      description: >-
        Returns Hosts matching the optional query parameters. Results are
        filtered to only include resources the caller may read.
      operationId: findHosts
      parameters:
        - name: networkId
          in: query
          description: Filter by Network ID(s). Repeat to specify multiple.
          example: 11111111-2222-3333-4444-555555555555
        - name: provider
          in: query
          description: Filter by cloud provider(s). Repeat to specify multiple.
          example: AWS
        - name: providerInstanceId
          in: query
          description: Filter by provider instance identifier(s).
          example: i-0abc123def4567890
        - name: port
          in: query
          description: >-
            Deprecated: previous controller port filter; use component-specific
            resources.
          deprecated: true
          example: 8443
        - name: ipAddress
          in: query
          description: Filter by IP address(es).
          example: 203.0.113.10
        - name: sshPort
          in: query
          description: Filter by SSH port(s).
          example: 22
        - name: sshPrivateKeyStoredSecretId
          in: query
          description: Filter by StoredSecret ID that holds the SSH private key.
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: hostSize
          in: query
          description: Filter by abstract Host size(s).
          example: small
        - name: region
          in: query
          description: Filter by cloud region code(s).
          example: us-east-1
        - name: ownerIdentityId
          in: query
          description: Filter by Owner Identity ID(s).
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: createdBy
          in: query
          description: Filter by creator identity ID(s).
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID(s).
          example: dddddddd-eeee-ffff-1111-222222222222
        - name: createdAt
          in: query
          description: >-
            Created-at filter expressions. Supports >, >=, <, <=, =, != (e.g.,
            createdAt=>=2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Deleted-at filter expressions.
          example: '>2025-10-01T00:00:00Z'
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., provider,updatedAt,desc.
          example: provider,asc
      responses:
        '200':
          description: A paginated list of Hosts.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
          links:
            self:
              operationId: findHosts
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/host-addresses/{ip}:
    get:
      tags:
        - Host Addresses
      summary: Get Cloud Address
      description: >-
        Returns the reserved Host address resource for the specified IP. The
        caller must have read permission on the owning Network.
      operationId: getCloudAddress
      parameters:
        - name: ip
          in: path
          description: The IP address for which to retrieve the cloud address resource.
          required: true
          schema:
            type: string
          example: 203.0.113.10
      responses:
        '200':
          description: Cloud address retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get cloud address response
                  value: |-
                    {
                      "ip" : "1.2.3.4",
                      "networkId" : "66df3494-8726-4847-9c22-74aae27cc696",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "createdAt" : "2025-11-17T16:33:13.865113Z",
                      "expiresAt" : "2025-11-27T16:33:13.865214Z",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses/1.2.3.4"
                        },
                        "addresses" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=66df3494-8726-4847-9c22-74aae27cc696"
                        }
                      }
                    }
          links:
            addresses:
              operationId: findCloudAddresses
              parameters:
                networkId: $response.body#/networkId
            self:
              operationId: getCloudAddress
              parameters:
                ip: $response.body#/ip
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
    delete:
      tags:
        - Host Addresses
      summary: Release Cloud Address
      description: >
        Releases the reserved Host address identified by IP. The address is
        released but the address record is not expired.

        This action cannot be undone. The caller must have delete permission on
        the owning Network.
      operationId: releaseCloudAddress
      parameters:
        - name: ip
          in: path
          description: The IP address of the cloud address to be released.
          required: true
          schema:
            type: string
          example: 203.0.113.10
      responses:
        '200':
          description: Cloud address released.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample release cloud address response
                  value: |-
                    {
                      "ip" : "1.2.3.4",
                      "networkId" : "f965c1b4-c62f-42b9-a2bc-a3c4dc049b38",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "createdAt" : "2025-11-17T16:33:16.322872Z",
                      "expiresAt" : "2025-11-27T16:33:16.322873Z",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses/1.2.3.4"
                        },
                        "addresses" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/host-addresses?networkId=f965c1b4-c62f-42b9-a2bc-a3c4dc049b38"
                        }
                      }
                    }
          links:
            addresses:
              operationId: findCloudAddresses
              parameters:
                networkId: $response.body#/networkId
            self:
              operationId: getCloudAddress
              parameters:
                ip: $response.body#/ip
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/executions/{id}:
    get:
      tags:
        - Executions
      summary: Get an Execution
      description: >-
        Retrieve a single Execution resource by its ID. The caller must have
        read permission on the associated Network.
      operationId: getExecution
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Execution.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * processData: Return detailed process step data
          schema:
            type: array
            items:
              type: string
              enum:
                - processData
      responses:
        '200':
          description: The requested Execution resource.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get execution response
                  value: |-
                    {
                      "id" : "2b7a084e-2d98-40a0-8cf5-9942a1f5d6f4",
                      "networkId" : "453e2d2f-3578-4022-963c-db7663cb35ff",
                      "processId" : "46221766-5fed-4a11-99d2-0626f9ac0372",
                      "name" : "CreateNetworkProcess",
                      "description" : "Fake Process",
                      "resourceType" : "network",
                      "resourceId" : null,
                      "startedAt" : "2025-11-17T16:31:32.975506Z",
                      "finishedAt" : "2025-11-17T16:31:32.975506Z",
                      "traceId" : "trace3",
                      "status" : "FAILED",
                      "initiatingIdentityId" : "59405773-3867-4422-a281-bf3bf77814b7",
                      "createdAt" : "2025-11-17T16:31:32.975430Z",
                      "updatedAt" : "2025-11-17T16:31:32.975430Z",
                      "actions" : [ {
                        "title" : "Replay",
                        "method" : "PUT",
                        "url" : "http://localhost:8080/core/v2/networks/453e2d2f-3578-4022-963c-db7663cb35ff/replay"
                      } ],
                      "_links" : {
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/networks/453e2d2f-3578-4022-963c-db7663cb35ff",
                          "profile" : "parent"
                        },
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/executions/2b7a084e-2d98-40a0-8cf5-9942a1f5d6f4",
                          "title" : "CreateNetworkProcess"
                        }
                      }
                    }
          links:
            self:
              operationId: getExecution
              parameters:
                id: $request.path.id
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/executions:
    get:
      tags:
        - Executions
      summary: Find Executions
      description: >-
        Find all Execution instances that match the specified search criteria.
        Results exclude resources the caller is not authorized to read;
        therefore this endpoint never returns 403/404, only an empty list when
        no authorized results are found.
      operationId: findExecutions
      parameters:
        - name: id
          in: query
          description: Filter by Execution ID.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: networkId
          in: query
          description: Filter by associated Network ID.
          example: 6b9f3a0e-7f68-4f8a-8f9e-2f3a1c9f2a11
        - name: name
          in: query
          description: Filter by execution name (supports multiple values).
          example: 'Delete: myNetwork'
        - name: description
          in: query
          description: Filter by execution description.
          example: Deletes the specified network and its resources.
        - name: resourceType
          in: query
          description: >-
            Filter by resource type acted upon (e.g., Network,
            NetworkController).
          example: Network
        - name: resourceId
          in: query
          description: Filter by resource ID.
          example: 11111111-2222-3333-4444-555555555555
        - name: processId
          in: query
          description: Filter by underlying process ID.
          example: 2f1b4a2e-9a2b-4c53-9e6c-9f1e8b6a7c21
        - name: traceId
          in: query
          description: Filter by trace correlation ID.
          example: trace-0af7651916cd43dd8448eb211c80319c
        - name: status
          in: query
          description: Filter by execution status.
          examples:
            running:
              description: running
              value: RUNNING
            success:
              description: success
              value: SUCCESS
            failed:
              description: failed
              value: FAILED
        - name: initiatingIdentityId
          in: query
          description: Filter by the initiating identity ID.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        - name: startedAt
          in: query
          description: >-
            Filter by startedAt with comparison operators. Supports >, >=, <,
            <=, =, != (e.g., startedAt=>=2025-01-01T00:00:00Z)
          examples:
            started-after:
              description: started-after
              value: '>2025-01-01T00:00:00Z'
            started-before:
              description: started-before
              value: <2025-12-31T23:59:59Z
        - name: finishedAt
          in: query
          description: Filter by finishedAt with comparison operators.
          example: '=2025-05-10T13:37:00Z'
        - name: createdAt
          in: query
          description: Filter by createdAt with comparison operators.
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Filter by updatedAt with comparison operators.
          example: <=2025-10-09T18:00:00Z
        - name: page
          in: query
          description: Zero-based page index.
          example: 0
        - name: size
          in: query
          description: The size of the page to be returned.
          example: 20
        - name: sort
          in: query
          description: >-
            Sorting criteria in the format: property,(asc|desc). Multiple sort
            params are supported.
          examples:
            name-asc:
              description: name-asc
              value: name,asc
            createdAt-desc:
              description: createdAt-desc
              value: createdAt,desc
      responses:
        '200':
          description: A paginated list of Executions.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find executions response
                  value: |-
                    {
                      "_embedded" : {
                        "executionList" : [ {
                          "id" : "2561979f-ace4-41a0-96c8-36f140c1c716",
                          "networkId" : "60efa278-d9c1-442c-98cb-7dd862406776",
                          "processId" : "0188a610-dcb6-4c45-8962-570e55d1a7c7",
                          "name" : "CreateNetworkProcess",
                          "description" : "Fake Process",
                          "resourceType" : "network",
                          "resourceId" : null,
                          "startedAt" : "2025-11-17T16:31:32.579616Z",
                          "finishedAt" : "2025-11-17T16:31:32.579616Z",
                          "traceId" : "trace3",
                          "status" : "FAILED",
                          "initiatingIdentityId" : "806b0712-d415-4433-9fbc-c518d6365069",
                          "createdAt" : "2025-11-17T16:31:32.579442Z",
                          "updatedAt" : "2025-11-17T16:31:32.579442Z",
                          "actions" : [ {
                            "title" : "Replay",
                            "method" : "PUT",
                            "url" : "http://localhost:8080/core/v2/networks/60efa278-d9c1-442c-98cb-7dd862406776/replay"
                          } ],
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/60efa278-d9c1-442c-98cb-7dd862406776",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/executions/2561979f-ace4-41a0-96c8-36f140c1c716",
                              "title" : "CreateNetworkProcess"
                            }
                          }
                        }, {
                          "id" : "68c31949-3bf4-4dba-aa9d-e3240a4db84b",
                          "networkId" : "60efa278-d9c1-442c-98cb-7dd862406776",
                          "processId" : "252e502c-8979-4f5d-81e0-cba9e8061db1",
                          "name" : "CreateEndpointProcess",
                          "description" : "Fake Process",
                          "resourceType" : "component",
                          "resourceId" : "98f9de14-67de-4104-bc63-254b42dd023f",
                          "startedAt" : "2025-11-17T16:31:32.573991Z",
                          "finishedAt" : null,
                          "traceId" : "trace2",
                          "status" : "RUNNING",
                          "initiatingIdentityId" : "9dd9fefb-f1fe-4222-8365-aacfaa7f62cf",
                          "createdAt" : "2025-11-17T16:31:32.574793Z",
                          "updatedAt" : "2025-11-17T16:31:32.574793Z",
                          "actions" : [ {
                            "title" : "Cancel",
                            "method" : "PUT",
                            "url" : "http://localhost:8080/core/v2/executions/68c31949-3bf4-4dba-aa9d-e3240a4db84b/cancel"
                          } ],
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/60efa278-d9c1-442c-98cb-7dd862406776",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/executions/68c31949-3bf4-4dba-aa9d-e3240a4db84b",
                              "title" : "CreateEndpointProcess"
                            }
                          }
                        }, {
                          "id" : "6a41cced-6e9a-4a2c-879f-66379a67e475",
                          "networkId" : "60efa278-d9c1-442c-98cb-7dd862406776",
                          "processId" : "a8713822-229b-4f63-8441-dae402bc575d",
                          "name" : "CreateEndpointProcess",
                          "description" : "Fake Process",
                          "resourceType" : "component",
                          "resourceId" : "6b0088c5-ba19-4040-9e37-7d6116d0ac9b",
                          "startedAt" : "2025-11-17T16:31:32.529892Z",
                          "finishedAt" : "2025-11-17T16:31:32.529892Z",
                          "traceId" : "trace1",
                          "status" : "SUCCESS",
                          "initiatingIdentityId" : "3fcde6bc-6288-4af9-88c5-3808bfec70d8",
                          "createdAt" : "2025-11-17T16:31:32.546710Z",
                          "updatedAt" : "2025-11-17T16:31:32.546710Z",
                          "actions" : [ ],
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/60efa278-d9c1-442c-98cb-7dd862406776",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/executions/6a41cced-6e9a-4a2c-879f-66379a67e475",
                              "title" : "CreateEndpointProcess"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/executions?networkId=60efa278-d9c1-442c-98cb-7dd862406776"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 3,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
          links:
            self:
              operationId: findExecutions
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/containers/{id}:
    get:
      tags:
        - Containers
      summary: Get Container
      description: |
        Returns a single Container by its unique identifier.
        The caller must have read permissions on the Container resource.
      operationId: getContainer
      parameters:
        - name: id
          in: path
          description: The unique identifier of the Container.
          required: true
          schema:
            type: string
            format: uuid
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        - name: meta
          in: query
          description: |
            Query and return (external) resources. Allowed meta values:
               * describeCloudContainer: Return detailed cloud container data
          schema:
            type: array
            items:
              type: string
              enum:
                - describeCloudContainer
      responses:
        '200':
          description: Container retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get container response
                  value: |-
                    {
                      "id" : "42321e36-4976-4a37-95dd-20399a092755",
                      "networkId" : "02239445-9a27-4680-984d-caf78df69950",
                      "provider" : "AWS",
                      "region" : "us-east-1",
                      "clusterId" : "cluster-1958",
                      "serviceId" : "service-1959",
                      "certificateId" : "service-1959",
                      "size" : "small",
                      "ipAddress1" : "1.2.3.4",
                      "ipAddress2" : "2.3.4.5",
                      "revision" : "556",
                      "image" : "ghcr.fake/container:0.2.1",
                      "imageDigest" : "QmQjNzewPfrhgtH0HBAzq",
                      "port" : 8080,
                      "createdBy" : "b9323d92-6a7b-4062-b136-3b88dfab202b",
                      "createdAt" : "2025-12-05T15:21:27.087054Z",
                      "updatedAt" : "2025-12-05T15:21:27.087054Z",
                      "deletedBy" : null,
                      "deletedAt" : null,
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/containers/42321e36-4976-4a37-95dd-20399a092755"
                        },
                        "network" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/networks/02239445-9a27-4680-984d-caf78df69950",
                          "profile" : "parent"
                        },
                        "provider" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/AWS"
                        },
                        "region" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/regions/AWS/us-east-1"
                        }
                      }
                    }
          links:
            provider:
              operationId: getCloudProvider
              parameters:
                cloudProvider: $response.body#/provider
            self:
              operationId: getContainer
              parameters:
                id: $response.body#/id
            region:
              operationId: getRegion
              parameters:
                provider: $response.body#/provider
                locationCode: $response.body#/region
            network:
              operationId: getNetwork
              parameters:
                id: $response.body#/networkId
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/containers:
    get:
      tags:
        - Containers
      summary: Find Containers
      description: >-
        Returns Containers matching the optional query parameters. Results are
        filtered to only include resources the caller may read.
      operationId: findContainers
      parameters:
        - name: networkId
          in: query
          description: Filter by Network ID(s). Repeat to specify multiple.
          example: 11111111-2222-3333-4444-555555555555
        - name: provider
          in: query
          description: Filter by cloud provider(s). Repeat to specify multiple.
          example: AWS
        - name: clusterId
          in: query
          description: Filter by provider cluster identifier(s).
          example: cluster-123456
        - name: serviceId
          in: query
          description: Filter by provider service/workload identifier(s).
          example: service-abcdef
        - name: certificateId
          in: query
          description: Filter by certificate identifier(s) installed on the load balancer.
          example: cert-xyz
        - name: ipAddress
          in: query
          description: Filter by IP address(es).
          example: 203.0.113.10
        - name: image
          in: query
          description: Filter by container image reference(s).
          example: netfoundry/edge-router:%
        - name: port
          in: query
          description: Filter by exposed container port(s).
          example: 8443
        - name: revision
          in: query
          description: Filter by task/workload definition revision(s).
          example: 3
        - name: containerSize
          in: query
          description: Filter by abstract Container size(s).
          example: small
        - name: region
          in: query
          description: Filter by cloud region code(s).
          example: us-east-1
        - name: availabilityZone
          in: query
          description: Filter by availability zone(s).
          example: us-east-1a
        - name: createdBy
          in: query
          description: Filter by creator identity ID(s).
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        - name: deletedBy
          in: query
          description: Filter by deleter identity ID(s).
          example: dddddddd-eeee-ffff-1111-222222222222
        - name: createdAt
          in: query
          description: >-
            Created-at filter expressions. Supports >, >=, <, <=, =, != (e.g.,
            createdAt=>=2025-01-01T00:00:00Z).
          example: '>=2025-01-01T00:00:00Z'
        - name: updatedAt
          in: query
          description: Updated-at filter expressions.
          example: <=2025-12-31T23:59:59Z
        - name: deletedAt
          in: query
          description: Deleted-at filter expressions.
          example: '>2025-10-01T00:00:00Z'
        - name: page
          in: query
          description: Page index (0-based).
          example: 0
        - name: size
          in: query
          description: Page size.
          example: 20
        - name: sort
          in: query
          description: Sort expressions, e.g., provider,updatedAt,desc.
          example: provider,asc
      responses:
        '200':
          description: A paginated list of Containers.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples: {}
          links:
            self:
              operationId: findContainers
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/container-sizes:
    get:
      tags:
        - Container Sizes
      summary: Find Container Sizes
      description: >-
        Returns container sizes aggregated across the selected cloud providers
        and optional container type filter. If no provider is specified, all
        providers are included. If no type is specified, both NC and ER sizes
        are returned.
      operationId: findContainerSizes
      parameters:
        - name: provider
          in: query
          description: Filter to cloud provider(s). Repeat to specify multiple.
          required: false
          schema:
            type: array
            items:
              type: string
              description: >-
                Enumerates supported cloud provider keys used throughout the
                API.
              enum:
                - AWS
                - AZURE
                - GCP
                - OCI
                - CUSTOMER
              example: AWS
          example: AWS
        - name: type
          in: query
          description: >-
            Container type filter. Accepts NC (NetworkController) or ER
            (EdgeRouter).
          required: false
          schema:
            type: string
          example: ER
      responses:
        '200':
          description: A collection of ContainerSize resources.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CollectionModel'
              examples:
                default:
                  description: Sample find container sizes response
                  value: |-
                    {
                      "_embedded" : {
                        "containerSizeList" : [ {
                          "name" : "small",
                          "containerType" : "BOOTSTRAPPER",
                          "providers" : [ "GCP", "OCI", "AWS", "AZURE" ],
                          "description" : [ ],
                          "default" : true,
                          "containerImage" : null,
                          "containerPort" : null
                        }, {
                          "name" : "medium",
                          "containerType" : "BOOTSTRAPPER",
                          "providers" : [ "GCP", "OCI", "AWS", "AZURE" ],
                          "description" : [ ],
                          "default" : false,
                          "containerImage" : null,
                          "containerPort" : null
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/container-sizes"
                        },
                        "providers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                        }
                      }
                    }
          links:
            self:
              operationId: findContainerSizes
            providers:
              operationId: listCloudProviders
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/clusters:
    get:
      tags:
        - Clusters
      summary: Find and retrieve a list of Clusters
      description: >
        Retrieve a paginated list of clusters. Filter the results by providing
        query parameters that correspond to the fields in the FindCluster
        object.

        Each cluster in the response contains links to itself, its parent
        network, and its leader.

        Instances that the API client does not have authorization to read will
        be removed from the results.
      operationId: findClusters
      parameters:
        - name: id
          in: query
          description: Filter by Cluster ID.
          schema:
            type: string
            format: uuid
        - name: networkId
          in: query
          description: Filter by Network ID.
          schema:
            type: string
            format: uuid
        - name: leaderId
          in: query
          description: Filter by Leader (Network Controller) ID.
          schema:
            type: string
            format: uuid
        - name: createdAt
          in: query
          description: >-
            Filter by creation timestamp using InstantFilter syntax (e.g.,
            >2025-01-01T00:00:00Z, <2025-12-31T23:59:59Z).
          schema:
            type: string
        - name: updatedAt
          in: query
          description: >-
            Filter by update timestamp using InstantFilter syntax (e.g.,
            >2025-01-01T00:00:00Z).
          schema:
            type: string
        - name: deletedAt
          in: query
          description: Filter by deletion timestamp using InstantFilter syntax.
          schema:
            type: string
        - name: page
          in: query
          description: Zero-based page index.
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: size
          in: query
          description: The number of resources returned per page.
          schema:
            type: integer
            default: 20
            minimum: 1
        - name: sort
          in: query
          description: 'Sorting criteria in the format: property,(asc|desc).'
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of Clusters.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/PagedModel'
              examples:
                default:
                  description: Sample find clusters request
                  value: |-
                    {
                      "_embedded" : {
                        "clusterList" : [ {
                          "id" : "c2d807d4-5604-4e83-8b33-3ac271c38502",
                          "networkId" : "5216bf18-ea8c-4346-ba21-426127201d78",
                          "leaderId" : "364330fb-1db0-4e3c-a678-a48e57fa1a92",
                          "createdAt" : "2025-11-17T16:30:43.439882Z",
                          "updatedAt" : "2025-11-17T16:30:43.439882Z",
                          "deletedAt" : null,
                          "readOnly" : false,
                          "partitioned" : false,
                          "leaderMemberInfos" : [ {
                            "id" : "364330fb-1db0-4e3c-a678-a48e57fa1a92",
                            "address" : "364330fb-1db0-4e3c-a678-a48e57fa1a92",
                            "voter" : true,
                            "leader" : true,
                            "version" : null,
                            "connected" : true,
                            "readOnly" : false
                          } ],
                          "_links" : {
                            "network" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/networks/5216bf18-ea8c-4346-ba21-426127201d78",
                              "profile" : "parent"
                            },
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/clusters/c2d807d4-5604-4e83-8b33-3ac271c38502"
                            },
                            "leader" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v2/network-controllers/364330fb-1db0-4e3c-a678-a48e57fa1a92"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v2/clusters"
                        }
                      },
                      "page" : {
                        "size" : 3500,
                        "totalElements" : 1,
                        "totalPages" : 1,
                        "number" : 0
                      }
                    }
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/cloud-providers/{cloudProvider}:
    get:
      tags:
        - Cloud Providers
      summary: Get Cloud Provider
      description: >-
        Returns a single Cloud Provider by its machine-readable key (e.g., AWS,
        GCP, OCI).
      operationId: getCloudProvider
      parameters:
        - name: cloudProvider
          in: path
          description: Cloud provider key.
          required: true
          schema:
            type: string
            description: Enumerates supported cloud provider keys used throughout the API.
            enum:
              - AWS
              - AZURE
              - GCP
              - OCI
              - CUSTOMER
            example: AWS
          example: AWS
      responses:
        '200':
          description: Cloud Provider retrieved.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EntityModel'
              examples:
                default:
                  description: Sample get cloud provider response
                  value: |-
                    {
                      "type" : "OCI",
                      "name" : "OCI Name",
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/OCI"
                        },
                        "providers" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                        },
                        "regions" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/regions?providers=OCI"
                        }
                      }
                    }
          links:
            regions:
              operationId: findRegions
            self:
              operationId: getCloudProvider
              parameters:
                cloudProvider: $request.path.cloudProvider
            providers:
              operationId: listCloudProviders
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
  /v3/cloud-providers:
    get:
      tags:
        - Cloud Providers
      summary: List Cloud Providers
      description: Returns the list of supported cloud providers.
      operationId: listCloudProviders
      responses:
        '200':
          description: A collection of CloudProvider resources.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CollectionModel'
              examples:
                default:
                  description: Sample list cloud providers response
                  value: |-
                    {
                      "_embedded" : {
                        "cloudProviderList" : [ {
                          "type" : "AWS",
                          "name" : "AWS Name",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/AWS"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/regions?providers=AWS"
                            }
                          }
                        }, {
                          "type" : "AZURE",
                          "name" : "Azure Name",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/AZURE"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/regions?providers=AZURE"
                            }
                          }
                        }, {
                          "type" : "GCP",
                          "name" : "GCP Name",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/GCP"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/regions?providers=GCP"
                            }
                          }
                        }, {
                          "type" : "OCI",
                          "name" : "OCI Name",
                          "_links" : {
                            "self" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers/OCI"
                            },
                            "providers" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                            },
                            "regions" : {
                              "href" : "https://gateway.production.netfoundry.io/core/v3/regions?providers=OCI"
                            }
                          }
                        } ]
                      },
                      "_links" : {
                        "self" : {
                          "href" : "https://gateway.production.netfoundry.io/core/v3/cloud-providers"
                        }
                      }
                    }
          links:
            self:
              operationId: listCloudProviders
        '400':
          description: Invalid Client Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '401':
          description: Not Authenticated
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '403':
          description: Not Authorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProblemDetailsException'
              examples: {}
components:
  schemas:
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
          format: uri
        properties:
          type: object
          additionalProperties: {}
    ProblemDetailsException:
      type: object
      properties:
        cause:
          type: object
          properties:
            stackTrace:
              type: array
              items:
                type: object
                properties:
                  classLoaderName:
                    type: string
                  moduleName:
                    type: string
                  moduleVersion:
                    type: string
                  methodName:
                    type: string
                  fileName:
                    type: string
                  lineNumber:
                    type: integer
                    format: int32
                  className:
                    type: string
                  nativeMethod:
                    type: boolean
            message:
              type: string
            localizedMessage:
              type: string
        stackTrace:
          type: array
          items:
            type: object
            properties:
              classLoaderName:
                type: string
              moduleName:
                type: string
              moduleVersion:
                type: string
              methodName:
                type: string
              fileName:
                type: string
              lineNumber:
                type: integer
                format: int32
              className:
                type: string
              nativeMethod:
                type: boolean
        problemDetail:
          $ref: '#/components/schemas/ProblemDetail'
        message:
          type: string
        suppressed:
          type: array
          items:
            type: object
            properties:
              stackTrace:
                type: array
                items:
                  type: object
                  properties:
                    classLoaderName:
                      type: string
                    moduleName:
                      type: string
                    moduleVersion:
                      type: string
                    methodName:
                      type: string
                    fileName:
                      type: string
                    lineNumber:
                      type: integer
                      format: int32
                    className:
                      type: string
                    nativeMethod:
                      type: boolean
              message:
                type: string
              localizedMessage:
                type: string
        localizedMessage:
          type: string
    Network:
      type: object
      properties:
        id:
          type: string
          format: uuid
        ownerIdentityId:
          type: string
          format: uuid
        createdBy:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedBy:
          type: string
          format: uuid
        deletedAt:
          type: string
          format: date-time
        name:
          type: string
        networkGroupId:
          type: string
          format: uuid
        size:
          type: string
          deprecated: true
        productVersion:
          $ref: '#/components/schemas/Semver'
        platformVersion:
          type: integer
          format: int32
        region:
          type: string
          deprecated: true
        status:
          type: string
          description: >-
            Enumerates lifecycle and operational states for Core resources
            (e.g., Edge Routers, Network Controllers, Networks). Useful for
            clients to track long-running operations and final states.
          enum:
            - NEW
            - PROVISIONING
            - PROVISIONED
            - ERROR
            - UPDATING
            - SUSPENDED
            - REPLACING
            - DELETING
            - DELETED
            - OFFLINE
          example: PROVISIONED
        publicCertEnabled:
          type: boolean
        haEnabled:
          type: boolean
        dnsZoneId:
          type: string
          format: uuid
        networkController:
          $ref: '#/components/schemas/NetworkController'
          deprecated: true
      required:
        - name
        - networkGroupId
        - productVersion
        - size
    NetworkController:
      type: object
      properties:
        id:
          type: string
          format: uuid
        ownerIdentityId:
          type: string
          format: uuid
        networkId:
          type: string
          format: uuid
        domainName:
          type: string
        alternateDomainName:
          type: string
        publicDomainName:
          type: string
        alternatePublicDomainName:
          type: string
        port:
          type: integer
          format: int32
        name:
          type: string
        productVersion:
          $ref: '#/components/schemas/Semver'
        hostId:
          type: string
          format: uuid
        status:
          type: string
          description: >-
            Enumerates lifecycle and operational states for Core resources
            (e.g., Edge Routers, Network Controllers, Networks). Useful for
            clients to track long-running operations and final states.
          enum:
            - NEW
            - PROVISIONING
            - PROVISIONED
            - ERROR
            - UPDATING
            - SUSPENDED
            - REPLACING
            - DELETING
            - DELETED
            - OFFLINE
          example: PROVISIONED
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
        createdBy:
          type: string
          format: uuid
        deletedBy:
          type: string
          format: uuid
        softwareDeploymentStateId:
          type: string
          format: uuid
        haPrimaryNode:
          type: boolean
    Semver:
      type: object
      properties:
        originalValue:
          type: string
        value:
          type: string
        major:
          type: integer
          format: int32
        minor:
          type: integer
          format: int32
        patch:
          type: integer
          format: int32
        suffixTokens:
          type: array
          items:
            type: string
        build:
          type: string
        type:
          type: string
          enum:
            - STRICT
            - LOOSE
            - NPM
            - COCOAPODS
            - IVY
        stable:
          type: boolean
    RestartOptions:
      type: object
      description: Options to control restart behavior for network processes and hosts.
      properties:
        concurrentControllerRestart:
          type: boolean
          description: >-
            If true, restarts controller services concurrently with the primary
            restart operation. Defaults to false when omitted.
          example: false
    EntityModel:
      type: object
      properties:
        content: {}
        _links:
          $ref: '#/components/schemas/Links'
    MoveHost:
      type: object
      description: >-
        Payload to move a host to a different provider/region or within the same
        provider. When moving within the same provider and region, you may
        either request a new IP to be assigned or specify a previously allocated
        IP address.
      properties:
        provider:
          type: string
          description: Target cloud provider for the host.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        region:
          type: string
          description: Target region within the selected provider.
          example: us-east-1
        assignNewIp:
          type: boolean
          description: >-
            If true, force assignment of a new IP address when moving within the
            same provider and region. Ignored when moving across
            providers/regions.
          example: false
        ipAddress:
          type: string
          description: >-
            A previously allocated IPv4 address to assign to the host. Provide
            either this value or set assignNewIp to true, but not both.
          example: 203.0.113.10
        skipBackup:
          type: boolean
          description: >-
            If true, skip taking a new backup before moving. The latest existing
            backup will be used.
      required:
        - provider
        - region
    ResizeHost:
      type: object
      description: >-
        Payload to resize a host. Provide the desired deployment size
        identifier; valid values depend on provider/region and account policy
        (e.g., small, medium, large).
      properties:
        size:
          type: string
          description: Desired deployment size identifier for the host.
          example: small
      required:
        - size
    CreateAppWan:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        serviceAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        endpointAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        postureCheckAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
    CreateCertificateAuthority:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        autoCaEnrollmentEnabled:
          type: boolean
        authEnabled:
          type: boolean
        ottCaEnrollmentEnabled:
          type: boolean
        certPem:
          type: string
          maxLength: 2147483647
          minLength: 100
        endpointAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        identityNameFormat:
          type: string
      required:
        - certPem
    CreateConfig:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        configTypeId:
          type: string
          format: uuid
        configTypeName:
          type: string
        configType:
          $ref: '#/components/schemas/CreateConfigType'
        data:
          $ref: '#/components/schemas/JsonNode'
    CreateConfigType:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        schema:
          $ref: '#/components/schemas/JsonNode'
    CreateEdgeRouter:
      type: object
      description: >-
        Payload to create an Edge Router. When provider is CUSTOMER, region is
        ignored.
      properties:
        networkId:
          type: string
          format: uuid
          description: ID of the Network in which to create the Edge Router.
          example: 11111111-2222-3333-4444-555555555555
        zitiId:
          type: string
          description: The Ziti ID to assign to the Edge Router.
          example: zi:er:abcd1234
        provider:
          type: string
          description: Hosting provider. Use CUSTOMER for customer-hosted routers.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        region:
          type: string
          description: >-
            Cloud region code. Required for NF-hosted providers; ignored for
            CUSTOMER.
          example: us-east-1
        hostSize:
          type: string
          description: Host size or instance type for NF-hosted Edge Router.
          example: SMALL
        linkListener:
          type: boolean
          description: Enable legacy link listener (TCP).
          example: true
        wssListener:
          type: boolean
          description: Enable WSS listener for the Edge Router.
          example: true
        alternateDomainName:
          type: string
          description: >-
            Optional alternate DNS name to assign to the Edge Router host.
            Ignored for CUSTOMER hosted routers.
          example: er1.example.net
      required:
        - networkId
        - provider
        - zitiId
    CreateEdgeRouterPolicy:
      type: object
      properties:
        name:
          type: string
        networkId:
          type: string
          format: uuid
        semantic:
          type: string
          enum:
            - AllOf
            - AnyOf
        endpointAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        edgeRouterAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
      required:
        - name
        - networkId
        - semantic
    CreateEndpoint:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        enrollmentMethod:
          $ref: '#/components/schemas/EnrollmentMethod'
        externalId:
          type: string
        authPolicyId:
          type: string
          format: uuid
        attributes:
          type: array
          items:
            type: string
          uniqueItems: true
        syncId:
          type: string
          format: uuid
        syncResourceId:
          type: string
        brandingOrganizationId:
          type: string
          format: uuid
        shareRegistration:
          $ref: '#/components/schemas/EmailParam'
      required:
        - enrollmentMethod
    CreateNetworkController:
      type: object
      description: >-
        Payload to create a Network Controller. Fields marked as required must
        be present. When provider is CUSTOMER, region is ignored and
        customerProviderDetails must be supplied. If haVotingMember is omitted,
        it defaults to true.
      properties:
        networkId:
          type: string
          format: uuid
          description: ID of the Network in which to create the Network Controller.
          example: f4fe1cd7-5a87-45a2-a2c8-d37e6066a794
        name:
          type: string
          description: >-
            Human-friendly name of the Network Controller. Must be unique within
            the Network.
          example: east-us-controller
        hostSize:
          type: string
          description: >-
            Deployment size identifier for the controller host. If omitted, a
            provider-specific default will be used.
          example: small
        provider:
          type: string
          description: >-
            Cloud provider that will host the controller. Use CUSTOMER for
            customer-hosted controllers.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        region:
          type: string
          description: >-
            Cloud region for NetFoundry-hosted controllers. Ignored when
            provider is CUSTOMER.
          example: us-east-1
        alternateDomainName:
          type: string
          description: Optional alternate domain name (CNAME) to use for the controller.
          example: nc.example.com
        customerProviderDetails:
          $ref: '#/components/schemas/CustomerProviderDetails'
          description: >-
            Required when provider is CUSTOMER. Connection and access details
            for the customer-managed host.
        haVotingMember:
          type: boolean
          description: >-
            Whether this controller participates as a voting member in an HA
            cluster. Defaults to true when omitted.
          example: true
      required:
        - name
        - networkId
        - provider
    CreatePostureCheck:
      type: object
      properties:
        name:
          type: string
        networkId:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - OS
            - PROCESS
            - DOMAIN
            - MAC
            - MFA
            - PROCESS_MULTI
        attributes:
          type: array
          items:
            type: string
          uniqueItems: true
        data:
          oneOf:
            - $ref: '#/components/schemas/DomainPostureCheckData'
            - $ref: '#/components/schemas/MacPostureCheckData'
            - $ref: '#/components/schemas/MfaPostureCheckData'
            - $ref: '#/components/schemas/OsPostureCheckData'
            - $ref: '#/components/schemas/ProcessMultiPostureCheckData'
            - $ref: '#/components/schemas/ProcessPostureCheckData'
      required:
        - data
    CreateService:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        encryptionRequired:
          type: boolean
        terminatorStrategy:
          type: string
        configIds:
          type: array
          items:
            type: string
            format: uuid
          uniqueItems: true
        configNames:
          type: array
          items:
            type: string
          uniqueItems: true
        configs:
          type: array
          items:
            $ref: '#/components/schemas/CreateConfig'
          uniqueItems: true
        attributes:
          type: array
          items:
            type: string
          uniqueItems: true
        modelType:
          type: string
          enum:
            - Generic
            - TunnelerToSdk
            - TunnelerToEndpoint
            - TunnelerToEdgeRouter
            - AdvancedTunnelerToEndpoint
            - ZSSH
        model:
          $ref: '#/components/schemas/PlatformModel'
    CreateServiceEdgeRouterPolicy:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        semantic:
          type: string
          enum:
            - AllOf
            - AnyOf
        edgeRouterAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        serviceAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
      required:
        - name
        - networkId
        - semantic
    CreateServicePolicy:
      type: object
      properties:
        networkId:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
            - Dial
            - Bind
        semantic:
          type: string
          enum:
            - AllOf
            - AnyOf
        serviceAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        endpointAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        postureCheckAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
      required:
        - name
        - networkId
        - semantic
    CustomerProviderDetails:
      type: object
      description: >-
        Details required when the network controller is deployed in a hybrid
        environment.
      properties:
        ipAddress:
          type: string
          description: >-
            IP address or hostname for the customer-managed controller's
            management interface.
          example: 203.0.113.10
        managementPort:
          type: integer
          format: int32
          default: 8443
          description: TCP port for the controller's management API.
          example: 8443
          maximum: 65535
          minimum: 1
        sshAccessKeyPairName:
          type: string
          description: >-
            Name of the stored SSH access key pair to use for connecting to the
            host.
          example: nc-admin-keypair
      required:
        - ipAddress
        - sshAccessKeyPairName
    DomainPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            domains:
              type: array
              items:
                type: string
              minItems: 1
              uniqueItems: true
      required:
        - domains
    EmailParam:
      type: object
      properties:
        id:
          type: string
          format: uuid
        toList:
          type: array
          items:
            type: string
          minItems: 1
        ccList:
          type: array
          items:
            type: string
        subject:
          type: string
      required:
        - id
        - toList
    EnrollmentMethod:
      type: object
      properties:
        ott:
          type: boolean
        updb:
          type: string
        ottca:
          type: string
          format: uuid
    JsonNode: {}
    MacPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            macAddresses:
              type: array
              items:
                type: string
              minItems: 1
              uniqueItems: true
      required:
        - macAddresses
    MfaPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            timeoutSeconds:
              type: integer
              format: int32
              minimum: -1
            promptOnWake:
              type: boolean
            promptOnUnlock:
              type: boolean
            ignoreLegacyEndpoints:
              type: boolean
    OperatingSystem:
      type: object
      properties:
        type:
          type: string
          enum:
            - Windows
            - Android
            - iOS
            - Linux
            - macOS
            - WindowsServer
        versions:
          type: array
          items:
            type: string
          uniqueItems: true
      required:
        - type
        - versions
    OsPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            operatingSystems:
              type: array
              items:
                $ref: '#/components/schemas/OperatingSystem'
              minItems: 1
              uniqueItems: true
      required:
        - operatingSystems
    PlatformModel: {}
    PostureCheckDataObject: {}
    Process:
      type: object
      properties:
        osType:
          type: string
          enum:
            - Windows
            - WindowsServer
            - Android
            - iOS
            - Linux
            - macOS
        path:
          type: string
          minLength: 1
        hashes:
          type: array
          items:
            type: string
            pattern: ^[0-9A-Fa-f]*$
          uniqueItems: true
        signerFingerprints:
          type: array
          items:
            type: string
          uniqueItems: true
      required:
        - osType
        - path
    ProcessMultiPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            processes:
              type: array
              items:
                $ref: '#/components/schemas/Process'
              minItems: 1
              uniqueItems: true
            semantic:
              type: string
              enum:
                - AllOf
                - AnyOf
      required:
        - processes
    ProcessPostureCheckData:
      allOf:
        - $ref: '#/components/schemas/PostureCheckDataObject'
        - type: object
          properties:
            process:
              $ref: '#/components/schemas/Process'
      required:
        - process
    UpdateNetwork:
      type: object
      description: >-
        Payload to update mutable properties of a Network. Omit fields you do
        not wish to change. Supports PATCH and PUT semantics where omitted
        fields remain unchanged.
      properties:
        name:
          type: string
          description: New human-friendly name for the Network.
          example: My Updated Network
        publicCertEnabled:
          type: boolean
          description: >-
            Enable public certificate for the Network (required for v8
            networks). If omitted, controller may enforce defaults.
          example: true
        haEnabled:
          type: boolean
          description: Enable High Availability (allows additional Network Controllers).
          example: true
        networkControllers:
          type: array
          items:
            $ref: '#/components/schemas/CreateNetworkController'
          uniqueItems: true
        edgeRouters:
          type: array
          items:
            $ref: '#/components/schemas/CreateEdgeRouter'
          uniqueItems: true
        edgeRouterPolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateEdgeRouterPolicy'
          uniqueItems: true
        serviceEdgeRouterPolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateServiceEdgeRouterPolicy'
          uniqueItems: true
        servicePolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateServicePolicy'
          uniqueItems: true
        services:
          type: array
          items:
            $ref: '#/components/schemas/CreateService'
          uniqueItems: true
        certificateAuthorities:
          type: array
          items:
            $ref: '#/components/schemas/CreateCertificateAuthority'
          uniqueItems: true
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/CreateEndpoint'
          uniqueItems: true
        appWans:
          type: array
          items:
            $ref: '#/components/schemas/CreateAppWan'
          uniqueItems: true
        postureChecks:
          type: array
          items:
            $ref: '#/components/schemas/CreatePostureCheck'
          uniqueItems: true
        ownerIdentityId:
          type: string
          format: uuid
          description: Transfer ownership to another identity.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    UpdateStoredSecret:
      type: object
      description: >-
        Payload to update an existing Stored Secret. You may change the
        human-friendly name and/or update the secret value. Omit a field to
        leave it unchanged. When updating via the share-token OTT flow, only the
        value is accepted and the body is plain text.
      properties:
        name:
          type: string
          description: >-
            New human-friendly name for the secret (must be unique within the
            Network Group). When omitted, the name is unchanged.
          example: my-ssh-key-updated
        value:
          description: >-
            New secret value to store. Treated as opaque. If the secret type is
            PRIVATE_KEY, provide a PEM formatted private key string. When
            omitted (or empty string for JSON requests), the value is not
            updated. In the OTT flow, this field is required and the request
            body is plain text.
          example: |-
            -----BEGIN PRIVATE KEY-----
            MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...
            -----END PRIVATE KEY-----
    UpdateSoftwareDeploymentState:
      type: object
      description: >-
        Fields that can be updated on a SoftwareDeploymentState. All properties
        are optional; omit or set to null to leave a field unchanged.
      properties:
        softwareConfigurationPortEnabled:
          type: boolean
          description: >-
            Enable or disable the privileged software configuration management
            port on the resource.
          example: true
    UpdateNetworkGroup:
      type: object
      description: >-
        Fields that can be updated on a Network Group. All properties are
        optional; only provided values will be changed.
      properties:
        name:
          type: string
          description: New human-friendly name for the Network Group.
          example: engineering-networks
        billingAccountId:
          type: string
          format: uuid
          description: Billing Account ID to associate with this Network Group.
          example: 11111111-2222-3333-4444-555555555555
        ownerIdentityId:
          type: string
          format: uuid
          description: Identity ID of the owner for this Network Group.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    ValidationError:
      type: object
      properties:
        path:
          type: string
        label:
          type: string
        message:
          type: string
    UpdateNetworkController:
      type: object
      description: >-
        Payload to update a Network Controller. Omit fields you do not wish to
        change. When a field is present with a null value (for PATCH), it will
        be ignored due to validation rules.
      properties:
        name:
          type: string
          description: >-
            New human-friendly name of the Network Controller. Must be unique
            within the Network.
          example: east-us-controller
        haVotingMember:
          type: boolean
          description: >-
            Whether this controller participates as a voting member in an HA
            cluster. If omitted, no change will be made.
          example: false
    UpdateDnsZone:
      type: object
      description: >-
        Fields that can be updated on a DnsZone. Currently only the name is
        mutable. All properties are optional; only provided values will be
        changed.
      properties:
        name:
          type: string
          description: New human-friendly name for the DnsZone.
          example: corp-zone
    UpdateCluster:
      type: object
      properties:
        leaderId:
          type: string
          format: uuid
          description: Identifies the network controller that leads the cluster.
          example: 123e4567-e89b-12d3-a456-426614174000
    Cluster:
      type: object
      description: Properties of the network's cluster.
      properties:
        id:
          type: string
          format: uuid
          description: Uniquely identifies the cluster.
          example: 123e4567-e89b-12d3-a456-426614174000
        networkId:
          type: string
          format: uuid
          description: Identifies the network to which this cluster belongs.
          example: 123e4567-e89b-12d3-a456-426614174000
        leaderId:
          type: string
          format: uuid
          description: Identifies the network controller that leads the cluster.
          example: 123e4567-e89b-12d3-a456-426614174000
        createdAt:
          type: string
          format: date-time
          description: Specifies the timestamp when the cluster was created.
        updatedAt:
          type: string
          format: date-time
          description: Specifies the timestamp when the cluster was last updated.
        deletedAt:
          type: string
          format: date-time
          description: Specifies the timestamp when the cluster was deleted.
        readOnly:
          type: boolean
          description: Indicates if the cluster is in read-only mode.
        partitioned:
          type: boolean
          description: Indicates if the cluster is partitioned.
        leaderMemberInfos:
          type: array
          description: >-
            Provides information about the members of the cluster, as reported
            by the leader.
          items:
            $ref: '#/components/schemas/ZitiMemberInfo'
      required:
        - networkId
    ZitiMemberInfo:
      type: object
      properties:
        id:
          type: string
        address:
          type: string
        voter:
          type: boolean
        leader:
          type: boolean
        version:
          type: string
        connected:
          type: boolean
        readOnly:
          type: boolean
    CreateNetworkAssembly:
      type: object
      description: >-
        Payload to create a Network from an assembly. Includes desired product
        version, network HA setting, optional DNS zone, entities to import, Ziti
        export data and hosting definitions for Network Controllers and Edge
        Routers.
      properties:
        name:
          type: string
          description: Display name for the Network to be created.
          example: acme-prod
        haEnabled:
          type: boolean
          description: Enable High Availability (multiple controller nodes).
          example: true
        productVersion:
          type: string
          description: >-
            Desired product version for the Network (semantic version). If
            omitted, current default is used.
          example: 8.0.43
        customerProviderDetails:
          $ref: '#/components/schemas/CustomerProviderDetails'
          description: >-
            Provider details required when using CUSTOMER hosting for
            controllers/routers.
        entities:
          type: array
          description: >-
            Subset of entities from the Ziti export to import when creating the
            Network.
          example:
            - all
          items:
            type: string
          uniqueItems: true
        zitiData:
          $ref: '#/components/schemas/ZitiData'
          description: >-
            Ziti export data to seed the Network with services, identities,
            policies, etc.
        hosting:
          $ref: '#/components/schemas/CreateNetworkAssemblyHosting'
          description: >-
            Hosting directives that define controller nodes and edge routers to
            create.
        dnsZoneId:
          type: string
          format: uuid
          description: Optional DNS Zone to use for public DNS records.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        networkGroupId:
          type: string
          format: uuid
          description: ID of the Network Group in which to create the Network.
          example: 11111111-2222-3333-4444-555555555555
      required:
        - hosting
        - name
        - networkGroupId
    CreateNetworkAssemblyHosting:
      type: object
      description: Hosting directives for controllers and routers created with the Network.
      example:
        networkControllers:
          - name: nc-primary
            provider: AWS
            region: us-east-1
            size: SMALL
            productVersion: 8.0.43
            haPrimaryNode: true
        edgeRouters:
          - name: er-1
            provider: AWS
            region: us-east-1
            size: SMALL
      properties:
        networkControllers:
          type: array
          description: Controller nodes to create. If haEnabled=true, one must be primary.
          items:
            $ref: '#/components/schemas/NetworkControllerHosting'
          minItems: 1
        edgeRouters:
          type: array
          description: Edge Routers to create for this Network.
          items:
            $ref: '#/components/schemas/EdgeRouterHosting'
      required:
        - networkControllers
    EdgeRouterHosting:
      type: object
      description: Hosting details for a single Edge Router instance.
      properties:
        name:
          type: string
          description: Name to assign to the edge router instance.
          example: er-1
        provider:
          type: string
          description: Cloud provider where the instance will be deployed.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: aws
        region:
          type: string
          description: Region or zone identifier within the cloud provider.
          example: us-west-2
        size:
          type: string
          description: Instance size or flavor to use.
          example: t3.small
        alternateDomainName:
          type: string
          description: >-
            Optional alternate domain name (CNAME) to associate with this edge
            router.
          example: er1.acme.example.com
        linkListener:
          type: boolean
          description: >-
            Optional boolean indicating if the link (fabric) listener should be
            enabled.
          example: true
    NetworkControllerHosting:
      type: object
      description: Hosting details for a single Network Controller instance.
      properties:
        name:
          type: string
          description: Name to assign to the network controller instance.
          example: ctrl-primary
        provider:
          type: string
          description: Cloud provider where the instance will be deployed.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: aws
        region:
          type: string
          description: Region or zone identifier within the cloud provider.
          example: us-east-1
        size:
          type: string
          description: Instance size or flavor to use.
          example: t3.medium
        productVersion:
          $ref: '#/components/schemas/Semver'
          description: >-
            Desired product version for this controller, if different from the
            assembly version.
          example: 8.3.0
        haPrimaryNode:
          type: boolean
          description: >-
            When HA is enabled, indicates if this node is the primary
            controller.
          example: true
    ZitiData:
      type: object
      description: >-
        Ziti controller export/import payload containing controller version and
        collections of exported resources.
      properties:
        zitiVersion:
          $ref: '#/components/schemas/Semver'
          description: Ziti Controller semantic version for this export.
          example: 0.29.7
        identities:
          type: array
          description: >-
            List of identity resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        edgeRouters:
          type: array
          description: >-
            List of Edge Router resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        services:
          type: array
          description: >-
            List of service resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        configs:
          type: array
          description: >-
            List of config resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        configTypes:
          type: array
          description: >-
            List of config type resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        servicePolicies:
          type: array
          description: >-
            List of service policy resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        serviceEdgeRouterPolicies:
          type: array
          description: >-
            List of service edge router policy resources as arbitrary JSON
            objects from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        edgeRouterPolicies:
          type: array
          description: >-
            List of edge router policy resources as arbitrary JSON objects from
            the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        authPolicies:
          type: array
          description: >-
            List of authentication policy resources as arbitrary JSON objects
            from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        certificateAuthorities:
          type: array
          description: >-
            List of certificate authority resources as arbitrary JSON objects
            from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        externalJwtSigners:
          type: array
          description: >-
            List of external JWT signer resources as arbitrary JSON objects from
            the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        postureChecks:
          type: array
          description: >-
            List of posture check resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
    UpdateNetworkAssembly:
      type: object
      description: >-
        Payload to update a Network from an assembly. Includes desired product
        version, network HA setting, optional DNS zone, entities to import, Ziti
        export data and hosting definitions for Network Controllers and Edge
        Routers.
      properties:
        name:
          type: string
          description: Display name for the Network to be created.
          example: acme-prod
        haEnabled:
          type: boolean
          description: Enable High Availability (multiple controller nodes).
          example: true
        productVersion:
          type: string
          description: >-
            Desired product version for the Network (semantic version). If
            omitted, current default is used.
          example: 8.0.43
        customerProviderDetails:
          $ref: '#/components/schemas/CustomerProviderDetails'
          description: >-
            Provider details required when using CUSTOMER hosting for
            controllers/routers.
        entities:
          type: array
          description: >-
            Subset of entities from the Ziti export to import when creating the
            Network.
          example:
            - all
          items:
            type: string
          uniqueItems: true
        zitiData:
          $ref: '#/components/schemas/ZitiData'
          description: >-
            Ziti export data to seed the Network with services, identities,
            policies, etc.
        hosting:
          $ref: '#/components/schemas/CreateNetworkAssemblyHosting'
          description: >-
            Hosting directives that define controller nodes and edge routers to
            create.
        dnsZoneId:
          type: string
          format: uuid
          description: Optional DNS Zone to use for public DNS records.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
      required:
        - hosting
        - name
    UpdateEdgeRouter:
      type: object
      description: >-
        Payload to update an existing Edge Router. Attribute changes are only
        supported via PATCH.
      example:
        name: er-nyc-01
        linkListener: true
      properties:
        name:
          type: string
          description: Display name for the Edge Router.
          example: er-nyc-01
        linkListener:
          type: boolean
          description: Enable or disable link listener (TCP) for hosted edge routers only.
          example: true
        attributes:
          type: array
          description: Attributes to apply to the Edge Router.
          items:
            type: string
          uniqueItems: true
        empty:
          type: boolean
    CreateRegistration:
      type: object
      properties:
        organizationId:
          type: string
          format: uuid
        networkId:
          type: string
          format: uuid
        id:
          type: string
        type:
          type: string
          enum:
            - IDENTITY
            - EDGEROUTER
        to:
          type: array
          items:
            type: string
          minItems: 1
        cc:
          type: array
          items:
            type: string
        subject:
          type: string
      required:
        - id
        - networkId
        - to
        - type
    CreateNetwork:
      type: object
      description: >-
        Payload to create a new Network. Specify the Network Group, optional
        product version and region, and whether features like public
        certificates and HA are enabled. When provider is CUSTOMER,
        customerProviderDetails must be supplied.
      properties:
        networkGroupId:
          type: string
          format: uuid
          description: ID of the Network Group that will own the new Network.
          example: 11111111-2222-3333-4444-555555555555
        size:
          type: string
          description: >-
            Requested deployment size for controller hosts. If omitted, a
            provider-specific default is selected.
          example: small
        name:
          type: string
          description: Human-friendly name for the Network.
          example: My Production Network
        productVersion:
          $ref: '#/components/schemas/Semver'
          description: >-
            Desired Network software product version in semantic version format.
            If omitted, defaults to the current v8 default.
          example: 8.1.0
        provider:
          type: string
          description: >-
            Cloud provider that will host the Network. Use CUSTOMER for
            customer-hosted networks.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        region:
          type: string
          description: >-
            Cloud region code. Ignored for CUSTOMER provider where it is set to
            'none'.
          example: us-east-1
        publicCertEnabled:
          type: boolean
          description: >-
            Enable public certificate for the Network (required for v8
            networks). If omitted, controller may enforce defaults.
          example: true
        haEnabled:
          type: boolean
          description: >-
            Enable High Availability (allow creation of additional Network
            Controllers).
          example: false
        dnsZoneId:
          type: string
          format: uuid
          description: Reference to a validated DNS Zone to use for public certificates.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        alternateDomainName:
          type: string
          description: Alternate domain name to use for controller endpoints.
          example: edge.example.com
        customerProviderDetails:
          $ref: '#/components/schemas/CustomerProviderDetails'
          description: >-
            Details required when provider is CUSTOMER (e.g., SSH key pair name,
            VPC, etc.).
        networkControllers:
          type: array
          items:
            $ref: '#/components/schemas/CreateNetworkController'
          uniqueItems: true
        edgeRouters:
          type: array
          items:
            $ref: '#/components/schemas/CreateEdgeRouter'
          uniqueItems: true
        edgeRouterPolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateEdgeRouterPolicy'
          uniqueItems: true
        serviceEdgeRouterPolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateServiceEdgeRouterPolicy'
          uniqueItems: true
        servicePolicies:
          type: array
          items:
            $ref: '#/components/schemas/CreateServicePolicy'
          uniqueItems: true
        services:
          type: array
          items:
            $ref: '#/components/schemas/CreateService'
          uniqueItems: true
        certificateAuthorities:
          type: array
          items:
            $ref: '#/components/schemas/CreateCertificateAuthority'
          uniqueItems: true
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/CreateEndpoint'
          uniqueItems: true
        appWans:
          type: array
          items:
            $ref: '#/components/schemas/CreateAppWan'
          uniqueItems: true
        postureChecks:
          type: array
          items:
            $ref: '#/components/schemas/CreatePostureCheck'
          uniqueItems: true
      required:
        - name
        - networkGroupId
        - provider
    ExchangeRequest:
      type: object
      description: >-
        Payload for exchanging the caller's authenticated Core API context for a
        Ziti token. If omitted, the default token type is AUTO.
      properties:
        type:
          type: string
          description: >-
            The type of token to return. Auto will return a Bearer token for HA
            enabled networks and Session for non-HA networks.
          enum:
            - AUTO
            - SESSION
            - BEARER
          example: SESSION
    CreateRegistrationKey:
      type: object
      description: >-
        Request payload to create or fetch an Edge Router registration key for a
        given Network and Ziti ID. The Ziti ID must not already be provisioned.
      example:
        networkId: 11111111-2222-3333-4444-555555555555
        zitiId: abcd1234
      properties:
        networkId:
          type: string
          format: uuid
          description: ID of the Network in which the Edge Router is being registered.
          example: 11111111-2222-3333-4444-555555555555
        zitiId:
          type: string
          description: >-
            Ziti ID of the Edge Router to register. Must correspond to an
            unprovisioned router.
          example: abcd1234
      required:
        - networkId
        - zitiId
    EdgeRouterRegistrationKeyResponse:
      type: object
      properties:
        registrationKey:
          type: string
        expiresAt:
          type: string
          format: date-time
    EdgeRouter:
      type: object
      description: Represents an Edge Router within a Network.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of this Edge Router.
          example: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
        hostId:
          type: string
          format: uuid
          description: ID of the Host running this Edge Router, when applicable.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        ownerIdentityId:
          type: string
          format: uuid
          description: Identity ID of the owner for this Edge Router.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        createdBy:
          type: string
          format: uuid
          description: Identity ID that created this Edge Router.
          example: bbbbbbbb-1111-2222-3333-cccccccccccc
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this Edge Router was created (UTC).
          example: '2025-10-09T12:34:56Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this Edge Router was last updated (UTC).
          example: '2025-10-09T12:40:00Z'
        deletedBy:
          type: string
          format: uuid
          description: Identity ID that deleted this Edge Router, if applicable.
          example: dddddddd-eeee-ffff-1111-222222222222
        deletedAt:
          type: string
          format: date-time
          description: Timestamp when this Edge Router was deleted (UTC), if applicable.
          example: '2025-10-09T13:00:00Z'
        zitiId:
          type: string
          description: >-
            Ziti Edge Router identifier within the Ziti controller, when
            applicable.
          example: er_abcdef123456
        domainName:
          type: string
          description: Primary DNS name for this Edge Router.
          example: er1.example.netfoundry.io
        alternateDomainName:
          type: string
          description: Alternate DNS name for this Edge Router, when configured.
          example: alt-er1.example.netfoundry.io
        publicDomainName:
          type: string
          description: Publicly reachable DNS name if exposed through a public interface.
        name:
          type: string
          description: Display name of the Edge Router (unique within a Network).
          example: er-east-1a
        productVersion:
          $ref: '#/components/schemas/Semver'
          description: Network product version of the Edge Router.
          example: 8.5.0
        networkId:
          type: string
          format: uuid
          description: ID of the Network to which this Edge Router belongs.
          example: 11111111-2222-3333-4444-555555555555
        jwt:
          type: string
          description: >-
            JWT used for Edge Router enrollment. This is a short-lived token
            that is exchanged for a client certificate upon successful
            enrollment.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        linkListener:
          type: boolean
          description: True when the link (fabric) listener is enabled.
          example: true
        wssListener:
          type: boolean
          description: True when the WebSocket (WSS) listener is enabled.
          example: false
        online:
          type: boolean
          description: True when edge router is online.
          example: true
        verified:
          type: boolean
          description: True when edge router is verified.
          example: true
        status:
          type: string
          description: Operational status of the Edge Router.
          enum:
            - NEW
            - PROVISIONING
            - PROVISIONED
            - ERROR
            - UPDATING
            - SUSPENDED
            - REPLACING
            - DELETING
            - DELETED
            - OFFLINE
          example: PROVISIONED
        softwareDeploymentStateId:
          type: string
          format: uuid
          description: ID of the SoftwareDeploymentState associated with this Edge Router.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        provider:
          type: string
          deprecated: true
          description: Enumerates supported cloud provider keys used throughout the API.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        region:
          type: string
          deprecated: true
        hostSize:
          type: string
          deprecated: true
        attributes:
          type: array
          items:
            type: string
          uniqueItems: true
    EdgeRouterRegistrationResponse:
      type: object
      description: >-
        Response returned to an Edge Router registration request. Contains the
        Edge Router resource, the Network Controller host the router should
        contact, the configuration template content, an expiration timestamp for
        the registration token, the controller/product version and related
        metadata, and whether High Availability (HA) is enabled.
      example:
        edgeRouter:
          id: 8f14e45f-ea3c-4c9f-9e9a-8a7d7f3a1c2b
          name: er-nyc-01
          networkId: 11111111-2222-3333-4444-555555555555
        networkControllerHost: controller-abc.netfoundry.io
        template: ... rendered edge router config ...
        expiresAt: '2025-01-01T00:00:00Z'
        productVersion: 8.0.43
        productMetadata:
          component: edge-router
        haEnabled: true
      properties:
        edgeRouter:
          $ref: '#/components/schemas/EdgeRouter'
          description: The Edge Router resource associated with this registration.
        networkControllerHost:
          type: string
          description: >-
            The Network Controller host that the Edge Router should contact for
            enrollment/operation.
          example: controller-abc.netfoundry.io
        template:
          type: string
          description: >-
            Edge Router configuration template or rendered content used by the
            registration script.
          example: ... rendered edge router config ...
        expiresAt:
          type: string
          format: date-time
          description: Timestamp when this registration response expires.
          example: '2025-01-01T00:00:00Z'
        productVersion:
          type: string
          description: Product/Controller version managing this registration.
          example: 8.0.43
        productMetadata:
          $ref: '#/components/schemas/JsonNode'
          description: Additional product metadata that may inform registration behavior.
          example:
            component: edge-router
        haEnabled:
          type: boolean
          description: Indicates if High Availability (HA) is enabled for the Network.
          example: true
    CreateStoredSecret:
      type: object
      description: >
        Payload to create a new Stored Secret within a Network Group. Provide a
        unique name within the group,

        an optional type (defaults to GENERIC), and an optional value. When type
        is PRIVATE_KEY,

        value must be a PEM formatted private key string. If value is omitted,
        the secret metadata is created and

        the value can be set later via the share-token OTT flow.
      properties:
        networkGroupId:
          type: string
          format: uuid
          description: ID of the Network Group that will own the secret.
          example: 11111111-2222-3333-4444-555555555555
        name:
          type: string
          description: >-
            Human-friendly name of the secret (must be unique within the Network
            Group).
          example: my-ssh-key
        type:
          type: string
          description: Type of the secret to store. Defaults to GENERIC when omitted.
          enum:
            - GENERIC
            - PRIVATE_KEY
          example: GENERIC
        value:
          description: >-
            Secret value to store. Treated as opaque. When type is PRIVATE_KEY,
            provide a PEM formatted private key string.
          example: >-
            -----BEGIN PRIVATE
            KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcw...\n-----END PRIVATE
            KEY-----
      required:
        - name
        - networkGroupId
    UpgradeNetwork:
      type: object
      description: Specifies the details for a network upgrade.
      properties:
        target:
          $ref: '#/components/schemas/Semver'
          description: >-
            The target version for the upgrade. If not specified, the network
            will be upgraded to the latest version available.
          example: 8.3.0
        ignoreOffline:
          type: boolean
          description: Whether to ignore offline edge routers during the upgrade.
        edgeRouterIds:
          type: array
          description: >-
            A set of edge router IDs to include in the upgrade. If not
            specified, all edge routers in the network will be upgraded.
          items:
            type: string
            format: uuid
          uniqueItems: true
        upgradeMode:
          type: string
          description: >-
            The upgrade mode to use. `FULL` will upgrade controllers and
            routers. `CONTROLLERS_ONLY` will upgrade only controllers.
            `EDGE_ROUTERS_ONLY` will upgrade only edge routers.
          enum:
            - FULL
            - CONTROLLERS_ONLY
            - EDGE_ROUTERS_ONLY
        concurrentControllerUpgrades:
          type: boolean
          description: Whether to upgrade network controllers concurrently.
    RestoreBackup:
      type: object
      description: >-
        Payload to restore a backup. Provide the S3 object name (filename) of
        the backup to restore. If omitted or null, the latest backup will be
        restored.
      properties:
        fileName:
          type: string
          description: >-
            Object name (filename) of the backup in S3. Null or empty means
            restore the latest.
          example: backup-2025-10-01T12-00-00Z.tar.gz
    CreateNetworkGroup:
      type: object
      description: >-
        Request body to create a Network Group. Provide the group's display
        name, billing account, and optionally an explicit owner identity.
      properties:
        name:
          type: string
          description: >-
            Human-friendly name for the Network Group (unique within your
            organization).
          example: engineering-networks
        billingAccountId:
          type: string
          format: uuid
          description: Billing Account ID that will be charged for this Network Group.
          example: 11111111-2222-3333-4444-555555555555
        ownerIdentityId:
          type: string
          format: uuid
          description: >-
            Identity ID of the owner for this Network Group. If omitted,
            defaults to the caller's identity.
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    UpgradeNetworkController:
      type: object
      description: Specifies the target version for a Network Controller upgrade.
      properties:
        target:
          $ref: '#/components/schemas/Semver'
          description: The target version for the upgrade.
          example: 8.3.0
      required:
        - target
    AllocateCloudAddress:
      type: object
      description: >-
        Request body to allocate a cloud IP address within a specific Network
        and region for the given provider.
      properties:
        provider:
          type: string
          description: Cloud provider where the address will be allocated.
          enum:
            - AWS
            - AZURE
            - GCP
            - OCI
            - CUSTOMER
          example: AWS
        networkId:
          type: string
          format: uuid
          description: ID of the Network in which to allocate the address.
          example: 11111111-2222-3333-4444-555555555555
        region:
          type: string
          description: Cloud region code where the address will be allocated.
          example: us-east-1
      required:
        - networkId
        - provider
        - region
    UpgradeEdgeRouter:
      type: object
      description: Specifies the target version for an Edge Router upgrade.
      properties:
        target:
          $ref: '#/components/schemas/Semver'
          description: >-
            The target version for the upgrade. If not specified, the Edge
            Router will be upgraded to the latest version available for the
            network.
          example: 8.3.0
    CreateDnsZone:
      type: object
      description: >-
        Request body to create a DnsZone within a Network Group. Exactly one of
        route53ZoneId or domain must be provided. Use route53ZoneId to reference
        an existing AWS Route53 hosted zone, or provide a domain to request
        creation/association of a hosted zone.
      properties:
        networkGroupId:
          type: string
          format: uuid
          description: ID of the Network Group that will own this DnsZone.
          example: 11111111-2222-3333-4444-555555555555
        name:
          type: string
          description: >-
            Human-friendly name for the DnsZone (unique within the Network
            Group).
          example: corp-zone
        route53ZoneId:
          type: string
          description: >-
            AWS Route53 hosted zone identifier. Provide this to reference an
            existing hosted zone.
          example: Z04008363AMXYS4T3J7OB
        domain:
          type: string
          description: >-
            Root domain name to host (used when creating/associating a hosted
            zone).
          example: example.com
    NetworkAssembly:
      type: object
      description: >-
        Composite representation of a Network and its Ziti controller export
        plus hosting information for controllers and edge routers.
      properties:
        name:
          type: string
          description: Human-readable name for the network to create or import.
          example: acme-prod-net
        version:
          $ref: '#/components/schemas/Semver'
          description: >-
            Product version of the NetFoundry platform targeted by this assembly
            (semantic version).
          example: 8.3.0
        zitiVersion:
          $ref: '#/components/schemas/Semver'
          description: Ziti Controller semantic version for this export.
          example: 0.29.7
        identities:
          type: array
          description: >-
            List of identity resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        edgeRouters:
          type: array
          description: >-
            List of Edge Router resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        services:
          type: array
          description: >-
            List of service resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        configs:
          type: array
          description: >-
            List of config resources as arbitrary JSON objects from the Ziti
            controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        configTypes:
          type: array
          description: >-
            List of config type resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        servicePolicies:
          type: array
          description: >-
            List of service policy resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        serviceEdgeRouterPolicies:
          type: array
          description: >-
            List of service edge router policy resources as arbitrary JSON
            objects from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        edgeRouterPolicies:
          type: array
          description: >-
            List of edge router policy resources as arbitrary JSON objects from
            the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        authPolicies:
          type: array
          description: >-
            List of authentication policy resources as arbitrary JSON objects
            from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        certificateAuthorities:
          type: array
          description: >-
            List of certificate authority resources as arbitrary JSON objects
            from the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        externalJwtSigners:
          type: array
          description: >-
            List of external JWT signer resources as arbitrary JSON objects from
            the Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        postureChecks:
          type: array
          description: >-
            List of posture check resources as arbitrary JSON objects from the
            Ziti controller export.
          items:
            $ref: '#/components/schemas/JsonNode'
        zitiData:
          description: >-
            Ziti controller export/import payload. Fields are unwrapped at the
            top level of the payload.
        hosting:
          $ref: '#/components/schemas/NetworkAssemblyHosting'
          description: >-
            Hosting instructions for network controllers and edge routers.
            Optional; if omitted, defaults may be applied.
        haEnabled:
          type: boolean
          description: >-
            Whether High Availability (HA) is enabled for the network
            controllers.
          example: false
    NetworkAssemblyHosting:
      type: object
      description: Hosting configuration for network controllers and edge routers.
      properties:
        networkControllers:
          type: array
          description: List of network controller hosting definitions.
          items:
            $ref: '#/components/schemas/NetworkControllerHosting'
        edgeRouters:
          type: array
          description: List of edge router hosting definitions.
          items:
            $ref: '#/components/schemas/EdgeRouterHosting'
    CollectionModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            objectList:
              type: array
              items: {}
        _links:
          $ref: '#/components/schemas/Links'
    PageMetadata:
      type: object
      properties:
        size:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
        number:
          type: integer
          format: int64
    PagedModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            objectList:
              type: array
              items: {}
        _links:
          $ref: '#/components/schemas/Links'
        page:
          $ref: '#/components/schemas/PageMetadata'
    Backup:
      type: object
      description: >-
        Metadata describing a backup artifact stored in object storage (e.g.,
        S3).
      properties:
        name:
          type: string
          description: Object name (filename) of the backup.
          example: backup-2025-10-01T12-00-00Z.tar.gz
        lastModified:
          type: string
          format: date-time
          description: Timestamp when the backup object was last modified.
          example: '2025-10-01T12:00:10Z'
        size:
          type: integer
          format: int64
          description: Size of the backup object in bytes.
          example: 10485760
    RegisteredEdgeRouter:
      type: object
      description: >-
        Payload posted by an Edge Router registration process to indicate the
        outcome. A status of 0 indicates success (the router has registered
        successfully); any non-zero value indicates an error. The optional
        message provides additional details.
      example:
        status: 0
        message: Successful
      properties:
        status:
          type: integer
          format: int32
          description: >-
            Registration status code reported by the Edge Router. 0 = success;
            non-zero = error.
          example: 0
        message:
          type: string
          description: Optional descriptive message about the registration result.
          example: Successful
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
