Canonical Projects API

The projects API from Canonical — 4 operation(s) for projects.

Documentation GitHub OpenAPI

Operations 10

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /1.0/projects List URLs of LXD projects · Get the projects #

Ask an LLM

“Which projects exist on my LXD server, as a list of links?”

“How do I get just the project URLs without their configuration?”

Tell an agent

List the URLs of all LXD projects.

Give me links to every project on the server.

POST /1.0/projects Create an LXD project · Add a project #

Ask an LLM

“How do I create a new project to isolate instances in LXD?”

“Can I set the default network and storage pool when creating a project?”

Tell an agent

Create project {name} described as {description}.

Create project {name} using network {network} and storage pool {storage}.

DELETE /1.0/projects/{name} Delete an LXD project · Delete the project #

Ask an LLM

“How do I remove a project from LXD?”

“Can I force-delete a project that still has resources in it?”

Tell an agent destructive · confirm first

Delete the project I name.

Force-delete the project with force set to {force}.

GET /1.0/projects/{name} Get one LXD project · Get the project #

Ask an LLM

“What's the configuration of a particular project?”

“Can I look up a single LXD project by name?”

Tell an agent

Show me the project I name and its settings.

Look up one LXD project by name.

PATCH /1.0/projects/{name} Change some of a project's settings · Partially update the project #

Ask an LLM

“Can I change one project setting without resending the rest?”

“Is there a way to update just a project's description?”

Tell an agent

Patch the project so only these config keys change: {config}.

Update just the project's description to {description}.

POST /1.0/projects/{name} Rename an LXD project · Rename the project #

Ask an LLM

“Can I rename an existing LXD project?”

“What's the call to give a project a new name?”

Tell an agent

Rename the project to {name}.

Give this LXD project the new name {name}.

PUT /1.0/projects/{name} Replace a project's entire configuration · Update the project #

Ask an LLM

“How do I overwrite a project's whole configuration?”

“Will a full project update drop config keys I leave out?”

Tell an agent

Replace the project's entire config with {config}.

Rewrite the project with description {description} and config {config}.

GET /1.0/projects/{name}/state Get a project's resource usage · Get the project state #

Ask an LLM

“How much CPU, memory and disk is a project consuming?”

“Can I check a project's resource usage against its limits?”

Tell an agent

Show the resource consumption of the project I name.

Report current usage for this LXD project.

PUT /1.0/projects/{name}/state Promote or demote a project for replication · Update the project replica state #

Ask an LLM

“How do I promote a project to leader for replication?”

“Can I demote a replicated project, and force it if needed?”

Tell an agent

Set the project's replica mode to {replica_mode}.

Force replica mode {replica_mode} on the project with force {force}.

GET /1.0/projects?recursion=1 List LXD projects with full configuration · Get the projects #

Ask an LLM

“Can I see every project's config and description in one call?”

“What features and limits is each LXD project set up with?”

Tell an agent

Fetch all projects with their full configuration, not just links.

Show every project's description and config settings.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/canonical:canonical-projects-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  contact:
    email: lxd@lists.canonical.com
    name: LXD upstream
    url: https://github.com/canonical/lxd
  description: 'This is the REST API used by all LXD clients.

    Internal endpoints aren''t included in this documentation.


    The LXD 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.'
  license:
    name: AGPL-3.0-only
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  title: LXD external REST Projects API
  version: '1.0'
tags:
- name: Projects
paths:
  /1.0/projects:
    get:
      description: Returns a list of projects (URLs).
      operationId: projects_get
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the projects
      tags:
      - Projects
    post:
      description: Creates a new project.
      operationId: projects_post
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Add a project
      tags:
      - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectsPost'
        description: Project
        required: true
  /1.0/projects/{name}:
    delete:
      description: Removes the project.
      operationId: project_delete
      parameters:
      - description: Force delete project and its entities
        in: query
        name: force
        schema:
          type: boolean
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete the project
      tags:
      - Projects
    get:
      description: Gets a specific project.
      operationId: project_get
      responses:
        '200':
          description: Project
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the project
      tags:
      - Projects
    patch:
      description: Updates a subset of the project configuration.
      operationId: project_patch
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Partially update the project
      tags:
      - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectPut'
        description: Project configuration
        required: true
    post:
      description: Renames an existing project.
      operationId: project_post
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Rename the project
      tags:
      - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectPost'
        description: Project rename request
        required: true
    put:
      description: Updates the entire project configuration.
      operationId: project_put
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the project
      tags:
      - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectPut'
        description: Project configuration
        required: true
  /1.0/projects/{name}/state:
    get:
      description: Gets a specific project resource consumption information.
      operationId: project_state_get
      responses:
        '200':
          description: Project state
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the project state
      tags:
      - Projects
    put:
      description: Promotes or demotes the project for replication.
      operationId: project_state_put
      parameters:
      - description: Skip validation of remote project states
        example: false
        in: query
        name: force
        schema:
          type: boolean
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the project replica state
      tags:
      - Projects
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectStatePut'
        description: Project state
        required: true
  /1.0/projects?recursion=1:
    get:
      description: Returns a list of projects (structs).
      operationId: projects_get_recursion1
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of projects
                    items:
                      $ref: '#/components/schemas/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: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the projects
      tags:
      - Projects
components:
  schemas:
    Operation:
      description: Operation represents a LXD background operation
      properties:
        child_count:
          description: 'Number of child operations.


            API extension: operation_child_count'
          example: 2
          format: int64
          type: integer
          x-go-name: ChildCount
        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
        err_code:
          description: 'Operation error code


            API extension: bulk_operations'
          example: 404
          format: int64
          type: integer
          x-go-name: ErrCode
        id:
          description: UUID of the operation
          example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
          type: string
          x-go-name: ID
        location:
          description: 'Which cluster member this record was found on


            API extension: operation_location'
          example: lxd01
          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
        requestor:
          $ref: '#/components/schemas/OperationRequestor'
        resources:
          additionalProperties:
            items:
              type: string
            type: array
          description: Affected resources
          example:
            instances:
            - /1.0/instances/foo
            - /1.0/instances/bar
          type: object
          x-go-name: Resources
        status:
          description: Status name
          example: Running
          type: string
          x-go-name: Status
        status_code:
          $ref: '#/components/schemas/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/canonical/lxd/shared/api
    ProjectStatePut:
      description: ProjectStatePut represents the fields for updating project replica state
      properties:
        replica_mode:
          description: 'Replica mode to set: "leader", "standby", or "" to clear the replica mode'
          example: leader
          type: string
          x-go-name: ReplicaMode
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    StatusCode:
      format: int64
      title: StatusCode represents a valid LXD operation and container status.
      type: integer
      x-go-package: github.com/canonical/lxd/shared/api
    OperationRequestor:
      description: 'API extension: operation_requestor.'
      properties:
        address:
          description: Address is the origin address of the request.
          example: 10.0.2.15
          type: string
          x-go-name: Address
        protocol:
          description: Protocol represents the method used to authenticate the requestor.
          example: oidc
          type: string
          x-go-name: Protocol
        username:
          description: Username is the username of the requestor. This is the identifier of the identity, or the username if using the unix socket.
          example: jane.doe@example.com
          type: string
          x-go-name: Username
      title: OperationRequestor represents the initial requestor of an operation
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    Project:
      description: Project represents a LXD project
      properties:
        access_entitlements:
          description: AccessEntitlements represents the entitlements that are granted to the requesting user on the attached entity.
          example:
          - can_view
          - can_edit
          items:
            type: string
          type: array
          x-go-name: AccessEntitlements
        config:
          additionalProperties:
            type: string
          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
        replica_mode:
          description: 'Replica mode for the project (leader, standby, or empty)

            This field is updated via PUT /1.0/projects/<name>/state


            API extension: project_replica_mode'
          example: leader
          readOnly: true
          type: string
          x-go-name: ReplicaMode
        used_by:
          description: List of URLs of objects using this project
          example:
          - /1.0/images/0e60015346f06627f10580d56ac7fffd9ea775f6d4f25987217d5eed94910a20
          - /1.0/instances/c1
          - /1.0/networks/lxdbr0
          - /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/canonical/lxd/shared/api
    ProjectsPost:
      description: ProjectsPost represents the fields of a new LXD project
      properties:
        config:
          additionalProperties:
            type: string
          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
        network:
          description: Add a network device connected to the specified network to the default profile
          example: lxdbr0
          type: string
          x-go-name: Network
        storage:
          description: Add a root disk device using the specified storage pool to the default profile
          example: default
          type: string
          x-go-name: StoragePool
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ProjectPut:
      description: ProjectPut represents the modifiable fields of a LXD project
      properties:
        config:
          additionalProperties:
            type: string
          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/canonical/lxd/shared/api
    ProjectStateResource:
      description: ProjectStateResource represents the state of a particular resource in a LXD 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/canonical/lxd/shared/api
    ProjectPost:
      description: ProjectPost represents the fields required to rename a LXD 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/canonical/lxd/shared/api
    ProjectState:
      description: ProjectState represents the current running state of a LXD project
      properties:
        resources:
          additionalProperties:
            $ref: '#/components/schemas/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/canonical/lxd/shared/api
  responses:
    Operation:
      description: Operation
      content:
        application/json:
          schema:
            properties:
              metadata:
                $ref: '#/components/schemas/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
    EmptySyncResponse:
      description: Empty sync response
      content:
        application/json:
          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
    BadRequest:
      description: Bad Request
      content:
        application/json:
          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
    Forbidden:
      description: Forbidden
      content:
        application/json:
          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
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          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
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          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
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            properties:
              error:
                example: not found
                type: string
                x-go-name: Error
              error_code:
                example: 404
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object

Canonical Projects API

Operations 10

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification