Cloudron API (1.0.0)

Download OpenAPI specification:Download

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.

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": 1,
  • "enableRedis": 1,
  • "checklist": { },
  • "enableMailbox": true,
  • "mailboxDisplayName": "",
  • "mailboxName": "wiki.app",
  • "mailboxDomain": "your.domain.com",
  • "enableInbox": false,
  • "inboxName": null,
  • "inboxDomain": null,
  • "accessLevel": "Admin"
}

Get app icon

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
{