API reference
Every endpoint the Bitsmith API serves, grouped by domain. Each entry shows the HTTP method and path, the scope a token needs, the endpoint’s hints, and the JSON schema of its arguments. Path parameters are part of the path; the rest of the arguments go in the request body (POST, PATCH, PUT) or the query string (GET, DELETE).
The same operations are also exposed to MCP clients as tools, so an access token works on both transports. See the MCP docs.
The page is generated from the server source, so it matches this release; for a given server, GET /api/v1/catalog is the live catalog.
155 endpoints across 12 domains.
System
Section titled “System”15 endpoints · scopes backups.manage, backups.read, connections.manage, connections.read, docker.manage, docker.read, files.manage, files.read, host.exec, lxc.exec, lxc.manage, lxc.read, proxy.manage, proxy.read, storage.read, system.manage, system.power, system.read, vm.exec, vm.manage, vm.read
GET /api/v1/activity Search the activity log.
Arguments
{ "type": "object", "properties": { "category": { "type": "string", "description": "Filter by category: auth, user, share, file, storage, backup, app, update, license, system, or agent. Omit for all." }, "severity": { "type": "string", "description": "Filter by severity: info, warning, or critical. Omit for all." }, "outcome": { "type": "string", "description": "Filter by outcome: success or failure. Omit for all, including events that record no outcome." }, "target_type": { "type": "string", "description": "Only events about this kind of target, as target_type reads in results (virtual_machine, lxc_container, app, storage, ...)." }, "target_id": { "type": "string", "description": "Only events about the target with this id, as target_id reads in results." }, "search": { "type": "string", "description": "Text matched, ignoring case, against the summary, target label and actor label." }, "since": { "type": "string", "description": "Only events at or after this RFC3339 timestamp; fractional seconds count." }, "until": { "type": "string", "description": "Only events at or before this RFC3339 timestamp; fractional seconds count." }, "limit": { "type": "integer", "description": "Maximum events to return (1-200). Defaults to 50." }, "cursor": { "type": "string", "description": "Pagination cursor from a previous call's next_cursor." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/catalog List every endpoint of the tool API.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/cluster Show the cluster's servers, roles, version and any Update all run.
Arguments
No arguments.
PUT /api/v1/cluster/role-priority Set the preferred holder order for a cluster role.
Arguments
{ "type": "object", "properties": { "role": { "type": "string", "description": "Cluster role to order, from get_cluster_status: proxy (the server that runs the sites), alerts (the server that sends the cluster's alerts), updates (the server that runs Update all) or runners (the server that runs the runner pools)." }, "server_ids": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Servers in the order they should hold the role (from list_servers; this server may be one). An empty list clears the preference." } }, "required": [ "role", "server_ids" ], "additionalProperties": false}GET /api/v1/guest-network Report whether the guest network is on, and its address plan.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/guest-network Turn the guest network on or off. Turning it off is refused while any guest uses it.
Arguments
{ "type": "object", "properties": { "enabled": { "type": "boolean" }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "enabled" ], "additionalProperties": false}GET /api/v1/placement Suggest which servers can take a new VM, container, app or template.
Arguments
{ "type": "object", "properties": { "kind": { "type": "string", "description": "What is new: vm, lxc, catalog_app, docker_app, template_build, vm_media or lxc_template." }, "catalog_app_id": { "type": "string", "description": "For catalog_app: the app id from list_app_catalog." }, "cpu_cores": { "type": "integer", "description": "Cores it needs, when known.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "description": "Memory in MiB it needs, when known. Without it, fits leaves memory out: free_memory_bytes says what each server has free.", "minimum": 0, "maximum": 4294967295 }, "disk_size_gb": { "type": "integer", "description": "Disk in GiB it needs, when known.", "minimum": 0, "maximum": 4294967295 } }, "required": [ "kind" ], "additionalProperties": false}GET /api/v1/servers List the other servers in the cluster.
Arguments
No arguments.
POST /api/v1/servers/{server_id}/power-off Ask another server to power off.
Arguments
No arguments.
POST /api/v1/servers/{server_id}/wake Send a wake-on-lan magic packet to another server.
Arguments
{ "type": "object", "properties": { "mac": { "type": "string", "description": "MAC address to wake. Omitted, the MAC saved for server_id is used; a server with none saved needs this. Either server_id or mac must be set." }, "port": { "type": "integer", "description": "UDP port to send the magic packet to. Defaults to 9." } }, "additionalProperties": false}GET /api/v1/system/allocation Summarize CPU and memory allocation against host capacity.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/system/health Return host CPU, memory, and overall health.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/tasks List queued and running background tasks.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/tasks/{task_id} Get a background task.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/tasks/{task_id}/logs Get the log lines a background task produced.
Arguments
{ "type": "object", "properties": { "after_line": { "type": "integer", "description": "Only return log lines after this line number, for incremental polling. Defaults to 0 (from the start)." }, "limit": { "type": "integer", "description": "Maximum log lines to return (1-500). Defaults to 200." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}LXC containers
Section titled “LXC containers”23 endpoints · scopes lxc.exec, lxc.manage, lxc.read, vm.manage, vm.read
GET /api/v1/app-catalog List the Apps catalog of ready-made apps.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/app-catalog Install a catalog app as an LXC container or a VM.
Arguments
{ "type": "object", "properties": { "app_id": { "type": "string", "description": "Catalog app id, e.g. jellyfin." }, "name": { "type": "string" }, "storage_id": { "type": "string" }, "cpu_cores": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "disk_size_bytes": { "type": "integer", "minimum": 0 }, "folders": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "Catalog folder id it fills." }, "host_path": { "type": "string", "description": "Folder path on storage." }, "container_path": { "type": "string", "description": "Path inside the app." }, "read_only": { "type": "boolean" } }, "required": [ "host_path" ], "additionalProperties": false } }, "network": { "type": "string", "description": "home (own LAN address) or server (forwarded port)." }, "gpu": { "type": [ "null", "string" ], "description": "GPU render node, e.g. renderD128. Omit for default_gpu when the app uses one; empty for none." }, "run_as": { "type": "string", "description": "container or vm. Omit for the server's default, which list_app_catalog reports as default_run_as. A VM takes no network or gpu." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "app_id" ], "additionalProperties": false}POST /api/v1/app-catalog/retry Run a failed catalog app install again.
Arguments
{ "type": "object", "properties": { "lxcid": { "type": "integer", "description": "Numeric LXC ID of an app's container. Set this or vmid." }, "vmid": { "type": "integer", "description": "Numeric VM ID of an app installed as a virtual machine. Set this or lxcid." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/app-catalog/update Update an installed catalog app.
Arguments
{ "type": "object", "properties": { "lxcid": { "type": "integer", "description": "Numeric LXC ID of an app's container. Set this or vmid." }, "vmid": { "type": "integer", "description": "Numeric VM ID of an app installed as a virtual machine. Set this or lxcid." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/lxc List LXC containers.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/lxc Create an LXC container from a template image.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Name for the new LXC container." }, "template": { "type": "string", "description": "Image ID from the LXC image catalog (e.g. debian-13-generic)." }, "cpu_cores": { "type": "integer", "description": "Number of virtual CPU cores. Defaults to the image minimum when omitted.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "description": "Memory in MiB. Defaults to the image minimum when omitted.", "minimum": 0, "maximum": 4294967295 }, "storage_id": { "type": "string", "description": "Storage pool for the container rootfs. Empty means the host's default LXC storage: the admission sandbox storage pool when one is configured, the system drive otherwise." }, "lxcid": { "type": "integer", "description": "Numeric LXC ID. Automatically assigned when omitted." }, "network_type": { "type": "string", "description": "Network type (e.g. 'bridged', 'none')." }, "dns_servers": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "DNS servers for the container." }, "ip_address": { "type": "string", "description": "Static IPv4 address, for example 192.168.1.50. The subnet prefix is optional and defaults to /24." }, "gateway": { "type": "string", "description": "Static IPv4 gateway address." }, "ip_address_v6": { "type": "string", "description": "Static IPv6 address, e.g. fd00:1234::50. The subnet prefix is optional and defaults to /64." }, "gateway_v6": { "type": "string", "description": "Static IPv6 gateway. Requires ip_address_v6." }, "autostart": { "type": "boolean", "description": "Start the container on host boot." }, "privileged": { "type": "boolean", "description": "Run fully privileged. When false (default), apply idmap + capability dropping + seccomp confinement." }, "nesting": { "type": "boolean", "description": "Enable nested containers (kernel-level mount and seccomp nesting). Mutable via Update at any time." }, "environment": { "type": "object", "description": "Environment variables for the container.", "additionalProperties": { "type": "string" } }, "disk_size_bytes": { "type": "integer", "description": "Root disk size in bytes. Zero uses the template default.", "minimum": 0 }, "template_storage_id": { "type": "string", "description": "Storage pool where the template image resides." }, "mount_points": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "host_path": { "type": "string" }, "container_path": { "type": "string" }, "read_only": { "type": "boolean" } }, "required": [ "host_path", "container_path", "read_only" ], "additionalProperties": false }, "description": "Additional mount points to bind into the container." }, "network_bridge": { "type": "string", "description": "Bridge for bridged containers. Empty uses the global default." }, "linked_clone": { "type": "boolean", "description": "Clone the image as a copy-on-write ZFS clone instead of extracting it. Requires a ZFS pool. Near-instant, but the image cannot be deleted or moved while this container exists." }, "seed_data": { "type": "string", "description": "Data written into the guest at /etc/bitsmith/seed before its first boot, for per-container identity such as an enrollment token." }, "start_after_create": { "type": [ "null", "boolean" ], "description": "Start the container as the final step of the create task so it is running when the task succeeds. Omitted means start; set false to leave it stopped." }, "delete_on_stop": { "type": "boolean", "description": "Delete the container automatically when it stops. One-way: a halted, crashed, or API-stopped container is gone. Omitted means the container is kept." }, "gpu": { "type": "string", "description": "Host GPU render node from get_lxc_host_status, e.g. renderD128." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name", "template" ], "additionalProperties": false}GET /api/v1/lxc/host-status Return LXC host runtime checks.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/lxc/images List cached LXC template images.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/lxc/images/catalog List LXC template images available for download.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/lxc/images/{image_id} Delete a cached LXC template image.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Storage pool where the image is cached." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "storage_id" ], "additionalProperties": false}POST /api/v1/lxc/images/{image_id} Download an LXC template image into a storage pool.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Storage pool to download the image into. Defaults to the default cache storage." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/lxc/images/{image_id}/move Move a cached LXC template image to another storage pool.
Arguments
{ "type": "object", "properties": { "source_storage_id": { "type": "string", "description": "Current storage pool of the image." }, "target_storage_id": { "type": "string", "description": "Destination storage pool for the image." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "source_storage_id", "target_storage_id" ], "additionalProperties": false}DELETE /api/v1/lxc/{id} Delete an LXC container.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/lxc/{id} Get an LXC container.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}PATCH /api/v1/lxc/{id} Update an LXC container's name, CPU, memory, or network settings.
Arguments
{ "type": "object", "properties": { "cpu_cores": { "type": "integer", "description": "Number of CPU cores. 0 leaves unchanged.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "description": "Memory in MiB. 0 leaves unchanged.", "minimum": 0, "maximum": 4294967295 }, "nesting": { "type": [ "null", "boolean" ], "description": "Allow nested containers: true enables, false disables, omit to keep. Changes native config only; no rootfs change needed." }, "new_name": { "type": [ "null", "string" ], "description": "New display name for the container. Omit to keep the current name. Must pass backend validation: no slashes, newlines, null bytes, or the 'bitsmith-lxc-' prefix; max 128 chars." }, "ip_address": { "type": [ "null", "string" ], "description": "Static IPv4 address, for example 192.168.1.50. The subnet prefix is optional and defaults to /24. Omit to keep current; pass an empty string to clear (revert to DHCP)." }, "gateway": { "type": [ "null", "string" ], "description": "Static IPv4 gateway. Omit to keep current; pass an empty string to clear." }, "ip_address_v6": { "type": [ "null", "string" ], "description": "Static IPv6 address, for example 2001:db8::50. The subnet prefix is optional and defaults to /64. Omit to keep current; pass an empty string to clear." }, "gateway_v6": { "type": [ "null", "string" ], "description": "Static IPv6 gateway. Omit to keep current; pass an empty string to clear. Requires ip_address_v6." }, "dns_servers": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "DNS servers. Omit to keep current; pass an empty array to clear." }, "network_type": { "type": [ "null", "string" ], "description": "Network type: bridged or none. Omit to keep." }, "network_bridge": { "type": [ "null", "string" ], "description": "Bridge name for bridged containers. Omit to keep; empty uses the global default." }, "gpu": { "type": [ "null", "string" ], "description": "Host GPU render node from get_lxc_host_status. Omit to keep; empty removes. Applies on next start." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/lxc/{id}/actions Start, stop, restart, freeze or unfreeze an LXC container.
Arguments
{ "type": "object", "properties": { "action": { "type": "string", "description": "start, stop, restart, freeze or unfreeze." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "action" ], "additionalProperties": false}POST /api/v1/lxc/{id}/clone Clone an LXC container to a new name.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Name for the cloned LXC container." }, "lxcid": { "type": "integer", "description": "Numeric LXC ID for the clone. Automatically assigned when omitted." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name" ], "additionalProperties": false}PATCH /api/v1/lxc/{id}/disk Set an LXC container's disk limit.
Arguments
{ "type": "object", "properties": { "disk_size_bytes": { "type": "integer", "description": "Maximum disk usage in bytes. Zero removes the limit.", "minimum": 0 }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "disk_size_bytes" ], "additionalProperties": false}POST /api/v1/lxc/{id}/exec Run a shell command inside an LXC container.
Arguments
{ "type": "object", "properties": { "command": { "type": "string", "description": "Shell command to run inside the container via /bin/sh -c." }, "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait for the command. Defaults to 60." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "command" ], "additionalProperties": false}POST /api/v1/lxc/{id}/move Move a stopped LXC container to another server.
Arguments
{ "type": "object", "properties": { "from_server_id": { "type": "string", "description": "Server that holds the container, from list_servers. Omit for this server." }, "to_server_id": { "type": "string", "description": "Server to move the container to, from list_servers." }, "storage_id": { "type": "string", "description": "Storage pool on that server. Empty uses its system drive." } }, "required": [ "to_server_id" ], "additionalProperties": false}POST /api/v1/lxc/{id}/move-storage Move an LXC container's rootfs to another storage pool.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Target storage pool to move the container rootfs into." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "storage_id" ], "additionalProperties": false}GET /api/v1/lxc/{id}/stats Get an LXC container's resource usage.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/lxc/{id}/template Capture an LXC container's rootfs as a reusable template image.
Arguments
{ "type": "object", "properties": { "image_id": { "type": "string", "description": "Optional ID for the new template image. Defaults to the container name, sanitized. Fails if an image with this ID already exists on the storage." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}Backups
Section titled “Backups”13 endpoints · scopes backups.manage, backups.read
POST /api/v1/backups/now Back up something once, without a schedule.
Arguments
{ "type": "object", "properties": { "vmid": { "type": "integer", "description": "Back up this VM." }, "lxcid": { "type": "integer", "description": "Back up this LXC container." }, "app_id": { "type": "integer", "description": "Back up this Docker app's data." }, "folder_id": { "type": "string", "description": "Back up this folder." }, "sub_path": { "type": "string", "description": "With folder_id, back up only this path inside the folder." }, "vm_policy": { "type": "string", "description": "VM only: stop_backup_restart_if_was_running (default), guest_agent_snapshot or live_snapshot." }, "lxc_policy": { "type": "string", "description": "Container only: auto (default), freeze or stop." }, "checksum": { "type": "boolean", "description": "Folder only: compare file contents, not just size and time." }, "storage_id": { "type": "string", "description": "Back up to this storage pool, or system for the system drive." }, "location_id": { "type": "string", "description": "Back up to this connected location instead." }, "to_server_id": { "type": "string", "description": "With storage_id, back up to that storage on this other server (ids from list_servers)." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/backups/runs List backup runs, newest first.
Arguments
{ "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum runs to return, newest first (1-200). Defaults to 50." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/backups/schedules List backup schedules.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}PUT /api/v1/backups/schedules Create or change a backup schedule.
Arguments
{ "type": "object", "properties": { "schedule_id": { "type": "string", "description": "Omit to create a schedule; an ID from list_backup_schedules changes that schedule." }, "vmid": { "type": "integer", "description": "Create only: back up this VM." }, "lxcid": { "type": "integer", "description": "Create only: back up this LXC container." }, "app_id": { "type": "integer", "description": "Create only: back up this Docker app's data." }, "folder_id": { "type": "string", "description": "Create only: back up this folder." }, "sub_path": { "type": "string", "description": "Create only: with folder_id, back up only this path inside the folder." }, "storage_id": { "type": "string", "description": "Create only: back up to this storage pool, or system for the system drive." }, "location_id": { "type": "string", "description": "Create only: back up to this connected location instead." }, "to_server_id": { "type": "string", "description": "Create only: with storage_id, back up to that storage on this other server (ids from list_servers)." }, "cadence": { "type": [ "null", "string" ], "description": "When it runs: a five-field cron expression such as 0 3 * * *, or daily or weekly (03:00). Required to create." }, "keep_versions": { "type": [ "null", "integer" ], "description": "Versions to keep at the destination, 1 or more. A new schedule keeps 5." }, "enabled": { "type": [ "null", "boolean" ], "description": "false pauses the schedule, true resumes it. A new schedule runs unless this is false." }, "vm_policy": { "type": [ "null", "string" ], "description": "VM schedules: stop_backup_restart_if_was_running (default), guest_agent_snapshot or live_snapshot." }, "lxc_policy": { "type": [ "null", "string" ], "description": "Container schedules: auto (default), freeze or stop." }, "checksum": { "type": [ "null", "boolean" ], "description": "Folder schedules: compare file contents, not just size and time." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/backups/schedules/{schedule_id} Delete a backup schedule.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/backups/schedules/{schedule_id}/run Run a backup schedule now.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/backups/settings Get the backup settings.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}PATCH /api/v1/backups/settings Change the backup settings.
Arguments
{ "type": "object", "properties": { "system_disk_limit_mib_per_second": { "type": [ "null", "integer" ], "description": "Speed limit for backup reads and writes on the system drive, in MiB/s. 0 is no limit." }, "include_app_images": { "type": [ "null", "boolean" ], "description": "Whether Docker app backups also save the app's images." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/backups/versions List backup versions, including those kept for other servers.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/backups/versions/{version_id} Delete a backup version.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/backups/versions/{version_id}/contents List the files inside a backup version.
Arguments
{ "type": "object", "properties": { "path": { "type": "string", "description": "Folder inside the version. Empty is its top." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/backups/versions/{version_id}/replace Put a backup version back over what exists.
Arguments
{ "type": "object", "properties": { "folder_id": { "type": "string", "description": "Folder versions: restore into this folder." }, "location_id": { "type": "string", "description": "Folder versions: restore into this connected location instead." }, "sub_path": { "type": "string", "description": "Path inside the folder or location. Empty is its top." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/backups/versions/{version_id}/restore Restore a backup version as something new.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "VM, container or app versions: storage for the new one, or system (the default) for the system drive." }, "folder_id": { "type": "string", "description": "Folder versions: restore into this folder." }, "location_id": { "type": "string", "description": "Folder versions: restore into this connected location instead." }, "sub_path": { "type": "string", "description": "Path inside the folder or location. Empty is its top." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}docker
Section titled “docker”10 endpoints · scopes docker.manage, docker.read
GET /api/v1/docker List Docker Compose apps.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/docker Install a Docker Compose app.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "App name." }, "compose_content": { "type": "string", "description": "Docker Compose file." }, "storage_id": { "type": "string", "description": "Storage pool ID for app data." }, "folder_assignments": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "Folder ID to mount." }, "sub_path": { "type": "string", "description": "Sub-path within the folder." }, "container_path": { "type": "string", "description": "Mount point path inside the container." }, "read_only": { "type": "boolean", "description": "Mount as read-only." } }, "required": [ "folder_id", "container_path" ], "additionalProperties": false }, "description": "Folder mount assignments." }, "volume_folders": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "service": { "type": "string", "description": "Compose service name." }, "source": { "type": "string", "description": "Host path as the compose file writes it." }, "folder_id": { "type": "string", "description": "Folder to keep it in instead." }, "sub_path": { "type": "string", "description": "Sub-path within the folder." } }, "required": [ "service", "source", "folder_id" ], "additionalProperties": false }, "description": "Host path volumes to keep in a folder instead." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name", "compose_content" ], "additionalProperties": false}GET /api/v1/docker/discovered List Docker containers Bitsmith does not manage.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/docker/{app_id} Uninstall a Docker app.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/docker/{app_id}/actions Start, stop or restart a Docker app.
Arguments
{ "type": "object", "properties": { "action": { "type": "string", "description": "start, stop or restart." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "action" ], "additionalProperties": false}PATCH /api/v1/docker/{app_id}/compose Update a Docker app's compose file.
Arguments
{ "type": "object", "properties": { "compose_content": { "type": "string", "description": "New compose YAML content." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "compose_content" ], "additionalProperties": false}PATCH /api/v1/docker/{app_id}/folders Update a Docker app's folder mounts.
Arguments
{ "type": "object", "properties": { "folder_assignments": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "Folder ID to mount." }, "sub_path": { "type": "string", "description": "Sub-path within the folder." }, "container_path": { "type": "string", "description": "Mount point path inside the container." }, "read_only": { "type": "boolean", "description": "Mount as read-only." } }, "required": [ "folder_id", "container_path" ], "additionalProperties": false }, "description": "Every folder mount the app keeps: the list replaces its mounts, so include the ones it already has. An empty list removes every mount." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "folder_assignments" ], "additionalProperties": false}GET /api/v1/docker/{app_id}/logs Get a Docker app's container logs.
Arguments
{ "type": "object", "properties": { "tail": { "type": "integer", "description": "Number of trailing log lines to return. Defaults to 50.", "minimum": 0, "maximum": 4294967295 }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/docker/{app_id}/move Move a Docker app's data to another storage pool.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Target storage pool ID." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "storage_id" ], "additionalProperties": false}GET /api/v1/docker/{app_id}/stats Get a Docker app's resource usage.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}Files and folders
Section titled “Files and folders”11 endpoints · scopes files.manage, files.read
GET /api/v1/folders List managed folders.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/folders Create a folder in a storage pool.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Storage pool ID." }, "name": { "type": "string", "description": "Folder name." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "storage_id", "name" ], "additionalProperties": false}DELETE /api/v1/folders/{folder_id} Delete a folder.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}PATCH /api/v1/folders/{folder_id} Rename a folder.
Arguments
{ "type": "object", "properties": { "new_name": { "type": "string", "description": "New folder name." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "new_name" ], "additionalProperties": false}GET /api/v1/folders/{folder_id}/contents List the entries at a path.
Arguments
{ "type": "object", "properties": { "sub_path": { "type": "string", "description": "Optional sub-path inside the folder." }, "target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Target to list: {kind: folder | connection, id, path}. Overrides the folder_id and sub_path pair when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/folders/{folder_id}/entries/batch Move several files or folders at once.
Arguments
{ "type": "object", "properties": { "moves": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "src_sub_path": { "type": "string", "description": "Source sub-path inside the folder." }, "dst_sub_path": { "type": "string", "description": "Destination sub-path inside the folder." } }, "required": [ "src_sub_path", "dst_sub_path" ], "additionalProperties": false }, "description": "Array of source and destination path pairs, relative to the folder or connection root." }, "target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Container the moves happen in: {kind: folder | connection, id}, without a path. Overrides folder_id when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "moves" ], "additionalProperties": false}PATCH /api/v1/folders/{folder_id}/entries/{src_sub_path} Move or rename a file or folder.
Arguments
{ "type": "object", "properties": { "dst_sub_path": { "type": "string", "description": "Destination sub-path inside the folder." }, "src_target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Source {kind: folder | connection, id, path}. Pair with dst_target; overrides folder_id and the sub paths.", "required": [ "kind", "id" ], "additionalProperties": false }, "dst_target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Destination in the same folder or connection as src_target.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/folders/{folder_id}/entries/{sub_path} Delete a file or folder.
Arguments
{ "type": "object", "properties": { "target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Entry to delete: {kind: folder | connection, id, path}. Overrides the folder_id and sub_path pair when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/folders/{folder_id}/search Search files and folders by name.
Arguments
{ "type": "object", "properties": { "pattern": { "type": "string", "description": "Name pattern to match (substring, case-insensitive). Use * for glob-style wildcards." }, "sub_path": { "type": "string", "description": "Optional sub-path to start search from." }, "target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Where to search: {kind: folder | connection, id, path}. Overrides the folder_id and sub_path pair when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "required": [ "pattern" ], "additionalProperties": false}POST /api/v1/folders/{folder_id}/subfolders/batch Create one or more subfolders.
Arguments
{ "type": "object", "properties": { "sub_path": { "type": "string", "description": "Path inside the folder to create them in. Empty is the folder's root." }, "names": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Names of the folders to create. One folder is a one-element list." }, "target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Parent to create in: {kind: folder | connection, id, path}. Overrides the folder_id and sub_path pair when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "names" ], "additionalProperties": false}POST /api/v1/folders/{src_folder_id}/entries/{src_sub_path}/copy Copy a file or folder.
Arguments
{ "type": "object", "properties": { "dst_folder_id": { "type": "string", "description": "Destination folder ID." }, "dst_sub_path": { "type": "string", "description": "Destination sub-path inside the folder." }, "src_target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Source {kind: folder | connection, id, path}. Overrides src_folder_id and src_sub_path when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "dst_target": { "type": [ "null", "object" ], "properties": { "kind": { "type": "string", "description": "folder for a managed folder, connection for a connected location." }, "id": { "type": "string", "description": "Folder ID or connected location ID." }, "path": { "type": "string", "description": "Path inside it, relative to its root. Empty is the root." } }, "description": "Destination {kind: folder | connection, id, path}. Overrides dst_folder_id and dst_sub_path when set.", "required": [ "kind", "id" ], "additionalProperties": false }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}1 endpoints · scopes host.exec
POST /api/v1/host/exec Run a shell command on the host.
Arguments
{ "type": "object", "properties": { "command": { "type": "string", "description": "Shell command to run on the host via /bin/sh -c." }, "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait for the command. Defaults to 60, capped at 300." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "command" ], "additionalProperties": false}Connected storage
Section titled “Connected storage”7 endpoints · scopes connections.manage, connections.read
GET /api/v1/locations List connected network shares.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/locations Connect a network share and mount it.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the connected location." }, "type": { "type": "string", "description": "Connection type. Defaults to smb, the only type this server mounts today." }, "remote": { "type": "string", "description": "Share address, for example //nas.local/media or nas.local/media." }, "username": { "type": "string", "description": "Optional SMB username. Omit together with password for guest access." }, "password": { "type": "string", "description": "Optional SMB password. Stored in the secret store, never echoed back." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name", "remote" ], "additionalProperties": false}POST /api/v1/locations/discover Discover SMB hosts on the network, or list one host's shares.
Arguments
{ "type": "object", "properties": { "host": { "type": "string", "description": "SMB host name or address. Omit to discover hosts on the local network; set it to list that host's shares." }, "ip": { "type": "string", "description": "Optional resolved IP for host, used when the name does not resolve." }, "username": { "type": "string", "description": "Optional SMB username for listing shares. Omit for guest access." }, "password": { "type": "string", "description": "Optional SMB password for listing shares. Used for the probe only, never stored or echoed." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/locations/{location_id} Remove a connected location and its stored credentials.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/locations/{location_id} Get a connected location.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/locations/{location_id}/disconnect Unmount a connected location.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/locations/{location_id}/reconnect Mount a connected location again.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}Reverse proxy
Section titled “Reverse proxy”25 endpoints · scopes proxy.manage, proxy.read
PATCH /api/v1/proxy Enable or disable the reverse proxy.
Arguments
{ "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the reverse proxy should be enabled." } }, "required": [ "enabled" ], "additionalProperties": false}PUT /api/v1/proxy/acme/config Set the ACME account email and directory URL.
Arguments
{ "type": "object", "properties": { "email": { "type": "string", "description": "The ACME account email." }, "dir_url": { "type": "string", "description": "The ACME directory URL. Empty uses the Let's Encrypt production directory." }, "dns_resolvers": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Recursive resolvers the DNS-01 propagation precheck queries. Empty uses the public defaults (1.1.1.1, 8.8.8.8)." } }, "required": [ "email" ], "additionalProperties": false}PUT /api/v1/proxy/acme/credentials Store DNS provider credentials for public certificates.
Arguments
{ "type": "object", "properties": { "provider": { "type": "string", "description": "The DNS provider name (e.g. cloudflare)." }, "credentials": { "type": "object", "description": "The provider credential key/value pairs.", "additionalProperties": { "type": "string" } } }, "required": [ "provider", "credentials" ], "additionalProperties": false}GET /api/v1/proxy/certs Get TLS certificate status per base domain.
Arguments
No arguments.
GET /api/v1/proxy/config Get the reverse proxy configuration.
Arguments
No arguments.
GET /api/v1/proxy/diagnostics Collect reverse proxy diagnostics from the cluster node holding the proxy.
Arguments
No arguments.
PUT /api/v1/proxy/dns Set the DNS resolvers the built-in responder forwards to.
Arguments
{ "type": "object", "properties": { "dns_upstreams": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "The recursive resolvers the built-in DNS responder forwards non-zone queries to." } }, "required": [ "dns_upstreams" ], "additionalProperties": false}GET /api/v1/proxy/dns-publish Get the DNS publishing state of every base domain.
Arguments
No arguments.
GET /api/v1/proxy/dns/rewrites List the DNS rewrites the built-in responder answers.
Arguments
No arguments.
DELETE /api/v1/proxy/dns/rewrites/{domain} Delete a DNS rewrite.
Arguments
No arguments.
PUT /api/v1/proxy/dns/rewrites/{domain} Add or change a DNS rewrite.
Arguments
{ "type": "object", "properties": { "mode": { "type": "string", "description": "create or update." }, "ipv4": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Answers for A queries. On update the list replaces the old one; omit it to keep it." }, "ipv6": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Answers for AAAA queries. On update the list replaces the old one; omit it to keep it." }, "new_domain": { "type": [ "null", "string" ], "description": "Update only: rename the rewrite." } }, "required": [ "mode" ], "additionalProperties": false}DELETE /api/v1/proxy/domains/{domain} Remove a base domain.
Arguments
No arguments.
PUT /api/v1/proxy/domains/{domain} Add or change a base domain the proxy serves.
Arguments
{ "type": "object", "properties": { "mode": { "type": "string", "description": "create or update." }, "cert_source": { "type": [ "null", "string" ], "description": "\"internal\" for the internal CA, or a DNS provider name (e.g. cloudflare) for a public ACME cert. Required to create; omit on update to keep it." }, "new_name": { "type": [ "null", "string" ], "description": "Update only: rename the domain. Its entries follow." } }, "required": [ "mode" ], "additionalProperties": false}POST /api/v1/proxy/domains/{domain}/certs/renew Force a TLS certificate renewal for a base domain.
Arguments
No arguments.
PUT /api/v1/proxy/domains/{domain}/dns-publish Turn publishing a base domain in its DNS provider on or off.
Arguments
{ "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true publishes the apex and wildcard A/AAAA records pointing at the proxy's virtual IP; false deletes the records Bitsmith created." }, "replace_existing": { "type": "boolean", "description": "Overwrite the records the last attempt reported as conflicts (records Bitsmith did not create). Turns publishing on." } }, "required": [ "enabled" ], "additionalProperties": false}DELETE /api/v1/proxy/domains/{domain}/entries/{subdomain} Delete a reverse proxy entry.
Arguments
{ "type": "object", "properties": { "listen_port": { "type": "integer", "description": "VIP/listen port of the proxy entry to delete; 0/omitted = default 443." } }, "additionalProperties": false}PUT /api/v1/proxy/domains/{domain}/entries/{subdomain} Add or change a reverse proxy entry.
Arguments
{ "type": "object", "properties": { "mode": { "type": "string", "description": "create or update." }, "listen_port": { "type": "integer", "description": "Listen port of the entry; 0/omitted = 443. Two entries may share a subdomain only on different listen ports." }, "host": { "type": [ "null", "string" ], "description": "Upstream IP or hostname. Create needs host or target_id. With a target_id, an address of its own pins the entry to it; omit it to follow the target." }, "port": { "type": [ "null", "integer" ], "description": "Upstream port (1-65535). Required to create." }, "target_id": { "type": [ "null", "string" ], "description": "App, VM or LXC target to link the entry to, from list_proxy_upstreams. On update an empty value unlinks it." }, "upstream_scheme": { "type": [ "null", "string" ], "description": "\"http\" or \"https\"; empty picks it from the port (443 is https, any other http)." }, "tls_skip_verify": { "type": [ "null", "boolean" ], "description": "Skip certificate verification on an https upstream. Omitted on create, it is skipped on port 443 only." }, "header_up": { "type": "object", "description": "Upstream header overrides: HTTP token keys, Caddyfile-token values ({host} works), an empty value clears that header. On update it replaces the old map.", "additionalProperties": { "type": "string" } }, "new_domain": { "type": [ "null", "string" ], "description": "Update only: move the entry to another configured domain." }, "new_subdomain": { "type": [ "null", "string" ], "description": "Update only: rename the subdomain." }, "new_listen_port": { "type": [ "null", "integer" ], "description": "Update only: serve the entry on another listen port; 0 = 443." } }, "required": [ "mode" ], "additionalProperties": false}GET /api/v1/proxy/host-status Return reverse proxy host status.
Arguments
No arguments.
PATCH /api/v1/proxy/http3 Turn HTTP/3 serving on or off.
Arguments
{ "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the proxy serves HTTP/3 (QUIC) in addition to h1/h2; false pins Caddy to h1/h2 (the default)." } }, "required": [ "enabled" ], "additionalProperties": false}GET /api/v1/proxy/incidents List captured reverse proxy incident bundles.
Arguments
No arguments.
GET /api/v1/proxy/incidents/{incident_id} Get one captured incident bundle.
Arguments
No arguments.
POST /api/v1/proxy/move Move the reverse proxy to another server.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to move the cluster proxy to, from list_servers. Omit to take the proxy over on this server when the holder is unreachable." } }, "additionalProperties": false}GET /api/v1/proxy/providers List the DNS providers supported for public certificates.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/proxy/upstreams List targets the proxy can route to.
Arguments
No arguments.
PUT /api/v1/proxy/vip Set the reverse proxy's floating addresses.
Arguments
{ "type": "object", "properties": { "vip": { "type": "string", "description": "The IPv4 floating address the proxy binds." }, "vip_iface": { "type": "string", "description": "The network interface the VIPs are bound to. Required when a vip is set." }, "vip_prefix": { "type": "integer", "description": "The IPv4 VIP prefix length (1-32)." }, "vip6": { "type": "string", "description": "The optional IPv6 floating address the proxy binds." }, "vip6_prefix": { "type": "integer", "description": "The IPv6 VIP prefix length (1-128)." } }, "additionalProperties": false}Virtual machines
Section titled “Virtual machines”35 endpoints · scopes backups.manage, connections.manage, docker.manage, docker.read, files.manage, host.exec, lxc.manage, lxc.read, proxy.manage, sandbox.manage, sandbox.read, system.power, vm.exec, vm.manage, vm.read
GET /api/v1/resource-docs/{kind}/{id} Get the documentation stored for a VM, LXC container or Docker app.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}PUT /api/v1/resource-docs/{kind}/{id} Replace or append to the documentation of a VM, LXC container or Docker app.
Arguments
{ "type": "object", "properties": { "content": { "type": "string", "description": "Markdown documentation. Replaces the docs, or with append_entry is the text of one new entry." }, "append_entry": { "type": "boolean", "description": "Append content as a timestamped entry below the existing docs instead of replacing them." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "content" ], "additionalProperties": false}POST /api/v1/tasks/{task_id}/cancel Cancel a queued or running background task.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server the task lives on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/templates Build a reusable VM template from a base image and a cloud-init script.
Arguments
{ "type": "object", "properties": { "base_image_id": { "type": "string", "description": "ID of the image the build machine boots from, such as debian-13-genericcloud-amd64. It is downloaded first if this host does not have it yet." }, "name": { "type": "string", "description": "Name for the template this build produces." }, "user_data": { "type": "string", "description": "Cloud-init user-data the build machine boots with: a #cloud-config document or a #! script. End it by powering the machine off: that is how the build says it is finished. On an ipv6_only build machine it runs after the IPv4 translator is up." }, "labels": { "type": "object", "description": "Labels stored verbatim on the resulting image and returned by list_virtual_machine_images. The label built_by_client is reserved.", "additionalProperties": { "type": "string" } }, "network_stack": { "type": "string", "description": "IP families of the build machine: dual_stack or ipv6_only (no IPv4 lease; IPv4 hosts are reached through CLAT and the server's NAT64 prefix). Omitted: the server default, which is ipv6_only when get_sandbox_capabilities reports it available." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "base_image_id", "name" ], "additionalProperties": false}GET /api/v1/templates/{task_id} Report how a template build is going.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms List virtual machines.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms Create a VM from an image or a captured template.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Name for the new virtual machine." }, "image_id": { "type": "string", "description": "ID of the VM image to clone, such as debian-13-genericcloud-amd64." }, "cpu_cores": { "type": "integer", "description": "Number of virtual CPU cores. Server applies image minimum when omitted.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "description": "Memory in MiB. Server applies image minimum when omitted.", "minimum": 0, "maximum": 4294967295 }, "swap_enabled": { "type": [ "null", "boolean" ], "description": "Provision a guest swap file on first boot, sized to the VM's memory (512 MiB floor, 4 GiB cap). Omitted means enabled." }, "disk_size_gb": { "type": "integer", "description": "Target VM disk size in GiB. Server applies image minimum when omitted.", "minimum": 0, "maximum": 4294967295 }, "additional_disks": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "size_gb": { "type": "integer", "description": "Size of the additional disk in GiB (must be at least 1).", "minimum": 0, "maximum": 4294967295 } }, "required": [ "size_gb" ], "additionalProperties": false }, "description": "Additional empty disks to attach at create, each as its own virtio block device (vdb, vdc, ...)." }, "username": { "type": "string", "description": "Cloud-init username. Defaults to the image default user when omitted." }, "ssh_public_key": { "type": "string", "description": "SSH public key to install with cloud-init. Install your own key here to SSH into the VM after it boots; the cloud-init user has passwordless sudo." }, "storage_id": { "type": "string", "description": "Storage pool ID for the VM disk. Omit to use the host's default VM storage pool (the Sandbox storage setting on the VM capacity page; the system drive when unset)." }, "vmid": { "type": "integer", "description": "Numeric VM ID. Automatically assigned when omitted." }, "package_upgrade": { "type": "boolean", "description": "Run package upgrades during cloud-init." }, "ssh_password_auth": { "type": "boolean", "description": "Enable SSH password authentication in cloud-init." }, "dns_servers": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Cloud-init DNS servers." }, "ip_address": { "type": "string", "description": "Static cloud-init IPv4 address, for example 192.168.1.50. The subnet prefix is optional and defaults to /24. Use ip_address_v6 for IPv6." }, "gateway": { "type": "string", "description": "Static cloud-init IPv4 gateway, for use with ip_address." }, "ip_address_v6": { "type": "string", "description": "Static cloud-init IPv6 address for a dual-stack guest, for example 2001:db8::50. The subnet prefix is optional and defaults to /64. ip_address must be IPv4 when set." }, "gateway_v6": { "type": "string", "description": "Static cloud-init IPv6 gateway, for use with ip_address_v6." }, "autostart": { "type": "boolean", "description": "Start the VM on host boot." }, "linked_clone": { "type": "boolean", "description": "Clone the image as a copy-on-write overlay instead of copying it. Creation is near-instant regardless of image size, but the image cannot be deleted or moved while this VM exists." }, "seed_data": { "type": "string", "description": "Data written into the guest at /etc/bitsmith/seed before its first boot, for per-VM identity such as an enrollment token." }, "skip_rekey": { "type": "boolean", "description": "Keep the source image's machine-id and SSH host keys instead of clearing them. Use it when the image re-keys itself on first boot or comes from a warm state." }, "start_after_create": { "type": [ "null", "boolean" ], "description": "Start the VM as the final step of the create task so it is running when the task succeeds. Omitted means start; set false to leave it stopped." }, "delete_on_stop": { "type": "boolean", "description": "Delete the VM automatically when it stops. One-way: a powered-off, crashed, or API-stopped VM is gone. Omitted means the VM is kept." }, "network_stack": { "type": "string", "description": "IP families: dual_stack (default) or ipv6_only (no IPv4 lease; IPv4 hosts reached through CLAT and the server's NAT64 prefix, which must be set first). Not combinable with ip_address or gateway. Fixed at create." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name", "image_id" ], "additionalProperties": false}GET /api/v1/vms/capacity Report the memory ledger that decides whether a new VM or container is created or queued.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms/host-status Return VM host runtime checks.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms/images List VM images and templates stored on this server.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms/images/catalog List VM images available for download. An image with micro_vm makes micro VMs: they boot in about a second, with a serial console and no display, passthrough devices or installer ISOs.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/vms/images/{image_id} Delete a VM image or captured template.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Storage pool holding the template. Empty means the system drive." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/images/{image_id}/move Move a VM image to another storage pool.
Arguments
{ "type": "object", "properties": { "source_storage_id": { "type": "string", "description": "Current storage pool of the image." }, "target_storage_id": { "type": "string", "description": "Destination storage pool for the image." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "source_storage_id", "target_storage_id" ], "additionalProperties": false}GET /api/v1/vms/isos List installer ISOs stored on this server.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/isos/{iso_id}/move Move an installer ISO to another storage pool.
Arguments
{ "type": "object", "properties": { "source_storage_id": { "type": "string", "description": "Current storage pool of the ISO." }, "target_storage_id": { "type": "string", "description": "Destination storage pool for the ISO." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "source_storage_id", "target_storage_id" ], "additionalProperties": false}GET /api/v1/vms/warm-states List saved VM warm states.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/vms/warm-states/{id} Delete a saved warm state.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/warm-states/{id} Create a VM that resumes from a saved warm state.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Name for the new virtual machine." }, "vmid": { "type": "integer", "description": "Numeric VM ID for the new VM. Automatically assigned when omitted." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name" ], "additionalProperties": false}DELETE /api/v1/vms/{id} Delete a VM.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms/{id} Get a VM.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}PATCH /api/v1/vms/{id} Update a stopped VM's CPU and memory.
Arguments
{ "type": "object", "properties": { "cpu_cores": { "type": [ "null", "integer" ], "description": "Number of virtual CPU cores. Omit to keep unchanged.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": [ "null", "integer" ], "description": "Memory in MiB. Omit to keep unchanged.", "minimum": 0, "maximum": 4294967295 }, "autostart": { "type": [ "null", "boolean" ], "description": "Start the VM on host boot. Omit to keep unchanged." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/{id}/actions Start, stop, suspend or resume a VM.
Arguments
{ "type": "object", "properties": { "action": { "type": "string", "description": "start, stop, suspend or resume." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "action" ], "additionalProperties": false}POST /api/v1/vms/{id}/clone Clone a stopped VM's disk into a new VM.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Name for the cloned virtual machine." }, "vmid": { "type": "integer", "description": "Numeric VM ID for the clone. Automatically assigned when omitted." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "name" ], "additionalProperties": false}POST /api/v1/vms/{id}/cloud-init Update a VM's cloud-init settings.
Arguments
{ "type": "object", "properties": { "cloud_init_enabled": { "type": [ "null", "boolean" ], "description": "Enable or disable cloud-init for the VM." }, "username": { "type": [ "null", "string" ], "description": "Cloud-init username." }, "ssh_public_key": { "type": [ "null", "string" ], "description": "SSH public key to install with cloud-init. Empty disables key-based SSH unless ssh_enabled is set." }, "password": { "type": [ "null", "string" ], "description": "Cloud-init password to set for the user." }, "clear_password": { "type": [ "null", "boolean" ], "description": "Clear the stored cloud-init password." }, "ssh_enabled": { "type": [ "null", "boolean" ], "description": "Enable SSH setup in cloud-init." }, "ssh_password_auth": { "type": [ "null", "boolean" ], "description": "Enable SSH password authentication in cloud-init." }, "dns_servers": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Cloud-init DNS servers. Provide an empty array to clear." }, "ip_address": { "type": [ "null", "string" ], "description": "Static cloud-init IPv4 address. Empty clears it. Use ip_address_v6 for IPv6." }, "gateway": { "type": [ "null", "string" ], "description": "Static cloud-init IPv4 gateway. Empty clears it." }, "ip_address_v6": { "type": [ "null", "string" ], "description": "Static cloud-init IPv6 address. Empty clears it." }, "gateway_v6": { "type": [ "null", "string" ], "description": "Static cloud-init IPv6 gateway. Empty clears it." }, "package_upgrade": { "type": [ "null", "boolean" ], "description": "Run package upgrades during cloud-init." }, "swap_enabled": { "type": [ "null", "boolean" ], "description": "Enable or disable the guest swap file that cloud-init provisions on boot. Omit to keep the current value." }, "swap_size_mb": { "type": [ "null", "integer" ], "description": "Size in MB of the guest swap file. 0 selects the default (the VM's memory, clamped 512 MiB to 4 GiB); explicit values must be between 256 and 32768. Omit to keep the current value.", "minimum": 0, "maximum": 4294967295 }, "network_type": { "type": [ "null", "string" ], "description": "Network type: bridged or none." }, "network_bridge": { "type": [ "null", "string" ], "description": "Bridge name when network_type is bridged." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/vms/{id}/connection Get SSH connection details for a VM.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/{id}/disks Attach a new empty disk to a VM.
Arguments
{ "type": "object", "properties": { "size_gb": { "type": "integer", "description": "Size of the new disk in GiB (must be \u003e= 1).", "minimum": 0, "maximum": 4294967295 }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "size_gb" ], "additionalProperties": false}DELETE /api/v1/vms/{id}/disks/{disk_id} Detach and delete an additional disk from a VM.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}PATCH /api/v1/vms/{id}/disks/{disk_id} Grow an additional disk on a VM.
Arguments
{ "type": "object", "properties": { "size_gb": { "type": "integer", "description": "Target size of the disk in GiB (must be at least 1; server enforces grow-only).", "minimum": 0, "maximum": 4294967295 }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "size_gb" ], "additionalProperties": false}POST /api/v1/vms/{id}/exec Run a shell command inside a VM through its guest agent.
Arguments
{ "type": "object", "properties": { "command": { "type": "string", "description": "Shell command to run inside the guest via /bin/sh -c." }, "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait for the command. Defaults to 60." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "command" ], "additionalProperties": false}POST /api/v1/vms/{id}/move Move a stopped VM to another server.
Arguments
{ "type": "object", "properties": { "from_server_id": { "type": "string", "description": "Server that holds the VM, from list_servers. Omit for this server." }, "to_server_id": { "type": "string", "description": "Server to move the VM to, from list_servers." }, "storage_id": { "type": "string", "description": "Storage pool on that server. Empty uses its system drive." } }, "required": [ "to_server_id" ], "additionalProperties": false}PATCH /api/v1/vms/{id}/storage Grow a VM's root (system) disk.
Arguments
{ "type": "object", "properties": { "size_gb": { "type": "integer", "description": "Target size of the root (system) disk in GiB (must be at least 1; server enforces grow-only).", "minimum": 0, "maximum": 4294967295 }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "size_gb" ], "additionalProperties": false}POST /api/v1/vms/{id}/template Capture a VM's disk as a reusable template.
Arguments
{ "type": "object", "properties": { "template_name": { "type": "string", "description": "Optional name for the captured template image. Defaults to the VM name." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/{id}/wait-ip Wait until a VM has an IP address.
Arguments
{ "type": "object", "properties": { "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait. Defaults to 60." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/{id}/wait-ready Wait until a VM is running and reachable.
Arguments
{ "type": "object", "properties": { "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait. Defaults to 60." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/vms/{id}/warm-states Save a running VM as a warm state.
Arguments
{ "type": "object", "properties": { "name": { "type": "string", "description": "Label for the warm state. Defaults to the VM name when omitted." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}CI runner pools
Section titled “CI runner pools”5 endpoints · scopes runners.manage, runners.read
GET /api/v1/runner-pools List CI runner pools and their health.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}PUT /api/v1/runner-pools Create or change a runner pool.
Arguments
{ "type": "object", "properties": { "pool_id": { "type": "string", "description": "Omit to create a pool; an ID from list_runner_pools changes that pool." }, "name": { "type": [ "null", "string" ], "description": "Display name. Required to create." }, "kind": { "type": [ "null", "string" ], "description": "Code host kind: forgejo or gitea. Required to create." }, "repo_url": { "type": [ "null", "string" ], "description": "Repository URL the pool serves, such as https://forgejo.example/owner/repo; base_url, owner and repo are derived from it. Required to create." }, "label": { "type": [ "null", "string" ], "description": "runs-on label jobs route on. A new pool uses on-demand." }, "image_config": { "type": [ "null", "string" ], "description": "Runner image config override, the keys of .bitsmith/machine.yaml. The repository's machine.yaml (or the older runner.yaml) wins over it, then the built-in default. base_image must be Debian or Ubuntu." }, "image_config_ref": { "type": [ "null", "string" ], "description": "Git ref (branch or tag) to read .bitsmith/machine.yaml from (or the older runner.yaml). Empty reads the default branch; a ref with neither file fails the build." }, "cpu_cores": { "type": [ "null", "integer" ], "description": "vCPUs per runner. 0 means the default, 4.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": [ "null", "integer" ], "description": "Memory in MB per runner. 0 means the default, 4096.", "minimum": 0, "maximum": 4294967295 }, "disk_size_gb": { "type": [ "null", "integer" ], "description": "Root disk size in GB per runner. 0 means the default, 40.", "minimum": 0, "maximum": 4294967295 }, "max_runners": { "type": [ "null", "integer" ], "description": "Most runner VMs the pool may hold at once. 0 means the default, 8.", "minimum": 0, "maximum": 4294967295 }, "boots_per_tick": { "type": [ "null", "integer" ], "description": "Most runners the reconciler boots in one tick. 0 means the default, 3.", "minimum": 0, "maximum": 4294967295 }, "spare_disks": { "type": [ "null", "integer" ], "description": "Blank data disks attached to each runner (vdb onward).", "minimum": 0, "maximum": 4294967295 }, "spare_disk_size_gb": { "type": [ "null", "integer" ], "description": "Size in GB of each spare disk.", "minimum": 0, "maximum": 4294967295 }, "enabled": { "type": [ "null", "boolean" ], "description": "Whether the reconciler serves the pool. A new pool is off unless this is true." }, "placement": { "type": [ "null", "string" ], "description": "holder (only the server holding the pool boots runners) or cluster (it may boot runner VMs on the listed hosts). A new pool uses holder." }, "hosts": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "With placement cluster: server IDs allowed to host runner VMs. Empty means every active member." }, "api_token": { "type": [ "null", "string" ], "description": "Code-host API token: reads the queue and the runner list and mints runner records. Stored in the secret store, never returned; omit on update to keep the stored one." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}POST /api/v1/runner-pools/move Move the runner pools to another server, or take them over here.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to move the runner pools to, from list_servers. Omit to take them over on this server when the server that runs them is unreachable." } }, "additionalProperties": false}DELETE /api/v1/runner-pools/{pool_id} Delete a runner pool and reap its runner VMs.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/runner-pools/{pool_id} Get a runner pool.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}Sandboxes
Section titled “Sandboxes”9 endpoints · scopes sandbox.manage, sandbox.read
GET /api/v1/sandboxes List this token's sandboxes.
Arguments
{ "type": "object", "properties": { "labels": { "type": "object", "description": "Only return sandboxes carrying every one of these label key/value pairs.", "additionalProperties": { "type": "string" } }, "include_destroyed": { "type": "boolean", "description": "Include destroyed sandboxes, which are tombstones and hidden by default." }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/sandboxes Create a sandbox owned by this token.
Arguments
{ "type": "object", "properties": { "image_id": { "type": "string", "description": "ID of the VM image the sandbox boots from, such as debian-13-genericcloud-amd64." }, "name": { "type": "string", "description": "Name for the sandbox. A friendly two-word name when omitted." }, "seed_data": { "type": "string", "description": "Data written into the guest at /etc/bitsmith/seed before its first boot, for per-sandbox identity such as an enrollment token." }, "resources": { "type": [ "null", "object" ], "properties": { "cpu_cores": { "type": "integer", "description": "Virtual CPU cores. Host default applies when omitted.", "minimum": 0, "maximum": 4294967295 }, "memory_mb": { "type": "integer", "description": "Memory in MiB. Host default applies when omitted.", "minimum": 0, "maximum": 4294967295 }, "disk_gb": { "type": "integer", "description": "Disk size in GiB. Host default applies when omitted.", "minimum": 0, "maximum": 4294967295 } }, "description": "CPU, memory, and disk the sandbox is admitted with.", "additionalProperties": false }, "network_type": { "type": "string", "description": "Network the sandbox uses: \"guest\" for the private guest network or \"bridged\" for the LAN bridge. Omitted picks the guest network when it is on, otherwise the LAN bridge." }, "bridge": { "type": "string", "description": "Overrides the host default bridge for a bridged sandbox. Invalid with network_type \"guest\"." }, "labels": { "type": "object", "description": "Arbitrary key/value labels stored with the sandbox and matchable by list_sandboxes.", "additionalProperties": { "type": "string" } }, "idempotency_key": { "type": "string", "description": "Replaying a create with this same key returns the sandbox the first call made instead of a twin." }, "autostart": { "type": "boolean", "description": "Start the sandbox again when the host boots. Off by default: a throwaway sandbox should not outlive a reboot; a client's long-lived machine should." }, "network_stack": { "type": "string", "description": "IP families: dual_stack (default) or ipv6_only (no IPv4 lease; IPv4 hosts reached through CLAT and the server's NAT64 prefix, which must be set first)." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "image_id" ], "additionalProperties": false}GET /api/v1/sandboxes/capabilities Report IPv6-only availability and the default network stack for new sandboxes.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}GET /api/v1/sandboxes/images List images a sandbox can boot from.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/sandboxes/images/{image_id} Delete an image this token built.
Arguments
{ "type": "object", "properties": { "storage_id": { "type": "string", "description": "Storage pool to look in. Omitted: the pool that holds the image." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}DELETE /api/v1/sandboxes/{id} Destroy a sandbox.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "additionalProperties": false}GET /api/v1/sandboxes/{id} Get one of this token's sandboxes.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}POST /api/v1/sandboxes/{id}/actions Suspend or resume a sandbox.
Arguments
{ "type": "object", "properties": { "action": { "type": "string", "description": "suspend or resume." }, "server_id": { "type": "string", "description": "Server to run on (from list_servers)." } }, "required": [ "action" ], "additionalProperties": false}POST /api/v1/sandboxes/{id}/wait Wait until a sandbox is running.
Arguments
{ "type": "object", "properties": { "timeout_seconds": { "type": "integer", "description": "Maximum seconds to wait. Defaults to 120.", "minimum": 0, "maximum": 4294967295 }, "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}Storage
Section titled “Storage”1 endpoints · scopes storage.read
GET /api/v1/storage List storage pools and their health.
Arguments
{ "type": "object", "properties": { "server_id": { "type": "string", "description": "Only this server (from list_servers)." } }, "additionalProperties": false}