openapi.yaml

openapi: 3.0.0
info:
  title: TrueNAS RESTful API
  description: Go SDK for interacting with TrueNAS APIs (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
  version: v2.0
paths:
  /pool:
    get:
      operationId: listPools
      security:
        - bearerAuth: [ ]
      tags:
        - pool
      responses:
        '200':
          description: 'A list of pools'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
  /pool/dataset:
    post:
      tags:
        - dataset
      operationId: createDataset
      security:
        - bearerAuth: [ ]
      description: |+
        Creates a dataset/zvol.

        `volsize` is required for type=VOLUME and is supposed to be a multiple of the block size.
        `sparse` and `volblocksize` are only used for type=VOLUME.

        `encryption` when enabled will create an ZFS encrypted root dataset for `name` pool.
        There are 2 cases where ZFS encryption is not allowed for a dataset:
        1) Pool in question is GELI encrypted.
        2) If the parent dataset is encrypted with a passphrase and `name` is being created
          with a key for encrypting the dataset.

        `encryption_options` specifies configuration for encryption of dataset for `name` pool.
        `encryption_options.passphrase` must be specified if encryption for dataset is desired with a passphrase
        as a key.
        Otherwise a hex encoded key can be specified by providing `encryption_options.key`.
        `encryption_options.generate_key` when enabled automatically generates the key to be used
        for dataset encryption.

        It should be noted that keys are stored by the system for automatic locking/unlocking
        on import/export of encrypted datasets. If that is not desired, dataset should be created
        with a passphrase as a key.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetParams'
      responses:
        '200':
          description: 'Dataset details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pool/dataset/id/{id}:
    get:
      tags:
        - dataset
      operationId: getDataset
      security:
        - bearerAuth: [ ]
      description: |-
        Query Pool Datasets with `query-filters` and `query-options`.

        We provide two ways to retrieve datasets. The first is a flat structure (default), where
        all datasets in the system are returned as separate objects which contain all data
        there is for their children. This retrieval type is slightly slower because of duplicates in each object.
        The second type is hierarchical, where only top level datasets are returned in the list. They contain all the
        children in the `children` key. This retrieval type is slightly faster.
        These options are controlled by the `query-options.extra.flat` attribute (default true).
      parameters:
        - name: id
          in: path
          description: ID of the dataset
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 'Dataset details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
        - dataset
      operationId: updateDataset
      security:
        - bearerAuth: [ ]
      description: Update dataset
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatasetParams'
      responses:
        '200':
          description: 'Dataset details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - dataset
      operationId: deleteDataset
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      description: |+
        Delete dataset/zvol

        `recursive` will also delete/destroy all children datasets.
        `force` will force delete busy datasets.
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /cronjob/id/{id}:
    get:
      tags:
        - cronjob
      operationId: getCronJob
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          description: ID of the cronjob
          required: true
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 'CronJob details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CronJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
        - cronjob
      operationId: deleteCronJob
      security:
        - bearerAuth: [ ]
      parameters:
      - name: id
        in: path
        description: ID of the cronjob
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/Success'

        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
        - cronjob
      operationId: updateCronJob
      description: Update cronjob
      security:
        - bearerAuth: [ ]
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCronjobParams'
      responses:
        '200':
          description: 'CronJob details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CronJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /cronjob:
    post:
      tags:
       - cronjob
      operationId: createCronJob
      security:
        - bearerAuth: [ ]
      description:
        Create a new cron job.

        `stderr` and `stdout` are boolean values which if `true`, represent that we would like to suppress
        standard error / standard output respectively.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCronjobParams'
      responses:
        '200':
          description: 'CronJob details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CronJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /network/configuration:
    get:
      tags:
        - network
      operationId: getNetworkConfiguration
      security:
        - bearerAuth: [ ]
      parameters: []
      responses:
        '200':
          description: 'General network configuration'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /network/general/summary:
    get:
      tags:
        - network
      operationId: getNetworkSummary
      security:
        - bearerAuth: [ ]
      parameters: [ ]
      responses:
        '200':
          description: 'General network summary'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /service/id/{id}:
    get:
      tags:
        - service
      operationId: getService
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          description: ID of the cronjob
          required: true
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 'Service details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /vm:
    get:
      tags:
        - vm
      operationId: listVMS
      description: Get a list of VMs
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: 'List of VMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMSResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
  /vm/id/{id}:
    get:
      tags:
        - vm
      operationId: getVM
      security:
        - bearerAuth: [ ]
      description: Get VM details
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
        - name: count
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 'VM details'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VM'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
  schemas:
    CreateCronjobParams:
      type: object
      required:
        - user
        - command
      properties:
        user:
          type: string
        command:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        stdout:
          type: boolean
        stderr:
          type: boolean
        schedule:
          $ref: '#/components/schemas/CronJobSchedule'
    CreateDatasetParams:
      type: object
      required:
        - name
      properties:
        atime:
          type: string
        aclmode:
          type: string
        name:
          type: string
        comments:
          type: string
        compression:
          type: string
        casesensitivity:
          type: string
        copies:
          type: integer
        deduplication:
          type: string
        encryption:
          type: boolean
        encryption_options:
          type: object
          properties:
            algorithm:
              type: string
            generate_key:
              type: boolean
            passphrase:
              type: string
            key:
              type: string
        exec:
          type: string
        force_size:
          type: boolean
        inherit_encryption:
          type: boolean
        quota:
          type: integer
          format: int64
        quota_critical:
          type: integer
          format: int64
        quota_warning:
          type: integer
          format: int64
        volsize:
          type: integer
          format: int64
        volblocksize:
          type: string
        readonly:
          type: string
        recordsize:
          type: string
        refquota:
          type: integer
          format: int64
        refquota_critical:
          type: integer
          format: int64
        refquota_warning:
          type: integer
          format: int64
        refreservation:
          type: integer
          format: int64
        reservation:
          type: integer
          format: int64
        share_type:
          type: string
        snapdir:
          type: string
        sync:
          type: string
        type:
          type: string
    UpdateDatasetParams:
      type: object
      properties:
        atime:
          type: string
        aclmode:
          type: string
        comments:
          type: string
        compression:
          type: string
        copies:
          type: integer
        deduplication:
          type: string
        exec:
          type: string
        force_size:
          type: boolean
        quota:
          type: integer
          format: int64
        readonly:
          type: string
        recordsize:
          type: string
        refquota:
          type: integer
          format: int64
        refreservation:
          type: integer
          format: int64
        volsize:
          type: integer
          format: int64
        snapdir:
          type: string
        sync:
          type: string
    CompositeValue:
      type: object
      required:
        - rawvalue
      properties:
        value:
          type: string
        rawvalue:
          type: string
#        Does not seem to work yet:
#        parsed:
#          anyOf:
#            - type: string
#            - type: number
        source:
          type: string
    CronJob:
      type: object
      properties:
        id:
          type: integer
        user:
          type: string
        command:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        stdout:
          type: boolean
        stderr:
          type: boolean
        schedule:
          $ref: '#/components/schemas/CronJobSchedule'
    CronJobSchedule:
      type: object
      properties:
        minute:
          type: string
        hour:
          type: string
        dom:
          type: string
        month:
          type: string
        dow:
          type: string
    Dataset:
      type: object
      required:
        - id
        - name
        - pool
        - type
      properties:
        id:
          type: string
        name:
          type: string
        pool:
          type: string
        type:
          type: string
        mountpoint:
          type: string
        encrypted:
          type: boolean
        encryption_root:
          type: string
        key_loaded:
          type: boolean
        locked:
          type: boolean
        encryption_algorithm:
          $ref: '#/components/schemas/CompositeValue'
        aclmode:
          $ref: '#/components/schemas/CompositeValue'
        acltype:
          $ref: '#/components/schemas/CompositeValue'
        atime:
          $ref: '#/components/schemas/CompositeValue'
        casesensitivity:
          $ref: '#/components/schemas/CompositeValue'
        comments:
          $ref: '#/components/schemas/CompositeValue'
        compression:
          $ref: '#/components/schemas/CompositeValue'
        deduplication:
          $ref: '#/components/schemas/CompositeValue'
        exec:
          $ref: '#/components/schemas/CompositeValue'
        key_format:
          $ref: '#/components/schemas/CompositeValue'
        managedby:
          $ref: '#/components/schemas/CompositeValue'
        copies:
          $ref: '#/components/schemas/CompositeValue'
        quota:
          $ref: '#/components/schemas/CompositeValue'
        quota_critical:
          $ref: '#/components/schemas/CompositeValue'
        quota_warning:
          $ref: '#/components/schemas/CompositeValue'
        reservation:
          $ref: '#/components/schemas/CompositeValue'
        refreservation:
          $ref: '#/components/schemas/CompositeValue'
        refquota:
          $ref: '#/components/schemas/CompositeValue'
        refquota_critical:
          $ref: '#/components/schemas/CompositeValue'
        refquota_warning:
          $ref: '#/components/schemas/CompositeValue'
        readonly:
          $ref: '#/components/schemas/CompositeValue'
        recordsize:
          $ref: '#/components/schemas/CompositeValue'
        sync:
          $ref: '#/components/schemas/CompositeValue'
        snapdir:
          $ref: '#/components/schemas/CompositeValue'
        pbkdf2iters:
          $ref: '#/components/schemas/CompositeValue'
        origin:
          $ref: '#/components/schemas/CompositeValue'
        xattr:
          $ref: '#/components/schemas/CompositeValue'
        volsize:
          $ref: '#/components/schemas/CompositeValue'
        volblocksize:
          $ref: '#/components/schemas/CompositeValue'
    NetworkConfig:
      type: object
      properties:
        id:
          type: integer
        hostname:
          type: string
        domain:
          type: string
        ipv4gateway:
          type: string
        ipv6gateway:
          type: string
        nameserver1:
          type: string
        nameserver2:
          type: string
        nameserver3:
          type: string
        httpproxy:
          type: string
        netwait_enabled:
          type: boolean
        netwait_ip:
          type: array
          items:
            type: string
        hosts:
          type: string
        domains:
          type: array
          items:
            type: string
        service_announcement:
          type: object
          properties:
            netbios:
              type: boolean
            mdns:
              type: boolean
            wsd:
              type: boolean
        hostname_local:
          type: string
    NetworkSummary:
      type: object
      properties:
        ips:
          type: object
          additionalProperties:
            type: object
            properties:
              IPV4:
                type: array
                items:
                  type: string
              IPV6:
                type: array
                items:
                  type: string
        default_routes:
          type: array
          items:
            type: string
        nameservers:
          type: array
          items:
            type: string
    PoolsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Pool'
    Pool:
      type: object
      required:
        - id
        - name
        - path
      properties:
        id:
          type: integer
        name:
          type: string
        guid:
          type: string
        path:
          type: string
        status:
          type: string
        healthy:
          type: boolean
        is_decrypted:
          type: boolean
        encryptkey_path:
          type: string
    Service:
      type: object
      required:
        - id
        - service
      properties:
        id:
          type: integer
        service:
          type: string
        enable:
          type: boolean
        state:
          type: string
        pids:
          type: array
          items:
            type: integer
    VM:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        vcpus:
          type: integer
        memory:
          type: integer
        autostart:
          type: boolean
        time:
          type: string
        bootloader:
          type: string
        cores:
          type: integer
        threads:
          type: integer
        shutdown_timeout:
          type: integer
        devices:
          type: array
          items:
            type: object
            required:
              - id
              - dtype
            properties:
              id:
                type: integer
              dtype:
                type: string
              order:
                type: integer
              vm:
                type: integer
              attributes:
                type: object
        status:
          type: object
          properties:
            state:
              type: string
            pid:
              type: integer
            domain_state:
              type: string
    VMSResponse:
      type: array
      items:
        $ref: '#/components/schemas/VM'
  responses:
    NotFound:
      description: Endpoint not found
    Unauthorized:
      description: No authorization for this endpoint
    Success:
      description: Operation succeeded