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

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

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
}

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

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

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

User Directory

Users & Groups Configuration

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