swagger: "2.0"
info:
title: Cloudron API
version: 1.0.0
x-logo:
url: "/img/cloudron-banner.png"
description: Cloudron provides a RESTful API to manage all aspects of the Cloudron like adding users, configuring groups and installing apps.
<br/>
<br/>
If you are an app developer, the [Cloudron CLI tool](https://www.npmjs.com/package/cloudron) implements a workflow that allows
you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.
<br/>
<br/>
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>`.
host: my.example.com
basePath: /api/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
# Primary objects
- name: "Cloudron"
- name: "Appstore"
- name: "App Passwords"
- name: "Apps"
- name: "Backups"
- name: "Branding"
- name: "Domains"
description: Add and manage domains.
- name: "Groups"
- name: "Mail"
- name: "Mailserver"
- name: "Network"
- name: "Notifications"
- name: "Profile"
- name: "Services"
- name: "Settings"
- name: "Tasks"
- name: "Tokens"
- name: "Users"
- name: "Volumes"
parameters:
DomainName:
in: path
name: domain
description: Domain
required: true
type: string
MailboxName:
in: path
name: name
description: Mailbox
required: true
type: string
PaginationPage:
in: query
name: page
type: integer
format: int32
minimum: 1
default: 1
PaginationPerPage:
in: query
name: per_page
type: integer
format: int32
minimum: 1
default: 25
TaskId:
in: path
name: taskId
description: Task ID
required: true
type: integer
UserId:
in: path
name: userId
description: User ID
required: true
type: string
GroupId:
in: path
name: groupId
description: Group ID
required: true
type: string
ServiceName:
in: path
name: service
description: Service Name
required: true
type: string
enum:
- mail
- mongodb
- mysql
- postgresql
- docker
- unbound
- sftp
- graphite
- nginx
definitions:
Mailbox:
description: Mailbox
type: object
properties:
name:
type: string
example: webmaster
domain:
type: string
example: example.com
ownerId:
type: string
example: uid-be9dcf57-ad65-40e0-a3f8-d1c75974bf01
ownerType:
type: string
example: user
aliases:
type: array
example: "[{ name, domain }]"
Domain:
description: Domain Info
type: object
properties:
domain:
type: string
example: example.com
enabled:
type: boolean
example: true
mailFromValidation:
type: boolean
example: true
catchAll:
type: array
example: []
relay:
type: object
properties:
provider:
$ref: '#/definitions/MailRelayProvider'
banner:
type: object
description: Text and HTML mail signature
properties:
text:
type: string
html:
type: string
UserId:
description: User ID
type: string
example: 'uid-5d06e9da-8e4a-4184-b63c-c25487e1c70b'
Group:
type: object
properties:
id:
type: string
example: gid-e08ca116-d3e5-43c9-b43f-6eb990be58ea
name:
type: string
example: Manager
GroupWithMembers:
type: object
properties:
id:
type: string
example: gid-e08ca116-d3e5-43c9-b43f-6eb990be58ea
name:
type: string
example: Manager
userIds:
type: array
items:
$ref: '#/definitions/UserId'
example: [ 'uid-e08ca116-d3e5-43c9-b43f-6eb990be58ea' ]
User:
type: object
properties:
id:
type: string
username:
type: string
displayName:
type: string
email:
type: string
format: email
fallbackEmail:
type: string
format: email
groupIds:
type: array
example: []
admin:
type: boolean
active:
type: boolean
source:
type: string
description: A value of `ldap` indicates, this user if from an LDAP/ActiveDirectory user, otherwise a local user
enum:
- ''
- ldap
RestrictedUser:
type: object
properties:
id:
type: string
username:
type: string
displayName:
type: string
email:
type: string
format: email
active:
type: boolean
Provider:
type: string
description: VPS provider name tag
enum:
- ami
- azure
- cloudscale
- contabo
- digitalocean
- ec2
- exoscale
- galaxygate
- gce
- hetzner
- interox
- lightsail
- linode
- netcup
- ovh
- rosehosting
- scaleway
- skysilk
- time4vps
- upcloud
- vultr
- generic
example: linode
MailRelayProvider:
type: string
description: Mail SMTP relay provider
enum:
- cloudron-smtp
- external-smtp
- external-smtp-noauth
- ses-smtp
- elasticemail-smtp
- google-smtp
- mailgun-smtp
- mailjet-smtp
- postmark-smtp
- sendgrid-smtp
- sparkpost-smtp
- noop
example: postmark-smtp
Service:
type: object
properties:
name:
type: string
example: mysql
enum:
- mail
- mongodb
- mysql
- postgresql
- docker
- unbound
- sftp
- graphite
- nginx
status:
type: string
example: active
enum:
- starting
- active
- stopped
memoryUsed:
type: integer
format: int32
minimum: 0
memoryPercent:
type: integer
format: int32
minimum: 0
error:
type: string
example: ''
x-nullable: true
config:
type: object
description: If `memory` and `memorySwap` is not set, then they cannot be configured
properties:
memory:
type: integer
format: int32
minimum: 0
memorySwap:
type: integer
format: int32
minimum: 0
TaskType:
type: string
example: update
enum:
- app
- backup
- update
- renewcerts
- prepareDashboardDomain
- cleanBackups
- syncExternalLdap
Task:
type: object
properties:
id:
type: integer
type:
$ref: '#/definitions/TaskType'
percent:
type: integer
example: 33
minimum: 0
maximum: 100
message:
type: string
description: For display purpose to show more informed progress
error:
type: object
properties:
message:
type: string
code:
type: string
example: crashed
enum:
- stopped
- crashed
- timeout
active:
type: boolean
description: Determines if this task is currently active. Progress can be tracked with `message` and `percent`
example: true
creationTime:
type: integer
description: Creation time UTC timestamp
result:
type: object
ts:
type: integer
description: Last modified UTC timestamp
success:
type: boolean
example: true
description: Determines if the task was successful. If `false` check `error` or `active` properties.
AddonConfig:
type: object
properties:
memory:
type: integer
example: 268435456
description: Memory limit in bytes. Example is 256MB
memorySwap:
type: integer
example: 536870912
description: Swap memory limit in bytes. Example is 512MB
DnsProvider:
type: string
example: digitalocean
enum:
- route53
- cloudflare
- digitalocean
- gandi
- godaddy
- gcdns
- linode
- namecom
- namecheap
- wildcard
- manual
- noop
TlsConfig:
type: object
properties:
provider:
type: string
example: letsencrypt-prod
enum:
- letsencrypt-prod
- letsencrypt-staging
- fallback
wildcard:
type: boolean
example: false
SysConfig:
type: object
properties:
provider:
type: string
description: Currently the sysinfo provider is only used to determine the public IP of the server. Which in turn is used in the DNS logic to setup records.
enum:
- fixed
- network-interface
- generic
example: generic
DomainConfig:
type: object
required:
- provider
- config
properties:
provider:
$ref: '#/definitions/DnsProvider'
config:
description: Provider specific config. May include username and api tokens
type: object
hyphenatedSubdomains:
type: boolean
wildcard:
type: boolean
zoneName:
type: string
fallbackCertificate:
type: object
properties:
key:
type: string
example: ""
cert:
type: string
example: ""
tlsConfig:
$ref: '#/definitions/TlsConfig'
AppManifest:
type: object
properties:
id:
type: string
App:
type: object
properties:
id:
type: string
example: "2b97b864-37b6-4e79-88b0-63712186a326"
appStoreId:
type: string
example: "org.wordpress.cloudronapp"
installationState:
type: string
example: "installed"
error:
type: object
example: null
runState:
type: string
example: "running"
health:
type: string
example: "healthy"
taskId:
type: string
x-nullable: true
example: "1234"
location:
type: string
description: This is the subdomain, the app is installed on. May be an empty string if no subdomain is configured
example: "www"
domain:
type: string
example: "example.com"
fqdn:
type: string
description: FullQualifiedDomainName is essentially `location`.`domain`
example: "www.example.com"
manifest:
$ref: '#/definitions/AppManifest'
portBindings:
type: object
iconUrl:
type: string
example: "/api/v1/apps/2b97b864-37b6-4e79-88b0-63712186a326/icon"
creationTime:
type: string
description: Time the app was installed
format: date-time
example: ISO-8601 UTC date
ts:
type: string
description: Time the app was last modified
format: date-time
example: ISO-8601 UTC date
tags:
type: array
label:
type: string
x-nullable: true
example: "MyGreatWebsite"
BackupFormat:
type: string
example: rsync
enum:
- rsync
- targz
BackupConfig:
type: object
properties:
provider:
type: string
example: s3
enum:
- s3
- gcs
- filesystem
- minio
- s3-v4-compat
- digitalocean-spaces
- exoscale-sos
- wasabi
- scaleway-objectstorage
- noop
format:
$ref: '#/definitions/BackupFormat'
retentionSecs:
type: integer
description: Maximum time to keep backups in seconds (1 week is 604800 seconds)
example: 604800
intervalSecs:
type: integer
description: Interval for automatic backups in seconds. Must be atleast 6 hours (21600 seconds)
example: 1
minimum: 21600
key:
type: string
description: Encyrption key. May contain a placeholder string to not leak the key
syncConcurrency:
type: integer
example: 5
minimum: 1
acceptSelfSignedCerts:
type: boolean
example: false
backupFolder:
type: string
description: only for filesystem provider
noHardlinks:
type: boolean
description: only for filesystem provider
externalDisk:
type: boolean
description: only for filesystem provider
accessKeyId:
type: string
description: only for S3 style provider
secretAccessKey:
type: string
description: only for S3 style provider
signatureVersion:
type: string
description: only for S3 style provider
endpoint:
type: string
description: only for S3 style provider
region:
type: string
description: only for S3 style provider
bucket:
type: string
description: only for S3 and gcs style provider
prefix:
type: string
description: only for S3 and gcs style provider
projectId:
type: string
description: only for gcs provider
credentials:
type: object
description: only for gcs provider
properties:
client_email:
type: string
private_key:
type: string
PlatformConfig:
type: object
properties:
mysql:
$ref: '#/definitions/AddonConfig'
postgresql:
$ref: '#/definitions/AddonConfig'
mail:
$ref: '#/definitions/AddonConfig'
mongodb:
$ref: '#/definitions/AddonConfig'
ExternalLdapConfig:
type: object
required:
- provider
- url
- baseDn
- filter
properties:
provider:
type: string
enum:
- ad
- jumpcloud
- okta
- other
- noop
url:
type: string
format: url
baseDn:
type: string
filter:
type: string
usernameField:
type: string
default: uid
bindDn:
type: string
bindPassword:
type: string
autoCreate:
type: boolean
RegistryConfig:
type: object
required:
- serverAddress
properties:
serverAddress:
type: string
format: url
username:
type: string
email:
type: string
format: email
password:
type: string
SysinfoConfig:
type: object
required:
- provider
properties:
provider:
type: string
default: generic
enum:
- generic
- fixed
- network-interface
ip:
type: string
description: Only applies to the `fixed` provider
example: 123.123.123.123
ifname:
type: string
description: Only applies to the `network-interface` provider
example: eth0
UpdatePattern:
type: object
required:
- pattern
properties:
pattern:
type: string
example: 0 030 4 1,15 * 5
description: The format listed in the [node-cron](https://github.com/ncb000gt/node-cron#cron-ranges) page.
Note that unlike classic crontab format, the pattern contains seconds as the first part. Setting pattern to `never` disables auto update.
Some examples of patterns are
* `00 00 1,3,5,23 * * *` would run updates at 1am, 3am, 5am, 11pm every night.
* `0 030 4 1,15 * 5` would run updates at 4:30 am on the 1st and 15th of each month, plus every Friday.
TimezoneConfig:
type: object
required:
- timeZone
properties:
timeZone:
type: string
default: America/Los_Angeles
description: Timezone is automatically set based on the IP address from where the Cloudron was activated. This timezone is used with the auto update pattern to trigger updates at the correct time.
See the [Tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of valid values.
CloudronNameConfig:
type: object
required:
- name
properties:
name:
type: string
default: Cloudron
paths:
/cloudron/setup:
post:
summary: Initial DNS Setup
description: |
Public route and very first call to setup the dashboard domain.
<br/><br/>
<b>This call has to be made against the raw IP address (eg. https://1.2.3.4 ) accepting self-signed certificates.</b>
<br/><br/>
A curl example could look like:<br/>
```curl -k -X POST -H 'Content-Type: application/json' --data '{...}' http://1.2.3.4/api/v1/cloudron/setup```
<br/><br/>
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`.
<br/><br/>
This routes gets disabled once the Cloudron has been activated.
tags: [ "Cloudron" ]
parameters:
- in: body
name: dns config
schema:
type: object
required:
- dnsConfig
properties:
dnsConfig:
type: object
required:
- provider
- domain
- config
properties:
provider:
$ref: '#/definitions/DnsProvider'
domain:
type: string
example: hello.example.com
zoneName:
type: string
example: example.com
config:
type: object
description: DNS provider specific configuration, for example API tokens and secrets
example: { "token": "digitalocean_api_token" }
tlsConfig:
$ref: '#/definitions/TlsConfig'
sysinfoConfig:
$ref: '#/definitions/SysConfig'
responses:
200:
description: OK
schema:
type: object
/cloudron/status:
get:
summary: Get status
description: Public route to get status information for this Cloudron.
tags: [ "Cloudron" ]
responses:
200:
description: OK
schema:
type: object
properties:
version:
type: string
description: Cloudron version
example: 5.1.0
apiServerOrigin:
type: string
description: The API endpoint to make App Store requests
example: https://api.cloudron.io
webServerOrigin:
type: string
description: The Web endpoint for App Store assets (docs, images, etc)
example: https://cloudron.io
provider:
$ref: '#/definitions/Provider'
cloudronName:
type: string
description: Name of the Cloudron used in the login screen, nav bar
example: My Space
footer:
type: string
description: Markdown formatted footer content
example: "© 2020 [Cloudron](https://cloudron.io) [Forum <i class=\"fa fa-comments\"></i>](https://forum.cloudron.io)"
adminFqdn:
type: string
description: The FQDN of the Cloudron dashboard
example: my.example.com
activated:
type: boolean
description: Indicates if this Cloudron was already activated. This is true once the first user was created during setup.
example: true
setup:
type: object
properties:
active:
type: boolean
description: Indicates if a DNS setup is currently in progress. This happens after /api/v1/cloudron/setup was issued.
example: false
message:
type: string
description: Setup process status messages for ongoing progress display
example: Fetching SSL certificate ...
errorMessage:
type: string
x-nullable: true
example: null
restore:
type: object
properties:
active:
type: boolean
description: Indicates if a restore is currently in progress.
example: false
message:
type: string
description: Restore process status messages for ongoing progress display
example: Downloading backups ...
errorMessage:
type: string
x-nullable: true
example: null
/cloudron/activate:
post:
summary: Activate
description:
Public route to activate the Cloudron. This creates the first user (aka owner) account.
<br/><br/>
Before installing apps, the Cloudron must be registered with a valid Appstore account as well using the 'Register Cloudron' route.
tags: [ "Cloudron" ]
parameters:
- in: body
name: activate config
schema:
type: object
required:
- username
- password
- email
properties:
username:
type: string
description: Username. The first user is also called the Owner.
example: oksana
password:
type: string
description: Password. Minimum of 8 characters required.
example: strongPa55word!?
email:
type: string
description: Primary email of the user.
example: oksane@example.com
displayName:
type: string
description: Full name of the user.
example: Oksana Muller
responses:
201:
description: OK
schema:
type: object
properties:
userId:
type: string
description: Unique ID of the created user
example: uid-e08ca116-d3e5-43c9-b43f-6eb990be58ea
token:
type: string
description: A token that will authenticate the user for future API requests. Pass this as `?access_token=<token>`.
example: sometoken
expires:
type: string
description: Expiry time of token
format: date-time
example: ISO-8601 UTC date
/cloudron/restore:
post:
summary: Restore
description: Public route to restore a whole Cloudron from backup. This is only available until the Cloudron is activated.
tags: [ "Cloudron" ]
parameters:
- in: body
name: restore config
schema:
type: object
required:
- backupConfig
- backupId
- version
properties:
backupConfig:
$ref: "#/definitions/BackupConfig"
backupId:
type: string
example: 2020-04-20-161041-646/box_2020-04-20-161045-600_v5.2.0
version:
type: string
example: 5.1.0
sysinfoConfig:
$ref: "#/definitions/SysinfoConfig"
responses:
200:
description: OK
schema:
type: object
/cloudron/login:
post:
summary: API Login
description: Login to the Cloudron API to obtain an access token
tags: [ "Cloudron" ]
parameters:
- in: body
name: login data
schema:
type: object
required:
- username
- password
properties:
username:
type: string
example: julia
password:
type: string
example: supersecret
responses:
200:
description: OK
schema:
type: object
properties:
token:
type: string
example: sometoken
expiresAt:
type: string
format: date-time
example: ISO-8601 UTC date
/config:
get:
summary: Get Config
description: This config object contains the platform configuration.
tags: [ "Cloudron" ]
responses:
200:
description: OK
schema:
type: object
properties:
apiServerOrigin:
type: string
format: url
example: https://api.cloudron.io
webServerOrigin:
type: string
format: url
example: https://cloudron.io
adminDomain:
type: string
description: The main domain for this Cloudron. `adminFqdn` and `mailFqdn` depend on this
example: example.com
adminFqdn:
type: string
description: Subdomain where the dashboard is reachable.
example: my.example.com
mailFqdn:
type: string
description: Subdomain where the mail server is reachable.
example: my.example.com
version:
type: string
description: Cloudron version
example: 4.1.2
isDemo:
type: boolean
example: false
provider:
$ref: '#/definitions/Provider'
cloudronName:
type: string
description: Same as /api/v1/settings/clouron_name
example: My Cloudron
uiSpec:
type: object
description: See https://docs.cloudron.io/hosting-provider/#customization
/appstore/register_cloudron:
post:
summary: Register Cloudron
description: Register this Cloudron with cloudron.io AppStore and enable access to the app library.
tags: [ "Appstore" ]
parameters:
- in: body
name: login data
schema:
type: object
required:
- signup
- email
- password
properties:
signup:
type: boolean
description:
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.
example: false
email:
type: string
format: email
example: julia@example.com
password:
type: string
example: supersecret
totpToken:
type: string
description: 2FA token. Required when the cloudron.io account already exists and was setup with 2FA.
responses:
201:
description: OK
/appstore/subscription:
get:
summary: Get Subscription
tags: [ "Appstore" ]
responses:
200:
description: OK
schema:
type: object
properties:
email:
type: string
format: email
example: julia@example.com
cloudronId:
type: string
cloudronCreatedAt:
type: string
format: date-time
example: ISO-8601 UTC date
plan:
type: string
current_period_end:
type: string
format: date-time
example: ISO-8601 UTC date
canceled_at:
type: string
format: date-time
example: ISO-8601 UTC date
cancel_at:
type: string
format: date-time
example: ISO-8601 UTC date
status:
type: string
features:
type: string
/domains:
get:
summary: List Domains
description: Get all domains
tags: [ "Domains" ]
responses:
200:
description: OK
schema:
type: object
properties:
domains:
type: array
example: []
post:
summary: Add Domain
description: Add a new domain
tags: [ "Domains" ]
parameters:
- in: body
name: Domain config
schema:
allOf:
- type: object
required:
- domain
properties:
domain:
type: string
example: example.com
- $ref: '#/definitions/DomainConfig'
responses:
201:
description: OK
400:
description: Invalid fields or provider credentials
409:
description: Conflict. Domain already exists.
/domains/{domain}:
parameters:
- in: path
name: domain
description: Domain
required: true
type: string
get:
summary: Get Domain
tags: [ "Domains" ]
responses:
200:
description: OK
schema:
type: object
properties:
domain:
type: string
example: cloud.example.com
zoneName:
type: string
example: example.com
provider:
type: string
example: cloudflare
config:
type: object
properties:
hyphenatedSubdomains:
type: boolean
example: false
tlsConfig:
type: object
properties:
provider:
type: string
example: letsencrypt-prod
wildcard:
type: boolean
example: true
fallbackCertificate:
type: object
properties:
cert:
type: string
example: ''
key:
type: string
example: ''
locked:
type: boolean
example: false
put:
summary: Update Domain
tags: [ "Domains" ]
parameters:
- in: body
name: domain config
schema:
$ref: '#/definitions/DomainConfig'
responses:
204:
description: OK
400:
description: Invalid fields or provider credentials
delete:
summary: Remove Domain
tags: [ "Domains" ]
responses:
204:
description: OK
409:
description: Conflict. The domain is still in use
/domains/{domain}/dns_check:
parameters:
- in: path
name: domain
description: Domain
required: true
type: string
- in: query
name: subdomain
type: string
description: The subdomain to check the DNS record for
get:
summary: Check DNS Records
tags: [ "Domains" ]
responses:
200:
description: OK
schema:
type: object
properties:
needsOverwrite:
type: boolean
example: false
/settings/dynamic_dns:
get:
summary: Get Dynamic DNS State
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
type: object
properties:
enabled:
type: boolean
example: false
post:
summary: Set Dynamic DNS State
tags: [ "Settings" ]
parameters:
- in: body
name: dynamic dns config
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
example: false
responses:
200:
description: OK
/apps/install:
post:
summary: Install App
description: This triggers an app installation. Use the `taskId` from the response with the Tasks API to follow the installation progress
<br/>
<br/>
**Either `manifest` or `appStoreId` are required!** In most cases the `appStoreId` is the correct property to be used for installing apps from the Cloudron app catalogue.
tags: [ "Apps" ]
parameters:
- in: body
name: app config
schema:
type: object
required:
# https://stackoverflow.com/questions/29708505/swagger-2-0-how-to-make-one-or-the-other-parameter-required for manifest or appStoreId
- location
- domain
- accessRestriction
properties:
# Currently we ignore the key, cert, env and debugMode params in the docs
manifest:
$ref: '#/definitions/AppManifest'
appStoreId:
type: string
example: "org.wordpress.cloudronapp"
location:
type: string
description: Subdomain the app is installed at. This may be an empty string if the app is installed directly at `domain`
example: "www"
domain:
type: string
example: "example.com"
accessRestriction:
type: object
description: By default all users have access
default: {}
example: {}
portBindings:
type: object
default: {}
icon:
type: string
label:
type: string
default: ""
example: "MyAwesomeWebsite"
memoryLimit:
type: number
format: int32
default: Value from the AppManifest
description: Memory limit as a number of `MB * 1024 * 1024`. So 600MB memory limit is 629145600
example: 629145600
sso:
type: boolean
description: For apps with `optionalSso` set in the manifest.
default: true
example: true
enableBackup:
type: boolean
default: true
example: true
enableAutomaticUpdate:
type: boolean
default: true
example: true
alternateDomains:
type: array
default: []
overwriteDns:
type: boolean
description: If set to `true` Cloudron will overwrite any existing DNS records. This should not be required in most cases.
default: false
example: false
responses:
200:
description: OK
schema:
type: object
properties:
id:
type: string
example: "2b97b864-37b6-4e79-88b0-63712186a326"
taskId:
type: string
example: "1234"
/apps:
get:
summary: List installed Apps
tags: [ "Apps" ]
responses:
200:
description: OK
schema:
type: object
properties:
apps:
type: array
items:
$ref: '#/definitions/App'
/apps/{appid}:
get:
summary: Get installed App
tags: [ "Apps" ]
parameters:
- in: path
name: appid
description: Installed App ID
required: true
type: string
responses:
200:
description: OK
schema:
$ref: "#/definitions/App"
/apps/{appid}/logs:
get:
summary: Get App Logs
description: "For format `plain` simple text lines are returned. When format is `json` each log line looks like `{
realtimeTimestamp: timestamp,
message: message,
source: appId
}`"
tags: [ "Apps" ]
parameters:
- in: path
name: appid
description: Installed App ID
required: true
type: string
- in: query
name: lines
schema:
type: integer
description: Number of log lines to fetch. Starting at latest.
default: 10
- in: query
name: format
schema:
type: string
description: Log type
default: json
enum:
- plain
- json
responses:
200:
description: OK
content:
application/x-logs:
schema:
type: string
/apps/{appid}/logstream:
get:
summary: Get App Logstream
description: "A logstream is of type [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource). For format `plain` simple text lines are returned. When format is `json` each log line looks like `{
realtimeTimestamp: timestamp,
message: message,
source: appId
}`"
tags: [ "Apps" ]
parameters:
- in: path
name: appid
description: Installed App ID
required: true
type: string
- in: query
name: lines
schema:
type: integer
description: Number of log lines to fetch. Starting at latest.
default: 10
- in: query
name: format
schema:
type: string
description: Log type
default: json
enum:
- plain
- json
responses:
200:
description: OK
content:
text/event-stream:
schema:
type: string
/settings/unstable_apps:
get:
summary: Get Unstable Apps State
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
type: object
properties:
enabled:
type: boolean
example: false
post:
summary: Set Unstable Apps State
tags: [ "Settings" ]
parameters:
- in: body
name: unstable apps config
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
example: false
responses:
200:
description: OK
/settings/backup_config:
get:
summary: Get Backup Config
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/BackupConfig'
post:
summary: Set Backup Config
tags: [ "Settings" ]
parameters:
- in: body
name: backup config
schema:
$ref: '#/definitions/BackupConfig'
responses:
200:
description: OK
/settings/platform_config:
get:
summary: Get Platform Config
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/PlatformConfig'
post:
summary: Set Platform Config
tags: [ "Settings" ]
parameters:
- in: body
name: platform config
schema:
$ref: '#/definitions/PlatformConfig'
responses:
200:
description: OK
/settings/external_ldap_config:
get:
summary: Get External LDAP Config
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/ExternalLdapConfig'
post:
summary: Set External LDAP Config
tags: [ "Settings" ]
parameters:
- in: body
name: external ldap config
schema:
$ref: '#/definitions/ExternalLdapConfig'
responses:
200:
description: OK
400:
description: Invalid field
/settings/registry_config:
get:
summary: Get Registry Config
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/RegistryConfig'
post:
summary: Set Registry Config
tags: [ "Settings" ]
parameters:
- in: body
name: registry config
schema:
$ref: '#/definitions/RegistryConfig'
responses:
200:
description: OK
400:
description: Invalid field
/settings/sysinfo_config:
get:
summary: Get Sysinfo Config
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/SysinfoConfig'
post:
summary: Set Sysinfo Config
tags: [ "Settings" ]
parameters:
- in: body
name: sysinfo config
schema:
$ref: '#/definitions/SysinfoConfig'
responses:
200:
description: OK
400:
description: Invalid field
/settings/app_autoupdate_pattern:
get:
summary: Get Apps Autoupdate Pattern
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/UpdatePattern'
post:
summary: Set Apps Autoupdate Pattern
tags: [ "Settings" ]
parameters:
- in: body
name: apps autoupdate pattern
schema:
$ref: '#/definitions/UpdatePattern'
responses:
200:
description: OK
/settings/box_autoupdate_pattern:
get:
summary: Get Cloudron Autoupdate Pattern
description: Gets the pattern that the Cloudron uses to automatically update itself and installed apps. Patterns are matched based on the Cloudron's timezone.
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/UpdatePattern'
post:
summary: Set Cloudron Autoupdate Pattern
tags: [ "Settings" ]
parameters:
- in: body
name: cloudron autoupdate pattern
schema:
$ref: '#/definitions/UpdatePattern'
responses:
200:
description: OK
/settings/time_zone:
get:
summary: Get Timezone
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/TimezoneConfig'
post:
summary: Set Timezone
tags: [ "Settings" ]
parameters:
- in: body
name: timezone
schema:
$ref: '#/definitions/TimezoneConfig'
responses:
200:
description: OK
/settings/cloudron_name:
get:
summary: Get Cloudron Name
tags: [ "Settings" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/CloudronNameConfig'
post:
summary: Set Cloudron Name
tags: [ "Settings" ]
parameters:
- in: body
name: cloudron name
schema:
$ref: '#/definitions/CloudronNameConfig'
responses:
200:
description: OK
/settings/cloudron_avatar:
get:
summary: Get Cloudron Avatar
tags: [ "Settings" ]
produces:
- image/png
responses:
200:
description: OK
schema:
type: file
post:
summary: Set Cloudron Avatar
tags: [ "Settings" ]
consumes:
- multipart/form-data
parameters:
- in: formData
name: avatar
required: true
type: file
responses:
200:
description: OK
/backups:
get:
summary: List Backups
tags: [ "Backups" ]
parameters:
- $ref: '#/parameters/PaginationPage'
- $ref: '#/parameters/PaginationPerPage'
responses:
200:
description: OK
schema:
type: object
properties:
backups:
type: array
items:
type: object
properties:
id:
type: string
creationTime:
type: number
format: date-time
version:
type: string
description: Cloudron version that backups was made for
example: 4.2.1
type:
type: string
description: Is always `box` since this API returns the list of platform backups. Individual app backups can be retrieved with the /api/v1/apps/ routes.
dependsOn:
type: array
description: Contains a list of backup IDs referencing the app backups
items:
type: string
state:
type: string
enum:
- normal
- creating
- error
manifest:
type: object
example: null
description: Is always `null` since this API returns the list of platform backups. Individual app backups can be retrieved with the /api/v1/apps/ routes.
format:
$ref: '#/definitions/BackupFormat'
preserveSecs:
type: integer
description: Time to keep this backup in seconds (1 week is 604800 seconds). This number + `creationTime` determines if a backup is kept or removed
example: 604800
/backups/create:
post:
summary: Trigger new Backup
description: This will trigger a new backup for the whole system, including all apps.
tags: [ "Backups" ]
responses:
202:
description: OK
schema:
type: object
properties:
taskId:
type: integer
description: This id can be used with the /api/v1/tasks routes to determine state and get logs
example: 123
/backups/cleanup:
post:
summary: Cleanup old Backups
description: Based on the backup creation and `retentionSecs` specified in the backup config, backups will be purged.
This should not need to be called manually as the same logic is called automatically very 6 hours.
tags: [ "Backups" ]
responses:
202:
description: OK
schema:
type: object
properties:
taskId:
type: integer
description: This id can be used with the /api/v1/tasks routes to determine state and get logs
example: 123
/tasks:
get:
summary: List Tasks
tags: [ "Tasks" ]
parameters:
- $ref: '#/parameters/PaginationPage'
- $ref: '#/parameters/PaginationPerPage'
- in: query
name: type
type: string
default: ''
enum:
- app
- backup
- update
- renewcerts
- prepareDashboardDomain
- cleanBackups
- syncExternalLdap
responses:
200:
description: OK
schema:
type: object
properties:
tasks:
type: array
items:
$ref: '#/definitions/Task'
/tasks/{taskId}:
parameters:
- $ref: '#/parameters/TaskId'
get:
summary: Get Task
tags: [ "Tasks" ]
responses:
200:
description: OK
schema:
$ref: '#/definitions/Task'
/tasks/{taskId}/logs:
parameters:
- $ref: '#/parameters/TaskId'
get:
summary: Get Task Logs
tags: [ "Tasks" ]
produces:
- application/x-logs
responses:
200:
description: OK
schema:
type: file
/tasks/{taskId}/logstream:
parameters:
- $ref: '#/parameters/TaskId'
get:
summary: Get Task Logstream
description: The log stream is in [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) format
tags: [ "Tasks" ]
produces:
- text/event-stream
responses:
200:
description: OK
/tasks/{taskId}/stop:
parameters:
- $ref: '#/parameters/TaskId'
post:
summary: Stop Task
tags: [ "Tasks" ]
responses:
204:
description: OK
/services:
get:
summary: Get Services
tags: [ "Services" ]
responses:
200:
description: OK
schema:
type: object
properties:
services:
type: array
items:
type: string
example: mysql
enum:
- mail
- mongodb
- mysql
- postgresql
- docker
- unbound
- sftp
- graphite
- nginx
/services/{service}:
get:
summary: Get Service
tags: [ "Services" ]
parameters:
- $ref: '#/parameters/ServiceName'
responses:
200:
description: OK
schema:
$ref: '#/definitions/Service'
post:
summary: Configure Service
tags: [ "Services" ]
parameters:
- $ref: '#/parameters/ServiceName'
- in: body
name: service config
schema:
type: object
properties:
memory:
type: integer
format: int32
minimum: 0
responses:
202:
description: OK
/services/{service}/logs:
get:
summary: Get Service Logs
tags: [ "Services" ]
parameters:
- $ref: '#/parameters/ServiceName'
produces:
- application/x-logs
responses:
200:
description: OK
schema:
type: file
/services/{service}/logstream:
get:
summary: Get Service Logstream
description: The log stream is in [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) format
tags: [ "Services" ]
parameters:
- $ref: '#/parameters/ServiceName'
produces:
- text/event-stream
responses:
200:
description: OK
/services/{service}/restart:
post:
summary: Restart Service
tags: [ "Services" ]
parameters:
- $ref: '#/parameters/ServiceName'
responses:
202:
description: OK
/users:
get:
summary: List Users
description: Get all users
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/PaginationPage'
- $ref: '#/parameters/PaginationPerPage'
- in: query
name: search
type: string
default: ''
responses:
200:
description: OK
schema:
type: object
properties:
users:
type: array
example: []
post:
summary: Add User
description: Add new User
tags: [ "Users" ]
parameters:
- in: body
name: user object
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
username:
type: string
description: If not specified, the new user will have to set it during onboarding
displayName:
type: string
description: If not specified, the new user will have to set it during onboarding
password:
type: string
description: If not specified, the new user will have to set it during onboarding
admin:
type: boolean
default: false
responses:
201:
description: OK
schema:
$ref: '#/definitions/User'
/users/{userId}:
get:
summary: Get User
description: Get user
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'
post:
summary: Update User
description: Update user
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
- in: body
name: user object
schema:
type: object
properties:
email:
type: string
format: email
fallbackEmail:
type: string
format: email
username:
type: string
description: If not specified, the new user will have to set it during onboarding
displayName:
type: string
description: If not specified, the new user will have to set it during onboarding
admin:
type: boolean
active:
type: boolean
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'
delete:
summary: Delete User
description: Delete user
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
responses:
204:
description: OK
/users/{userId}/password:
post:
summary: Change Password
description: Change Password
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
- in: body
name: password change
schema:
type: object
required:
- password
properties:
password:
type: string
responses:
204:
description: OK
/users/{userId}/groups:
put:
summary: Set Groups
description: Set groups a user belongs to
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
- in: body
name: groups
schema:
type: object
required:
- groupIds
properties:
groupIds:
type: array
example: []
responses:
204:
description: OK
/users/{userId}/send_invite:
post:
summary: Send Invite
description: Send user invite email. This will not reset the invite token. See the create invite route.
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
responses:
200:
description: OK
/users/{userId}/create_invite:
post:
summary: Create Invite
description: Create a new invite token. This will invalidate the previous one. This only works for local users, not LDAP/ActiveDirectory users.
tags: [ "Users" ]
parameters:
- $ref: '#/parameters/UserId'
responses:
200:
description: OK
schema:
type: object
properties:
resetToken:
type: string
/groups:
get:
summary: List Groups
description: List groups
tags: [ "Groups" ]
responses:
200:
description: OK
schema:
type: object
properties:
groups:
type: array
items:
$ref: '#/definitions/Group'
example:
- id: gid-e08ca116-d3e5-43c9-b43f-6eb990be58ea
name: Manager
- id: gid-351904ce-6a21-4fbc-806e-4f457b120ef3
name: Employee
post:
summary: Add Group
description: Add group
tags: [ "Groups" ]
parameters:
- in: body
name: group
schema:
type: object
required:
- name
properties:
name:
type: string
example: Manager
responses:
201:
description: OK
schema:
$ref: '#/definitions/Group'
/groups/{groupId}:
get:
summary: Get Group
description: Get group
tags: [ "Groups" ]
parameters:
- $ref: '#/parameters/GroupId'
responses:
200:
description: OK
schema:
$ref: '#/definitions/GroupWithMembers'
post:
summary: Update Group
description: Update group
tags: [ "Groups" ]
parameters:
- $ref: '#/parameters/GroupId'
- in: body
name: group
schema:
type: object
required:
- name
properties:
name:
type: string
example: Manager
responses:
200:
description: OK
delete:
summary: Delete Group
description: Delete group
tags: [ "Groups" ]
parameters:
- $ref: '#/parameters/GroupId'
responses:
204:
description: OK
/groups/{groupId}/members:
put:
summary: Set Group Members
description: Set group members
tags: [ "Groups" ]
parameters:
- $ref: '#/parameters/GroupId'
- in: body
name: groupMembers
schema:
type: object
required:
- userIds
properties:
userIds:
type: array
items:
$ref: '#/definitions/UserId'
responses:
200:
description: OK
/mail/{domain}:
get:
summary: Get Mail Domain Info
description: Get Mail Domain Info
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
responses:
200:
description: OK
schema:
$ref: '#/definitions/Domain'
/mail/{domain}/status:
get:
summary: Get Mail Domain Status
description: Get Mail Domain Status
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
responses:
200:
description: OK
schema:
type: object
properties:
dns:
type: object
properties:
mx:
type: object
properties:
domain:
type: string
example: "example.com"
name:
type: string
example: "@"
type:
type: string
example: "MX"
value:
type: string
example: "10 my.example.com."
expected:
type: string
example: "10 my.example.com."
status:
type: boolean
example: true
spf:
type: object
properties:
domain:
type: string
example: "example.com"
name:
type: string
example: "@"
type:
type: string
example: "TXT"
value:
type: string
example: "v=spf1 a:my.example.com ~all"
expected:
type: string
example: "v=spf1 a:my.example.com ~all"
status:
type: boolean
example: true
dmarc:
type: object
properties:
domain:
type: string
example: "_dmarc.nebulon.space"
name:
type: string
example: "_dmarc"
type:
type: string
example: "TXT"
value:
type: string
example: "v=DMARC1; p=reject; pct=100"
expected:
type: string
example: "v=DMARC1; p=reject; pct=100"
status:
type: boolean
example: true
dkim:
type: object
properties:
domain:
type: string
example: "cloudron._domainkey.example.com"
name:
type: string
example: "cloudron._domainkey"
type:
type: string
example: "TXT"
expected:
type: string
example: "v=DKIM1; t=s; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDBooiGgy1csAPyIf2bfpSrhbVu8l086BXynoCPLlznxpa1HzhYJhv/Y72/3ce88WsSUs7NmtfAYSMc59BrC+ad3ibHTFj3Z5I6YwWsKymxQsoD2hd71IMkmHe9I9zV+r2NTiBwTFSfli8+GUUTMSwCl/vb4o53DRVkCxXBlxNGvQIDAQAB"
value:
type: string
example: "v=DKIM1; t=s; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDBooiGgy1csAPyIf2bfpSrhbVu8l086BXynoCPLlznxpa1HzhYJhv/Y72/3ce88WsSUs7NmtfAYSMc59BrC+ad3ibHTFj3Z5I6YwWsKymxQsoD2hd71IMkmHe9I9zV+r2NTiBwTFSfli8+GUUTMSwCl/vb4o53DRVkCxXBlxNGvQIDAQAB"
status:
type: boolean
example: true
ptr:
type: object
properties:
domain:
type: string
example: "59.133.179.95.in-addr.arpa"
name:
type: string
example: "95.179.133.59"
type:
type: string
example: "PTR"
value:
type: string
example: "my.example.com"
expected:
type: string
example: "my.example.com"
status:
type: boolean
example: true
rbl:
type: object
properties:
status:
type: boolean
example: true
ip:
type: string
example: "1.2.3.4"
servers:
type: array
example: []
relay:
type: object
properties:
value:
type: string
example: "OK"
status:
type: boolean
example: true
/mail/{domain}/enable:
post:
summary: Enable Incoming Email
description: Enable incoming email for the domain to receive emails. By default, only email sending is enabled.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: enable mailboxes
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
responses:
202:
description: OK
/mail/{domain}/mail_from_validation:
post:
summary: Set Mail From Validation
description: Set Mail From Validation
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: from validation
schema:
type: object
required:
- enabled
properties:
enabled:
type: boolean
responses:
202:
description: OK
/mail/{domain}/catch_all:
post:
summary: Set Catchall
description: Set Catchall addresses
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: catchall addresses
schema:
type: object
required:
- addresses
properties:
addresses:
type: array
example: [ 'mailbox@example.com' ]
responses:
202:
description: OK
/mail/{domain}/relay:
post:
summary: Set SMTP Relay
description: Configure a SMTP relay for this domain
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: relay settings
schema:
type: object
required:
- provider
properties:
provider:
$ref: '#/definitions/MailRelayProvider'
host:
type: string
port:
type: number
username:
type: string
password:
type: string
acceptSelfSignedCerts:
type: boolean
responses:
202:
description: OK
/mail/{domain}/banner:
post:
summary: Set Mail Signature
description: Set Mail Signature
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: banner
schema:
type: object
required:
- text
properties:
text:
type: string
html:
type: string
responses:
202:
description: OK
/mail/{domain}/send_test_mail:
post:
summary: Test Mail
description: Sent a test mail from domain.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: banner
schema:
type: object
required:
- to
properties:
to:
type: string
example: "hello@example.com"
responses:
202:
description: OK
/mail/{domain}/mailbox_count:
get:
summary: Get Mailbox Count
description: Get mailbox count.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
responses:
200:
description: OK
schema:
type: object
properties:
count:
type: number
/mail/{domain}/mailboxes:
get:
summary: List Mailboxes
description: List mailboxes for this domain.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- $ref: '#/parameters/PaginationPage'
- $ref: '#/parameters/PaginationPerPage'
- in: query
name: search
type: string
default: ''
responses:
200:
description: OK
schema:
type: object
properties:
mailboxes:
type: array
items:
$ref: '#/definitions/Mailbox'
post:
summary: Add Mailbox
description: Add mailbox.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- in: body
name: mailbox
schema:
type: object
required:
- name
- ownerId
- ownerType
properties:
name:
type: string
example: webmaster
ownerId:
type: string
example: uid-be9dcf57-ad65-40e0-a3f8-d1c75974bf01
ownerType:
type: string
example: user
responses:
201:
description: OK
/mail/{domain}/mailboxes/{name}:
get:
summary: Get Mailbox
description: Get mailbox information.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- $ref: '#/parameters/MailboxName'
responses:
200:
description: OK
schema:
$ref: '#/definitions/Mailbox'
post:
summary: Update Mailbox
description: Update mailbox.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- $ref: '#/parameters/MailboxName'
responses:
204:
description: OK
delete:
summary: Delete Mailbox
description: Delete mailbox.
tags: [ "Mail" ]
parameters:
- $ref: '#/parameters/DomainName'
- $ref: '#/parameters/MailboxName'
- in: body
name: delete options
schema:
type: object
properties:
deleteMails:
type: boolean
description: Also delete emails in mailbox.
default: false
responses:
201:
description: OK