Webspace API: SSH, commands and files
Run commands, manage SSH keys and work with the files of your webspace over SFTP through the Sitequest REST API.
Run commands, manage SSH keys and work with the files of your webspace over SFTP through the Sitequest REST API.
Run a one-shot shell command as the webspace's unprivileged system user (ws_<slug>). Working directory is ~/. Cgroup limits apply.
Required scope: webspace:exec
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
command |
Yes | Shell command (max 8192 chars). |
timeout |
No | Timeout in seconds (1–300, default 60). |
{
"data": {
"exitCode": 0,
"stdout": "Linux node-bf015 6.6.20-cloud-amd64 ...\n",
"stderr": "",
"durationMs": 142,
"truncated": false
}
}
| Field | Type | Description |
|---|---|---|
truncated |
boolean | true if stdout was capped at 32 MB or stderr at 256 KB. |
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_COMMAND |
command is missing or not a string. |
| 400 | COMMAND_TOO_LONG |
Command exceeds 8192 characters. |
| 408 | COMMAND_TIMEOUT |
Command exceeded the requested timeout. |
| 502 | SSH_CONN_ERROR |
Could not connect to the webspace node. |
curl -X POST https://site.quest/api/v1/webspaces/69e80ac1.../exec \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "command": "ls -la public_html", "timeout": 10 }'
This action is also available via the webspace_exec MCP tool.
List SSH public keys installed in this webspace's ~/.ssh/authorized_keys. Includes the panel-managed web-terminal key.
Required scope: webspace:read
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
{
"data": [
{
"id": "sha256-hQ0YFLi6TKgF3E9pn-lcUxVLx1VjSQwc",
"type": "ssh-ed25519",
"publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...",
"comment": "root@node-bf015.sitequest.eu"
}
]
}
| Field | Type | Description |
|---|---|---|
id |
string | SHA-256 fingerprint (URL-safe). Used as the keyId in the delete endpoint. |
curl https://site.quest/api/v1/webspaces/69e80ac1.../ssh-keys \
-H "Authorization: Bearer sq_live_..."
This action is also available via the webspace_list_ssh_keys MCP tool.
Append an SSH public key to this webspace's authorized_keys. Supports ssh-ed25519, ssh-rsa, and ecdsa-*.
Required scope: webspace:exec
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
publicKey |
Yes | Full public-key line (ssh-ed25519 AAA…). |
comment |
No | Optional label (defaults to the comment in the key line). |
{
"data": {
"id": "sha256-hQ0YFLi6TKgF...",
"type": "ssh-ed25519",
"publicKey": "ssh-ed25519 AAAA...",
"comment": "my-laptop"
}
}
| Status | Code | Description |
|---|---|---|
| 400 | MISSING_PUBLIC_KEY |
publicKey is missing. |
| 400 | INVALID_PUBLIC_KEY |
Public key could not be parsed. |
curl -X POST https://site.quest/api/v1/webspaces/69e80ac1.../ssh-keys \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "publicKey": "ssh-ed25519 AAAA... my-laptop", "comment": "my-laptop" }'
This action is also available via the webspace_add_ssh_key MCP tool.
Remove an SSH key by its fingerprint id. The web-terminal key cannot be deleted.
Required scope: webspace:manage
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
{ "data": { "id": "sha256-hQ0YFLi6TKgF...", "deleted": true } }
| Status | Code | Description |
|---|---|---|
| 404 | KEY_NOT_FOUND |
Key id is not present in authorized_keys. |
curl -X DELETE https://site.quest/api/v1/webspaces/69e80ac1.../ssh-keys/sha256-hQ0... \
-H "Authorization: Bearer sq_live_..."
This action is also available via the webspace_delete_ssh_key MCP tool.
List directory contents under the webspace home (~/). All paths are validated against the jail root.
Required scope: webspace:files
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/ (e.g. /home/ws_xxx/public_html). |
{
"data": {
"path": "/home/ws_0862c/public_html",
"entries": [
{ "name": "index.html", "isDirectory": false, "size": 256, "modifiedAt": "2026-04-22T12:34:56+0000" },
{ "name": "assets", "isDirectory": true, "size": 4096, "modifiedAt": "2026-04-22T12:30:00+0000" }
]
}
}
| Status | Code | Description |
|---|---|---|
| 400 | PATH_OUTSIDE_JAIL |
Path escapes the webspace home. |
curl "https://site.quest/api/v1/webspaces/69e80ac1.../sftp/list?path=/home/ws_0862c/public_html" \
-H "Authorization: Bearer sq_live_..."
This action is also available via the webspace_list_files MCP tool.
Read a file's content from the webspace home. Max 32 MB.
Required scope: webspace:files
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/. |
encoding |
No | utf8 (default) or base64. |
{
"data": {
"path": "/home/ws_0862c/public_html/index.html",
"content": "<!doctype html><html>...</html>",
"encoding": "utf8",
"size": 256
}
}
| Status | Code | Description |
|---|---|---|
| 404 | FILE_NOT_FOUND |
File does not exist. |
| 413 | FILE_TOO_LARGE |
File exceeds 32 MB. |
curl "https://site.quest/api/v1/webspaces/69e80ac1.../sftp/read?path=/home/ws_0862c/public_html/index.html" \
-H "Authorization: Bearer sq_live_..."
This action is also available via the webspace_read_file MCP tool.
Write content to a file in the webspace home. Creates parent directories as needed. Max 32 MB.
Required scope: webspace:exec
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/. |
content |
Yes | File content (string). |
encoding |
No | utf8 (default) or base64. |
{ "data": { "path": "/home/ws_0862c/public_html/index.html", "size": 256 } }
| Status | Code | Description |
|---|---|---|
| 400 | MISSING_CONTENT |
content is missing or not a string. |
| 413 | CONTENT_TOO_LARGE |
Content exceeds 32 MB. |
curl -X PUT https://site.quest/api/v1/webspaces/69e80ac1.../sftp/write \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "path": "/home/ws_0862c/public_html/hello.txt", "content": "Hello World!" }'
This action is also available via the webspace_write_file MCP tool.
Delete a file or directory inside the webspace home. The home dir itself cannot be deleted.
Required scope: webspace:manage
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/. |
recursive |
No | If true, delete directories recursively (rm -rf). |
{ "data": { "path": "/home/ws_0862c/old", "deleted": true, "recursive": true } }
| Status | Code | Description |
|---|---|---|
| 403 | HOME_DIR_PROTECTED |
Cannot delete the webspace home directory. |
curl -X DELETE https://site.quest/api/v1/webspaces/69e80ac1.../sftp/delete \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "path": "/home/ws_0862c/old", "recursive": true }'
This action is also available via the webspace_delete_path MCP tool.
Rename or move a file/directory inside the webspace home. Both from and to must be inside ~/.
Required scope: webspace:exec
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
from |
Yes | Source path. |
to |
Yes | Destination path. |
{ "data": { "from": "/home/ws_0862c/a.txt", "to": "/home/ws_0862c/b.txt", "renamed": true } }
curl -X POST https://site.quest/api/v1/webspaces/69e80ac1.../sftp/rename \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "from": "/home/ws_0862c/a.txt", "to": "/home/ws_0862c/b.txt" }'
This action is also available via the webspace_rename MCP tool.
Create a directory inside the webspace home.
Required scope: webspace:manage
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/. |
recursive |
No | Default true (mkdir -p). Set to false to fail when parents are missing. |
{ "data": { "path": "/home/ws_0862c/uploads", "created": true, "recursive": true } }
curl -X POST https://site.quest/api/v1/webspaces/69e80ac1.../sftp/mkdir \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "path": "/home/ws_0862c/uploads" }'
This action is also available via the webspace_mkdir MCP tool.
Change permissions on a file or directory inside the webspace home.
Required scope: webspace:exec
| Header | Required | Value |
|---|---|---|
Authorization |
Yes | Bearer YOUR_API_KEY |
Content-Type |
Yes | application/json |
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Absolute path inside ~/. |
mode |
Yes | Octal string ("0755") or decimal int (0–4095). |
{ "data": { "path": "/home/ws_0862c/public_html/index.php", "mode": "0644" } }
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_MODE |
mode is not a valid octal string or decimal int. |
curl -X POST https://site.quest/api/v1/webspaces/69e80ac1.../sftp/chmod \
-H "Authorization: Bearer sq_live_..." \
-H "Content-Type: application/json" \
-d '{ "path": "/home/ws_0862c/public_html/index.php", "mode": "0644" }'
This action is also available via the webspace_chmod MCP tool.