2563 lines
70 KiB
YAML
2563 lines
70 KiB
YAML
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
|