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

Cloudron

Initial DNS Setup

Public route and very first call to setup the dashboard domain.

This call has to be made against the raw IP address (eg. https://1.2.3.4 ) accepting self-signed certificates.

A curl example could look like:
curl -k -X POST -H 'Content-Type: application/json' --data '{...}' http://1.2.3.4/api/v1/cloudron/setup

Once called, the process can be tracked through the setup object in the /api/v1/cloudron/status API reply. After the status API returns a success, future API requests must be made to https://my.domain.com.

This routes gets disabled once the Cloudron has been activated.

Request Body schema: application/json
dnsConfig
required
object

Responses

200

OK

post /cloudron/setup
https://my.example.com/api/v1/cloudron/setup

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{ }

Get status

Public route to get status information for this Cloudron.

Responses

200

OK

get /cloudron/status
https://my.example.com/api/v1/cloudron/status

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "version": "5.1.0",
  • "apiServerOrigin": "https://api.cloudron.io",
  • "webServerOrigin": "https://cloudron.io",
  • "provider": "linode",
  • "cloudronName": "My Space",
  • "footer": "&copy; 2020 &nbsp; [Cloudron](https://cloudron.io) &nbsp; &nbsp; &nbsp; [Forum <i class=\"fa fa-comments\"></i>](https://forum.cloudron.io)",
  • "adminFqdn": "my.example.com",
  • "activated": true,
  • "setup":
    {
    },
  • "restore":
    {
    }
}

Activate

Public route to activate the Cloudron. This creates the first user (aka owner) account.

Before installing apps, the Cloudron must be registered with a valid Appstore account as well using the 'Register Cloudron' route.

Request Body schema: application/json
username
required
string

Username. The first user is also called the Owner.

password
required
string

Password. Minimum of 8 characters required.

email
required
string

Primary email of the user.

displayName
string

Full name of the user.

Responses

201

OK

post /cloudron/activate
https://my.example.com/api/v1/cloudron/activate

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "username": "oksana",
  • "password": "strongPa55word!?",
  • "email": "oksane@example.com",
  • "displayName": "Oksana Muller"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId": "uid-e08ca116-d3e5-43c9-b43f-6eb990be58ea",
  • "token": "sometoken",
  • "expires": "ISO-8601 UTC date"
}

Restore

Public route to restore a whole Cloudron from backup. This is only available until the Cloudron is activated.

Request Body schema: application/json
backupConfig
required
object (BackupConfig)
backupId
required
string
version
required
string
sysinfoConfig
object (SysinfoConfig)

Responses

200

OK

post /cloudron/restore
https://my.example.com/api/v1/cloudron/restore

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "backupConfig":
    {
    },
  • "backupId": "2020-04-20-161041-646/box_2020-04-20-161045-600_v5.2.0",
  • "version": "5.1.0",
  • "sysinfoConfig":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{ }

API Login

Login to the Cloudron API to obtain an access token

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

Responses

200

OK

post /cloudron/login
https://my.example.com/api/v1/cloudron/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": "linode",
  • "cloudronName": "My Cloudron",
  • "uiSpec": { }
}

Appstore

Register Cloudron

Register this Cloudron with cloudron.io AppStore and enable access to the app library.

Request Body schema: application/json
signup
required
boolean

If true a new cloudron.io account will be created. If an account already exists, this request will return an error. Otherwise, this Cloudron will be assigned to the existing account.

email
required
string <email>
password
required
string
totpToken
string

2FA token. Required when the cloudron.io account already exists and was setup with 2FA.

Responses

201

OK

post /appstore/register_cloudron
https://my.example.com/api/v1/appstore/register_cloudron

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signup": false,
  • "email": "julia@example.com",
  • "password": "supersecret",
  • "totpToken": "string"
}

Get Subscription

Responses

200

OK

get /appstore/subscription
https://my.example.com/api/v1/appstore/subscription

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "email": "julia@example.com",
  • "cloudronId": "string",
  • "cloudronCreatedAt": "ISO-8601 UTC date",
  • "plan": "string",
  • "current_period_end": "ISO-8601 UTC date",
  • "canceled_at": "ISO-8601 UTC date",
  • "cancel_at": "ISO-8601 UTC date",
  • "status": "string",
  • "features": "string"
}

Domains

Add and manage domains.

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" "linode" "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": "digitalocean",
  • "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" "linode" "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