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.

128 endpoints across 8 domains.

Virtual machines

38 endpoints · scopes sandbox.manage, sandbox.read, vm.exec, vm.manage, vm.read

GET /api/v1/vms List virtual machines. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms Create a VM from an image or a captured template. vm.manage

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
    },
    "disk_size_gb": {
      "type": "integer",
      "description": "Target VM disk size in GiB. Server applies image minimum when omitted.",
      "minimum": 0,
      "maximum": 4294967295
    },
    "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."
    },
    "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 IP address, optionally with CIDR."
    },
    "gateway": {
      "type": "string",
      "description": "Static cloud-init gateway."
    },
    "autostart": {
      "type": "boolean",
      "description": "Start the VM on host boot."
    },
    "linked_clone": {
      "type": "boolean",
      "description": "Provision the disk as a copy-on-write overlay on the image instead of copying it. Creation becomes near-instant regardless of image size, but the image can no longer 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": "Skip clearing the source image's machine-id and SSH host keys. The seed is still written. This is not a speed option: creation takes about the same time either way, because the cost is the offline image pass that writes the seed, not the re-key. Use it when the VM's identity has to survive creation, which means the source VM of a warm state, or a guest image that re-keys itself on first boot. A VM re-keyed by neither side shares its source's identity and can register itself as its source, so leave it off otherwise."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name",
    "image_id"
  ],
  "additionalProperties": false
}

GET /api/v1/vms/images List VM images and templates stored on this server. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/images/catalog List VM images available for download. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/vms/images/{image_id} Delete a VM image or captured template. vm.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Storage pool holding the template. Empty means the system drive."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/images/{image_id}/move Move a VM image to another storage pool. vm.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "source_storage_id",
    "target_storage_id"
  ],
  "additionalProperties": false
}

GET /api/v1/vms/isos List installer ISOs stored on this server. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/isos/{iso_id}/move Move an installer ISO to another storage pool. vm.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "source_storage_id",
    "target_storage_id"
  ],
  "additionalProperties": false
}

GET /api/v1/vms/warm-states List saved VM warm states. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/warm-states/{id} Create a VM that resumes from a saved warm state. vm.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

DELETE /api/v1/vms/warm-states/{id} Delete a saved warm state. vm.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/capacity Report whether the host can run another VM. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/host-status Return VM host runtime checks. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/{id} Get a VM. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/vms/{id} Update a stopped VM's CPU and memory. vm.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/vms/{id} Delete a VM. vm.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/start Start a VM. vm.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/stop Shut a VM down, hard-stopping it if it ignores the graceful request. vm.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/suspend Suspend a VM: save its guest memory to disk and stop it. vm.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/resume Resume a suspended VM. vm.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/clone Clone a stopped VM's disk into a new VM. vm.manage

Arguments

{
  "type": "object",
  "properties": {
    "source_vmid": {
      "type": "integer",
      "description": "Numeric VM ID of the source virtual machine to clone."
    },
    "name": {
      "type": "string",
      "description": "Name for the cloned virtual machine."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "source_vmid",
    "name"
  ],
  "additionalProperties": false
}

POST /api/v1/vms/{id}/cloud-init Update a VM's cloud-init settings. vm.manage

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 IP address, optionally with CIDR. Empty clears it."
    },
    "gateway": {
      "type": [
        "null",
        "string"
      ],
      "description": "Static cloud-init gateway. Empty clears it."
    },
    "package_upgrade": {
      "type": [
        "null",
        "boolean"
      ],
      "description": "Run package upgrades during cloud-init."
    },
    "network_type": {
      "type": [
        "null",
        "string"
      ],
      "description": "Network type: bridged or none."
    },
    "network_bridge": {
      "type": [
        "null",
        "string"
      ],
      "description": "Bridge name when network_type is bridged."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/exec Run a shell command inside a VM through its guest agent. vm.exec destructive

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "command"
  ],
  "additionalProperties": false
}

POST /api/v1/vms/{id}/wait-ready Wait until a VM is running and reachable. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "timeout_seconds": {
      "type": "integer",
      "description": "Maximum seconds to wait. Defaults to 60."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/wait-ip Wait until a VM has an IP address. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "timeout_seconds": {
      "type": "integer",
      "description": "Maximum seconds to wait. Defaults to 60."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/{id}/connection Get SSH connection details for a VM. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/disks Attach a new empty disk to a VM. vm.manage

Arguments

{
  "type": "object",
  "properties": {
    "size_gb": {
      "type": "integer",
      "description": "Size of the new disk in GiB (must be \u003e= 1).",
      "minimum": 0,
      "maximum": 4294967295
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "size_gb"
  ],
  "additionalProperties": false
}

DELETE /api/v1/vms/{id}/disks/{disk_id} Detach and delete an additional disk from a VM. vm.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/vms/{id}/disks/{disk_id} Grow an additional disk on a VM. vm.manage

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "size_gb"
  ],
  "additionalProperties": false
}

POST /api/v1/vms/{id}/template Capture a VM's disk as a reusable template. vm.manage

Arguments

{
  "type": "object",
  "properties": {
    "template_name": {
      "type": "string",
      "description": "Optional name for the captured template image. Defaults to the VM name."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/vms/{id}/warm-states Save a running VM as a warm state. vm.manage

Arguments

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Label for the warm state. Defaults to the VM name when omitted."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/vms/{id}/docs Get the documentation stored for a VM. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PUT /api/v1/vms/{id}/docs Set or append to a VM's documentation. vm.manage

Arguments

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Markdown documentation content. Replaces the docs when append_entry is false; the text of one new entry when append_entry is true."
    },
    "append_entry": {
      "type": "boolean",
      "description": "Append content as a timestamped entry below the existing docs instead of replacing them."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "content"
  ],
  "additionalProperties": false
}

GET /api/v1/tasks List queued and running background tasks. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/tasks/{task_id} Get a background task. vm.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/tasks/{task_id}/logs Get the log lines a background task produced. vm.read read-only

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/templates Build a reusable VM template from a base image and a cloud-init script. vm.manage sandbox.manage

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, used verbatim. End it by powering the machine off: that is how the build says it is finished."
    },
    "labels": {
      "type": "object",
      "description": "Labels stored verbatim on the resulting image and returned by list_virtual_machine_images.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "base_image_id",
    "name"
  ],
  "additionalProperties": false
}

GET /api/v1/templates/{task_id} Report how a template build is going. vm.read sandbox.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

System

4 endpoints · scopes system.read

GET /api/v1/system/health Return host CPU, memory, and overall health. system.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/system/allocation Summarize CPU and memory allocation against host capacity. system.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/activity Search the activity log. system.read read-only

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."
    },
    "search": {
      "type": "string",
      "description": "Substring matched against the event summary and target label."
    },
    "since": {
      "type": "string",
      "description": "Only events at or after this RFC3339 timestamp."
    },
    "until": {
      "type": "string",
      "description": "Only events at or before this RFC3339 timestamp."
    },
    "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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/peers List the paired servers in the cluster. system.read read-only

Arguments

No arguments.

Apps

13 endpoints · scopes apps.manage, apps.read

GET /api/v1/apps List installed apps. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/apps Install an app. apps.manage

Arguments

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "Template ID to install from catalog."
    },
    "name": {
      "type": "string",
      "description": "Optional custom name for the app."
    },
    "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."
          },
          "mount_point_id": {
            "type": "string",
            "description": "Optional mount point ID."
          },
          "read_only": {
            "type": "boolean",
            "description": "Mount as read-only."
          }
        },
        "required": [
          "folder_id",
          "container_path"
        ],
        "additionalProperties": false
      },
      "description": "Folder mount assignments."
    },
    "compose_content": {
      "type": "string",
      "description": "Custom compose content (for custom apps)."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false
}

GET /api/v1/apps/templates List apps available to install. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/apps/discovered List unmanaged containers found on the host. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/apps/{app_id} Uninstall an app. apps.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/apps/{app_id}/actions Start, stop, or restart an app. apps.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "One of start, stop, or restart."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "action"
  ],
  "additionalProperties": false
}

GET /api/v1/apps/{app_id}/logs Get an app's container logs. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "tail": {
      "type": "integer",
      "description": "Number of trailing log lines to return. Defaults to the server default.",
      "minimum": 0,
      "maximum": 4294967295
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/apps/{app_id}/stats Get an app's resource usage. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/apps/{app_id}/compose Update an app's compose file. apps.manage

Arguments

{
  "type": "object",
  "properties": {
    "compose_content": {
      "type": "string",
      "description": "New compose YAML content."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "compose_content"
  ],
  "additionalProperties": false
}

PATCH /api/v1/apps/{app_id}/folders Update an app's folder mounts. apps.manage

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."
          },
          "mount_point_id": {
            "type": "string",
            "description": "Optional mount point ID."
          },
          "read_only": {
            "type": "boolean",
            "description": "Mount as read-only."
          }
        },
        "required": [
          "folder_id",
          "container_path"
        ],
        "additionalProperties": false
      },
      "description": "New folder assignments."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/apps/{app_id}/move Move an app's data to another storage pool. apps.manage

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Target storage pool ID."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "storage_id"
  ],
  "additionalProperties": false
}

GET /api/v1/apps/{app_id}/docs Get the documentation stored for an app. apps.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PUT /api/v1/apps/{app_id}/docs Set or append to an app's documentation. apps.manage

Arguments

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Markdown documentation content. Replaces the docs when append_entry is false; the text of one new entry when append_entry is true."
    },
    "append_entry": {
      "type": "boolean",
      "description": "Append content as a timestamped entry below the existing docs instead of replacing them."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "content"
  ],
  "additionalProperties": false
}

LXC containers

24 endpoints · scopes lxc.exec, lxc.manage, lxc.read

GET /api/v1/lxc List LXC containers. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc Create an LXC container from a template image. lxc.manage

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 ID for the container rootfs."
    },
    "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 IP address, optionally with CIDR."
    },
    "gateway": {
      "type": "string",
      "description": "Gateway IP address."
    },
    "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": "Provision the rootfs as a copy-on-write ZFS clone of the image's base dataset instead of a full extract. Requires storage_id to be a ZFS pool; near-instant create with a minimal footprint, 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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name",
    "template"
  ],
  "additionalProperties": false
}

GET /api/v1/lxc/images List cached LXC template images. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/lxc/images/catalog List LXC template images available for download. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/images/{image_id} Download an LXC template image into a storage pool. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Storage pool to download the image into. Defaults to the default cache storage."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/template Capture an LXC container's rootfs as a reusable template image. lxc.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/lxc/images/{image_id} Delete a cached LXC template image. lxc.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Storage pool where the image is cached."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "storage_id"
  ],
  "additionalProperties": false
}

POST /api/v1/lxc/images/{image_id}/move Move a cached LXC template image to another storage pool. lxc.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "source_storage_id",
    "target_storage_id"
  ],
  "additionalProperties": false
}

GET /api/v1/lxc/host-status Return LXC host runtime checks. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/lxc/{id} Get an LXC container. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/lxc/{id} Update an LXC container's name, CPU, memory, or network settings. lxc.manage

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": "boolean",
      "description": "Enable nested containers. 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, path traversal, or the 'bitsmith-lxc-' prefix; max 128 chars; spaces and uppercase allowed)."
    },
    "ip_address": {
      "type": [
        "null",
        "string"
      ],
      "description": "Static IP address, optionally with CIDR. Omit to keep current; pass an empty string to clear (revert to DHCP)."
    },
    "gateway": {
      "type": [
        "null",
        "string"
      ],
      "description": "Static gateway. Omit to keep current; pass an empty string to clear."
    },
    "dns_servers": {
      "type": [
        "null",
        "array"
      ],
      "items": {
        "type": "string"
      },
      "description": "DNS servers. Omit to keep current; pass an empty array to clear."
    },
    "network_type": {
      "type": "string",
      "description": "Network type (e.g. 'bridged', 'none')."
    },
    "network_bridge": {
      "type": "string",
      "description": "Bridge name for bridged containers. Empty uses the global default."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/lxc/{id} Delete an LXC container. lxc.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/start Start an LXC container. lxc.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/stop Stop an LXC container. lxc.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/restart Restart an LXC container. lxc.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/freeze Freeze an LXC container, pausing all its processes. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/unfreeze Unfreeze a frozen LXC container. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/clone Clone an LXC container to a new name. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "source_lxcid": {
      "type": "integer",
      "description": "Numeric LXC ID of the source container to clone."
    },
    "name": {
      "type": "string",
      "description": "Name for the cloned LXC container."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "source_lxcid",
    "name"
  ],
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/exec Run a shell command inside an LXC container. lxc.exec destructive

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "command"
  ],
  "additionalProperties": false
}

GET /api/v1/lxc/{id}/stats Get an LXC container's resource usage. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/lxc/{id}/disk Set an LXC container's disk limit. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "disk_size_bytes": {
      "type": "integer",
      "description": "Maximum disk usage in bytes. Zero removes the limit.",
      "minimum": 0
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "disk_size_bytes"
  ],
  "additionalProperties": false
}

POST /api/v1/lxc/{id}/move Move an LXC container's rootfs to another storage pool. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Target storage pool to move the container rootfs into."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "storage_id"
  ],
  "additionalProperties": false
}

GET /api/v1/lxc/{id}/docs Get the documentation stored for an LXC container. lxc.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PUT /api/v1/lxc/{id}/docs Set or append to an LXC container's documentation. lxc.manage

Arguments

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Markdown documentation content. Replaces the docs when append_entry is false; the text of one new entry when append_entry is true."
    },
    "append_entry": {
      "type": "boolean",
      "description": "Append content as a timestamped entry below the existing docs instead of replacing them."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "content"
  ],
  "additionalProperties": false
}

Files and folders

12 endpoints · scopes files.manage, files.read

GET /api/v1/folders List managed folders. files.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/folders Create a folder in a storage pool. files.manage

Arguments

{
  "type": "object",
  "properties": {
    "storage_id": {
      "type": "string",
      "description": "Storage pool ID."
    },
    "name": {
      "type": "string",
      "description": "Folder name."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "storage_id",
    "name"
  ],
  "additionalProperties": false
}

PATCH /api/v1/folders/{folder_id} Rename a folder. files.manage

Arguments

{
  "type": "object",
  "properties": {
    "new_name": {
      "type": "string",
      "description": "New folder name."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "new_name"
  ],
  "additionalProperties": false
}

DELETE /api/v1/folders/{folder_id} Delete a folder. files.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/folders/{folder_id}/contents List the entries at a path. files.read read-only

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/folders/{folder_id}/subfolders Create a subfolder. files.manage

Arguments

{
  "type": "object",
  "properties": {
    "sub_path": {
      "type": "string",
      "description": "Sub-path within the folder."
    },
    "name": {
      "type": "string",
      "description": "Subfolder name."
    },
    "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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

POST /api/v1/folders/{folder_id}/subfolders/batch Create several subfolders at once. files.manage

Arguments

{
  "type": "object",
  "properties": {
    "sub_path": {
      "type": "string",
      "description": "Sub-path within the folder."
    },
    "names": {
      "type": [
        "null",
        "array"
      ],
      "items": {
        "type": "string"
      },
      "description": "Folder names to create."
    },
    "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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "names"
  ],
  "additionalProperties": false
}

PATCH /api/v1/folders/{folder_id}/entries/{src_sub_path} Move or rename a file or folder. files.manage

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/folders/{src_folder_id}/entries/{src_sub_path}/copy Copy a file or folder. files.manage

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/folders/{folder_id}/entries/{sub_path} Delete a file or folder. files.manage destructive

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/folders/{folder_id}/search Search files and folders by name. files.read read-only

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
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "pattern"
  ],
  "additionalProperties": false
}

POST /api/v1/folders/{folder_id}/entries/batch Move several files or folders at once. files.manage destructive

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}. Overrides folder_id when set.",
      "required": [
        "kind",
        "id"
      ],
      "additionalProperties": false
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "moves"
  ],
  "additionalProperties": false
}

Connected storage

7 endpoints · scopes connections.manage, connections.read

GET /api/v1/locations List connected network shares. connections.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/locations Connect a network share and mount it. connections.manage

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name",
    "remote"
  ],
  "additionalProperties": false
}

POST /api/v1/locations/discover Discover SMB hosts on the network, or list one host's shares. connections.read read-only

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/locations/{location_id} Get a connected location. connections.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/locations/{location_id}/disconnect Unmount a connected location. connections.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/locations/{location_id}/reconnect Mount a connected location again. connections.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/locations/{location_id} Remove a connected location and its stored credentials. connections.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

Reverse proxy

22 endpoints · scopes proxy.manage, proxy.read

GET /api/v1/proxy/config Get the reverse proxy configuration. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PATCH /api/v1/proxy Enable or disable the reverse proxy. proxy.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether the reverse proxy should be enabled."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}

POST /api/v1/proxy/move Move the reverse proxy to another cluster node. proxy.manage

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Peer to make the cluster proxy holder. Omit to take over the proxy on this node when the recorded holder is unreachable."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/upstreams List targets the proxy can route to. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/providers List the DNS providers supported for public certificates. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/host-status Return reverse proxy host status. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PUT /api/v1/proxy/acme/credentials Store DNS provider credentials for public certificates. proxy.manage idempotent

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"
      }
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "provider",
    "credentials"
  ],
  "additionalProperties": false
}

PUT /api/v1/proxy/acme/config Set the ACME account email and directory URL. proxy.manage idempotent

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)."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

PUT /api/v1/proxy/vip Set the reverse proxy's floating addresses. proxy.manage idempotent

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)."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

PUT /api/v1/proxy/dns Set the DNS resolvers the built-in responder forwards to. proxy.manage idempotent

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "dns_upstreams"
  ],
  "additionalProperties": false
}

PATCH /api/v1/proxy/http3 Turn HTTP/3 serving on or off. proxy.manage idempotent

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)."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}

GET /api/v1/proxy/certs Get TLS certificate status per base domain. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/diagnostics Collect reverse proxy diagnostics from the cluster node holding the proxy. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/incidents List captured reverse proxy incident bundles. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/proxy/incidents/{incident_id} Get one captured incident bundle. proxy.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/proxy/domains Add a base domain the proxy serves. proxy.manage

Arguments

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Base domain the proxy serves (e.g. bitsmith.home.arpa)."
    },
    "cert_source": {
      "type": "string",
      "description": "Certificate source for the domain: \"internal\" for the internal CA, or a DNS provider name (e.g. cloudflare) for a public ACME cert."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "name",
    "cert_source"
  ],
  "additionalProperties": false
}

PATCH /api/v1/proxy/domains/{domain} Rename a base domain or change its certificate source. proxy.manage

Arguments

{
  "type": "object",
  "properties": {
    "new_name": {
      "type": "string",
      "description": "New base domain name."
    },
    "cert_source": {
      "type": "string",
      "description": "Certificate source for the domain: \"internal\" or a DNS provider name (e.g. cloudflare)."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "new_name",
    "cert_source"
  ],
  "additionalProperties": false
}

DELETE /api/v1/proxy/domains/{domain} Remove a base domain. proxy.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/proxy/domains/{domain}/entries Map a subdomain to an upstream host and port. proxy.manage

Arguments

{
  "type": "object",
  "properties": {
    "subdomain": {
      "type": "string",
      "description": "Subdomain of the proxy entry (the left-most label of the proxied hostname)."
    },
    "host": {
      "type": "string",
      "description": "Upstream IP or hostname to forward to. Required when no target_id is set."
    },
    "port": {
      "type": "integer",
      "description": "Upstream host port to forward to (1-65535)."
    },
    "listen_port": {
      "type": "integer",
      "description": "VIP/listen port the entry serves on; 0/omitted = default 443. Two entries may share a subdomain only on different listen ports."
    },
    "target_id": {
      "type": "string",
      "description": "Optional app, VM, or LXC target to link the entry to."
    },
    "upstream_scheme": {
      "type": "string",
      "description": "Explicit upstream scheme. \"http\", \"https\", or empty (omit) to auto-detect from the port (443 -\u003e https, else http)."
    },
    "tls_skip_verify": {
      "type": [
        "null",
        "boolean"
      ],
      "description": "Optional. When omitted, legacy auto-detection applies (skips verify on port 443); when set, it is authoritative. Only emitted when the effective upstream scheme is https. Must be true/false/omitted."
    },
    "header_up": {
      "type": "object",
      "description": "Optional. Map of upstream header overrides. Keys must be valid HTTP tokens (RFC 7230). Values are passed through as Caddyfile tokens, so Caddy placeholders like {host} or {remote_host} work at request time. Empty string values clear a header.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "subdomain",
    "port"
  ],
  "additionalProperties": false
}

PATCH /api/v1/proxy/domains/{domain}/entries/{subdomain} Update a reverse proxy entry. proxy.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "listen_port": {
      "type": "integer",
      "description": "Current VIP/listen port of the entry; 0/omitted = default 443."
    },
    "new_domain": {
      "type": "string",
      "description": "New base domain (must be a configured domain); omitted keeps the current one."
    },
    "new_subdomain": {
      "type": "string",
      "description": "New subdomain for the entry; omitted keeps the current one."
    },
    "new_listen_port": {
      "type": "integer",
      "description": "New VIP/listen port the entry serves on; 0/omitted keeps the current one."
    },
    "host": {
      "type": "string",
      "description": "Upstream IP or hostname to forward to. Required when no target_id is set."
    },
    "port": {
      "type": "integer",
      "description": "Upstream host port to forward to (1-65535)."
    },
    "target_id": {
      "type": "string",
      "description": "Optional app, VM, or LXC target to link the entry to."
    },
    "upstream_scheme": {
      "type": "string",
      "description": "Explicit upstream scheme. \"http\", \"https\", or empty (omit) to auto-detect from the port (443 -\u003e https, else http)."
    },
    "tls_skip_verify": {
      "type": [
        "null",
        "boolean"
      ],
      "description": "Optional. When omitted, legacy auto-detection applies (skips verify on port 443); when set, it is authoritative. Only emitted when the effective upstream scheme is https. Must be true/false/omitted."
    },
    "header_up": {
      "type": "object",
      "description": "Optional. Map of upstream header overrides. Keys must be valid HTTP tokens (RFC 7230). Values are passed through as Caddyfile tokens, so Caddy placeholders like {host} or {remote_host} work at request time. Empty string values clear a header.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false
}

DELETE /api/v1/proxy/domains/{domain}/entries/{subdomain} Delete a reverse proxy entry. proxy.manage destructive

Arguments

{
  "type": "object",
  "properties": {
    "listen_port": {
      "type": "integer",
      "description": "VIP/listen port of the proxy entry to delete; 0/omitted = default 443."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/proxy/domains/{domain}/certs/renew Force a TLS certificate renewal for a base domain. proxy.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

Sandboxes

8 endpoints · scopes sandbox.manage, sandbox.read

GET /api/v1/sandboxes List this token's sandboxes. sandbox.read read-only

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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/sandboxes Create a sandbox owned by this token. sandbox.manage

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
    },
    "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."
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "required": [
    "image_id"
  ],
  "additionalProperties": false
}

GET /api/v1/sandboxes/images List images a sandbox can boot from. sandbox.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

GET /api/v1/sandboxes/{id} Get one of this token's sandboxes. sandbox.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/sandboxes/{id}/suspend Suspend a sandbox. sandbox.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/sandboxes/{id}/resume Resume a suspended sandbox. sandbox.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

DELETE /api/v1/sandboxes/{id} Destroy a sandbox. sandbox.manage idempotent

Arguments

{
  "type": "object",
  "properties": {
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}

POST /api/v1/sandboxes/{id}/wait Wait until a sandbox is running. sandbox.read read-only

Arguments

{
  "type": "object",
  "properties": {
    "timeout_seconds": {
      "type": "integer",
      "description": "Maximum seconds to wait. Defaults to 120.",
      "minimum": 0,
      "maximum": 4294967295
    },
    "peer_id": {
      "type": "string",
      "description": "Optional. Run this tool on the paired server with this peer_id instead of on this server; discover ids with list_peers. Background tasks a forwarded call starts live on that server too, so pass the same peer_id to get_background_task."
    }
  },
  "additionalProperties": false
}