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 operations API
  version: '1.0'
tags:
- name: operations
paths:
  /1.0/operations:
    get:
      description: Returns a JSON object of operation type to operation list (URLs).
      operationId: operations_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Retrieve operations from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                additionalProperties:
                  items:
                    type: string
                  type: array
                description: JSON object of operation types to operation URLs
                example: "{\n  \"running\": [\n    \"/1.0/operations/6916c8a6-9b7d-4abd-90b3-aedfec7ec7da\"\n  ]\n}"
                type: object
              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 operations
      tags:
      - operations
  /1.0/operations/{id}:
    delete:
      description: Cancels the operation if supported.
      operationId: operation_delete
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Cancel the operation
      tags:
      - operations
    get:
      description: Gets the operation state.
      operationId: operation_get
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Operation
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Operation'
              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 operation state
      tags:
      - operations
  /1.0/operations/{id}/wait:
    get:
      description: Waits for the operation to reach a final state (or timeout) and retrieve its final state.
      operationId: operation_wait_get
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      - description: Timeout in seconds (-1 means never)
        example: -1
        in: query
        name: timeout
        type: integer
      produces:
      - application/json
      responses:
        '200':
          description: Operation
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Operation'
              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: Wait for the operation
      tags:
      - operations
  /1.0/operations/{id}/wait?public:
    get:
      description: 'Waits for the operation to reach a final state (or timeout) and retrieve its final state.


        When accessed by an untrusted user, the secret token must be provided.'
      operationId: operation_wait_get_untrusted
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      - description: Authentication token
        example: random-string
        in: query
        name: secret
        type: string
      - description: Timeout in seconds (-1 means never)
        example: -1
        in: query
        name: timeout
        type: integer
      produces:
      - application/json
      responses:
        '200':
          description: Operation
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Operation'
              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: Wait for the operation
      tags:
      - operations
  /1.0/operations/{id}/websocket:
    get:
      description: 'Connects to an associated websocket stream for the operation.

        This should almost never be done directly by a client, instead it''s

        meant for server to server communication with the client only relaying the

        connection information to the servers.'
      operationId: operation_websocket_get
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      - description: Authentication token
        example: random-string
        in: query
        name: secret
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Websocket operation messages (dependent on operation)
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the websocket stream
      tags:
      - operations
  /1.0/operations/{id}/websocket?public:
    get:
      description: 'Connects to an associated websocket stream for the operation.

        This should almost never be done directly by a client, instead it''s

        meant for server to server communication with the client only relaying the

        connection information to the servers.


        The untrusted endpoint is used by the target server to connect to the source server.

        Authentication is performed through the secret token.'
      operationId: operation_websocket_get_untrusted
      parameters:
      - description: Operation ID
        in: path
        name: id
        required: true
        type: string
      - description: Authentication token
        example: random-string
        in: query
        name: secret
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Websocket operation messages (dependent on operation)
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the websocket stream
      tags:
      - operations
  /1.0/operations?recursion=1:
    get:
      description: Returns a list of operations (structs).
      operationId: operations_get_recursion1
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        type: string
      - description: Retrieve operations from all projects
        in: query
        name: all-projects
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of operations
                items:
                  $ref: '#/definitions/Operation'
                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 operations
      tags:
      - operations
definitions:
  Operation:
    description: Operation represents a background operation
    properties:
      class:
        description: Type of operation (task, token or websocket)
        example: websocket
        type: string
        x-go-name: Class
      created_at:
        description: Operation creation time
        example: '2021-03-23T17:38:37.753398689-04:00'
        format: date-time
        type: string
        x-go-name: CreatedAt
      description:
        description: Description of the operation
        example: Executing command
        type: string
        x-go-name: Description
      err:
        description: Operation error message
        example: Some error message
        type: string
        x-go-name: Err
      id:
        description: UUID of the operation
        example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
        type: string
        x-go-name: ID
      location:
        description: What cluster member this record was found on
        example: server01
        type: string
        x-go-name: Location
      may_cancel:
        description: Whether the operation can be canceled
        example: false
        type: boolean
        x-go-name: MayCancel
      metadata:
        additionalProperties: {}
        description: Operation specific metadata
        example:
          command:
          - bash
          environment:
            HOME: /root
            LANG: C.UTF-8
            PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
            TERM: xterm
            USER: root
          fds:
            '0': da3046cf02c0116febf4ef3fe4eaecdf308e720c05e5a9c730ce1a6f15417f66
            '1': 05896879d8692607bd6e4a09475667da3b5f6714418ab0ee0e5720b4c57f754b
          interactive: true
        type: object
        x-go-name: Metadata
      resources:
        additionalProperties:
          items:
            type: string
          type: array
        description: Affected resources
        example:
          instances:
          - /1.0/instances/foo
        type: object
        x-go-name: Resources
      status:
        description: Status name
        example: Running
        type: string
        x-go-name: Status
      status_code:
        $ref: '#/definitions/StatusCode'
      updated_at:
        description: Operation last change
        example: '2021-03-23T17:38:37.753398689-04:00'
        format: date-time
        type: string
        x-go-name: UpdatedAt
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  StatusCode:
    format: int64
    title: StatusCode represents a valid operation and container status.
    type: integer
    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
  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