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"
{- "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",
}
}
Delete a domain.
domain required | string The domain name. |
curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN"
{ }
Set domain config.
domain required | string The domain name. |
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"
}
}
{ }
Set well known uri's for domain.
domain required | string The domain name. |
wellKnown | object or null (wellKnown) A
|
{- "wellKnown": {
- "dnt-policy.txt": "Do Not Track Compliance Policy",
}
}
{ }
Check if a subdomain already exists.
domain required | string The domain name. |
subdomain required | string Subdomain for the dns check. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN/dns_check?$SUBDOMAIN"
{- "needsOverwrite": true
}
Get the Directory Server configuration
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/directory_server/config"
{- "enabled": true,
- "secret": true,
- "allowlist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Set the Directory Server configuration
enabled required | boolean If Directory Server is enabled |
secret | string Password for authenticating with the Directory Server |
allowlist | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "enabled": true,
- "secret": true,
- "allowlist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
List events
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
search | string Search string |
actions | Array of strings (action) Items Enum: "app.clone" "app.configure" "app.repair" "app.install" "app.restore" "app.import" "app.uninstall" "app.update" "app.update.finish" "app.backup" "app.backup.finish" "app.login" "app.oom" "app.up" "app.down" "app.start" "app.stop" "app.restart" "backup.finish" "backup.start" "backup.cleanup.finish" "certificate.new" "certificate.cleanup" "cloudron.activate" "cloudron.provision" "cloudron.install.finish" "cloudron.start" "dashboard.domain.update" "domain.add" "domain.update" "domain.remove" "dyndns.update" "mail.location" "mail.enabled" "mail.disabled" "mail.box.add" "mail.box.remove" "mail.box.update" "mail.list.add" "mail.list.remove" "mail.list.update" "service.configure" "service.rebuild" "service.restart" "cloudron.update" "cloudron.update.finish" "user.add" "user.login" "user.login.ghost" "user.logout" "user.remove" "user.update" "volume.add" "volume.update" "volume.remount" "volume.remove" "support.ticket" "support.ssh" Example: actions=volume.add,volume.remove Comma separated list of actions |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog"
{- "eventlogs": [
- {
- "id": "7f32f714-ad40-4bea-b5e5-e71562679f0c",
- "action": "volume.add",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "source": { },
- "data": { }
}
]
}
Get event by ID
eventId required | string Event Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog/$EVENT_ID"
{- "id": "7f32f714-ad40-4bea-b5e5-e71562679f0c",
- "action": "volume.add",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "source": { },
- "data": { }
}
The External Directory connector allows users from your existing LDAP or active directory to authenticate with Cloudron.
Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/config"
{- "provider": "jumpcloud",
- "url": "docker.io",
- "baseDn": "string",
- "usernameField": "string",
- "filter": "string",
- "groupBaseDn": "string",
- "bindDn": "string",
- "bindPassword": "string"
}
Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server
provider required | string Enum: "ad" "cloudron" "jumpcloud" "okta" "univention" "other" "noop" External LDAP Provider |
url | string Address of the Docker Registry |
baseDn | string Base DN for users |
usernameField | string LDAP Field to use as the username |
filter | string LDAP Filter to use for filtering users |
groupBaseDn | string Base DN for groups |
bindDn | string LDAP authentication username |
bindPassword | string LDAP authentication password |
{- "provider": "jumpcloud",
- "url": "docker.io",
- "baseDn": "string",
- "usernameField": "string",
- "filter": "string",
- "groupBaseDn": "string",
- "bindDn": "string",
- "bindPassword": "string"
}
{ }
Trigger synchronization with external LDAP server
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/sync"
{- "taskId": 295
}
Groups provide a convenient way to group users. You can assign one or more groups to apps to restrict who can access for an app.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups"
{- "groups": [
- {
- "id": "gid-bd6d2757-320c-4c8c-b429-b283a8bd7647",
- "name": "developer",
- "source": "",
- "userIds": [
- "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
]
}
]
}
Add a group. The role 'user-manager' is required to make this api call.
name required | string The name of group to be added. Valid characters are alphanumerals and all printable characters. |
{- "name": "string"
}
{- "id": "gid-bd6d2757-320c-4c8c-b429-b283a8bd7647",
- "name": "developer"
}
Get group
groupId required | string Group ID |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups/${GROUP_ID}"
{- "group": [
- {
- "id": "gid-bd6d2757-320c-4c8c-b429-b283a8bd7647",
- "name": "developer",
- "source": "",
- "userIds": [
- "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
]
}
]
}
Delete a group The role 'user-manager' is required to make this api call.
groupId required | string Group ID |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups/${GROUP_ID}"
{ }
Set members. The role 'user-manager' is required to make this api call.
groupId required | string Group ID |
userIds required | Array of strings unique |
{- "userIds": [
- "uid-9eb38938-95a7-4fc7-8c15-e02fa341cdae",
- "uid-9ebewj349-95a7-4fc7-85fd-43278sdawae"
]
}
{ }
Set group name. The role 'user-manager' is required to make this api call.
groupId required | string Group ID |
name required | string The name of the group. |
{- "name": "string"
}
{ }
Get mail domain
domain required | string Mail domain |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN
{- "domain": [
- {
- "domain": "my.cloudron.site.de",
- "enabled": true,
- "mailFromValidation": true,
- "catchAll": [
- "catchall@example.org",
- "allcatch@example.org"
], - "relay": {
- "provider": "cloudron-smtp"
}, - "banner": {
- "text": "Warm Regards",
- "html": "<h1> Warm Regards </h1>"
}
}
]
}
List mail domain lists
domain required | string Mail domain |
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
search | string Filter by lists which match either username or email. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists
{- "lists": [
- {
- "name": "public",
- "type": "list",
- "ownerId": "admin",
- "ownerType": "user",
- "aliasName": "public",
- "aliasDomain": "your.mail.domain.com",
- "creationTime": "2024-04-01T13:47:50.000Z",
- "membersOnly": false,
- "domain": "your.mail.domain.com",
- "active": true,
- "enablePop3": false,
- "storageQuota": 0,
- "messagesQuota": 0,
- "members": [
- "user@example.com",
- "user2@example.com"
]
}
]
}
Add a mail domain list.
domain required | string Mail domain |
name | string Name of the list. |
membersOnly | boolean Set for members only. |
active | boolean Set list active. |
members | Array of strings Members of the list. |
{- "name": "private list",
- "membersOnly": false,
- "active": false,
- "members": [
- "user@example.com",
- "user2@example.com"
]
}
{ }
Get mail domain list
domain required | string Mail domain |
name required | string Mailbox name |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists/$NAME/
{- "list": {
- "name": "public",
- "type": "list",
- "ownerId": "admin",
- "ownerType": "user",
- "aliasName": "public",
- "aliasDomain": "your.mail.domain.com",
- "creationTime": "2024-04-01T13:47:50.000Z",
- "membersOnly": false,
- "domain": "your.mail.domain.com",
- "active": true,
- "enablePop3": false,
- "storageQuota": 0,
- "messagesQuota": 0,
- "members": [
- "user@example.com",
- "user2@example.com"
]
}
}
Update mail domain list
domain required | string Mail domain |
name required | string Mailbox name |
members required | Array of strings Array of members of the list. |
membersOnly | boolean Set membersOnly on true or false. |
active | boolean Set active on true or false. |
{- "members": [
- [
- "user@example.org",
- "user2@example.org"
]
], - "membersOnly": false,
- "active": true
}
{ }
Delete mail domain list
domain required | string Mail domain |
name required | string Mailbox name |
curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists/$NAME"
{ }
Enable mail domain
domain required | string Mail domain |
enabled required | boolean Used to enable the mail domain. |
{- "enabled": true
}
{ }
Get status
domain required | string Mail domain |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/status
{- "status": [
- {
- "dns": {
- "spf": {
- "domain": "your.cloudron.site.com",
- "name": "@",
- "type": "TXT",
- "value": "v=spf1 a:your.cloudron.site-ovh.de a:your.maildomain.com ~all",
- "expected": "v=spf1 a:your.cloudron.site-ovh.de a:your.maildomain.com ~all",
- "status": true,
- "errorMessage": "Error!"
}, - "dkim": {
- "domain": "cloudron._domainkey.your.cloudron.site.de",
- "name": "cloudron._domainkey",
- "type": "TXT",
- "value": "\"v=DKIM1; t=s; p=MIGfMA0GCSqGS4gjh2QEBAQUAA4GJAKSKBiQKBgQCjJ8vxsY3tATVVJZEiYTq6wgWEptSkwEgaPDR423497EHJHJGdN1KTg9lv3bFH6mcNYUejhIGDs22HdYM7dBtX4FeY/XrzP8q+8fHJJdkjasgdjwRbR3j+lmP83DkuaatRheX/y4g1qTWYWzgoTyw87UmemQSQ2367821gQIDAQAB\"\n",
- "expected": "\"v=DKIM1; t=s; p=MIGfMA0GCSqGS4gjh2QEBAQUAA4GJAKSKBiQKBgQCjJ8vxsY3tATVVJZEiYTq6wgWEptSkwEgaPDR423497EHJHJGdN1KTg9lv3bFH6mcNYUejhIGDs22HdYM7dBtX4FeY/XrzP8q+8fHJJdkjasgdjwRbR3j+lmP83DkuaatRheX/y4g1qTWYWzgoTyw87UmemQSQ2367821gQIDAQAB \n",
- "status": true,
- "errorMessage": "Error!"
}, - "ptr": {
- "domain": "[IPV4.ADDRESS].in-addr.arpa",
- "name": "[IPV4 ADDRESS]",
- "type": "PTR",
- "value": "v2137868127121.powersrv.de",
- "expected": "your.cloudron.site.com",
- "status": false,
- "errorMessage": "Error!"
}
}, - "rbl": {
- "status": true,
- "ip": "string",
- "servers": [
- "string"
]
}, - "relay": {
- "value": "OK",
- "status": true,
- "errorMessage": "Error!"
}
}
]
}
Mail from validation
domain required | string Mail domain |
enabled required | boolean Enable for validation. |
{- "enabled": true
}
{ }
Set catch all addresses
domain required | string Mail domain |
addresses required | Array of strings It will set the addresses inside the array to catch all. If the array is empty, existing catch all addresses will be removed from catch all. |
{- "addresses": [
- "catchall@example.de",
- "catch.all@example.de"
]
}
{ }
Set mail relay
domain required | string Mail domain |
provider required | string Provider for mail relay. |
host | string The mail relay host. |
port | number Port used for mails. |
username | string Username for mail relay. |
password | string Password for mail relay. |
acceptSelfSignedCerts | boolean Indicates whether self-signed certificates are accepted. |
forceFromAddress | boolean Indicates whether to force a specific "From" address. |
{- "provider": "mailgun",
- "host": "your.mailgun.host.de",
- "port": 578,
- "username": "mailgun_username",
- "password": "mailgun_password",
- "acceptSelfSignedCerts": true,
- "forceFromAddress": true
}
{ }
Set mail signature
domain required | string Mail domain |
text required | string Your mail signature as a text. |
html | string Your mail signature as HTML. |
{- "text": "Warm regards, your Cloudron Team",
- "html": "<h5> Warm regards, your Cloudron Team </h5>"
}
{ }
Set test mail
domain required | string Mail domain |
to required | string The address that should recieve the test mail. |
{- "to": "testmail.recievier@example.org"
}
{ }
Get mailbox count
domain required | string Mail domain |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailbox_count
{- "count": 2
}
List mailboxes
domain required | string Mail domain |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes
{- "mailboxes": [
- {
- "name": "public",
- "domain": "your.mail.domain.de",
- "ownerId": "uid-92c987b8-c4d7-440b-a34a-54a3854983b8",
- "ownerType": "user",
- "active": true,
- "enablePop3": false,
- "storageQuota": 0,
- "messagesQuota": 0,
- "members": [
- "uid-92c987b8-c4d7-440b-a34a-54a3854983b8",
- "uid-92c987b8-c4d7-440b-a34a-jkl3827lki12"
], - "membersOnly": true,
- "aliases": [
- [
- {
- "name": "MailboxAlias",
- "domain": "your.mail.domain.com"
}
]
]
}
]
}
Add mailbox
domain required | string Mail domain |
name required | string Name of the mailbox. |
ownerId required | string User Id of the owner. |
ownerType required | string Role of the user. |
active required | boolean Status of the user. |
storageQuota | number Limitation of the storage for the mailbox. Limitation in Bytes. |
messagesQuota | number Limitation of saved messages inside the mailbox. Limitation in Bytes. |
{- "name": "public",
- "ownerId": "uid-92c322b8-c4d7-440b-a34a-54a6428233b6",
- "ownerType": "user",
- "active": true,
- "storageQuota": 0,
- "messagesQuota": 0
}
{ }
Get Mailbox
domain required | string Mail domain |
name required | string Mailbox name |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes/$NAME
{- "mailbox": {
- "name": "public",
- "type": "mailbox",
- "ownerId": "uid-92c987b8-c4d7-440b-a34a-54a3854983b8",
- "ownerType": "user",
- "aliasName": "public",
- "aliasDomain": "your.mail.domain.com",
- "creationTime": "2024-04-01T13:47:50.000Z",
- "membersOnly": false,
- "domain": "your.mail.domain.com",
- "active": true,
- "enablePop3": false,
- "storageQuota": 0,
- "messagesQuota": 0,
- "members": [
- "uid-92c987b8-c4d7-440b-a34a-54a3854983b8",
- "uid-92c987b8-c4d7-440b-a34a-jkl3827lki12"
]
}
}
Update mailbox
domain required | string Mail domain |
name required | string Mailbox name |
ownerId required | string User Id of the owner. |
ownerType required | string Role of the user. |
active required | boolean Status of the user. |
enablePop3 required | boolean Enable or disable pop3. |
storageQuota | number Limitation of the storage for the mailbox. Limitation in Bytes. |
messagesQuota | number Limitation of saved messages inside the mailbox. Limitation in Bytes. |
{- "ownerId": "uid-92c322b8-c4d7-440b-a34a-54a6428233b6",
- "ownerType": "user",
- "active": true,
- "enablePop3": false,
- "storageQuota": 0,
- "messagesQuota": 0
}
{ }
Delete Mailbox
domain required | string Mail domain |
name required | string Mailbox name |
deleteMails required | boolean Delete all the mails of the mailbox. |
{- "deleteMails": false
}
{ }
Get mailbox aliases
domain required | string Mail domain |
name required | string Mailbox name |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes/$NAME/aliases
{- "aliases": [
- {
- "name": "MailboxAlias",
- "domain": "your.mail.domain.com"
}
]
}
Set aliases
domain required | string Mail domain |
name required | string Mailbox name |
required | Array of objects Array of object including 'name' and 'domain'. |
{- "aliases": [
- {
- "name": "MailboxAlias",
- "domain": "your.mail.domain.com"
}
]
}
{ }
Get eventlogs.
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/mailserver/eventlog"
{- "eventlogs": [
- {
- "ts": 1716283785401,
- "type": "delivered",
- "direction": "outbound",
- "uuid": "6455AF14-CEGF-2253-D57B-E94A6C0F8493.2.2",
- "messageId": "<hgsdagj4h234hjAHSGJh234gjh.your.domain.org>",
- "mailFrom": "<mail.from@your.domain.org>",
- "spamStatus": "string",
- "mailbox": "string",
- "rcpTo": [
- "<rcp@your.domain.org>"
], - "server": {
- "hostName": "your.cloudron.domain.org",
- "ip": "YOUR_IP_ADDRESS",
- "port": 27
}, - "response": "Message Queued [...]"
}
]
}
Clear eventlogs.
till | integer >= 1 Default: 1 Filter to give time range in which evenlogs should be cleared. |
curl -X POST\ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/clear_eventlog"
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/location"
{- "domain": "your.domain.de",
- "subdomain": "mailserver"
}
Set the location of the mailserver.
domain required | string Domain of your mailserver. |
subdomain required | string Subdomain of your mailserver. |
{- "domain": "your.domain.de",
- "subdomain": "mailserver"
}
{- "taskId": 295
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/max_email_size"
{- "size": 2317823
}
Set the max size for an email.
size required | number Maximum size for an email. |
{- "size": 321894
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/spam_acl"
{- "whitelist": [
- "no-spam@mail.de"
], - "blacklist": [
- "spam@mail.de"
]
}
Set spam acl.
blacklist required | Array of strings List of email addresses that are blocked (blacklisted). To remove emails from the blacklist, send an empty array. Existing emails also have to be inside that array, otherwise blacklist array will be replaced by the the one sent with this call. |
{- "blacklist": [
- "spam@mail.de"
]
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/spam_custom_config"
{- "config": "header TO_ADDRESS_TO_BLOCK To =~ /^(mail@your.domain\\\\.io|mail@your.domain\\\\.org)$/i \nscore TO_ADDRESS_TO_BLOCK 10.0 \ndescribe TO_ADDRESS_TO_BLOCK Emails sent to blocked addresses are likely spam.\n"
}
Set spam custom config.
config required | string The configuration settings for the mail server's spam filter using SpamAssassin. This includes rules and criteria for identifying and blocking spam emails. The configuration is written in a domain-specific language that utilizes regular expressions to specify conditions for email addresses that should be blocked or flagged as spam. It also includes scoring mechanisms to determine the likelihood that an email is spam, and descriptions for each rule to explain its purpose and functionality. Explanation of the example:
|
{- "config": "header TO_ADDRESS_TO_BLOCK To =~ /^(mail@your.domain\\\\.io|mail@your.domain\\\\.org)$/i \nscore TO_ADDRESS_TO_BLOCK 10.0 \ndescribe TO_ADDRESS_TO_BLOCK Emails sent to blocked addresses are likely spam.\n"
}
{ }
Get the "Domain Name Sytem Blacklist" configurations.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/dnsbl_config"
{- "zones": [
- "your.spamcan.org"
]
}
Set the "Domain Name Sytem Blacklist" configurations.
zones required | Array of strings An array of DNSBL zones to be queried by the mail server. Each zone represents a DNS-based blacklist that the server will use to check the origin of incoming emails. IP addresses found in these zones are typically associated with known spam sources. Mail servers query these DNSBL zones during the email validation process to determine the reputation of the sender's IP address. Existing domains also have to be inside that array, otherwise zones array will be replaced by the the one sent with this call. |
{- "zones": [
- "your.spamcan.org"
]
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/solr_config"
{- "enabled": true
}
Enable or disable solr.
enabled required | boolean Information if solr is enabled or not. |
{- "enabled": true
}
{ }
Check if mailbox sharing is enabled or not.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/mailbox_sharing"
{- "enabled": true
}
Enable or disable mailbox sharing.
enabled required | boolean Information if mailbox sharing is enabled or not. |
{- "enabled": true
}
{ }
Check if virtual all mail is enabled or not.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/virtual_all_mail"
{- "enabled": true
}
Enable or disable virtual all mail.
enabled required | boolean Information if virtual all mail is enabled or not. |
{- "enabled": true
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/usage"
{- "name@maildomain.de": {
- "diskSize": 7423688,
- "quotaValue": 346434,
- "quotaLimit": 0,
- "quotaPercent": 0
}
}
Gets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/blocklist"
{- "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Sets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).
blocklist required | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
Gets the Dynamic DNS configuration. The Dynamic DNS option keeps all the DNS records in sync when the IP address changes dynamically (like in home networks).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/dynamic_dns"
{- "enabled": true
}
Sets the Dynamic DNS configuration. The Dynamic DNS option keeps all the DNS records in sync when the IP address changes dynamically (like in home networks).
enabled required | boolean |
{- "enabled": true
}
{ }
Get the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4_config"
{- "provider": "noop"
}
Set the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.
provider required | string The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:
|
{- "provider": "noop"
}
{ }
Get the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6_config"
{- "provider": "noop"
}
Set the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.
provider required | string The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:
|
{- "provider": "noop"
}
{ }
Gets the configured IPv4 address of the server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4"
{- "ip": "5.75.134.144"
}
Gets the configured IPv6 address of the server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6"
{- "ip": "2402:3a80:423:eb84:d72e:b50:7c58:83eb"
}
Cloudron displays notifications in the dashboard for various events like: app down, app out of memory, low disk space, updates available, app update etc. The notifications can be read by clicking on the bell icon in the navigation bar.
List notifications
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
acknowledged | boolean Filter by acknowledged status |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get notification by ID
notificationId required | string Notification Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications/$NOTIFICATION_ID"
{- "id": "50",
- "eventId": "051ceb23-5003-4b03-b46e-521611b02a1c",
- "title": "Reboot Required",
- "message": "To finish ubuntu security updates, a reboot is necessary.",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "acknowledged": false
}
Set notification acknowledged state. Unacknowledged notifications count appears in the navbar of the Dashboard.
notificationId required | string Notification Id |
acknowledged required | boolean Set notification to acknowledged or not |
{- "acknowledged": true
}
{ }
OpenID Connect. It allows clients to verify the identity of end-users based on the authentication performed by an authorization server.
List the existing OpenID Connect Clients.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients"
{- "clients": [
- {
- "id": "cid-6c4e2bc962b7e90b45b400224772cec7",
- "secret": "9cefe41f9cbd8aabe44da60d3827d45779fd233bbfdc0f381228564dsaasd5",
- "appId": "",
- "name": "Test Client",
- "loginRedirectUri": "your.oidc.uri.org",
- "tokenSignatureAlgorithm": "EdDSA"
}
]
}
Add an oidc client to your Cloudron.
name required | string The name of the client. |
loginRedirectUri required | string The URI to redirect to after login. |
tokenSignatureAlgorithm required | string Enum: "RS256" "EdDSA" The algorithm used to sign tokens. |
{- "name": "Test Client",
- "loginRedirectUri": "your.oidc.uri.org",
- "tokenSignatureAlgorithm": "EdDSA"
}
{- "id": "cid-6c4e2bc962b7e90b45b400224772cec7",
- "secret": "9cefe41f9cbd8aabe44da60d3827d45779fd233bbfdc0f381228564dsaasd5",
- "appId": "",
- "name": "Test Client",
- "loginRedirectUri": "your.oidc.uri.org",
- "tokenSignatureAlgorithm": "EdDSA"
}
Get a specific OpenID Connect Clients.
clientId required | string ID of an OpenID Connect Client. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients/$CLIENTID"
{- "id": "cid-6c4e2bc962b7e90b45b400224772cec7",
- "secret": "9cefe41f9cbd8aabe44da60d3827d45779fd233bbfdc0f381228564dsaasd5",
- "appId": "",
- "name": "Test Client",
- "loginRedirectUri": "your.oidc.uri.org",
- "tokenSignatureAlgorithm": "EdDSA"
}
Update OpenID Connect Client.
clientId required | string ID of an OpenID Connect Client. |
name required | string The name of the client. |
loginRedirectUri required | string The URI to redirect to after login. |
tokenSignatureAlgorithm required | string Enum: "RS256" "EdDSA" The algorithm used to sign tokens. |
{- "name": "Test Client",
- "loginRedirectUri": "your.oidc.uri.org",
- "tokenSignatureAlgorithm": "EdDSA"
}
{ }
Delete a specific OpenID Connect Clients.
clientId required | string ID of an OpenID Connect Client. |
curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients/$CLIENTID"
{ }
curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/sessions"
{ }
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile"
{- "id": "string",
- "username": "messi",
- "email": "goat@football.com",
- "fallbackEmail": "goat@soccer.com",
- "displayName": "Lionel Messi",
- "twoFactorAuthenticationEnabled": true,
- "role": "owner",
- "hasBackgroundImage": true,
- "avatarUrl": "string",
- "source": "ldap"
}
Update user's profile information
string Unique email address | |
fallbackEmail | string Unique fallback email address. This is the address password reset is sent to. This requires the |
password | string When trying to change the |
displayName | string Full name of the user |
{- "email": "goat@football.com",
- "fallbackEmail": "goat@soccer.com",
- "password": "string",
- "displayName": "Lionel Messi"
}
{ }
Get the User's custom avatar (icon). This route is public. As a simple security measure, this requires the user id.
To display the user's avatar , use the avatarUrl
property of the profile endpoint. The avatarUrl
will link to this endpoint when the user has a custom icon.
userId required | string User Id |
curl "https://$CLOUDRON_DOMAIN/api/v1/profile/avatar/$USER_ID"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get the user's custom background image for the dashboard.
Use the hasBackgroundImage
property of the profile endpoint to determine if the user has a custom background image.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/backgroundImage"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Set the user's background image for the dashboard
backgroundImage required | string <binary> |
curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/background_image" --form backgroundImage=@localfilename.png
{ }
Update user's password
password required | string Current password |
newPassword required | string New password |
{- "password": "current_password",
- "newPassword": "new_password"
}
{ }
Sets 2FA Secret. Enabling 2FA is a two step process:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/twofactorauthentication_secret"
{- "secret": "string",
- "qrcode": "string"
}
Enables Two Factor Authentication. Enabling 2FA is a two step process:
totpToken required | string Current TOTP Token based off the generate secret |
{- "totpToken": "string"
}
{ }
Disable 2FA
password required | string Current password |
{- "password": "current_password"
}
{ }
This endpoint allows users to provision and configure domain settings. It validates and applies various configurations such as provider details, domain name, zone information, TLS settings, and optional IPv4 and IPv6 configurations.
API endpoint to configure domain settings. To read more about the existing domain provider and their domain configs inside the Domain Route.
object | |
ipv4Config | object IPv4 configuration settings. |
ipv6Config | object IPv6 configuration settings. |
{- "domainConfig": {
- "provider": "string",
- "domain": "string",
- "zoneName": "string",
- "config": { },
- "tlsConfig": {
- "provider": "string"
}
}, - "ipv4Config": { },
- "ipv6Config": { }
}
{ }
Resotre
object | |
encryptedFilenames | boolean Enables or disables encrypted file names. |
remotePath | string The remote path where backups are stored (e.g., s3://mybucket/backups/). |
version | string The version of the provisioning script or configuration. |
ipv4Config | object Configuration settings for IPv4. |
ipv6Config | object Configuration settings for IPv6. |
skipDnsSetup | boolean Enable or disable to skip the DNS setup. |
{- "backupConfig": {
- "provider": "AWS",
- "format": "tar",
- "password": "securepassword123"
}, - "encryptedFilenames": true,
- "remotePath": "s3://mybucket/backups/",
- "version": "1.0.0",
- "ipv4Config": { },
- "ipv6Config": { },
- "skipDnsSetup": false
}
{ }
Activate your provision.
username | string The unique identifier for the user, typically used for login. |
password | string The user's password, used for authentication. This should be stored securely. |
string The user's email address, used for account recovery and notifications. | |
displayName | string The name displayed publicly for the user, such as in user profiles or posts. |
{- "username": "john_doe",
- "password": "securePassword123!",
- "email": "john.doe@example.com",
- "displayName": "John Doe"
}
{- "userId": "123456789",
- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvbiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "expires": "2024-12-31T23:59:59Z"
}
Trigger manual renewal of Let's encrypt certificates. Note that certs are automatically renewed by Cloudron, 1 month before their expiry.
rebuild | boolean Default: false When set all the nginx configurations are regenerated. |
{- "rebuild": false
}
{- "taskId": 295
}
Gets the list of proxies in front of Cloudron. Cloudron will trust the various reverse proxy headers like X-Forwarded-For
when requests originate from these proxy addresses.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/reverseproxy/trusted_ips"
{- "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Sets the list of proxies in front of Cloudron. Cloudron will trust the various reverse proxy headers like X-Forwarded-For
when requests originate from these proxy addresses.
trustedIps required | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services"
{- "services": [
- "turn",
- "mail",
- "mongodb",
- "mysql",
- "postgresql",
- "docker",
- "unbound",
- "sftp",
- "graphite",
- "nginx"
]
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services"
{- "message": "Ready"
}
Get information about a service.
service required | string Service name |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE"
{- "name": "mail",
- "status": "active",
- "memoryUsed": 755478528,
- "memoryPercent": 17,
- "error": null,
- "healthcheck": {
- "status": true,
- "haraka": {
- "status": true
}, - "dovecot": {
- "status": true
}, - "spamd": {
- "status": true
}, - "redis": {
- "status": true
}, - "solr": {
- "status": true
}
}, - "config": { },
- "defaultMemoryLimit": 536870912
}
This call is used to configure a service.
service required | string Service name |
memoryLimit required | number Limits the available memory. The unit used here is bytes. |
recoveryMode required | boolean Enables or disables the recovery mode. |
{- "memoryLimit": 4294967296,
- "recoveryMode": false
}
{ }
Get graphs of the service
service required | string Service name |
fromMinutes required | number Filter by minutes. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/graphs?fromMinutes=10"
{- "cpu": [ ],
- "memory": [ ],
- "blockRead": [ ],
- "blockWrite": [ ],
- "networkRead": [ ],
- "networkWrite": [ ],
- "blockReadTotal": 0,
- "blockWriteTotal": 0,
- "networkReadTotal": 0,
- "networkWriteTotal": 0,
- "cpuCount": 4
}
Download logs of a service.
service required | string Service name |
lines required | 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/services/$SERVICE/logs/?lines=10&format=json"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get Service 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.
service required | string Service name |
lines required | number Last lines displayed. |
format | string Default: "json" Enum: "json" "short" Defines the format of the logs. |
curl \ -H "Accept: text/event-stream" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/logstream?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Restart a service.
service required | string Service name |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/restart"
{ }
Rebuild a service.
service required | string Service name |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/rebuild"
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/info"
{- "sysVendor": "ACME Inc.",
- "productName": "Server",
- "uptimeSecs": 3600,
- "rebootRequired": false,
- "activationTime": "2024-05-15T08:00:00Z"
}
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/reboot"
{ }
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/cpus"
{- "cpus": [
- {
- "model": "AMD EPYC Processor",
- "speed": 2445,
- "times": {
- "user": 43406350,
- "nice": 595090,
- "sys": 23041560,
- "idle": 1932436310,
- "irq": 0
}
}, - {
- "model": "AMD EPYC Processor",
- "speed": 2445,
- "times": {
- "user": 43047330,
- "nice": 605510,
- "sys": 22909070,
- "idle": 1932424940,
- "irq": 0
}
}
]
}
Get information about disk usage for apps and other system components, like mail storage and docker images.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/disk_usage"
{- "usage": {
- "ts": 1699412641120,
- "disks": {
- "/dev/nvme0n1p2": {
- "available": 190863687680,
- "capacity": 0.6,
- "contents": [
- {
- "id": "platformdata",
- "path": "/home/yellowtent/platformdata",
- "type": "standard",
- "usage": 2969190400
}
], - "filesystem": "/dev/nvme0n1p2",
- "mountpoint": "/",
- "size": 502391562240,
- "speed": 523.6,
- "type": "ext4",
- "used": 285932556288
}
}
}
}
Disk usage is only updated automatically once per day. This API allows to trigger an update of that information.
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/disk_usage"
{- "taskId": 295
}
Get information of your sytem block devices.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/block_devices"
{- "devices": [
- {
- "path": "/dev/sda1",
- "size": "40G",
- "type": "ext4",
- "uuid": "55347856adabef0-1957-463e-534543534asdc",
- "mountpoint": "/"
}
]
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/memory"
{- "memory": 32423423,
- "swap": 32123442
}
Download the system logs.
unit required | number Unit for the logs. |
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/system/logs/$UNIT/?lines=10&format=json"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get system 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.
unit required | number Unit for the logs. |
lines | number Last lines displayed. |
format | string Default: "json" Enum: "json" "short" Defines the format of the logs. |
curl \ -H "Accept: text/event-stream" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/logstream/$UNIT?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Tasks are asynchronous operations performed in the background. Each task can be monitored separately using the task id.
List tasks
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
type | string (type) Enum: "app" "backup" "update" "checkCerts" "syncDyndns" "prepareDashboardLocation" "cleanBackups" "syncExternalLdap" "changeMailLocation" "syncDnsRecords" "updateDiskUsage" Example: type=cleanBackups Filter by Task Type |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks"
{- "tasks": [
- {
- "id": "364",
- "type": "cleanBackups",
- "percent": 1,
- "message": "Checking expired certs for removal",
- "error": {
- "message": "string",
- "code": 0
}, - "active": true,
- "pending": true,
- "creationTime": "2023-09-07T13:18:35.000Z",
- "result": { },
- "ts": "2023-09-07T13:18:35.000Z",
- "success": true
}
]
}
Get task by ID
taskId required | string Task Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID"
{- "id": "364",
- "type": "cleanBackups",
- "percent": 1,
- "message": "Checking expired certs for removal",
- "error": {
- "message": "string",
- "code": 0
}, - "active": true,
- "pending": true,
- "creationTime": "2023-09-07T13:18:35.000Z",
- "result": { },
- "ts": "2023-09-07T13:18:35.000Z",
- "success": true
}
Get task logs. Use this end point to download logs. If you want to follow logs tail -f
style, use the logstream endpoint instead.
taskId required | string Task Id |
lines | integer Default: 10 Number of lines in the log |
format | string Default: "json" Enum: "json" "short" Format of the lines in the log file |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logs?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get task 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.
taskId required | string Task Id |
lines | integer Default: 10 Number of lines in the log |
curl -H "Accept: text/event-stream" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logstream?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Stops a task
taskId required | string Task Id |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASK_ID/stop"
{ }
List the API tokens created by the user. Note that tokens are personal (per user) and not global.
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/tokens"
{- "tokens": [
- {
- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
]
}
Create an API token
name required | string (Token-properties-name) A label/display name for the the token |
expiresAt | integer (expires) Time (epoch) when the token expires |
scope | object (scope) Token permissions. This is a map of routes with r (read) or rw (read write) permission |
{- "name": "Token For Automation",
- "expiresAt": 1725615073184,
- "scope": {
- "*": "rw"
}
}
{- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
Get token by ID
tokenId required | string Token Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"
{- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
Deletes the Token. All future requests using this token will instantly fail.
tokenId required | string Token Id |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"
{ }
Gets information of any pending update to apps and the platform. This endpoint returns the cached update information and does not contact cloudron.io App Store. The update information could be stale and if you want the latest information use the checkForUpdates endpoint.
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/updates"
{- "updates": {
- "box": {
- "version": "string",
- "changelog": [
- "string"
], - "sourceTarballUrl": "string",
- "sourceTarballSigUrl": "string",
- "boxVersionsUrl": "string",
- "boxVersionsSigUrl": "string",
- "unstable": true
}, - "appId1": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}, - "appId2": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}
}
}
Gets information of any pending update to apps and the platform by contacting cloudron.io App Store. This call can take a while since it has to get the update information of each installed app. Use the getUpdates endpoint to get the update information since the last check.
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/check_for_updates"
{- "updates": {
- "box": {
- "version": "string",
- "changelog": [
- "string"
], - "sourceTarballUrl": "string",
- "sourceTarballSigUrl": "string",
- "boxVersionsUrl": "string",
- "boxVersionsSigUrl": "string",
- "unstable": true
}, - "appId1": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}, - "appId2": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}
}
}
Updates Cloudron to the next available release. The update is started asynchronously and can be monitored using the tasks API.
skipBackup | boolean Default: false Whether backup should be skipped before performing the update. |
{- "skipBackup": false
}
{- "taskId": 295
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/autoupdate_pattern"
{- "pattern": "00 00 1,3,5,23 * * *"
}
Sets the automatic update schedule
pattern required | string (CronPattern) Automatic update pattern in cron format. |
{- "pattern": "00 00 1,3,5,23 * * *"
}
{ }
List users
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 |
active | boolean Filter by active or not active users. If not provided any state matches. |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users"
{- "users": [
- {
- "id": "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc",
- "username": "helena",
- "email": "example@cloudron.io",
- "fallbackEmail": "fallback@example.com",
- "displayName": "Helena Mamchuk",
- "groupIds": [
- "gid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
], - "active": true,
- "source": "string",
- "role": "string",
- "twoFactorAuthenticationEnabled": true,
- "inviteAccepted": true
}
]
}
Add a user. The role 'user-manager' is required to make this api call.
email required | string The Primary email. |
username | string |
password | string Password used for the user. |
displayName | string |
role | string Enum: "owner" "admin" "usermanager" "mailmanager" "user" See user roles for more information on each role. |
fallbackEmail | string |
{- "email": "string",
- "username": "string",
- "password": "string",
- "displayName": "string",
- "role": "owner",
- "fallbackEmail": "string"
}
{- "id": "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
}
Get user
userId required | string User ID |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID
{- "id": "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc",
- "username": "helena",
- "email": "example@cloudron.io",
- "fallbackEmail": "fallback@example.com",
- "displayName": "Helena Mamchuk",
- "groupIds": [
- "gid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
], - "active": true,
- "source": "string",
- "role": "string",
- "twoFactorAuthenticationEnabled": true,
- "inviteAccepted": true
}
Delete a user. The role 'user-manager' is required to make this api call.
userId required | string User ID |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID"
{ }
Set user role. Users can't set roles for themselves. The role 'user-manager' is required to make this api call.
userId required | string User ID |
role | string Enum: "owner" "admin" "usermanager" "mailmanager" "user" See user roles for more information on each role. |
{- "role": "owner"
}
{ }
Set a user active or not A user can't set themselve as active or inactive. The role 'user-manager' is required to make this api call.
userId required | string User ID |
active required | boolean Specify whether the user is active or not. |
{- "active": true
}
{ }
Update user. Username can only be updated when the user has no existing username!
userId required | string User ID |
string Primary email for the user. | |
displayName | string Display name for the user. |
fallbackEmail | string Incase the email is hosted on the same Cloudron, this email is used for password resets. |
{- "email": "string",
- "displayName": "string",
- "fallbackEmail": "string"
}
{ }
Set password
userId required | string User ID |
password | string User's password. |
{- "password": "string"
}
{ }
Impersonate a user. You require the 'admin' role to use that call.
userId required | string User ID |
password required | string Temporary password |
expiresAt | integer Default: "6 * 60 * 60 * 1000; // 6 hours" Time until password expires in miliseconds. |
{- "password": "string",
- "expiresAt": 1725615073184
}
{ }
Set user group. The role 'user-manager' is required to make this api call.
userId required | string User ID |
groupIds required | Array of strings unique Array of groupIds |
{- "groupIds": [
- "gid-9eb38938-95a7-4fc7-8c15-e02fa341cdae",
- "gid-9ebewj349-95a7-4fc7-85fd-43278sdawae"
]
}
{ }
Get password reset link
userId required | string User ID |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID"
Send password reset email. The role 'user-manager' is required to make this api call.
userId required | string User ID |
email required | string |
{- "email": "string"
}
{ }
Get invite link
userId required | string User ID |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID/invite_link"
Send invite email. The role 'user-manager' is required to make this api call.
userId required | string User ID |
email required | string The email address, that should receive the invite link. |
{- "email": "string"
}
{ }
Disable 2FA. The role 'user-manager' is required to make this api call.
userId required | string User ID |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID/twofactorauthentication_disable"
{ }
Settings & Configuration for Cloudron User Directory.
Get the current profile configuration for all users in the user directory.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/user_directory/profile_config"
{- "lockUserProfiles": true,
- "mandatory2FA": true
}
Set the current profile configuration for all users in the user directory.
lockUserProfiles required | boolean If profile changes by users is disabled |
mandatory2FA required | boolean If two factor authentication for all users is enforced |
{- "lockUserProfiles": true,
- "mandatory2FA": true
}
{ }
Add volume. Note that the data in the cURL has to be adjusted based on the mountType.
name required | string A valid name for the volume should consist of printable characters and valid filesystem characters. This includes letters, numbers, spaces, and various symbols commonly accepted in filesystem naming conventions. |
mountType required | string Indicates the method or protocol used to mount a volume, defining how the volume is accessed and interacted with within the system. See more about mount types.
|
required | object Specifies extra settings for mounting a filesystem. Needed properties vary based on the mountType. |
{- "name": "Main Volume",
- "mountType": "cifs",
- "mountOptions": {
- "host": "example.com",
- "remoteDir": "/backup",
- "username": "u328893",
- "password": "your_password",
- "seal": true
}
}
{- "id": "1af5f811fddb4337ac5f71b0989c1d30"
}
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes"
{- "volumes": [
- {
- "id": "1af5f811fddb4337ac5f71b0989c1d30",
- "name": "Main Volume",
- "hostPath": "/mnt/volumes/",
- "creationTime": "2024-03-20T18:00:48.000Z",
- "mountType": "cifs",
- "mountOptions": {
- "host": "example.com",
- "remoteDir": "/backup",
- "username": "u328893",
- "password": "your_password",
- "seal": true
}
}
]
}
Get volume
id required | string Volume ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID"
{- "id": "1af5f811fddb4337ac5f71b0989c1d30",
- "name": "Main Volume",
- "hostPath": "/mnt/volumes/",
- "creationTime": "2024-03-20T18:00:48.000Z",
- "mountType": "cifs",
- "mountOptions": {
- "host": "example.com",
- "remoteDir": "/backup",
- "username": "u328893",
- "password": "your_password",
- "seal": true
}
}
Update volume. A volume can only be updated when it has the mount type CIFS
, NFS
or SSHFS
.
id required | string Volume ID |
required | object Specifies extra settings for mounting a filesystem. Needed properties vary based on the mountType. |
{- "mountOptions": {
- "host": "example.com",
- "remoteDir": "/backup",
- "username": "u328893",
- "password": "your_password",
- "seal": true
}
}
{ }
Delete volume
id required | string Volume ID |
curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID"
{ }
Get volume status
id required | string Volume ID |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/status"
{- "state": "active",
- "message": "mounted"
}
Remount volume
id required | string Volume ID |
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/remount"
{ }
Get a file located on a volume.
id required | string Volume ID |
filename required | string Name of a file located on the volume |
curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/files/$FILENAME"
This is the content of the file. It may contain multiple lines. Line 3... Line 4...