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. Unauthorized API call
403 Forbidden. Authorized but operation not permitted
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 create 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

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
{ }

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 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 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": [
    ]
}

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
{ }

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 -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
{ }

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
{ }

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
{ }

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/tasks/$TASKS_ID/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.

Is Reboot Required

Checks whether a server reboot is required. Automatic Ubuntu updates often requires a reboot to apply changes to system libraries.

Authorizations:
bearer_authquery_auth

Responses

Request samples 

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

Response samples

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

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 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
}

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