Cloudron API (1.0.0)

Download OpenAPI specification:Download

Cloudron provides a RESTful API to manage all aspects of the Cloudron like adding users, configuring groups and installing apps.

If you are an app developer, the Cloudron CLI tool implements a workflow that allows you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.

The access token can be provided via the request query ?access_token=<token> or the token can be provided via the Authorization header using Bearer <token>.

Developer login

Set username to your username and password to your password. Currently, only Cloudron administrators can create API tokens.

Request Body schema: application/json
username
required
string
password
required
string

Responses

200

OK

post /developer/login
https://my.example.com/api/v1/developer/login

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "username": "julia",
  • "password": "supersecret"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "sometoken",
  • "expiresAt": "ISO-8601 UTC date"
}

Get Config

This config object contains the platform configuration.

Responses

200

OK

get /config
https://my.example.com/api/v1/config

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "apiServerOrigin": "https://api.cloudron.io",
  • "webServerOrigin": "https://cloudron.io",
  • "adminDomain": "example.com",
  • "adminFqdn": "my.example.com",
  • "mailFqdn": "my.example.com",
  • "version": "4.1.2",
  • "isDemo": false,
  • "provider": "digitalocean",
  • "cloudronName": "My Cloudron",
  • "uiSpec": { }
}

List Domains

Get all domains

Responses

200

OK

get /domains
https://my.example.com/api/v1/domains

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "domains": [ ]
}

Add Domain

Add a new domain

Request Body schema: application/json
domain
required
string
provider
required
string (DnsProvider)
Enum: "route53" "cloudflare" "digitalocean" "gandi" "godaddy" "gcdns" "namecom" "namecheap" "wildcard" "manual" "noop"
config
required
object

Provider specific config. May include username and api tokens

hyphenatedSubdomains
boolean
wildcard
boolean
zoneName
string
fallbackCertificate
object
tlsConfig
object (TlsConfig)

Responses

201

OK

400

Invalid fields or provider credentials

409

Conflict. Domain already exists.

post /domains
https://my.example.com/api/v1/domains

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "domain": "example.com",
  • "provider": "cloudflare",
  • "config": { },
  • "hyphenatedSubdomains": true,
  • "wildcard": true,
  • "zoneName": "string",
  • "fallbackCertificate":
    {
    },
  • "tlsConfig":
    {
    }
}

Get Domain

path Parameters
domain
required
string

Domain

Responses

200

OK

get /domains/{domain}
https://my.example.com/api/v1/domains/{domain}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "domain": "cloud.example.com",
  • "zoneName": "example.com",
  • "provider": "cloudflare",
  • "config":
    {
    },
  • "tlsConfig":
    {
    },
  • "fallbackCertificate":
    {
    },
  • "locked": false
}

Update Domain

path Parameters
domain
required
string

Domain

Request Body schema: application/json
provider
required
string (DnsProvider)
Enum: "route53" "cloudflare" "digitalocean" "gandi" "godaddy" "gcdns" "namecom" "namecheap" "wildcard" "manual" "noop"
config
required
object

Provider specific config. May include username and api tokens

hyphenatedSubdomains
boolean
wildcard
boolean
zoneName
string
fallbackCertificate
object
tlsConfig
object (TlsConfig)

Responses

204

OK

400

Invalid fields or provider credentials

put /domains/{domain}
https://my.example.com/api/v1/domains/{domain}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "cloudflare",
  • "config": { },
  • "hyphenatedSubdomains": true,
  • "wildcard": true,
  • "zoneName": "string",
  • "fallbackCertificate":
    {
    },
  • "tlsConfig":
    {
    }
}

Remove Domain

path Parameters
domain
required
string

Domain

Responses

204

OK

409

Conflict. The domain is still in use

delete /domains/{domain}
https://my.example.com/api/v1/domains/{domain}

Check DNS Records

path Parameters
domain
required
string

Domain

query Parameters
subdomain
string

The subdomain to check the DNS record for

Responses

200

OK

get /domains/{domain}/dns_check
https://my.example.com/api/v1/domains/{domain}/dns_check

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "needsOverwrite": false
}

Get Dynamic DNS State

Responses

200

OK

get /settings/dynamic_dns
https://my.example.com/api/v1/settings/dynamic_dns

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "enabled": false
}

Set Dynamic DNS State

Request Body schema: application/json
enabled
required
boolean

Responses

200

OK

post /settings/dynamic_dns
https://my.example.com/api/v1/settings/dynamic_dns

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "enabled": false
}

Get Unstable Apps State

Responses

200

OK

get /settings/unstable_apps
https://my.example.com/api/v1/settings/unstable_apps

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "enabled": false
}

Set Unstable Apps State

Request Body schema: application/json
enabled
required
boolean

Responses

200

OK

post /settings/unstable_apps
https://my.example.com/api/v1/settings/unstable_apps

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "enabled": false
}

Get Backup Config

Responses

200

OK

get /settings/backup_config
https://my.example.com/api/v1/settings/backup_config

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "s3",
  • "format": "rsync",
  • "retentionSecs": 604800,
  • "intervalSecs": 1,
  • "key": "string",
  • "syncConcurrency": 5,
  • "acceptSelfSignedCerts": false,
  • "backupFolder": "string",
  • "noHardlinks": true,
  • "externalDisk": true,
  • "accessKeyId": "string",
  • "secretAccessKey": "string",
  • "signatureVersion": "string",
  • "endpoint": "string",
  • "region": "string",
  • "bucket": "string",
  • "prefix": "string",
  • "projectId": "string",
  • "credentials":
    {
    }
}

Set Backup Config

Request Body schema: application/json
provider
string
Enum: "s3" "gcs" "filesystem" "minio" "s3-v4-compat" "digitalocean-spaces" "exoscale-sos" "wasabi" "scaleway-objectstorage" "noop"
format
string (BackupFormat)
Enum: "rsync" "targz"
retentionSecs
integer

Maximum time to keep backups in seconds (1 week is 604800 seconds)

intervalSecs
integer >= 21600

Interval for automatic backups in seconds. Must be atleast 6 hours (21600 seconds)

key
string

Encyrption key. May contain a placeholder string to not leak the key

syncConcurrency
integer >= 1
acceptSelfSignedCerts
boolean
backupFolder
string

only for filesystem provider

noHardlinks
boolean

only for filesystem provider

externalDisk
boolean

only for filesystem provider

accessKeyId
string

only for S3 style provider

secretAccessKey
string

only for S3 style provider

signatureVersion
string

only for S3 style provider

endpoint
string

only for S3 style provider

region
string

only for S3 style provider

bucket
string

only for S3 and gcs style provider

prefix
string

only for S3 and gcs style provider

projectId
string

only for gcs provider

credentials
object

only for gcs provider

Responses

200

OK

post /settings/backup_config
https://my.example.com/api/v1/settings/backup_config

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "s3",
  • "format": "rsync",
  • "retentionSecs": 604800,
  • "intervalSecs": 1,
  • "key": "string",
  • "syncConcurrency": 5,
  • "acceptSelfSignedCerts": false,
  • "backupFolder": "string",
  • "noHardlinks": true,
  • "externalDisk": true,
  • "accessKeyId": "string",
  • "secretAccessKey": "string",
  • "signatureVersion": "string",
  • "endpoint": "string",
  • "region": "string",
  • "bucket": "string",
  • "prefix": "string",
  • "projectId": "string",
  • "credentials":
    {
    }
}

Get Platform Config

Responses

200

OK

get /settings/platform_config
https://my.example.com/api/v1/settings/platform_config

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "mysql":
    {
    },
  • "postgresql":
    {
    },
  • "mail":
    {
    },
  • "mongodb":
    {
    }
}

Set Platform Config

Request Body schema: application/json
mysql
object (AddonConfig)
postgresql
object (AddonConfig)
mail
object (AddonConfig)
mongodb
object (AddonConfig)

Responses

200

OK

post /settings/platform_config
https://my.example.com/api/v1/settings/platform_config

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "mysql":
    {
    },
  • "postgresql":
    {