Download OpenAPI specification:Download
Cloudron provides a RESTful API to manage apps, users, groups, domains and other resources.
All of the functionality in the Cloudron Dashboard is available through the API, allowing you to script complex actions.
If you are an app developer, the Cloudron CLI tool implements a workflow that allows you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.
The API follows standard HTTP REST API conventions.
Method | Usage |
---|---|
GET | Retrieveal operations |
DELETE | Destroys a resource |
POST | Create new objects or start a new task. Also used to update parts of a resource |
PUT | Idempotent operation that replaces a resource |
PATCH | API does not support PATCH |
HEAD | Read response headers and get no response |
The API follows standard HTTP REST API response conventions.
2xx responses indicate success. 4xx responses indicate request errors. 5xx responses indicate server errors.
Name | Description |
---|---|
200 | Success. Operation succeeded, response body contains more information |
204 | Success. Operation succeeded, empty response body |
401 | Access Denied. Usually caused by missing, invalid or expired token |
403 | Forbidden. Authenticated but operation not permitted. Usually caused by insufficient role/permissions |
5xx | Internal Server error |
When listing objects, query parameters page
and per_page
can be passed in. Note that these parameters have index
starting from 1.
To use the REST API, you must first create an API token. This token can be provided in two ways:
?access_token=<token>
Bearer <token>
API Tokens can be created as Readonly
or Read and Write
. With Readonly
token, only GET operations can be performed.
We use curl
to demonstrate how to use the API. The Cloudron Dashboard Domain and the API Token are variable fields.
You can export them in your shell as follows:
export CLOUDRON_DOMAIN=my.domain.com
export CLOUDRON_TOKEN=your_token_here
To list the domains using cURL and the Authorization
header:
curl -H 'ContentType: application/json' -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/domains
Alternately, to use the query parameter:
curl -H 'ContentType: application/json' "https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN"
To use the Bearer Authentication, you must first create an API token.
The API Token can be passed via the Authorization header Bearer <token>
:
curl -H 'ContentType: application/json' -H 'Authorization: Bearer $CLOUDRON_TOKEN' https://$CLOUDRON_DOMAIN/api/v1/domains
bearer
To use the Query Parameter Authentication, you must first create an API token.
The API Token can be passed via the access_token
query parameter:
curl -H 'ContentType: application/json' 'https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN'
access_token
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps"
{- "apps": [
- {
- "id": "cd98991f-1327-48de-a8e2-6t521e865ebc",
- "appStoreId": "",
- "installationState": "installed",
- "error": null,
- "runState": "running",
- "health": "healthy",
- "taskId": "177",
- "accessRestriction": null,
- "checklist": [
- { }
], - "secondaryDomains": [
- "your.secondary.domains.com"
], - "redirectDomains": [
- "your.redirect.domains.com"
], - "aliasDomains": [
- "your.alias.domains.com"
], - "sso": true,
- "subdomain": "test",
- "domain": "cloudron.io",
- "fqdn": "test.cloudron.io",
- "certificate": null,
- "manifest": { },
- "ports": { },
- "iconUrl": "/api/v1/21g3jh-321321k3-3213jh-423hjk234/icon",
- "creationTime": "2024-05-05T11:21:12.000Z",
- "ts": "2024-06-03T11:15:15.000Z",
- "tags": [
- "dev",
- "dev",
- "dev"
], - "label": "Office",
- "notes": { },
- "enableBackup": true,
- "upstreamUri": "upstream.uri.de",
- "accessLevel": "admin"
}
]
}
Get app information.
appId required | string App ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}"
{- "id": "cd98991f-1327-48de-a8e2-6t521e865ebc",
- "appStoreId": "",
- "installationState": "installed",
- "error": null,
- "runState": "running",
- "health": "healthy",
- "taskId": "177",
- "subdomain": "test",
- "domain": "cloudron.io",
- "fqdn": "test.cloudron.io",
- "certificate": null,
- "crontab": "*/15 * * * *",
- "upstreamUri": "upstream.uri.de",
- "accessRestriction": null,
- "manifest": { },
- "ports": { },
- "iconUrl": "/api/v1/21g3jh-321321k3-3213jh-423hjk234/icon",
- "memoryLimit": 123432345,
- "cpuQuota": 100,
- "operators": {
- "users": [
- "uid-15634b8e-28d4-412a-a46f-e7d0c17sdfdsc",
- "uid-15634b8e-28d4-412a-a46f-e7d0c17svcx32c"
], - "groups": [
- "gid-15634b8e-28d4-412a-a46f-e7d0c17sdfdsc",
- "gid-15634b8e-28d4-412a-a46f-e7d0c17svcx32c"
]
}, - "sso": true,
- "debugMode": {
- "readonlyRootfs": false,
- "cmd": [
- "/bin/bash",
- "-c",
- "echo \"Repair mode. [...]"
]
}, - "reverseProxyConfig": { },
- "enableBackup": true,
- "creationTime": "2024-05-05T11:21:12.000Z",
- "updateTime": "2024-05-05T11:21:12.000Z",
- "ts": "2024-06-03T11:15:15.000Z",
- "tags": [
- "dev",
- "dev",
- "dev"
], - "label": "Office",
- "notes": { },
- "secondaryDomains": [
- "your.secondary.domains.com"
], - "redirectDomains": [
- "your.redirect.domains.com"
], - "aliasDomains": [
- "your.alias.domains.com"
], - "env": { },
- "enableAutomaticUpdate": false,
- "storageVolumeId": null,
- "storageVolumePrefix": null,
- "mounts": [
- "ext4"
], - "enableTurn": 1,
- "enableRedis": 1,
- "checklist": { },
- "enableMailbox": true,
- "mailboxDisplayName": "",
- "mailboxName": "wiki.app",
- "mailboxDomain": "your.domain.com",
- "enableInbox": false,
- "inboxName": null,
- "inboxDomain": null,
- "accessLevel": "Admin"
}
Get app icon.
appId required | string App ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}/icon"
{- "icon": "< base64 encoded image >"
}
Uninstal an app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}/uninstall"
{- "taskId": 295
}
'Owner' role is required to repair app with docker addon.
appId required | string App ID |
manifest | object (manifest) Find more about the manifest specification in our knowledgebase. |
dockerImage | string Dockerimage. |
{- "manifest": { },
- "dockerImage": "Your_Dockerimage"
}
{- "taskId": 295
}
Check for availabe updates for the app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/check_for_updates"
{- "updates": { }
}
Update app.
appId required | string App ID |
manifest required | object (manifest) Find more about the manifest specification in our knowledgebase. |
appStoreId required | string (appStoreId) The identifier of the application in the app store. |
skipBackup | boolean Enable or disable a backup before the app will be updated. |
force | boolean Enable or disable if the update should be forced. |
{- "manifest": { },
- "appStoreId": "",
- "skipBackup": true,
- "force": true
}
{- "taskId": 295
}
Restore an app from backup.
appId required | string App ID |
backupId required | string ID of the backup used for the restore. |
{- "backupId": "app_v2.2.2_ff231fee"
}
{- "taskId": 295
}
Import an app.
appId required | string App ID |
remotePath | string The path or identifier of the backup used for restoring the app. |
backupFormat | string The format of the backup file. This indicates the structure or encoding used for the backup. |
object Configuration settings for the backup provider used during import. |
{- "remotePath": "app_v2.2.2_ff231fee",
- "backupFormat": "tar.gz",
- "backupConfig": {
- "provider": "aws-s3",
- "password": "my_secure_password",
- "encryptedFilenames": true
}
}
{- "taskId": 295
}
Export an app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/export"
{- "taskId": 295
}
Start an app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/start"
{- "taskId": 295
}
Stop an app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/stop"
{- "taskId": 295
}
Restart an app.
appId required | string App ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/restart"
{- "taskId": 295
}
Get app logs. Use this endpoint to stream logs (tail -f
style). If you want to download logs, use the logs endpoint instead. This endpoint implements Server Side Events. Use the EventSource interface to parse the returned stream.
appId required | string App ID |
lines | number Last lines displayed. |
format | string Default: "json" Enum: "json" "short" Defines the format of the logs. |
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Download app logs.
appId required | string App ID |
lines | number Last lines displayed. |
format | string Default: "json" Enum: "json" "short" Defines the format of the logs. |
curl -v \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/logs/$UNIT/?lines=10&format=json"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
List app eventlogs. There are different kind of eventlogs, each type has it's own properties.
appId required | string App ID |
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
search | string Filter by users which match either username, email, displayName |
since | integer >= 1 Default: 1 Filter by active or not active users. If not provided any state matches. |
types | string Types of eventlogs. Can be seperated by ",". |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/eventlog"
{- "eventlogs": [
- {
- "id": "1234567890",
- "action": "App Deployment",
- "creationTime": "2024-06-06T12:30:45Z",
- "source": {
- "username": "john_doe",
- "userId": "987654321",
- "ip": "192.168.1.100"
}, - "data": {
- "app": {
- "id": "cd98991f-1327-48de-a8e2-6t521e865ebc",
- "appStoreId": "",
- "installationState": "installed",
- "error": null,
- "runState": "running",
- "health": "healthy",
- "taskId": "177",
- "subdomain": "test",
- "domain": "cloudron.io",
- "fqdn": "test.cloudron.io",
- "certificate": null,
- "crontab": "*/15 * * * *",
- "upstreamUri": "upstream.uri.de",
- "accessRestriction": null,
- "manifest": { },
- "ports": { },
- "iconUrl": "/api/v1/21g3jh-321321k3-3213jh-423hjk234/icon",
- "memoryLimit": 123432345,
- "cpuQuota": 100,
- "operators": {
- "users": [
- "uid-15634b8e-28d4-412a-a46f-e7d0c17sdfdsc",
- "uid-15634b8e-28d4-412a-a46f-e7d0c17svcx32c"
], - "groups": [
- "gid-15634b8e-28d4-412a-a46f-e7d0c17sdfdsc",
- "gid-15634b8e-28d4-412a-a46f-e7d0c17svcx32c"
]
}, - "sso": true,
- "debugMode": {
- "readonlyRootfs": false,
- "cmd": [
- "/bin/bash",
- "-c",
- "echo \"Repair mode. [...]"
]
}, - "reverseProxyConfig": { },
- "enableBackup": true,
- "creationTime": "2024-05-05T11:21:12.000Z",
- "updateTime": "2024-05-05T11:21:12.000Z",
- "ts": "2024-06-03T11:15:15.000Z",
- "tags": [
- "dev",
- "dev",
- "dev"
], - "label": "Office",
- "notes": { },
- "secondaryDomains": [
- "your.secondary.domains.com"
], - "redirectDomains": [
- "your.redirect.domains.com"
], - "aliasDomains": [
- "your.alias.domains.com"
], - "env": { },
- "enableAutomaticUpdate": false,
- "storageVolumeId": null,
- "storageVolumePrefix": null,
- "mounts": [
- "ext4"
], - "enableTurn": 1,
- "enableRedis": 1,
- "checklist": { },
- "enableMailbox": true,
- "mailboxDisplayName": "",
- "mailboxName": "wiki.app",
- "mailboxDomain": "your.domain.com",
- "enableInbox": false,
- "inboxName": null,
- "inboxDomain": null,
- "accessLevel": "Admin"
}
}, - "appId": "d342-ef54003-dsads332-4322ds34ddff0\"",
- "taskId": 295
}
]
}
Get tasks of an app.
appId required | string App ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/task"
{- "id": "707",
- "type": "app",
- "percent": 20,
- "message": "Stopping container",
- "creationTime": "2024-06-06T10:07:17.000Z",
- "ts": "2024-06-06T10:07:18.000Z",
- "args": [
- [
- "dd7630af-2038-48de-af69-1ce020ffd294"
]
], - "result": "success",
- "error": "Failed to stop container",
- "active": true,
- "success": false,
- "pending": false
}
Clone an app.
appId required | string App ID |
backupId required | string ID of the backup used for the restore. |
subdomain required | string The subdomain on which the application runs. |
domain required | string The main domain on which the application runs. |
ports | object Object containing port bindings information. |
overwriteDns | boolean Indicates whether DNS settings should be overwritten. |
skipDnsSetup | boolean Indicates whether DNS setup should be skipped. |
{- "backupId": "app_v2.2.2_ff231fee",
- "subdomain": "test",
- "domain": "cloudron.io",
- "ports": { },
- "overwriteDns": false,
- "skipDnsSetup": true
}
{- "id": "c5a5db16-30c4-4202-bfdd-f5bdad6297888",
- "taskId": 295
}
Create app exec.
appId required | string App ID |
cmd | Array of strings Array of command strings to be executed in sequence. |
tty | boolean Indicates whether a TTY should be allocated. |
lang | string Language setting for the environment. |
{- "cmd": [
- "/bin/bash"
], - "tty": true,
- "lang": "en_US.UTF-8"
}
{- "id": "c5a5db16-30c4-4202-bfdd-f5bdad6297888"
}
Configure who will be able to access the app.
appId required | string App ID |
object |
{- "accessRestriction": {
- "users": [
- "uid-321dsa..."
], - "groups": [
- "gid-321dsa..."
]
}
}
{ }
Set who can access and also configure the app.
appId required | string App ID |
object |
{- "accessRestriction": {
- "users": [
- "uid-321dsa..."
], - "groups": [
- "gid-321dsa..."
]
}
}
{ }
Set app label.
appId required | string App ID |
label | null or string (label) A custom label for the application. |
{- "label": "Office"
}
{ }
Set app tags.
appId required | string App ID |
tags | Array of strings (tags) Tags for categorizing and filtering the application. |
{- "tags": [
- "dev",
- "dev",
- "dev"
]
}
{ }
Set app icon.
appId required | string App ID |
icon | string or null Base-64 encoded image string. An empty string means null. |
{- "icon": "Base-64 encoded image string."
}
{ }
Set app notes.
appId required | string App ID |
notes | string or null Notes shown in the app configs. |
{- "notes": "Used for office purposes."
}
{ }
Set the memory limit of an app.
appId required | string App ID |
memoryLimit | number (memoryLimit) The memory limit for the app in bytes. |
{- "memoryLimit": 123432345
}
{- "taskId": 295
}
Set the memory limit of an app.
appId required | string App ID |
cpuQuota | number (cpuQuota) The CPU quota for the app, expressed as a percentage. |
{- "cpuQuota": 100
}
{- "taskId": 295
}
Set whether the app should have automatic backups or not.
appId required | string App ID |
enable | boolean Enable for automatic backups of the app, disable if manual backups are preferred. |
{- "enable": true
}
{ }
Set whether the app should automatically update to newer available versions.
appId required | string App ID |
enable | boolean Enable for automatic updates of the app, disable if manual updates are preferred. |
{- "enable": true
}
{ }
Set up configs like the 'robots.txt'.
appId required | string App ID |
robotTxt | boolean Enable for automatic updates of the app, disable if manual updates are preferred. |
csp | null or string Content Security Policy (CSP) directives to specify allowed sources for content. |
hstsPreload | boolean Enable HTTP Strict Transport Security (HSTS) preload list inclusion. |
{- "robotTxt": true,
- "csp": "default-src 'self'; img-src 'self' data:; media-src 'self'",
- "hstsPreload": false
}
{ }
Set a certificate for an app.
appId required | string App ID |
subdomain | string (subdomain) The subdomain on which the application runs. |
domain required | string (domain) The main domain on which the application runs. |
key required | string The private key for the SSL certificate in PEM format. |
cert required | string The SSL certificate in PEM format. |
{- "subdomain": "test",
- "domain": "cloudron.io",
- "key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----",
- "cert": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKK5yMdlWzmMA0G...\n-----END CERTIFICATE-----"
}
{- "taskId": 295
}
Set debug mode is an internal route that is used to debug an app.
appId required | string App ID |
object |
{- "debugMode": {
- "cmd": [
- "/bin/bash",
- "-c",
- "echo \"Repair mode. [...]"
], - "readonlyRootfs": true
}
}
{- "taskId": 295
}
Set mailbox.
appId required | string App ID |
enable | boolean Enable or disable a seperate mailbox for an app. |
mailboxName | string (mailboxName) The name of the mailbox used by the app. |
mailboxDomain | string (mailboxDomain) Domain associated with the app's mailbox. |
mailboxDisplayName | string (mailboxDisplayName) Display name for the mailbox associated with the app. |
{- "enable": true,
- "mailboxName": "wiki.app",
- "mailboxDomain": "your.domain.com",
- "mailboxDisplayName": ""
}
{- "taskId": 295
}
Set inbox.
appId required | string App ID |
enable | boolean Enable or disable a seperate mailbox for an app. |
inboxName | string or null (inboxName) Name of the inbox used by the app. |
inboxDomain | string or null (inboxDomain) Domain associated with the app's inbox. |
{- "enable": true,
- "inboxName": null,
- "inboxDomain": null
}
{- "taskId": 295
}
Set app turn.
appId required | string App ID |
enable | boolean Enable for if turn should be active. |
{- "enable": true
}
{- "taskId": 295
}
Set app turn.
appId required | string App ID |
enable | boolean Enable redis for an app. |
{- "enable": true
}
{- "taskId": 295
}
Set app env.
appId required | string App ID |
env | object Used to set up the app environment. It is an object where the values are strings. |
{- "env": { }
}
{- "taskId": 295
}
Set app storage.
appId required | string App ID |
storageVolumeId | string or null (storageVolumeId) Identifier for the storage volume used by the app. |
storageVolumePrefix | string or null (storageVolumePrefix) Prefix used for the storage volume. |
{- "storageVolumeId": null,
- "storageVolumePrefix": null
}
{- "taskId": 295
}
Set app location.
appId required | string App ID |
ports | object (ports) The port bindings of the application. |
secondaryDomains | Array of strings (secondaryDomains) Secondary domains associated with the application. |
redirectDomains | Array of strings (redirectDomains) Domains that redirect to the application. |
aliasDomains | Array of strings (aliasDomains) Alias domains for the application. |
overwriteDns | boolean Determines whether existing DNS settings should be overwritten during configuration. |
skipDnsSetup | boolean Skips the DNS setup process if set to true, assuming DNS is already configured. |
{- "ports": { },
- "secondaryDomains": [
- "your.secondary.domains.com"
], - "redirectDomains": [
- "your.redirect.domains.com"
], - "aliasDomains": [
- "your.alias.domains.com"
], - "overwriteDns": false,
- "skipDnsSetup": false
}
{- "taskId": 295
}
Set app mounts.
appId required | string App ID |
Array of objects |
{- "mounts": [
- {
- "volumeId": "vol-123abc456def",
- "readOnly": true
}
]
}
{- "taskId": 295
}
Set app crontab.
appId required | string App ID |
crontab | string or null (crontab) The schedule in crontab format for running periodic tasks. |
{- "crontab": "*/15 * * * *"
}
{ }
Set app upstreamuri.
appId required | string App ID |
upstreamUri | string (upstreamUri) The upstream URI of the application. |
{- "upstreamUri": "upstream.uri.de"
}
{ }
List all backups for an app.
appId required | string App ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/backups"
{- "backups": [
- {
- "id": "box_v2.2.2_ff231fee",
- "remotePath": "2024-05-11-210000-872/box_v2.2.2",
- "label": "backupLabel",
- "identifier": "box",
- "creationTime": "22024-05-11T21:35:48.000Z\"",
- "packageVersion": "2.2.2",
- "type": "box",
- "state": "normal",
- "format": "tgz",
- "preserveSecs": 0,
- "encryptionVersion": 2,
- "dependsOn": [
- [
- "app_3a09fbae-a1bc-4ec8-b3b9-6d72b3cf84d2_v1.1.0_9f3e294c",
- "app_7b02debb-c1cd-4db6-a4c2-8e95a4ef02d1_v1.1.0_4b7d8a2e",
- "app_e82bfcde-d2ef-4fdc-c8c1-5a94b5da06e3_v1.1.0_7c6f9b3d",
- "app_1f93bdea-b3cd-4f2d-a9a5-2b83a5ec19f2_v1.1.0_2d9c8b4a",
- "app_4d7aecfb-a3de-4cfb-b7b8-1c72b9fd93d4_v1.1.0_8a1b2c3d"
]
], - "manifest": {
- "name": "Manifest"
}
}
]
}
Update a backup for an app.
appId required | string App ID |
backupId required | string Specific ID of a backup. |
label | string A label or name for the backup. |
preserveSecs | number The number of seconds to preserve the backup. |
{- "label": "daily-backup",
- "preserveSecs": 86400
}
{ }
Update a backup for an app.
appId required | string App ID |
backupId required | string Specific ID of a backup. |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/backups/$BACKUPID/download"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/applinks"
{- "applinks": [
- {
- "id": "365653e5-0b3c-46bf-b1bf-828d3de3362b",
- "creationTime": "2024-04-08T10:40:07.000Z",
- "updateTime": "2024-04-08T10:40:07.000Z",
- "ts": 1712572807000,
- "label": "Cloudron Docs",
- "tags": [
- "external",
- "dev"
], - "accessRestriction": {
- "users": [
- "uid-c431f056-704f-46df-a316-0e59fe654754",
- "uid-c431f056-704f-46df-a316-0e59fd76553"
], - "groups": [
- "gid-c431f056-704f-46df-a316-0e59fe654754",
- "gid-c431f056-704f-46df-a316-0e59fe654754"
]
}, - "icon": "< base64 encoded image >"
}
]
}
Add an applink. The role 'admin' is required to make this API call.
upstreamUri required | string The URI of the external app. |
label | string The display name of the external app. If empty it will fetch the name of the site you are adding. |
tags | Array of strings Array of tags that the external app will have after creation. Can be empty. |
object An object that includes arrays for user and group restrictions. If |
{- "upstreamUri": "string",
- "label": "string",
- "tags": [
- "string"
], - "accessRestriction": {
- "users": [
- "string"
], - "groups": [
- "string"
]
}
}
{ }
Get applink
id required | string Applink ID |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/applinks/${ID}"
{- "id": "365653e5-0b3c-46bf-b1bf-828d3de3362b",
- "creationTime": "2024-04-08T10:40:07.000Z",
- "updateTime": "2024-04-08T10:40:07.000Z",
- "ts": 1712572807000,
- "label": "Cloudron Docs",
- "tags": [
- "external",
- "dev"
], - "accessRestriction": {
- "users": [
- "uid-c431f056-704f-46df-a316-0e59fe654754",
- "uid-c431f056-704f-46df-a316-0e59fd76553"
], - "groups": [
- "gid-c431f056-704f-46df-a316-0e59fe654754",
- "gid-c431f056-704f-46df-a316-0e59fe654754"
]
}, - "icon": "< base64 encoded image >"
}
Update applink
id required | string Applink ID |
upstreamUri required | string The URI of the external app. |
label | string The display name of the external app. |
tags | Array of strings Array of tags that the external app will have after creation. |
object Sets access restriction for users or groups. Can be null. | |
icon | string Applink icon. When not set, this the favicon of the website. This can be an icon, png, jpeg depending on the upstream site. When a custom icon is set, this is the icon which was previously uploaded. |
{- "upstreamUri": "string",
- "label": "string",
- "tags": [
- "string"
], - "accessRestriction": {
- "users": [
- "string"
], - "groups": [
- "string"
]
}, - "icon": "string"
}
{ }
Delete applink The role 'user-manager' is required to make this api call.
id required | string Applink ID |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/applinks/$ID"
{ }
App passwords can be used as a security measure in desktop, email & mobile clients. For example, if you are trying out a new mobile app from an untrusted vendor, you can generate a temporary password that provides access to a specific app. This way your main password does not get compromised (and thus providing access to other apps as well).
List the App Passwords. App Passwords are personal for a user.
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords"
{- "appPasswords": [
- {
- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "name": "Password For Nextcloud mobile app",
- "userId": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5",
- "creationTime": "2022-03-05T02:30:00.000Z"
}
]
}
Create an App Password
name required | string (name) A label/display name for the the password |
identifier | string (identifier) The application that this password will authenticate. This can be an app id or |
{- "name": "Password For Nextcloud mobile app",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5"
}
{- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "password": "01e536bbd289619f"
}
Get App Password by ID
passwordId required | string App Password Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"
{- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "name": "Password For Nextcloud mobile app",
- "userId": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5",
- "creationTime": "2022-03-05T02:30:00.000Z"
}
Deletes the App Password. All future requests using this password will instantly fail.
passwordId required | string App Password Id |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"
{ }
List backups.
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups"
{- "backups": [
- {
- "id": "box_v2.2.2_ff231fee",
- "remotePath": "2024-05-11-210000-872/box_v2.2.2",
- "label": "backupLabel",
- "identifier": "box",
- "creationTime": "22024-05-11T21:35:48.000Z\"",
- "packageVersion": "2.2.2",
- "type": "box",
- "state": "normal",
- "format": "tgz",
- "preserveSecs": 0,
- "encryptionVersion": 2,
- "dependsOn": [
- [
- "app_3a09fbae-a1bc-4ec8-b3b9-6d72b3cf84d2_v1.1.0_9f3e294c",
- "app_7b02debb-c1cd-4db6-a4c2-8e95a4ef02d1_v1.1.0_4b7d8a2e",
- "app_e82bfcde-d2ef-4fdc-c8c1-5a94b5da06e3_v1.1.0_7c6f9b3d",
- "app_1f93bdea-b3cd-4f2d-a9a5-2b83a5ec19f2_v1.1.0_2d9c8b4a",
- "app_4d7aecfb-a3de-4cfb-b7b8-1c72b9fd93d4_v1.1.0_8a1b2c3d"
]
], - "manifest": {
- "name": "Manifest"
}
}
]
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/mount_status"
{- "state": "active",
- "message": "mounted"
}
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/create
{- "taskId": 295
}
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/cleanup
{- "taskId": 295
}
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/remount
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/config"
{- "provider": "filesystem",
- "format": "tgz",
- "limits": {
- "memoryLimit": 231214321
}, - "backupFolder": "/var/backups",
- "noHardLinks": false,
- "encryption": null
}
Set storage
provider | string (provider) Backup provider. |
format | string (format) Backup file format. |
password required | string The password used for encryption or authentication during backup. Please ensure to use a strong, secure password. |
encryptedFilenames required | boolean Specifies whether filenames in the backup should be encrypted for added security. |
{- "provider": "filesystem",
- "format": "tgz",
- "password": "Your_Password",
- "encryptedFilenames": true
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/policy"
{- "policy": {
- "schedule": "00 00 23 * * *",
- "retention": {
- "keepWWithinSecs": 172300
}
}
}
Set policy
schedule | string (schedule) Backup schedule in cron format or similar. |
required | object (retention) Retention policy for backups. |
{- "schedule": "00 00 23 * * *",
- "retention": {
- "keepWWithinSecs": 172300
}
}
{ }
Update a backup by its ID.
backupId required | string Specific ID of a backup. |
label | string (properties-label) Label for the backup. |
preserveSecs | number (preserveSecs) Number of seconds to preserve the backup. |
{- "label": "backupLabel",
- "preserveSecs": 0
}
{ }
The Branding configuration can be used to customize various aspects of the Cloudron like it's name, logo and footer.
Get the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_avatar"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Set the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.
avatar required | string <binary> |
curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name" --form avatar=@localfilename.png
{ }
Get the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name"
{- "name": "string"
}
Set the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.
name required | string [ 1 .. 64 ] |
{- "name": "string"
}
{ }
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name"
{- "name": "string"
}
background | string <binary> The background image file to be set. If not provided, the background image will be cleared. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_background"
{ }
Cloudron Healthcheck route and various global configuration like language & timezone can be found here.
Simple healthcheck route to check if Cloudron is running or not. This route does not require any authentication.
curl \ -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/status"
{- "version": "7.6.0"
}
Get the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages. This route does not require any authentication.
curl \ -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/avatar"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
curl \ -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/background"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
List the available languages (translations). This route does not require any authentication.
curl -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/languages"
{- "languages": [
- "en",
- "de",
- "fr",
- "nl"
]
}
The Cloudron Language is the language used for the Dashboard, Login Page, Invitation and Reset emails. Note that users can always set a different language for their Dashboard in their profile. The default language is en
(English).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/language"
{- "language": "de"
}
The Cloudron Language is the language used for the Dashboard, Login Page, Invitation and Reset emails. Note that users can always set a different language for their Dashboard in their profile. The default language is en
(English).
language required | string Default: "en" The Language ID |
{- "language": "de"
}
{ }
TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/time_zone"
{- "timeZone": "de"
}
TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.
timeZone |
{- "timeZone": "Europe/Zurich"
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/dashboard/config"
{- "dashboard": [
- {
- "adminDomain": "${YOUR_ADMIN_DOMAIN}",
- "adminFqdn": "${YOUR_ADMIN_FQDN}",
- "mailFqdn": "${YOUR_MAIL_FQDN}",
- "version": "8.0.0",
- "ubuntuVersion": "Ubuntu 22.04.4 LTS",
- "isDemo": false,
- "cloudronName": "Your Cloudron Instance",
- "footer": "\"Thanks for using Cloudron!\"\n",
- "features": {
- "userMaxCount": true,
- "userGroups": true,
- "userRoles": true,
- "domainMaxCount": null,
- "externalLdap": false,
- "privateDockerRegistry": false,
- "branding": true,
- "support": true,
- "directoryConfig": true,
- "profileConfig": true,
- "mailboxMaxCount": true,
- "emailPremium": true
}, - "profileLocked": false,
- "mandatory2FA": false,
- "external2FA": false
}
]
}
Set your dashboard location.
domain required | string The domain where the dashboard will be located at. The |
{- "domain": "example.org"
}
{- "taskId": 295
}
Change the location of your Cloudron dashboard.
domain required | string The domain where the dashboard will be located at. The |
{- "domain": "anotherExample.org"
}
{ }
A private docker registry can be setup to pull the docker images of custom apps.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/docker/registry_config"
{- "provider": "digitalocean",
- "serverAddress": "docker.io",
- "username": "string",
- "email": "string",
- "password": "string"
}
A private docker registry can be setup to pull the docker images of custom apps.
provider required | string Enum: "aws" "digitalocean" "dockerhub" "google-cloud" "linode" "quay" "treescale" "other" "noop" Docker Registry Provider |
serverAddress | string Address of the Docker Registry |
username | string Username for authenticating with the Docker Registry |
string Email for authenticating with the Docker Registry | |
password | string Password for authenticating with the Docker Registry |
{- "provider": "digitalocean",
- "serverAddress": "docker.io",
- "username": "string",
- "email": "string",
- "password": "string"
}
{ }
Web addresses for accessing your server and apps. Read more about Cloudron domain settings in our knowledgebase.
Add a domain.
domain required | string The domain name. | ||||||||||||||||||||||||||||||||||||||||
zoneName | string (zoneName) Specifying the web address for the server. | ||||||||||||||||||||||||||||||||||||||||
provider required | string (definitions-provider) The provider for your domain. Available provider:
| ||||||||||||||||||||||||||||||||||||||||
object (tlsConfig) Configuration for TLS. | |||||||||||||||||||||||||||||||||||||||||
object (fallbackCertificate) Configuration for the fallback TLS certificate. | |||||||||||||||||||||||||||||||||||||||||
required | object Specifies config for AWS Route53 |
{- "domain": "desec.your.domain.io",
- "zoneName": "desec.your.domain.org",
- "provider": "AWS Route53",
- "tlsConfig": {
- "provider": "letsencrypt-prod",
- "wildcard": false
}, - "fallbackCertificate": {
- "cert": "-----BEGIN CERTIFICATE...",
- "key": "-----BEGIN PRIVATE KEY..."
}, - "config": {
- "accessKeyId": "sd321dgjh23483267asjhsdadsa",
- "secretAccessKey": "YOUR_AWS_SECRET_ACCESS_KEY"
}
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains"
{- "domains": [
- {
- "domain": "desec.your.domain.io",
- "zoneName": "desec.your.domain.org",
- "provider": "route53",
- "config": { },
- "tlsConfig": {
- "provider": "letsencrypt-prod",
- "wildcard": false
}, - "fallbackCertificate": {
- "cert": "-----BEGIN CERTIFICATE...",
- "key": "-----BEGIN PRIVATE KEY..."
}, - "wellKnown": {
- "dnt-policy.txt": "Do Not Track Compliance Policy",
}
}
]
}
Sync DNS.
domain | string The domain name that will sync the dns records. If no domain will be sent with this api call, it will sync the dns records of every domain on your Cloudron. |
type | string If type is |
{- "domain": "your.domain.org",
- "type": ""
}
{- "taskId": 295
}
Get domain
domain required | string The domain name. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN"
{