edge-api/source/management/routers.yml

---
paths:
  # 'transit-routers' is deprecated, remove after 19.x, use 'routers' instead
  transit-routers:
    get:
      summary: List routers
      description: |
        Retrieves a list of router resources; supports filtering, sorting, and pagination. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: listTransitRouters
      parameters:
        - $ref: '../shared/parameters.yml#/limit'
        - $ref: '../shared/parameters.yml#/offset'
        - $ref: '../shared/parameters.yml#/filter'
      responses:
        '200':
          $ref: '#/responses/listRouters'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    post:
      summary: Create a router resource
      description: Create a router resource. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: createTransitRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router to create
          schema:
            $ref: '#/definitions/routerCreate'
      responses:
        '201':
          $ref: '../shared/standard-responses.yml#/responses/createResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  transit-routers-id:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    get:
      summary: Retrieves a single router
      description: Retrieves a single router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: detailTransitRouter
      responses:
        '200':
          $ref: '#/responses/detailRouter'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    put:
      summary: Update all fields on a router
      description: Update all fields on a router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: updateTransitRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router update object
          schema:
            $ref: '#/definitions/routerUpdate'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/updateResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    patch:
      summary: Update the supplied fields on a router
      description: Update the supplied fields on a router. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: patchTransitRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router patch object
          schema:
            $ref: '#/definitions/routerPatch'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/patchResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    delete:
      summary: Delete a router
      description: Delete a router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: deleteTransitRouter
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/deleteResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '409':
          $ref: '../shared/standard-responses.yml#/responses/cannotDeleteReferencedResourceResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  routers:
    get:
      summary: List routers
      description: |
        Retrieves a list of router resources; supports filtering, sorting, and pagination. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: listRouters
      parameters:
        - $ref: '../shared/parameters.yml#/limit'
        - $ref: '../shared/parameters.yml#/offset'
        - $ref: '../shared/parameters.yml#/filter'
      responses:
        '200':
          $ref: '#/responses/listRouters'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    post:
      summary: Create a router resource
      description: Create a router resource. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: createRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router to create
          schema:
            $ref: '#/definitions/routerCreate'
      responses:
        '201':
          $ref: '../shared/standard-responses.yml#/responses/createResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  routers-id:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    get:
      summary: Retrieves a single router
      description: Retrieves a single router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: detailRouter
      responses:
        '200':
          $ref: '#/responses/detailRouter'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    put:
      summary: Update all fields on a router
      description: Update all fields on a router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: updateRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router update object
          schema:
            $ref: '#/definitions/routerUpdate'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/updateResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    patch:
      summary: Update the supplied fields on a router
      description: Update the supplied fields on a router. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: patchRouter
      parameters:
        - name: router
          in: body
          required: true
          description: A router patch object
          schema:
            $ref: '#/definitions/routerPatch'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/patchResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    delete:
      summary: Delete a router
      description: Delete a router by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Router
      operationId: deleteRouter
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/deleteResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '409':
          $ref: '../shared/standard-responses.yml#/responses/cannotDeleteReferencedResourceResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

responses:
  listRouters:
    description: A list of specifications
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/listRoutersEnvelope'
  detailRouter:
    description: A single router
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/detailRouterEnvelope'

definitions:
  listRoutersEnvelope:
    type: object
    required:
      - meta
      - data
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/routerList'
  detailRouterEnvelope:
    type: object
    required:
      - meta
      - data
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/routerDetail'
  routerList:
    type: array
    items:
      $ref: '#/definitions/routerDetail'
  routerDetail:
    type: object
    allOf:
      - $ref: '../shared/base-entity.yml#/definitions/baseEntity'
      - type: object
        required:
          - name
          - isVerified
          - isOnline
          - fingerprint
          - cost
          - noTraversal
          - disabled
        properties:
          name:
            type: string
          fingerprint:
            type: string
          isVerified:
            type: boolean
          isOnline:
            type: boolean
          enrollmentToken:
            type: string
            x-nullable: true
          enrollmentJwt:
            type: string
            x-nullable: true
          enrollmentCreatedAt:
            type: string
            format: date-time
            x-nullable: true
          enrollmentExpiresAt:
            type: string
            format: date-time
            x-nullable: true
          unverifiedFingerprint:
            type: string
            x-nullable: true
            x-omitempty: false
          unverifiedCertPem:
            type: string
            x-nullable: true
            x-omitempty: false
          cost:
            type: integer
            minimum: 0
            maximum: 65535
          noTraversal:
            type: boolean
          disabled:
            type: boolean
          interfaces:
            type: array
            items:
              $ref: '../shared/interfaces.yml#/definitions/interface'

  routerCreate:
    type: object
    required:
      - name
    properties:
      name:
        type: string
      cost:
        type: integer
        x-nullable: true
        minimum: 0
        maximum: 65535
      noTraversal:
        type: boolean
        x-nullable: true
      disabled:
        type: boolean
        x-nullable: true
      tags:
        $ref: '../shared/base-entity.yml#/definitions/tags'
  routerUpdate:
    type: object
    required:
      - name
    properties:
      name:
        type: string
      cost:
        type: integer
        x-nullable: true
        minimum: 0
        maximum: 65535
      noTraversal:
        type: boolean
        x-nullable: true
      disabled:
        type: boolean
        x-nullable: true
      tags:
        $ref: '../shared/base-entity.yml#/definitions/tags'
  routerPatch:
    type: object
    properties:
      name:
        type: string
      cost:
        type: integer
        x-nullable: true
        minimum: 0
        maximum: 65535
      noTraversal:
        type: boolean
        x-nullable: true
      disabled:
        type: boolean
        x-nullable: true
      tags:
        $ref: '../shared/base-entity.yml#/definitions/tags'