doc/projects: Add API instructions

doc/howto/projects_confine.md

@@ -16,36 +16,86 @@ See {ref}`authentication-tls-certs` for detailed information.
 
 To confine the access from the time the client certificate is added, you must either use token authentication or add the client certificate to the server directly.
 
-Use the following command to add a restricted client certificate:
+Follow these instructions:
 
-````{tabs}
+`````{tabs}
+````{group-tab} CLI
 
-```{group-tab} Token authentication
+If you're using token authentication:
 
     lxc config trust add --projects <project_name> --restricted
 
-```
-
-```{group-tab} Add client certificate
+To add the client certificate directly:
 
     lxc config trust add <certificate_file> --projects <project_name> --restricted
+
+The client can then add the server as a remote in the usual way ([`lxc remote add <server_name> <token>`](lxc_remote_add.md) or [`lxc remote add <server_name> <server_address>`](lxc_remote_add.md)) and can only access the project or projects that have been specified.
+
+```{note}
+You can specify the `--project` flag when adding a remote.
+This configuration pre-selects the specified project.
+However, it does not confine the client to this project.
 ```
 
 ````
+````{group-tab} API
+If you're using token authentication, create the token first:
+
+    lxc query --request POST /1.0/certificates --data '{
+      "name": "<client_name>",
+      "projects": ["<project_name>"]
+      "restricted": true,
+      "token": true,
+      "type": "client",
+    }'
+
+% Include content from [/howto/server_expose.md](/howto/server_expose.md)
+```{include} /howto/server_expose.md
+   :start-after: <!-- include start token API -->
+   :end-before: <!-- include end token API -->
+```
 
-The client can then add the server as a remote in the usual way ([`lxc remote add <server_name> <token>`](lxc_remote_add.md) or [`lxc remote add <server_name> <server_address>`](lxc_remote_add.md)) and can only access the project or projects that have been specified.
+To instead add the client certificate directly, send the following request:
+
+    lxc query --request POST /1.0/certificates --data '{
+      "certificate": "<certificate>",
+      "name": "<client_name>",
+      "projects": ["<project_name>"]
+      "restricted": true,
+      "token": false,
+      "type": "client",
+    }'
+
+The client can then authenticate using this trust token or client certificate and can only access the project or projects that have been specified.
 
-To confine access for an existing certificate, use the following command:
+% Include content from [/howto/server_expose.md](/howto/server_expose.md)
+```{include} /howto/server_expose.md
+   :start-after: <!-- include start authenticate API -->
+   :end-before: <!-- include end authenticate API -->
+```
+````
+`````
+
+To confine access for an existing certificate:
+
+````{tabs}
+```{group-tab} CLI
+Use the following command:
 
     lxc config trust edit <fingerprint>
+```
+```{group-tab} API
+Send the following request:
 
-Make sure that `restricted` is set to `true` and specify the projects that the certificate should give access to under `projects`.
+    lxc query --request PATCH /1.0/certificates/<fingerprint> --data '{
+      "projects": ["<project_name>"],
+      "restricted": true
+      }'
 
-```{note}
-You can specify the `--project` flag when adding a remote.
-This configuration pre-selects the specified project.
-However, it does not confine the client to this project.
 ```
+````
+
+Make sure that `restricted` is set to `true` and specify the projects that the certificate should give access to under `projects`.
 
 (projects-confine-users)=
 ## Confine projects to specific LXD users

doc/howto/projects_create.md

@@ -6,6 +6,8 @@ However, note that it is not possible to modify the features that are enabled fo
 
 ## Create a project
 
+````{tabs}
+```{group-tab} CLI
 To create a project, use the [`lxc project create`](lxc_project_create.md) command.
 
 You can specify configuration options by using the `--config` flag.
@@ -18,12 +20,42 @@ For example, to create a project called `my-project` that isolates instances, bu
 To create a project called `my-restricted-project` that blocks access to security-sensitive features (for example, container nesting) but allows backups, enter the following command:
 
     lxc project create my-restricted-project --config restricted=true --config restricted.backups=allow
+```
+```{group-tab} API
+To create a project, send a POST request to the `/1.0/projects` endpoint.
+
+You can specify configuration options under the `"config"` field.
+See {ref}`ref-projects` for the available configuration options.
+
+For example, to create a project called `my-project` that isolates instances, but allows access to the default project's images and profiles, send the following request:
+
+    lxc query --request POST /1.0/projects --data '{
+      "config": {
+        "features.images": "false",
+        "features.profiles": "false"
+      },
+      "name": "my-project"
+    }'
+
+To create a project called `my-restricted-project` that blocks access to security-sensitive features (for example, container nesting) but allows backups, send the following request:
+
+    lxc query --request POST /1.0/projects --data '{
+      "config": {
+        "restricted": "true",
+        "restricted.backups": "allow"
+      },
+      "name": "my-restricted-project"
+    }'
+
+See [`POST /1.0/projects`](swagger:/projects/projects_post) for more information.
+```
+````
 
 ```{tip}
 When you create a project without specifying configuration options, {config:option}`project-features:features.profiles` is set to `true`, which means that profiles are isolated in the project.
 
 Consequently, the new project does not have access to the `default` profile of the `default` project and therefore misses required configuration for creating instances (like the root disk).
-To fix this, use the [`lxc profile device add`](lxc_profile_device_add.md) command to add a root disk device to the project's `default` profile.
+To fix this, add a root disk device to the project's `default` profile (see {ref}`profiles-set-options` for instructions).
 ```
 
 (projects-configure)=
@@ -35,6 +67,8 @@ Some configuration options can only be set for projects that do not contain any
 
 ### Set specific configuration options
 
+`````{tabs}
+````{group-tab} CLI
 To set a specific configuration option, use the [`lxc project set`](lxc_project_set.md) command.
 
 For example, to limit the number of containers that can be created in `my-project` to five, enter the following command:
@@ -47,10 +81,46 @@ To unset a specific configuration option, use the [`lxc project unset`](lxc_proj
 If you unset a configuration option, it is set to its default value.
 This default value might differ from the initial value that is set when the project is created.
 ```
+````
+````{group-tab} API
+To set a specific configuration option, send a PATCH request to the project.
+
+For example, to limit the number of containers that can be created in `my-project` to five, send the following request:
+
+    lxc query --request PATCH /1.0/projects/my-project --data '{
+      "config": {
+        "limits.containers": "5",
+        ...
+      }
+    }'
+
+```{note}
+The PATCH request updates the full content of the `config` field.
+Therefore, you must specify all configuration options as part of the PATCH request, and not only the option that you want to change.
+```
+
+See [`PATCH /1.0/projects/{name}`](swagger:/projects/project_patch) for more information.
+````
+`````
 
 ### Edit the project
 
+````{tabs}
+```{group-tab} CLI
 To edit the full project configuration, use the [`lxc project edit`](lxc_project_edit.md) command.
 For example:
 
     lxc project edit my-project
+```
+```{group-tab} API
+To update the entire project configuration, send a PUT request to the project.
+For example:
+
+    lxc query --request PUT /1.0/projects/my-project --data '{
+      "config": { ... },
+      "description": "<description>"
+    }'
+
+See [`PUT /1.0/projects/{name}`](swagger:/projects/project_put) for more information.
+```
+````

doc/howto/projects_work.md

@@ -11,6 +11,8 @@ Users without full access can only see information for the projects to which the
 
 ## List projects
 
+`````{tabs}
+````{group-tab} CLI
 To list all projects (that you have permission to see), enter the following command:
 
     lxc project list
@@ -32,36 +34,72 @@ By default, the output is presented as a list:
 
 You can request a different output format by adding the `--format` flag.
 See [`lxc project list --help`](lxc_project_list.md) for more information.
+````
+````{group-tab} API
+To list all projects (that you have permission to see), send the following request:
+
+    lxc query --request GET /1.0/projects
+
+To display information about each project, use {ref}`rest-api-recursion`:
+
+    lxc query --request GET /1.0/projects?recursion=1
+
+See [`GET /1.0/projects`](swagger:/projects/projects_get) and  [`GET /1.0/projects?recursion=1`](swagger:/projects/projects_get_recursion1) for more information.
+````
+`````
 
 ## Switch projects
 
+````{tabs}
+```{group-tab} CLI
 By default, all commands that you issue in LXD affect the project that you are currently using.
 To see which project you are in, use the [`lxc project list`](lxc_project_list.md) command.
 
 To switch to a different project, enter the following command:
 
     lxc project switch <project_name>
+```
+```{group-tab} API
+The API does not have the concept of switching projects.
+All requests target the default project unless a different project is specified (see {ref}`projects-target`).
+```
+````
 
+(projects-target)=
 ## Target a project
 
 Instead of switching to a different project, you can target a specific project when running a command.
-Many LXD commands support the `--project` flag to run an action in a different project.
+Many LXD commands support the `--project` flag or the `project` parameter to run an action in a different project.
 
 ```{note}
 You can target only projects that you have permission for.
 ```
 
-The following sections give some typical examples where you would typically target a project instead of switching to it.
-
-### List instances in a project
+An example for targeting another project instead of switching to it is listing the instances in a specific project:
 
+````{tabs}
+```{group-tab} CLI
 To list the instances in a specific project, add the `--project` flag to the [`lxc list`](lxc_list.md) command.
 For example:
 
     lxc list --project my-project
+```
+```{group-tab} API
+To list the instances in a specific project, add the `project` parameter to the request.
+For example:
+
+    lxc query --request GET /1.0/instances?project=my-project
 
-### Move an instance to another project
+Or with {ref}`rest-api-recursion`:
+
+    lxc query --request GET /1.0/instances?recursion=2\&project=my-project
+```
+````
 
+## Move an instance to another project
+
+````{tabs}
+```{group-tab} CLI
 To move an instance from one project to another, enter the following command:
 
     lxc move <instance_name> <new_instance_name> --project <source_project> --target-project <target_project>
@@ -71,20 +109,52 @@ You can keep the same instance name if no instance with that name exists in the
 For example, to move the instance `my-instance` from the `default` project to `my-project` and keep the instance name, enter the following command:
 
     lxc move my-instance my-instance --project default --target-project my-project
+```
+```{group-tab} API
+To move an instance from one project to another, send a POST request to the instance:
 
-### Copy a profile to another project
+    lxc query --request POST /1.0/instances/<instance_name>?project=<source_project> --data '{
+      "name": "<new_instance_name>",
+      "project": "<target_project>",
+      "migration": true
+    }'
 
-If you create a project with the default settings, profiles are isolated in the project ({config:option}`project-features:features.profiles` is set to `true`).
-Therefore, the project does not have access to the default profile (which is part of the `default` project), and you will see an error similar to the following when trying to create an instance:
+If no instance with that name exists in the target project, you can leave out the name for the new instance to keep the existing name.
 
-```{terminal}
-:input: lxc launch ubuntu:24.04 my-instance
+For example, to move the instance `my-instance` from the `default` project to `my-project` and keep the instance name, enter the following command:
+
+    lxc query --request POST /1.0/instances/my-instance?project=default --data '{
+      "project": "my-project",
+      "migration": true
+    }'
 
-Creating my-instance
-Error: Failed instance creation: Failed creating instance record: Failed initialising instance: Failed getting root disk: No root device could be found
+Depending on your projects, you might need to change other configuration options when moving the instance.
+For example, you might need to change the root disk device if one of the projects uses isolated storage volumes.
+
+See [`POST /1.0/instances/{name}`](swagger:/instances/instance_post) for more information.
 ```
+````
+
+## Copy a profile to another project
+
+If you create a project with the default settings, profiles are isolated in the project ({config:option}`project-features:features.profiles` is set to `true`).
+Therefore, the project does not have access to the default profile (which is part of the `default` project), and you will see an error similar to the following when trying to create an instance:
+
+    Error: Failed instance creation: Failed creating instance record: Failed initialising instance: Failed getting root disk: No root device could be found
 
 To fix this, you can copy the contents of the `default` project's default profile into the current project's default profile.
-To do so, enter the following command:
+To do so:
+
+````{tabs}
+```{group-tab} CLI
+Enter the following command:
 
     lxc profile show default --project default | lxc profile edit default
+```
+```{group-tab} API
+Send the following request, replacing `<project>` with the new project that has an empty default profile:
+
+    lxc query --request PUT /1.0/profiles/default?projects=<project> --data \
+      "$(lxc query --request GET /1.0/profiles/default)"
+```
+````

doc/howto/server_expose.md

@@ -94,6 +94,7 @@ To authenticate a CLI or API client using a trust token, complete the following
          "type": "client"
        }'
 
+   <!-- include start token API -->
    See [`POST /1.0/certificates`](swagger:/certificates/certificates_post) for more information.
 
    The return value of this query contains an operation that has the information that is required to generate the trust token:
@@ -117,6 +118,7 @@ To authenticate a CLI or API client using a trust token, complete the following
        echo -n '{"client_name":"<client_name>","fingerprint":"<fingerprint>",'\
        '"addresses":["<server_address>"],'\
        '"secret":"<secret>","expires_at":"0001-01-01T00:00:00Z"}' | base64 -w0
+   <!-- include end token API -->
    ```
    ````
 
@@ -135,6 +137,7 @@ To authenticate a CLI or API client using a trust token, complete the following
    ```
    ````
    ````{group-tab} API
+   <!-- include start authenticate API -->
    On the client, generate a certificate to use for the connection:
 
        openssl req -x509 -newkey rsa:2048 -keyout "<keyfile_name>" -nodes \
@@ -147,6 +150,7 @@ To authenticate a CLI or API client using a trust token, complete the following
        --data '{ "trust_token": "<trust_token>" }'
 
    See [`POST /1.0/certificates?public`](swagger:/certificates/certificates_post_untrusted) for more information.
+   <!-- include end authenticate API -->
    ````
    `````
 

doc/profiles.md

@@ -78,6 +78,7 @@ Enter at least a profile name and click {guilabel}`Create` to save the new profi
 You can either set specific configuration options for a profile or edit the full profile.
 See {ref}`instance-config` (and its subpages) for the available options.
 
+(profiles-set-options)=
 ### Set specific options for a profile
 
 ````{tabs}