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 projects API
  version: '1.0'
tags:
- name: projects
paths:
  /1.0/projects:
    get:
      description: Returns a list of projects (URLs).
      operationId: projects_get
      parameters:
      - 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/projects/default\",\n  \"/1.0/projects/foo\"\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 projects
      tags:
      - projects
    post:
      consumes:
      - application/json
      description: Creates a new project.
      operationId: projects_post
      parameters:
      - description: Project
        in: body
        name: project
        required: true
        schema:
          $ref: '#/definitions/ProjectsPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Add a project
      tags:
      - projects
  /1.0/projects/{name}:
    delete:
      description: Removes the project.
      operationId: project_delete
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      - description: Delete project and related artifacts
        in: query
        name: force
        type: boolean
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the project
      tags:
      - projects
    get:
      description: Gets a specific project.
      operationId: project_get
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Project
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Project'
              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 project
      tags:
      - projects
    patch:
      consumes:
      - application/json
      description: Updates a subset of the project configuration.
      operationId: project_patch
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      - description: Project configuration
        in: body
        name: project
        required: true
        schema:
          $ref: '#/definitions/ProjectPut'
      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 project
      tags:
      - projects
    post:
      consumes:
      - application/json
      description: Renames an existing project.
      operationId: project_post
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      - description: Project rename request
        in: body
        name: project
        required: true
        schema:
          $ref: '#/definitions/ProjectPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename the project
      tags:
      - projects
    put:
      consumes:
      - application/json
      description: Updates the entire project configuration.
      operationId: project_put
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      - description: Project configuration
        in: body
        name: project
        required: true
        schema:
          $ref: '#/definitions/ProjectPut'
      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 project
      tags:
      - projects
  /1.0/projects/{name}/access:
    get:
      description: Gets the access information for the project.
      operationId: project_access
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Access
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Access'
              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
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get who has access to a project
      tags:
      - projects
  /1.0/projects/{name}/state:
    get:
      description: Gets a specific project resource consumption information.
      operationId: project_state_get
      parameters:
      - description: Project name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Project state
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ProjectState'
              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 project state
      tags:
      - projects
  /1.0/projects?recursion=1:
    get:
      description: Returns a list of projects (structs).
      operationId: projects_get_recursion1
      parameters:
      - 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 projects
                items:
                  $ref: '#/definitions/Project'
                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 projects
      tags:
      - projects
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
  ProjectPut:
    description: ProjectPut represents the modifiable fields of a project
    properties:
      config:
        description: Project configuration map (refer to doc/projects.md)
        example:
          features.networks: 'false'
          features.profiles: 'true'
        type: object
        x-go-name: Config
      description:
        description: Description of the project
        example: My new project
        type: string
        x-go-name: Description
    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
  Access:
    items:
      $ref: '#/definitions/AccessEntry'
    title: Access represents everyone that may access a particular resource.
    type: array
    x-go-package: github.com/lxc/incus/v7/shared/api
  AccessEntry:
    properties:
      identifier:
        description: Certificate fingerprint
        example: 636b69519d27ae3b0e398cb7928043846ce1e3842f0ca7a589993dd913ab8cc9
        type: string
        x-go-name: Identifier
      provider:
        description: Which authorization method the certificate uses
        example: tls, openfga
        type: string
        x-go-name: Provider
      role:
        description: The role associated with the certificate
        example: admin, view, operator
        type: string
        x-go-name: Role
    title: AccessEntry represents an entity having access to the resource.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ProjectsPost:
    description: ProjectsPost represents the fields of a new project
    properties:
      config:
        description: Project configuration map (refer to doc/projects.md)
        example:
          features.networks: 'false'
          features.profiles: 'true'
        type: object
        x-go-name: Config
      description:
        description: Description of the project
        example: My new project
        type: string
        x-go-name: Description
      name:
        description: The name of the new project
        example: foo
        type: string
        x-go-name: Name
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ProjectPost:
    description: ProjectPost represents the fields required to rename a project
    properties:
      name:
        description: The new name for the project
        example: bar
        type: string
        x-go-name: Name
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ProjectStateResource:
    description: ProjectStateResource represents the state of a particular resource in a project
    properties:
      Limit:
        description: Limit for the resource (-1 if none)
        example: 10
        format: int64
        type: integer
      Usage:
        description: Current usage for the resource
        example: 4
        format: int64
        type: integer
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ProjectState:
    description: ProjectState represents the current running state of a project
    properties:
      resources:
        additionalProperties:
          $ref: '#/definitions/ProjectStateResource'
        description: Allocated and used resources
        example:
          containers:
            limit: 10
            usage: 4
          cpu:
            limit: 20
            usage: 16
        readOnly: true
        type: object
        x-go-name: Resources
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  Project:
    description: Project represents a project
    properties:
      config:
        description: Project configuration map (refer to doc/projects.md)
        example:
          features.networks: 'false'
          features.profiles: 'true'
        type: object
        x-go-name: Config
      description:
        description: Description of the project
        example: My new project
        type: string
        x-go-name: Description
      name:
        description: The project name
        example: foo
        readOnly: true
        type: string
        x-go-name: Name
      used_by:
        description: List of URLs of objects using this project
        example:
        - /1.0/images/0e60015346f06627f10580d56ac7fffd9ea775f6d4f25987217d5eed94910a20
        - /1.0/instances/c1
        - /1.0/networks/mybr0
        - /1.0/profiles/default
        - /1.0/storage-pools/default/volumes/custom/blah
        items:
          type: string
        readOnly: true
        type: array
        x-go-name: UsedBy
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
responses:
  Operation:
    description: Operation
    schema:
      properties:
        metadata:
          $ref: '#/definitions/Operation'
        operation:
          example: /1.0/operations/66e83638-9dd7-4a26-aef2-5462814869a1
          type: string
          x-go-name: Operation
        status:
          example: Operation created
          type: string
          x-go-name: Status
        status_code:
          example: 100
          format: int64
          type: integer
          x-go-name: StatusCode
        type:
          example: async
          type: string
          x-go-name: Type
      type: object
  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