Incus network-zones API

swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates network-zones API
  version: '1.0'
tags:
- name: network-zones
paths:
  /1.0/network-zones:
    get:
      description: Returns a list of network zones (URLs).
      operationId: network_zones_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Retrieve network zones from all projects
        example: true
        in: query
        name: all-projects
        type: boolean
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/network-zones/example.net\",\n  \"/1.0/network-zones/example.com\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zones
      tags:
      - network-zones
    post:
      consumes:
      - application/json
      description: Creates a new network zone.
      operationId: network_zones_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZonesPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a network zone
      tags:
      - network-zones
  /1.0/network-zones/{zone}:
    delete:
      description: Removes the network zone.
      operationId: network_zone_delete
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the network zone
      tags:
      - network-zones
    get:
      description: Gets a specific network zone.
      operationId: network_zone_get
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: zone
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/NetworkZone'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zone
      tags:
      - network-zones
    patch:
      consumes:
      - application/json
      description: Updates a subset of the network zone configuration.
      operationId: network_zone_patch
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone configuration
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZonePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the network zone
      tags:
      - network-zones
    put:
      consumes:
      - application/json
      description: Updates the entire network zone configuration.
      operationId: network_zone_put
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone configuration
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZonePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the network zone
      tags:
      - network-zones
  /1.0/network-zones/{zone}/records:
    get:
      description: Returns a list of network zone records (URLs).
      operationId: network_zone_records_get
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/network-zones/example.net/records/foo\",\n  \"/1.0/network-zones/example.net/records/bar\"\n]"
                items:
                  type: string
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zone records
      tags:
      - network-zones
    post:
      consumes:
      - application/json
      description: Creates a new network zone record.
      operationId: network_zone_records_post
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZoneRecordsPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a network zone record
      tags:
      - network-zones
  /1.0/network-zones/{zone}/records/{name}:
    delete:
      description: Removes the network zone record.
      operationId: network_zone_record_delete
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Record name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the network zone record
      tags:
      - network-zones
    get:
      description: Gets a specific network zone record.
      operationId: network_zone_record_get
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Record name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: zone
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/NetworkZoneRecord'
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zone record
      tags:
      - network-zones
    patch:
      consumes:
      - application/json
      description: Updates a subset of the network zone record configuration.
      operationId: network_zone_record_patch
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Record name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone record configuration
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZoneRecordPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the network zone record
      tags:
      - network-zones
    put:
      consumes:
      - application/json
      description: Updates the entire network zone record configuration.
      operationId: network_zone_record_put
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Record name
        in: path
        name: name
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: zone record configuration
        in: body
        name: zone
        required: true
        schema:
          $ref: '#/definitions/NetworkZoneRecordPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the network zone record
      tags:
      - network-zones
  /1.0/network-zones/{zone}/records?recursion=1:
    get:
      description: Returns a list of network zone records (structs).
      operationId: network_zone_records_get_recursion1
      parameters:
      - description: Network zone name
        in: path
        name: zone
        required: true
        type: string
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of network zone records
                items:
                  $ref: '#/definitions/NetworkZoneRecord'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zone records
      tags:
      - network-zones
  /1.0/network-zones?recursion=1:
    get:
      description: Returns a list of network zones (structs).
      operationId: network_zones_get_recursion1
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Retrieve network zones from all projects
        example: true
        in: query
        name: all-projects
        type: boolean
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of network zones
                items:
                  $ref: '#/definitions/NetworkZone'
                type: array
              status:
                description: Status description
                example: Success
                type: string
              status_code:
                description: Status code
                example: 200
                type: integer
              type:
                description: Response type
                example: sync
                type: string
            type: object
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the network zones
      tags:
      - network-zones
definitions:
  NetworkZoneRecordPut:
    description: NetworkZoneRecordPut represents the modifiable fields of a network zone record
    properties:
      config:
        description: Advanced configuration for the record
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the record
        example: SPF record
        type: string
        x-go-name: Description
      entries:
        description: Entries in the record
        items:
          $ref: '#/definitions/NetworkZoneRecordEntry'
        type: array
        x-go-name: Entries
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZonesPost:
    description: NetworkZonesPost represents the fields of a new network zone
    properties:
      config:
        description: Zone configuration map (refer to doc/network-zones.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the network zone
        example: Internal domain
        type: string
        x-go-name: Description
      name:
        description: The name of the zone (DNS domain name)
        example: example.net
        type: string
        x-go-name: Name
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZoneRecordsPost:
    description: NetworkZoneRecordsPost represents the fields of a new network zone record
    properties:
      config:
        description: Advanced configuration for the record
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the record
        example: SPF record
        type: string
        x-go-name: Description
      entries:
        description: Entries in the record
        items:
          $ref: '#/definitions/NetworkZoneRecordEntry'
        type: array
        x-go-name: Entries
      name:
        description: The record name in the zone
        example: '@'
        type: string
        x-go-name: Name
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZonePut:
    description: NetworkZonePut represents the modifiable fields of a network zone
    properties:
      config:
        description: Zone configuration map (refer to doc/network-zones.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the network zone
        example: Internal domain
        type: string
        x-go-name: Description
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZone:
    properties:
      config:
        description: Zone configuration map (refer to doc/network-zones.md)
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the network zone
        example: Internal domain
        type: string
        x-go-name: Description
      name:
        description: The name of the zone (DNS domain name)
        example: example.net
        type: string
        x-go-name: Name
      project:
        description: Project name
        example: project1
        type: string
        x-go-name: Project
      used_by:
        description: List of URLs of objects using this network zone
        example:
        - /1.0/networks/foo
        - /1.0/networks/bar
        items:
          type: string
        readOnly: true
        type: array
        x-go-name: UsedBy
    title: NetworkZone represents a network zone (DNS).
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZoneRecord:
    properties:
      config:
        description: Advanced configuration for the record
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: Description of the record
        example: SPF record
        type: string
        x-go-name: Description
      entries:
        description: Entries in the record
        items:
          $ref: '#/definitions/NetworkZoneRecordEntry'
        type: array
        x-go-name: Entries
      name:
        description: The name of the record
        example: '@'
        type: string
        x-go-name: Name
    title: NetworkZoneRecord represents a network zone (DNS) record.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  NetworkZoneRecordEntry:
    description: NetworkZoneRecordEntry represents the fields in a record entry
    properties:
      ttl:
        description: TTL for the entry
        example: 3600
        format: uint64
        type: integer
        x-go-name: TTL
      type:
        description: Type of DNS entry
        example: TXT
        type: string
        x-go-name: Type
      value:
        description: Value for the record
        example: v=spf1 mx ~all
        type: string
        x-go-name: Value
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
responses:
  Forbidden:
    description: Forbidden
    schema:
      properties:
        error:
          example: not authorized
          type: string
          x-go-name: Error
        error_code:
          example: 403
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  BadRequest:
    description: Bad Request
    schema:
      properties:
        error:
          example: bad request
          type: string
          x-go-name: Error
        error_code:
          example: 400
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  EmptySyncResponse:
    description: Empty sync response
    schema:
      properties:
        status:
          example: Success
          type: string
          x-go-name: Status
        status_code:
          example: 200
          format: int64
          type: integer
          x-go-name: StatusCode
        type:
          example: sync
          type: string
          x-go-name: Type
      type: object
  PreconditionFailed:
    description: Precondition Failed
    schema:
      properties:
        error:
          example: precondition failed
          type: string
          x-go-name: Error
        error_code:
          example: 412
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object
  InternalServerError:
    description: Internal Server Error
    schema:
      properties:
        error:
          example: internal server error
          type: string
          x-go-name: Error
        error_code:
          example: 500
          format: int64
          type: integer
          x-go-name: ErrorCode
        type:
          example: error
          type: string
          x-go-name: Type
      type: object