logo
API docs by Redocly

Cloudron API (1.0.0)

Download OpenAPI specification:Download

URL: https://forum.cloudron.io License: Apache 2.0

Introduction

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.

Requests

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

HTTP Statuses

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

Pagination

When listing objects, query parameters page and per_page can be passed in. Note that these parameters have index starting from 1.

API Token

To use the REST API, you must first create an API token. This token can be provided in two ways:

  • Via the request query parameter ?access_token=<token>
  • Via the Authorization header Bearer <token>

API Tokens can be created as Readonly or Read and Write. With Readonly token, only GET operations can be performed.

cURL Examples

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"

Authorization

bearer_auth

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
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

query_auth

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'
Security Scheme Type: API Key
Query parameter name: access_token

Apps

Handle your cloudron apps using the apps api.

Install app

Install an app. Up to Cloudron v8.1 this route is POST /api/v1/apps/install ! Either the manifest or the appStoreId must be specified!

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
appStoreId
required
string

Cloudron app store ID. Same as the id in the CloudronManifest.json

manifest
required
object (manifest)

Find more about the manifest specification in our knowledgebase.

ports
object (ports)

The port bindings of the application.

icon
string

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.

label
null or string (label)

A custom label for the application.

memoryLimit
number (memoryLimit)

The memory limit for the app in bytes.

sso
boolean

Indicates whether the application supports Single Sign-On (SSO).

enableBackup
boolean

Indicates whether backups are enabled for the application.

enableAutomaticUpdate
boolean

Indicates whether automatic updates are enabled.

object
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.

env
object

Used to set up the app environment. It is an object where the values are strings.

enableMailbox
boolean

Enable or disable the mailbox feature for the app.

enableTurn
boolean

Indicates whether TURN (Traversal Using Relays around NAT) is enabled.

upstreamUri
string

The upstream URI of the application.

Responses

Request samples

Content type
application/json
{
  • "appStoreId": "io.cloudron.surfer",
  • "manifest": { },
  • "ports": { },
  • "icon": "< base64 encoded image >",
  • "label": "Office",
  • "memoryLimit": 123432345,
  • "sso": true,
  • "enableBackup": true,
  • "enableAutomaticUpdate": false,
  • "debugMode": {
    },
  • "secondaryDomains": [
    ],
  • "redirectDomains": [
    ],
  • "aliasDomains": [
    ],
  • "overwriteDns": false,
  • "skipDnsSetup": false,
  • "env": { },
  • "enableMailbox": true,
  • "enableTurn": false,
  • "upstreamUri": "upstream.uri.de"
}

Response samples

Content type
application/json
{
  • "id": "d342-ef54003-dsads332-4322ds34ddff0",
  • "taskId": 295
}

List apps

List apps.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps"

Response samples

Content type
application/json
{
  • "apps": [
    ]
}

Get app

Get app information.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}"

Response samples

Content type
application/json
{
  • "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": {
    },
  • "sso": true,
  • "debugMode": {
    },
  • "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": [
    ],
  • "label": "Office",
  • "notes": { },
  • "secondaryDomains": [
    ],
  • "redirectDomains": [
    ],
  • "aliasDomains": [
    ],
  • "env": { },
  • "enableAutomaticUpdate": false,
  • "storageVolumeId": null,
  • "storageVolumePrefix": null,
  • "mounts": [
    ],
  • "enableTurn": true,
  • "enableRedis": true,
  • "checklist": { },
  • "enableMailbox": true,
  • "mailboxDisplayName": "",
  • "mailboxName": "wiki.app",
  • "mailboxDomain": "your.domain.com",
  • "enableInbox": false,
  • "inboxName": null,
  • "inboxDomain": null,
  • "accessLevel": "Admin"
}

Get app icon

Get app icon.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}/icon"

Response samples

Content type
application/json
{
  • "icon": "< base64 encoded image >"
}

Uninstall app

Uninstal an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/{APPID}/uninstall"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Repair app

'Owner' role is required to repair app with docker addon.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
manifest
object (manifest)

Find more about the manifest specification in our knowledgebase.

dockerImage
string

Dockerimage.

Responses

Request samples

Content type
application/json
{
  • "manifest": { },
  • "dockerImage": "Your_Dockerimage"
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Check updates

Check for availabe updates for the app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/check_for_updates"

Response samples

Content type
application/json
{
  • "updates": { }
}

Update app

Update app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "manifest": { },
  • "appStoreId": "",
  • "skipBackup": true,
  • "force": true
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Restore app

Restore an app from backup.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
backupId
required
string

ID of the backup used for the restore.

Responses

Request samples

Content type
application/json
{
  • "backupId": "app_v2.2.2_ff231fee"
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Import app

Import an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "remotePath": "app_v2.2.2_ff231fee",
  • "backupFormat": "tar.gz",
  • "backupConfig": {
    }
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Export app

Export an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/export"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Start app

Start an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/start"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Stop app

Stop an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/stop"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Restart app

Restart an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/restart"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get app logstream

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.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

query Parameters
lines
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Download app logs

Download app logs.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

query Parameters
lines
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Request samples 

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"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get app eventlogs

List app eventlogs. There are different kind of eventlogs, each type has it's own properties.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

query Parameters
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 ",".

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/eventlog"

Response samples

Content type
application/json
{
  • "eventlogs": [
    ]
}

Get app task

Get tasks of an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/task"

Response samples

Content type
application/json
{
  • "id": "707",
  • "type": "app",
  • "percent": 20,
  • "message": "Stopping container",
  • "creationTime": "2024-06-06T10:07:17.000Z",
  • "ts": "2024-06-06T10:07:18.000Z",
  • "args": [
    ],
  • "result": "success",
  • "error": "Failed to stop container",
  • "active": true,
  • "success": false,
  • "pending": false
}

Clone app

Clone an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "backupId": "app_v2.2.2_ff231fee",
  • "subdomain": "test",
  • "domain": "cloudron.io",
  • "ports": { },
  • "overwriteDns": false,
  • "skipDnsSetup": true
}

Response samples

Content type
application/json
{
  • "id": "c5a5db16-30c4-4202-bfdd-f5bdad6297888",
  • "taskId": 295
}

Create exec

Create app exec.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "cmd": [
    ],
  • "tty": true,
  • "lang": "en_US.UTF-8"
}

Response samples

Content type
application/json
{
  • "id": "c5a5db16-30c4-4202-bfdd-f5bdad6297888"
}

Set access restriction

Configure who will be able to access the app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "accessRestriction": {
    }
}

Response samples

Content type
application/json
{ }

Set operators

Set who can access and also configure the app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "accessRestriction": {
    }
}

Response samples

Content type
application/json
{ }

Set label

Set app label.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
label
null or string (label)

A custom label for the application.

Responses

Request samples

Content type
application/json
{
  • "label": "Office"
}

Response samples

Content type
application/json
{ }

Set tags

Set app tags.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
tags
Array of strings (tags)

Tags for categorizing and filtering the application.

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{ }

Set icon

Set app icon.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
icon
string or null

Base-64 encoded image string. An empty string means null.

Responses

Request samples

Content type
application/json
{
  • "icon": "Base-64 encoded image string."
}

Response samples

Content type
application/json
{ }

Set notes

Set app notes.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
notes
string or null

Notes shown in the app configs.

Responses

Request samples

Content type
application/json
{
  • "notes": "Used for office purposes."
}

Response samples

Content type
application/json
{ }

Set memory limit

Set the memory limit of an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
memoryLimit
number (memoryLimit)

The memory limit for the app in bytes.

Responses

Request samples

Content type
application/json
{
  • "memoryLimit": 123432345
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set cpu quota

Set the memory limit of an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
cpuQuota
number (cpuQuota)

The CPU quota for the app, expressed as a percentage.

Responses

Request samples

Content type
application/json
{
  • "cpuQuota": 100
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set automatic backup

Set whether the app should have automatic backups or not.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
enable
boolean

Enable for automatic backups of the app, disable if manual backups are preferred.

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{ }

Set automatic update

Set whether the app should automatically update to newer available versions.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
enable
boolean

Enable for automatic updates of the app, disable if manual updates are preferred.

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{ }

Set reverse proxy

Set up configs like the 'robots.txt'.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "robotTxt": true,
  • "csp": "default-src 'self'; img-src 'self' data:; media-src 'self'",
  • "hstsPreload": false
}

Response samples

Content type
application/json
{ }

Set certificate

Set a certificate for an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "subdomain": "test",
  • "domain": "cloudron.io",
  • "key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----",
  • "cert": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKK5yMdlWzmMA0G...\n-----END CERTIFICATE-----"
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set debug mode

Set debug mode is an internal route that is used to debug an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "debugMode": {
    }
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set mailbox

Set mailbox.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "mailboxName": "wiki.app",
  • "mailboxDomain": "your.domain.com",
  • "mailboxDisplayName": ""
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set inbox

Set inbox.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "inboxName": null,
  • "inboxDomain": null
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set turn

Set app turn.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
enable
boolean

Enable for if turn should be active.

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set redis

Set app turn.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
enable
boolean

Enable redis for an app.

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set env

Set app env.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
env
object

Used to set up the app environment. It is an object where the values are strings.

Responses

Request samples

Content type
application/json
{
  • "env": { }
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set storage

Set app storage.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "storageVolumeId": null,
  • "storageVolumePrefix": null
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set location

Set app location.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "ports": { },
  • "secondaryDomains": [
    ],
  • "redirectDomains": [
    ],
  • "aliasDomains": [
    ],
  • "overwriteDns": false,
  • "skipDnsSetup": false
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set mounts

Set app mounts.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "mounts": [
    ]
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Set crontab

Set app crontab.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
crontab
string or null (crontab)

The schedule in crontab format for running periodic tasks.

Responses

Request samples

Content type
application/json
{
  • "crontab": "*/15 * * * *"
}

Response samples

Content type
application/json
{ }

Set upstreamuri

Set app upstreamuri.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Request Body schema: application/json
required
upstreamUri
string (upstreamUri)

The upstream URI of the application.

Responses

Request samples

Content type
application/json
{
  • "upstreamUri": "upstream.uri.de"
}

Response samples

Content type
application/json
{ }

List app backups

List all backups for an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/backups"

Response samples

Content type
application/json
{
  • "backups": [
    ]
}

Update app backup

Update a backup for an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

backupId
required
string

Specific ID of a backup.

Request Body schema: application/json
required
label
string

A label or name for the backup.

preserveSecs
number

The number of seconds to preserve the backup.

Responses

Request samples

Content type
application/json
{
  • "label": "daily-backup",
  • "preserveSecs": 86400
}

Response samples

Content type
application/json
{ }

Download a specific backup for an app

Update a backup for an app.

Authorizations:
bearer_authquery_auth
path Parameters
appId
required
string

App ID

backupId
required
string

Specific ID of a backup.

Responses

Request samples 

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/apps/$APPID/backups/$BACKUPID/download"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get applink

Get applink

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Applink ID

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/applinks/${ID}"

Response samples

Content type
application/json
{
  • "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",
  • "upstreamUri": "https://docs.cloudron.io/",
  • "tags": [
    ],
  • "accessRestriction": {
    },
  • "icon": "< base64 encoded image >"
}

Delete applink

Delete applink The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Applink ID

Responses

Request samples 

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/applinks/$ID"

Response samples

Content type
application/json
{ }

Get icon

Get icon

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Applink ID

Responses

Response samples

Content type
application/json
{
  • "icon": [
    ]
}

App Passwords

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 App Passwords

List the App Passwords. App Passwords are personal for a user.

Authorizations:
bearer_authquery_auth
query Parameters
page
integer >= 1
Default: 1

Page number

per_page
integer >= 1
Default: 25

Items per page

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords"

Response samples

Content type
application/json
{
  • "appPasswords": [
    ]
}

Create App Password

Create an App Password

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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 mail

Responses

Request samples

Content type
application/json
{
  • "name": "Password For Nextcloud mobile app",
  • "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5"
}

Response samples

Content type
application/json
{
  • "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
  • "password": "01e536bbd289619f"
}

Get App Password

Get App Password by ID

Authorizations:
bearer_authquery_auth
path Parameters
passwordId
required
string

App Password Id

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"

Response samples

Content type
application/json
{
  • "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"
}

Delete App Password

Deletes the App Password. All future requests using this password will instantly fail.

Authorizations:
bearer_authquery_auth
path Parameters
passwordId
required
string

App Password Id

Responses

Request samples 

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"

Response samples

Content type
application/json
{ }

Backups

Handling the backups.

List backups

List backups.

Authorizations:
bearer_authquery_auth
query Parameters
page
integer >= 1
Default: 1

Page number

per_page
integer >= 1
Default: 25

Items per page

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups"

Response samples

Content type
application/json
{
  • "backups": [
    ]
}

Get Mountstatus

Get mount status of your backups.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/mount_status"

Response samples

Content type
application/json
{
  • "state": "active",
  • "message": "mounted"
}

Create backups

Create backups.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/create

Response samples

Content type
application/json
{
  • "taskId": 295
}

Clean up backups

Clean up backups.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/cleanup

Response samples

Content type
application/json
{
  • "taskId": 295
}

Remount backups

Remount backups

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/remount

Response samples

Content type
application/json
{ }

Get config

Get the configuration of your backups.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/config"

Response samples

Content type
application/json
{
  • "provider": "filesystem",
  • "format": "tgz",
  • "limits": {
    },
  • "backupFolder": "/var/backups",
  • "noHardLinks": false,
  • "encryption": null
}

Set storage

Set storage

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "provider": "filesystem",
  • "format": "tgz",
  • "password": "Your_Password",
  • "encryptedFilenames": true
}

Response samples

Content type
application/json
{ }

Get policy

Get the policy of your backups.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/backups/policy"

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Set policy

Set policy

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
schedule
string (schedule)

Backup schedule in cron format or similar.

required
object (retention)

Retention policy for backups.

Responses

Request samples

Content type
application/json
{
  • "schedule": "00 00 23 * * *",
  • "retention": {
    }
}

Response samples

Content type
application/json
{ }

Update backup

Update a backup by its ID.

Authorizations:
bearer_authquery_auth
path Parameters
backupId
required
string

Specific ID of a backup.

Request Body schema: application/json
required
label
string (properties-label)

Label for the backup.

preserveSecs
number (preserveSecs)

Number of seconds to preserve the backup.

Responses

Request samples

Content type
application/json
{
  • "label": "backupLabel",
  • "preserveSecs": 0
}

Response samples

Content type
application/json
{ }

Branding

The Branding configuration can be used to customize various aspects of the Cloudron like it's name, logo and footer.

Get Cloudron Avatar (icon)

Get the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_avatar"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Set Cloudron Avatar (icon)

Set the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.

Authorizations:
bearer_authquery_auth
Request Body schema: multipart/form-data
required
avatar
required
string <binary>

Responses

Request samples 

curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name" --form avatar=@localfilename.png

Response samples

Content type
application/json
{ }

Get Cloudron Name

Get the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name"

Response samples

Content type
application/json
{
  • "name": "string"
}

Set Cloudron Name

Set the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
name
required
string [ 1 .. 64 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{ }

Get Cloudron Background

Get the Cloudron Background.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name"

Response samples

Content type
application/json
{
  • "name": "string"
}

Set Cloudron background image

Authorizations:
bearer_authquery_auth
Request Body schema: multipart/form-data
required
background
string <binary>

The background image file to be set. If not provided, the background image will be cleared.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_background"

Response samples

Content type
application/json
{ }

Get Cloudron Footer

Get the Cloudron Footer. The Cloudron Footer is used in the Dashboard and Login pages.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/footer"

Response samples

Content type
application/json
{
  • "footer": "All Rights Reserved (c) 2010-%YEAR%"
}

Set Cloudron Footer

Set the Cloudron Footer. The Cloudron Footer is used in the Dashboard and Login pages.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
footer
required
string (Footer)

The footer is a markdown string. It can be templated with the following variables:

  • %YEAR% - the current year
  • %VERSION% - current Cloudron version

Responses

Request samples

Content type
application/json
{
  • "footer": "All Rights Reserved (c) 2010-%YEAR%"
}

Response samples

Content type
application/json
{ }

Cloudron

Cloudron Healthcheck route and various global configuration like language & timezone can be found here.

Get Status

Simple healthcheck route to check if Cloudron is running or not. This route does not require any authentication.

Responses

Request samples 

curl \
-H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/status"

Response samples

Content type
application/json
{
  • "version": "7.6.0"
}

Get Avatar (icon)

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.

Responses

Request samples 

curl \
-H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/avatar"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Cloudron background

Get the Cloudron Background.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/background"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Languages

List the available languages (translations). This route does not require any authentication.

Responses

Request samples 

curl -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/languages"

Response samples

Content type
application/json
{
  • "languages": [
    ]
}

Get Cloudron Language

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).

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/language"

Response samples

Content type
application/json
{
  • "language": "de"
}

Set Cloudron Language

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).

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
language
required
string
Default: "en"

The Language ID

Responses

Request samples

Content type
application/json
{
  • "language": "de"
}

Response samples

Content type
application/json
{ }

Get Cloudron Time Zone

TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/time_zone"

Response samples

Content type
application/json
{
  • "timeZone": "de"
}

Set Cloudron Time Zone

TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
timeZone
string
Default: "UTC"

Responses

Request samples

Content type
application/json
{
  • "timeZone": "Europe/Zurich"
}

Response samples

Content type
application/json
{ }

Dashboard

Configuration of your cloudron server.

Get config

Get config

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/dashboard/config"

Response samples

Content type
application/json
{
  • "dashboard": [
    ]
}

Set dashboard location

Set your dashboard location.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
domain
required
string

The domain where the dashboard will be located at. The my. can't be changed. With the given example it would look like this: my.example.org.

Responses

Request samples

Content type
application/json
{
  • "domain": "example.org"
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Change dashboard location

Change the location of your Cloudron dashboard.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
domain
required
string

The domain where the dashboard will be located at. The my. can't be changed. With the given example it would look like this: my.anotherExample.org.

Responses

Request samples

Content type
application/json
{
  • "domain": "anotherExample.org"
}

Response samples

Content type
application/json
{ }

Docker

Docker related configuration.

Get Private Container Registry Config

A private docker registry can be setup to pull the docker images of custom apps.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/docker/registry_config"

Response samples

Content type
application/json
{
  • "provider": "digitalocean",
  • "serverAddress": "docker.io",
  • "username": "string",
  • "email": "string",
  • "password": "string"
}

Set Private Container Registry Config

A private docker registry can be setup to pull the docker images of custom apps.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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

email
string

Email for authenticating with the Docker Registry

password
string

Password for authenticating with the Docker Registry

Responses

Request samples

Content type
application/json
{
  • "provider": "digitalocean",
  • "serverAddress": "docker.io",
  • "username": "string",
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{ }

Domains

Web addresses for accessing your server and apps. Read more about Cloudron domain settings in our knowledgebase.

Add a domain

Add a domain.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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:

Provider Description
route53 AWS Route53
bunny Bunny
cloudflare Cloudflare
digitalocean DigitalOcean
dnsimple DNSimple
gandi Gandi LiveDNS
godaddy GoDaddy
gcdns Google Cloud DNS
hetzner Hetzner
linode Linode
namecom Name.com
namecheap Namecheap
netcup Netcup
ovh OVH
porkbun Porkbun
vultr Vultr
wildcard Wildcard
manual Manual
noop No-op
object (tlsConfig)

Configuration for TLS.

object (fallbackCertificate)

Configuration for the fallback TLS certificate.

required
object

Specifies config for AWS Route53

Responses

Request samples

Content type
application/json
Example
{
  • "domain": "desec.your.domain.io",
  • "zoneName": "desec.your.domain.org",
  • "provider": "AWS Route53",
  • "tlsConfig": {
    },
  • "fallbackCertificate": {
    },
  • "config": {
    }
}

Response samples

Content type
application/json
{ }

List domains

List domains

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains"

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Sync DNS

Sync DNS.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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 mail only dns records connected to the mail server will be synchronized. If it's an empty string, it will synchronize all dns records.

Responses

Request samples

Content type
application/json
{
  • "domain": "your.domain.org",
  • "type": ""
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get domain

Get domain

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

The domain name.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN"

Response samples

Content type
application/json
{
  • "domain": "desec.your.domain.io",
  • "zoneName": "desec.your.domain.org",
  • "provider": "route53",
  • "config": { },
  • "tlsConfig": {
    },
  • "fallbackCertificate": {
    },
  • "wellKnown": {}
}

Delete domain

Delete a domain.

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

The domain name.

Responses

Request samples 

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN"

Response samples

Content type
application/json
{ }

Set domain config

Set domain config.

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

The domain name.

Request Body schema: application/json
required
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:

Provider Description
route53 AWS Route53
bunny Bunny
cloudflare Cloudflare
digitalocean DigitalOcean
dnsimple DNSimple
gandi Gandi LiveDNS
godaddy GoDaddy
gcdns Google Cloud DNS
hetzner Hetzner
linode Linode
namecom Name.com
namecheap Namecheap
netcup Netcup
ovh OVH
porkbun Porkbun
vultr Vultr
wildcard Wildcard
manual Manual
noop No-op
object (tlsConfig)

Configuration for TLS.

object (fallbackCertificate)

Configuration for the fallback TLS certificate.

required
object

Specifies config for AWS Route53

Responses

Request samples

Content type
application/json
Example
{
  • "domain": "desec.your.domain.io",
  • "zoneName": "desec.your.domain.org",
  • "provider": "AWS Route53",
  • "tlsConfig": {
    },
  • "fallbackCertificate": {
    },
  • "config": {
    }
}

Response samples

Content type
application/json
{ }

Set well known

Set well known uri's for domain.

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

The domain name.

Request Body schema: application/json
required
wellKnown
object or null (wellKnown)

A Map with the following Key and Value.

  • The Key of the map is the URI scheme as a string
  • The Value of the map is the content of the URI scheme as a string Once set, cURL https://domain/.well-known/$uri-scheme should return the content.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

Check dns records

Check if a subdomain already exists.

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

The domain name.

query Parameters
subdomain
required
string

Subdomain for the dns check.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/domains/$DOMAIN/dns_check?$SUBDOMAIN"

Response samples

Content type
application/json
{
  • "needsOverwrite": true
}

Directory Server

Directory Server Configuration

Get Directory Server Config

Get the Directory Server configuration

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/directory_server/config"

Response samples

Content type
application/json
{
  • "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 Directory Server Config

Set the Directory Server configuration

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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 # are treated as comments.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

Content type
application/json
{ }

Eventlog

Cloudron server activity can be monitored using the Eventlog API.

List Events

List events

Authorizations:
bearer_authquery_auth
query Parameters
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

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog"

Response samples

Content type
application/json
{
  • "eventlogs": [
    ]
}

Get Event

Get event by ID

Authorizations:
bearer_authquery_auth
path Parameters
eventId
required
string

Event Id

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog/$EVENT_ID"

Response samples

Content type
application/json
{
  • "id": "7f32f714-ad40-4bea-b5e5-e71562679f0c",
  • "action": "volume.add",
  • "creationTime": "2022-03-05T02:30:00.000Z",
  • "source": { },
  • "data": { }
}

External LDAP

The External Directory connector allows users from your existing LDAP or active directory to authenticate with Cloudron.

Get External Directory Config

Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/config"

Response samples

Content type
application/json
{
  • "provider": "jumpcloud",
  • "url": "docker.io",
  • "baseDn": "string",
  • "usernameField": "string",
  • "filter": "string",
  • "groupBaseDn": "string",
  • "bindDn": "string",
  • "bindPassword": "string"
}

Set External LDAP Config

Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "provider": "jumpcloud",
  • "url": "docker.io",
  • "baseDn": "string",
  • "usernameField": "string",
  • "filter": "string",
  • "groupBaseDn": "string",
  • "bindDn": "string",
  • "bindPassword": "string"
}

Response samples

Content type
application/json
{ }

Synchronize

Trigger synchronization with external LDAP server

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/sync"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Groups

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.

List groups

List groups

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups"

Response samples

Content type
application/json
{
  • "groups": [
    ]
}

Add a group

Add a group. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
name
required
string

The name of group to be added. Valid characters are alphanumerals and all printable characters.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "gid-bd6d2757-320c-4c8c-b429-b283a8bd7647",
  • "name": "developer"
}

Get group

Get group

Authorizations:
bearer_authquery_auth
path Parameters
groupId
required
string

Group ID

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups/${GROUP_ID}"

Response samples

Content type
application/json
{
  • "group": [
    ]
}

Delete group

Delete a group The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
groupId
required
string

Group ID

Responses

Request samples 

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/groups/${GROUP_ID}"

Response samples

Content type
application/json
{ }

Set members

Set members. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
groupId
required
string

Group ID

Request Body schema: application/json
required
userIds
required
Array of strings unique

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{ }

Set group name

Set group name. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
groupId
required
string

Group ID

Request Body schema: application/json
required
name
required
string

The name of the group.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{ }

Mail

Configuration for your mail domains.

Get mail domain

Get mail domain

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN

Response samples

Content type
application/json
{
  • "domain": [
    ]
}

List mail domain lists

List mail domain lists

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

query Parameters
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.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

Add mail domain list

Add a mail domain list.

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "private list",
  • "membersOnly": false,
  • "active": false,
  • "members": [
    ]
}

Response samples

Content type
application/json
{ }

Get mail domain list

Get mail domain list

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists/$NAME/

Response samples

Content type
application/json
{
  • "list": {
    }
}

Update mail domain list

Update mail domain list

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "members": [
    ],
  • "membersOnly": false,
  • "active": true
}

Response samples

Content type
application/json
{ }

Delete mail domain list

Delete mail domain list

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Responses

Request samples 

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/lists/$NAME"

Response samples

Content type
application/json
{ }

Enable mail domain

Enable mail domain

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
enabled
required
boolean

Used to enable the mail domain.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Get status

Get status

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Responses

Request samples 

curl \ 
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/status

Response samples

Content type
application/json
{
  • "status": [
    ]
}

Mail from validation

Mail from validation

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
enabled
required
boolean

Enable for validation.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Set catch all addresses

Set catch all addresses

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "addresses": [
    ]
}

Response samples

Content type
application/json
{ }

Set mail relay

Set mail relay

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "provider": "mailgun",
  • "host": "your.mailgun.host.de",
  • "port": 578,
  • "username": "mailgun_username",
  • "password": "mailgun_password",
  • "acceptSelfSignedCerts": true,
  • "forceFromAddress": true
}

Response samples

Content type
application/json
{ }

Set mail signature

Set mail signature

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
text
required
string

Your mail signature as a text.

html
string

Your mail signature as HTML.

Responses

Request samples

Content type
application/json
{
  • "text": "Warm regards, your Cloudron Team",
  • "html": "<h5> Warm regards, your Cloudron Team </h5>"
}

Response samples

Content type
application/json
{ }

Send test mail

Set test mail

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
to
required
string

The address that should recieve the test mail.

Responses

Request samples

Content type
application/json
{
  • "to": "testmail.recievier@example.org"
}

Response samples

Content type
application/json
{ }

Get mailbox count

Get mailbox count

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailbox_count

Response samples

Content type
application/json
{
  • "count": 2
}

List mailboxes

List mailboxes

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes

Response samples

Content type
application/json
{
  • "mailboxes": [
    ]
}

Add mailbox

Add mailbox

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "public",
  • "ownerId": "uid-92c322b8-c4d7-440b-a34a-54a6428233b6",
  • "ownerType": "user",
  • "active": true,
  • "storageQuota": 0,
  • "messagesQuota": 0
}

Response samples

Content type
application/json
{ }

Get Mailbox

Get Mailbox

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes/$NAME

Response samples

Content type
application/json
{
  • "mailbox": {
    }
}

Update mailbox

Update mailbox

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "ownerId": "uid-92c322b8-c4d7-440b-a34a-54a6428233b6",
  • "ownerType": "user",
  • "active": true,
  • "enablePop3": false,
  • "storageQuota": 0,
  • "messagesQuota": 0
}

Response samples

Content type
application/json
{ }

Delete Mailbox

Delete Mailbox

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Request Body schema: application/json
required
deleteMails
required
boolean

Delete all the mails of the mailbox.

Responses

Request samples

Content type
application/json
{
  • "deleteMails": false
}

Response samples

Content type
application/json
{ }

Get mailbox aliases

Get mailbox aliases

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/mail/$DOMAIN/mailboxes/$NAME/aliases

Response samples

Content type
application/json
{
  • "aliases": [
    ]
}

Set aliases

Set aliases

Authorizations:
bearer_authquery_auth
path Parameters
domain
required
string

Mail domain

name
required
string

Mailbox name

Request Body schema: application/json
required
required
Array of objects

Array of object including 'name' and 'domain'.

Responses

Request samples

Content type
application/json
{
  • "aliases": [
    ]
}

Response samples

Content type
application/json
{ }

Mailserver

Configuration, Logs and Information about the mailserver.

Get eventlogs

Get eventlogs.

Authorizations:
bearer_authquery_auth
query Parameters
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 ",".

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/eventlog"

Response samples

Content type
application/json
{
  • "eventlogs": [
    ]
}

Clear eventlogs

Clear eventlogs.

Authorizations:
bearer_authquery_auth
query Parameters
till
integer >= 1
Default: 1

Filter to give time range in which evenlogs should be cleared.

Responses

Request samples 

curl -X POST\
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/clear_eventlog"

Response samples

Content type
application/json
{ }

Get location

Get mailserver location.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/location"

Response samples

Content type
application/json
{
  • "domain": "your.domain.de",
  • "subdomain": "mailserver"
}

Set location

Set the location of the mailserver.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
domain
required
string

Domain of your mailserver.

subdomain
required
string

Subdomain of your mailserver.

Responses

Request samples

Content type
application/json
{
  • "domain": "your.domain.de",
  • "subdomain": "mailserver"
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get max email size

Get the max size for an email.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/max_email_size"

Response samples

Content type
application/json
{
  • "size": 2317823
}

Set max email size

Set the max size for an email.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
size
required
number

Maximum size for an email.

Responses

Request samples

Content type
application/json
{
  • "size": 321894
}

Response samples

Content type
application/json
{ }

Get spam acl

Get spam ACL.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/spam_acl"

Response samples

Content type
application/json
{
  • "whitelist": [
    ],
  • "blacklist": [
    ]
}

Set spam acl

Set spam acl.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "blacklist": [
    ]
}

Response samples

Content type
application/json
{ }

Get spam custom config

Get spam custom config.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/spam_custom_config"

Response samples

Content type
application/json
{
  • "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

Set spam custom config.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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:

Line Explanation
header TO_ADDRESS_TO_BLOCK To =~ /^(mail@your.domain\\.io|mail@your.domain\\.org)$/i Defines a rule to block emails sent to specific addresses using a case-insensitive regex pattern.
score TO_ADDRESS_TO_BLOCK 10.0 Assigns a spam score of 10.0 to emails that match the rule TO_ADDRESS_TO_BLOCK.
describe TO_ADDRESS_TO_BLOCK Emails sent to blocked addresses are likely spam. Provides a human-readable explanation of the rule's purpose, indicating that emails sent to blocked addresses are likely spam.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

Content type
application/json
{ }

Get DNSBL config

Get the "Domain Name Sytem Blacklist" configurations.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/dnsbl_config"

Response samples

Content type
application/json
{
  • "zones": [
    ]
}

Set DNSBL config

Set the "Domain Name Sytem Blacklist" configurations.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "zones": [
    ]
}

Response samples

Content type
application/json
{ }

Get Solr config

Check if solr is enabled or not.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/solr_config"

Response samples

Content type
application/json
{
  • "enabled": true
}

Set Solr config

Enable or disable solr.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
enabled
required
boolean

Information if solr is enabled or not.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Get mailbox sharing

Check if mailbox sharing is enabled or not.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/mailbox_sharing"

Response samples

Content type
application/json
{
  • "enabled": true
}

Set mailbox sharing

Enable or disable mailbox sharing.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
enabled
required
boolean

Information if mailbox sharing is enabled or not.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Get virtual all mail

Check if virtual all mail is enabled or not.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/virtual_all_mail"

Response samples

Content type
application/json
{
  • "enabled": true
}

Set virtual all mail

Enable or disable virtual all mail.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
enabled
required
boolean

Information if virtual all mail is enabled or not.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Get usage

Get usage.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/mailserver/usage"

Response samples

Content type
application/json
{
  • "name@maildomain.de": {
    }
}

Network

Networking and Firewall related configuration.

Get Block List

Gets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/blocklist"

Response samples

Content type
application/json
{
  • "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}

Set Block List

Sets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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 # are treated as comments.

Responses

Request samples

Content type
application/json
{
  • "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}

Response samples

Content type
application/json
{ }

Get Dynamic DNS

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).

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/dynamic_dns"

Response samples

Content type
application/json
{
  • "enabled": true
}

Set Dynamic DNS

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).

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{ }

Get IPv4 Config

Get the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4_config"

Response samples

Content type
application/json
Example
{
  • "provider": "noop"
}

Set IPv4 Config

Set the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
provider
required
string

The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:

  • noop - Disable setting DNS record
  • fixed - Use static IP for DNS records
  • interface - Use the IP address attached to the interface for DNS records
  • generic - Automatically detect public IP by calling cloudron.io

Responses

Request samples

Content type
application/json
Example
{
  • "provider": "noop"
}

Response samples

Content type
application/json
{ }

Get IPv6 Config

Get the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6_config"

Response samples

Content type
application/json
Example
{
  • "provider": "noop"
}

Set IPv6 Config

Set the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
provider
required
string

The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:

  • noop - Disable setting DNS record
  • fixed - Use static IP for DNS records
  • interface - Use the IP address attached to the interface for DNS records
  • generic - Automatically detect public IP by calling cloudron.io

Responses

Request samples

Content type
application/json
Example
{
  • "provider": "noop"
}

Response samples

Content type
application/json
{ }

Get IPv4 Address

Gets the configured IPv4 address of the server

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4"

Response samples

Content type
application/json
{
  • "ip": "5.75.134.144"
}

Get IPv6 Address

Gets the configured IPv6 address of the server

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6"

Response samples

Content type
application/json
{
  • "ip": "2402:3a80:423:eb84:d72e:b50:7c58:83eb"
}

Notifications

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

List notifications

Authorizations:
bearer_authquery_auth
query Parameters
page
integer >= 1
Default: 1

Page number

per_page
integer >= 1
Default: 25

Items per page

acknowledged
boolean

Filter by acknowledged status

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Notification

Get notification by ID

Authorizations:
bearer_authquery_auth
path Parameters
notificationId
required
string

Notification Id

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications/$NOTIFICATION_ID"

Response samples

Content type
application/json
{
  • "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
}

Update Notification

Set notification acknowledged state. Unacknowledged notifications count appears in the navbar of the Dashboard.

Authorizations:
bearer_authquery_auth
path Parameters
notificationId
required
string

Notification Id

Request Body schema: application/json
required
acknowledged
required
boolean

Set notification to acknowledged or not

Responses

Request samples

Content type
application/json
{
  • "acknowledged": true
}

Response samples

Content type
application/json
{ }

OIDC

OpenID Connect. It allows clients to verify the identity of end-users based on the authentication performed by an authorization server.

List oidc clients

List the existing OpenID Connect Clients.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients"

Response samples

Content type
application/json
{
  • "clients": [
    ]
}

Add oidc client

Add an oidc client to your Cloudron.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "name": "Test Client",
  • "loginRedirectUri": "your.oidc.uri.org",
  • "tokenSignatureAlgorithm": "EdDSA"
}

Response samples

Content type
application/json
{
  • "id": "cid-6c4e2bc962b7e90b45b400224772cec7",
  • "secret": "9cefe41f9cbd8aabe44da60d3827d45779fd233bbfdc0f381228564dsaasd5",
  • "appId": "",
  • "name": "Test Client",
  • "loginRedirectUri": "your.oidc.uri.org",
  • "tokenSignatureAlgorithm": "EdDSA"
}

Get oidc client

Get a specific OpenID Connect Clients.

Authorizations:
bearer_authquery_auth
path Parameters
clientId
required
string

ID of an OpenID Connect Client.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients/$CLIENTID"

Response samples

Content type
application/json
{
  • "id": "cid-6c4e2bc962b7e90b45b400224772cec7",
  • "secret": "9cefe41f9cbd8aabe44da60d3827d45779fd233bbfdc0f381228564dsaasd5",
  • "appId": "",
  • "name": "Test Client",
  • "loginRedirectUri": "your.oidc.uri.org",
  • "tokenSignatureAlgorithm": "EdDSA"
}

Update oidc client

Update OpenID Connect Client.

Authorizations:
bearer_authquery_auth
path Parameters
clientId
required
string

ID of an OpenID Connect Client.

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "name": "Test Client",
  • "loginRedirectUri": "your.oidc.uri.org",
  • "tokenSignatureAlgorithm": "EdDSA"
}

Response samples

Content type
application/json
{ }

Delete oidc client

Delete a specific OpenID Connect Clients.

Authorizations:
bearer_authquery_auth
path Parameters
clientId
required
string

ID of an OpenID Connect Client.

Responses

Request samples 

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/clients/$CLIENTID"

Response samples

Content type
application/json
{ }

Destroy user session

Destroy user session.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/oidc/sessions"

Response samples

Content type
application/json
{ }

Profile

User's profile information

Get Profile

Get the authenticated user's profile

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile"

Response samples

Content type
application/json
{
  • "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 Profile

Update user's profile information

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
email
string

Unique email address

fallbackEmail
string

Unique fallback email address. This is the address password reset is sent to. This requires the password field to be set to the user's current password.

password
string

When trying to change the fallbackEmail, set this field to the user's current password

displayName
string

Full name of the user

Responses

Request samples

Content type
application/json
{
  • "email": "goat@football.com",
  • "fallbackEmail": "goat@soccer.com",
  • "password": "string",
  • "displayName": "Lionel Messi"
}

Response samples

Content type
application/json
{ }

Update Avatar (icon)

Update user's avatar (icon)

Authorizations:
bearer_authquery_auth
Request Body schema:
required
avatar
required
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{ }

Get Custom Avatar (icon)

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.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User Id

Responses

Request samples 

curl "https://$CLOUDRON_DOMAIN/api/v1/profile/avatar/$USER_ID"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Background Image

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.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/backgroundImage"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Set Background Image (icon)

Set the user's background image for the dashboard

Authorizations:
bearer_authquery_auth
Request Body schema: multipart/form-data
required
backgroundImage
required
string <binary>

Responses

Request samples 

curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/background_image" --form backgroundImage=@localfilename.png

Response samples

Content type
application/json
{ }

Update Password

Update user's password

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
password
required
string

Current password

newPassword
required
string

New password

Responses

Request samples

Content type
application/json
{
  • "password": "current_password",
  • "newPassword": "new_password"
}

Response samples

Content type
application/json
{ }

Set 2FA Secret

Sets 2FA Secret. Enabling 2FA is a two step process:

  • Call this endpoint to generate a secret. The response contains the secret and a qrcode
  • Call the Enable 2FA endpoint with a TOTP Token (generated off the above secret)
Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/twofactorauthentication_secret"

Response samples

Content type
application/json
{
  • "secret": "string",
  • "qrcode": "string"
}

Enable 2FA

Enables Two Factor Authentication. Enabling 2FA is a two step process:

  • Call the Set 2FA Secret endpoint to generate a secret. The response contains the secret and a qrcode
  • Call this endpoint with a TOTP Token (generated off the above secret) to enable 2FA
Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
totpToken
required
string

Current TOTP Token based off the generate secret

Responses

Request samples

Content type
application/json
{
  • "totpToken": "string"
}

Response samples

Content type
application/json
{ }

Disable 2FA

Disable 2FA

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
password
required
string

Current password

Responses

Request samples

Content type
application/json
{
  • "password": "current_password"
}

Response samples

Content type
application/json
{ }

Provision

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.

Configure inital domain

API endpoint to configure domain settings. To read more about the existing domain provider and their domain configs inside the Domain Route.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
object
ipv4Config
object

IPv4 configuration settings.

ipv6Config
object

IPv6 configuration settings.

Responses

Request samples

Content type
application/json
{
  • "domainConfig": {
    },
  • "ipv4Config": { },
  • "ipv6Config": { }
}

Response samples

Content type
application/json
{ }

Restore from backup

Resotre

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "backupConfig": {
    },
  • "encryptedFilenames": true,
  • "remotePath": "s3://mybucket/backups/",
  • "version": "1.0.0",
  • "ipv4Config": { },
  • "ipv6Config": { },
  • "skipDnsSetup": false
}

Response samples

Content type
application/json
{ }

Create admin

Activate your provision.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

email
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.

Responses

Request samples

Content type
application/json
{
  • "username": "john_doe",
  • "password": "securePassword123!",
  • "email": "john.doe@example.com",
  • "displayName": "John Doe"
}

Response samples

Content type
application/json
{
  • "userId": "123456789",
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvbiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expires": "2024-12-31T23:59:59Z"
}

Reverse Proxy

The Reverse Proxy manages the nginx config and TLS certificates.

Renew Certs

Trigger manual renewal of Let's encrypt certificates. Note that certs are automatically renewed by Cloudron, 1 month before their expiry.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
optional
rebuild
boolean
Default: false

When set all the nginx configurations are regenerated.

Responses

Request samples

Content type
application/json
{
  • "rebuild": false
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get Trusted IPs

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.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/reverseproxy/trusted_ips"

Response samples

Content type
application/json
{
  • "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}

Set Trusted IPs

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.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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 # are treated as comments.

Responses

Request samples

Content type
application/json
{
  • "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}

Response samples

Content type
application/json
{ }

Services

Services that are used on your Cloudron instance such as 'mail', 'mysql' and way more.

List services

List services

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services"

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Get platform status

Get platform status

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services"

Response samples

Content type
application/json
{
  • "message": "Ready"
}

Get service

Get information about a service.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE"

Response samples

Content type
application/json
Example
{
  • "name": "mail",
  • "status": "active",
  • "memoryUsed": 755478528,
  • "memoryPercent": 17,
  • "error": null,
  • "healthcheck": {
    },
  • "config": { },
  • "defaultMemoryLimit": 536870912
}

Configure service

This call is used to configure a service.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

Request Body schema: application/json
required
memoryLimit
required
number

Limits the available memory. The unit used here is bytes.

recoveryMode
required
boolean

Enables or disables the recovery mode.

Responses

Request samples

Content type
application/json
{
  • "memoryLimit": 4294967296,
  • "recoveryMode": false
}

Response samples

Content type
application/json
{ }

Get service graphs

Get graphs of the service

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

query Parameters
fromMinutes
required
number

Filter by minutes.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/graphs?fromMinutes=10"

Response samples

Content type
application/json
{
  • "cpu": [ ],
  • "memory": [ ],
  • "blockRead": [ ],
  • "blockWrite": [ ],
  • "networkRead": [ ],
  • "networkWrite": [ ],
  • "blockReadTotal": 0,
  • "blockWriteTotal": 0,
  • "networkReadTotal": 0,
  • "networkWriteTotal": 0,
  • "cpuCount": 4
}

Download service logs

Download logs of a service.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

query Parameters
lines
required
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/logs/?lines=10&format=json"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Service logstream

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.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

query Parameters
lines
required
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Request samples 

curl \
-H "Accept: text/event-stream" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/logstream?lines=100"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Restart service

Restart a service.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/restart"

Response samples

Content type
application/json
{ }

Rebuild service

Rebuild a service.

Authorizations:
bearer_authquery_auth
path Parameters
service
required
string

Service name

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/services/$SERVICE/rebuild"

Response samples

Content type
application/json
{ }

System

Server related information.

Get system info

Get system information.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/info"

Response samples

Content type
application/json
{
  • "sysVendor": "ACME Inc.",
  • "productName": "Server",
  • "uptimeSecs": 3600,
  • "rebootRequired": false,
  • "activationTime": "2024-05-15T08:00:00Z"
}

Reboot

Reboots the server immediately.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/reboot"

Response samples

Content type
application/json
{ }

Get cpus

Get information of your sytem cpus.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/cpus"

Response samples

Content type
application/json
{
  • "cpus": [
    ]
}

Get Disk Usage

Get information about disk usage for apps and other system components, like mail storage and docker images.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/disk_usage"

Response samples

Content type
application/json
{
  • "usage": {
    }
}

Update Disk Usage

Disk usage is only updated automatically once per day. This API allows to trigger an update of that information.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/disk_usage"

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get block devices

Get information of your sytem block devices.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/block_devices"

Response samples

Content type
application/json
{
  • "devices": [
    ]
}

Get memory

Get information of your sytems memory.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/memory"

Response samples

Content type
application/json
{
  • "memory": 32423423,
  • "swap": 32123442
}

Download system logs

Download the system logs.

Authorizations:
bearer_authquery_auth
path Parameters
unit
required
number

Unit for the logs.

query Parameters
lines
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/logs/$UNIT/?lines=10&format=json"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get logstream

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.

Authorizations:
bearer_authquery_auth
path Parameters
unit
required
number

Unit for the logs.

query Parameters
lines
number

Last lines displayed.

format
string
Default: "json"
Enum: "json" "short"

Defines the format of the logs.

Responses

Request samples 

curl \
-H "Accept: text/event-stream" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/logstream/$UNIT?lines=100"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Tasks

Tasks are asynchronous operations performed in the background. Each task can be monitored separately using the task id.

List Tasks

List tasks

Authorizations:
bearer_authquery_auth
query Parameters
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

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks"

Response samples

Content type
application/json
{
  • "tasks": [
    ]
}

Get Task

Get task by ID

Authorizations:
bearer_authquery_auth
path Parameters
taskId
required
string

Task Id

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID"

Response samples

Content type
application/json
{
  • "id": "364",
  • "type": "cleanBackups",
  • "percent": 1,
  • "message": "Checking expired certs for removal",
  • "error": {
    },
  • "active": true,
  • "pending": true,
  • "creationTime": "2023-09-07T13:18:35.000Z",
  • "result": { },
  • "ts": "2023-09-07T13:18:35.000Z",
  • "success": true
}

Get Task Logs

Get task logs. Use this end point to download logs. If you want to follow logs tail -f style, use the logstream endpoint instead.

Authorizations:
bearer_authquery_auth
path Parameters
taskId
required
string

Task Id

query Parameters
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

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logs?lines=100"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Get Task Logs Stream

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.

Authorizations:
bearer_authquery_auth
path Parameters
taskId
required
string

Task Id

query Parameters
lines
integer
Default: 10

Number of lines in the log

Responses

Request samples 

curl -H "Accept: text/event-stream" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logstream?lines=100"

Response samples

Content type
application/json
{
  • "status": "HTTP Status Message",
  • "message": "Something bad happenned"
}

Stop Task

Stops a task

Authorizations:
bearer_authquery_auth
path Parameters
taskId
required
string

Task Id

Responses

Request samples 

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASK_ID/stop"

Response samples

Content type
application/json
{ }

Tokens

Tokens are used for API authentication.

List Tokens

List the API tokens created by the user. Note that tokens are personal (per user) and not global.

Authorizations:
bearer_authquery_auth
query Parameters
page
integer >= 1
Default: 1

Page number

per_page
integer >= 1
Default: 25

Items per page

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens"

Response samples

Content type
application/json
{
  • "tokens": [
    ]
}

Create Token

Create an API token

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "name": "Token For Automation",
  • "expiresAt": 1725615073184,
  • "scope": {
    }
}

Response samples

Content type
application/json
{
  • "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": {
    }
}

Get Token

Get token by ID

Authorizations:
bearer_authquery_auth
path Parameters
tokenId
required
string

Token Id

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"

Response samples

Content type
application/json
{
  • "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": {
    }
}

Delete Token

Deletes the Token. All future requests using this token will instantly fail.

Authorizations:
bearer_authquery_auth
path Parameters
tokenId
required
string

Token Id

Responses

Request samples 

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"

Response samples

Content type
application/json
{ }

Updater

Updater checks and manages updates of the apps and the platform.

Get Pending Updates

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.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/updates"

Response samples

Content type
application/json
{
  • "updates": {
    }
}

Check for updates

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.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/check_for_updates"

Response samples

Content type
application/json
{
  • "updates": {
    }
}

Update Cloudron

Updates Cloudron to the next available release. The update is started asynchronously and can be monitored using the tasks API.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
optional
skipBackup
boolean
Default: false

Whether backup should be skipped before performing the update.

Responses

Request samples

Content type
application/json
{
  • "skipBackup": false
}

Response samples

Content type
application/json
{
  • "taskId": 295
}

Get Update Schedule

Get the automatic update schedule

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/autoupdate_pattern"

Response samples

Content type
application/json
{
  • "pattern": "00 00 1,3,5,23 * * *"
}

Set Update Schedule

Sets the automatic update schedule

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
pattern
required
string (CronPattern)

Automatic update pattern in cron format.

Responses

Request samples

Content type
application/json
{
  • "pattern": "00 00 1,3,5,23 * * *"
}

Response samples

Content type
application/json
{ }

Users

Add, update and remove users from Cloudron User Directory.

List users

List users

Authorizations:
bearer_authquery_auth
query Parameters
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.

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users"

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Add a user

Add a user. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
email
required
string
username
password
string

Password used for the user.

displayName
role
string
Enum: "owner" "admin" "usermanager" "mailmanager" "user"

See user roles for more information on each role.

fallbackEmail

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "username": "string",
  • "password": "string",
  • "displayName": "string",
  • "role": "owner",
  • "fallbackEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc"
}

Get user

Get user

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID

Response samples

Content type
application/json
{
  • "id": "uid-3f07b9e7-8cf2-494b-95cc-93dd05fc5bbc",
  • "username": "helena",
  • "email": "example@cloudron.io",
  • "fallbackEmail": "fallback@example.com",
  • "displayName": "Helena Mamchuk",
  • "groupIds": [
    ],
  • "active": true,
  • "source": "string",
  • "role": "string",
  • "twoFactorAuthenticationEnabled": true,
  • "inviteAccepted": true
}

Delete user

Delete a user. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Responses

Request samples 

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID"

Response samples

Content type
application/json
{ }

Set a user's role

Set user role. Users can't set roles for themselves. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
role
string
Enum: "owner" "admin" "usermanager" "mailmanager" "user"

See user roles for more information on each role.

Responses

Request samples

Content type
application/json
{
  • "role": "owner"
}

Response samples

Content type
application/json
{ }

Set active

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.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
active
required
boolean

Specify whether the user is active or not.

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{ }

Update user

Update user. Username can only be updated when the user has no existing username!

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
email
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.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "displayName": "string",
  • "fallbackEmail": "string"
}

Response samples

Content type
application/json
{ }

Set password

Set password

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
password
string

User's password.

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{ }

Impersonate a user

Impersonate a user. You require the 'admin' role to use that call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
password
required
string

Temporary password

expiresAt
integer
Default: "6 * 60 * 60 * 1000; // 6 hours"

Time until password expires in miliseconds.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "expiresAt": 1725615073184
}

Response samples

Content type
application/json
{ }

Set user group

Set user group. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
groupIds
required
Array of strings unique

Array of groupIds

Responses

Request samples

Content type
application/json
{
  • "groupIds": [
    ]
}

Response samples

Content type
application/json
{ }

Send password reset email

Send password reset email. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{ }

Send invite email

Send invite email. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Request Body schema: application/json
required
email
required
string

The email address, that should receive the invite link.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{ }

Disable 2FA

Disable 2FA. The role 'user-manager' is required to make this api call.

Authorizations:
bearer_authquery_auth
path Parameters
userId
required
string

User ID

Responses

Request samples 

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/users/$USER_ID/twofactorauthentication_disable"

Response samples

Content type
application/json
{ }

User Directory

Settings & Configuration for Cloudron User Directory.

Get profile config

Get the current profile configuration for all users in the user directory.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/user_directory/profile_config"

Response samples

Content type
application/json
{
  • "lockUserProfiles": true,
  • "mandatory2FA": true
}

Set profile config

Set the current profile configuration for all users in the user directory.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
lockUserProfiles
required
boolean

If profile changes by users is disabled

mandatory2FA
required
boolean

If two factor authentication for all users is enforced

Responses

Request samples

Content type
application/json
{
  • "lockUserProfiles": true,
  • "mandatory2FA": true
}

Response samples

Content type
application/json
{ }

Volumes

Definition of storage volumes including their properties and configurations.

Add volume

Add volume. Note that the data in the cURL has to be adjusted based on the mountType.

Authorizations:
bearer_authquery_auth
Request Body schema: application/json
required
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.

  • cifs: Network file system protocol commonly used for sharing files and printers in a network.
  • filesystem: Refers to the type of volume that is mounted directly from the local filesystem.
  • ext4: A filesystem type recognized for its performance, scalability, and support for large file sizes and partitions.
  • mountpoint: Represents a location in the filesystem hierarchy where a volume is mounted.
  • nfs: Network File System, a distributed file system protocol allowing a user on a client computer to access files over a network as if the files were locally stored.
  • sshfs: SSH Filesystem, a network file system protocol built on the Secure Shell protocol.
  • xfs: Another type of filesystem known for its scalability and high-performance features.
required
object

Specifies extra settings for mounting a filesystem. Needed properties vary based on the mountType.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Main Volume",
  • "mountType": "cifs",
  • "mountOptions": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1af5f811fddb4337ac5f71b0989c1d30"
}

List volumes

List volumes

Authorizations:
bearer_authquery_auth

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes"

Response samples

Content type
application/json
{
  • "volumes": [
    ]
}

Get volume

Get volume

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

Responses

Request samples 

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID"

Response samples

Content type
application/json
{
  • "id": "1af5f811fddb4337ac5f71b0989c1d30",
  • "name": "Main Volume",
  • "hostPath": "/mnt/volumes/",
  • "creationTime": "2024-03-20T18:00:48.000Z",
  • "mountType": "cifs",
  • "mountOptions": {
    }
}

Update volume

Update volume. A volume can only be updated when it has the mount type CIFS, NFS or SSHFS.

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

Request Body schema: application/json
required
One of
required
object

Specifies extra settings for mounting a filesystem. Needed properties vary based on the mountType.

Responses

Request samples

Content type
application/json
Example
{
  • "mountOptions": {
    }
}

Response samples

Content type
application/json
{ }

Delete volume

Delete volume

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

Responses

Request samples 

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID"

Response samples

Content type
application/json
{ }

Get volume status

Get volume status

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

Responses

Request samples 

curl \ 
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/status"

Response samples

Content type
application/json
{
  • "state": "active",
  • "message": "mounted"
}

Remount volume

Remount volume

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

Responses

Request samples 

curl -X POST \
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/remount"

Response samples

Content type
application/json
{ }

Get a file from volume

Get a file located on a volume.

Authorizations:
bearer_authquery_auth
path Parameters
id
required
string

Volume ID

filename
required
string

Name of a file located on the volume

Responses

Request samples 

curl \ 
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/volumes/$ID/files/$FILENAME"

Response samples

Content type
text/plain
This is the content of the file.
It may contain multiple lines.
Line 3...
Line 4...