Download OpenAPI specification:Download
Cloudron provides a RESTful API to manage apps, users, groups, domains and other resources.
All of the functionality in the Cloudron Dashboard is available through the API, allowing you to script complex actions.
If you are an app developer, the Cloudron CLI tool implements a workflow that allows you to develop apps on your Cloudron. The CLI tool uses the REST API documented here.
The API follows standard HTTP REST API conventions.
Method | Usage |
---|---|
GET | Retrieveal operations |
DELETE | Destroys a resource |
POST | Create new objects or start a new task. Also used to update parts of a resource |
PUT | Idempotent operation that replaces a resource |
PATCH | API does not support PATCH |
HEAD | Read response headers and get no response |
The API follows standard HTTP REST API response conventions.
2xx responses indicate success. 4xx responses indicate request errors. 5xx responses indicate server errors.
Name | Description |
---|---|
200 | Success. Operation succeeded, response body contains more information |
204 | Success. Operation succeeded, empty response body |
401 | Access Denied. Unauthorized API call |
403 | Forbidden. Authorized but operation not permitted |
5xx | Internal Server error |
When listing objects, query parameters page
and per_page
can be passed in. Note that these parameters have index
starting from 1.
To use the REST API, you must first create an API token. This token can be provided in two ways:
?access_token=<token>
Bearer <token>
API Tokens can be create as Readonly
or Read and Write
. With Readonly
token only GET operations can be performed.
We use curl
to demonstrate how to use the API. The Cloudron Dashboard Domain and the API Token are variable fields.
You can export them in your shell as follows:
export CLOUDRON_DOMAIN=my.domain.com
export CLOUDRON_TOKEN=your_token_here
To list the domains using cURL and the Authorization
header:
curl -H 'ContentType: application/json' -H 'Authorization: Bearer $CLOUDRON_TOKEN' https://$CLOUDRON_DOMAIN/api/v1/domains
Alternately, to use the query parameter:
curl -H 'ContentType: application/json' 'https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN'
To use the Bearer Authentication, you must first create an API token.
The API Token can be passed via the Authorization header Bearer <token>
:
curl -H 'ContentType: application/json' -H 'Authorization: Bearer $CLOUDRON_TOKEN' https://$CLOUDRON_DOMAIN/api/v1/domains
bearer
To use the Query Parameter Authentication, you must first create an API token.
The API Token can be passed via the access_token
query parameter:
curl -H 'ContentType: application/json' 'https://$CLOUDRON_DOMAIN/api/v1/domains?access_token=$CLOUDRON_TOKEN'
access_token
App passwords can be used as a security measure in desktop, email & mobile clients. For example, if you are trying out a new mobile app from an untrusted vendor, you can generate a temporary password that provides access to a specific app. This way your main password does not get compromised (and thus providing access to other apps as well).
List the App Passwords. App Passwords are personal for a user.
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords"
{- "appPasswords": [
- {
- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "name": "Password For Nextcloud mobile app",
- "userId": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5",
- "creationTime": "2022-03-05T02:30:00.000Z"
}
]
}
Create an App Password
name required | string (name) A label/display name for the the password |
identifier | string (identifier) The application that this password will authenticate. This can be an app id or |
{- "name": "Password For Nextcloud mobile app",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5"
}
{- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "password": "01e536bbd289619f"
}
Get App Password by ID
passwordId required | string App Password Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"
{- "id": "uid-1bf6f7a0-c909-41f5-96a1-68183a6edd8b",
- "name": "Password For Nextcloud mobile app",
- "userId": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "identifier": "743e4cee-448e-4f82-b880-8a530265b1e5",
- "creationTime": "2022-03-05T02:30:00.000Z"
}
Deletes the App Password. All future requests using this password will instantly fail.
passwordId required | string App Password Id |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/app_passwords/$PASSWORD_ID"
{ }
The Branding configuration can be used to customize various aspects of the Cloudron like it's name, logo and footer.
Get the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_avatar"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Set the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages.
avatar required | string <binary> |
curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name" --form avatar=@localfilename.png
{ }
Get the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/branding/cloudron_name"
{- "name": "string"
}
Set the Cloudron Name. The Cloudron name is used in Email templates, Dashboard header and the Login pages.
name required | string [ 1 .. 64 ] |
{- "name": "string"
}
{ }
Cloudron Healthcheck route and various global configuration like language & timezone can be found here.
Simple healthcheck route to check if Cloudron is running or not. This route does not require any authentication.
curl -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/status"
{- "version": "7.6.0"
}
Get the Cloudron Avatar. The Cloudron avatar (icon) is used in Email templates, Dashboard header and the Login pages. This route does not require any authentication.
curl -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/avatar"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
List the available languages (translations). This route does not require any authentication.
curl -H "Content-Type: application/json" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/languages"
{- "languages": [
- "en",
- "de",
- "fr",
- "nl"
]
}
The Cloudron Language is the language used for the Dashboard, Login Page, Invitation and Reset emails. Note that users can always set a different language for their Dashboard in their profile. The default language is en
(English).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/language"
{- "language": "de"
}
The Cloudron Language is the language used for the Dashboard, Login Page, Invitation and Reset emails. Note that users can always set a different language for their Dashboard in their profile. The default language is en
(English).
language required | string Default: "en" The Language ID |
{- "language": "de"
}
{ }
TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/cloudron/time_zone"
{- "timeZone": "de"
}
TimeZone used for various cron jobs like backup, updates, date display in emails etc. Note that server time zone and database is always UTC.
timeZone |
{- "timeZone": "Europe/Zurich"
}
{ }
A private docker registry can be setup to pull the docker images of custom apps.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/docker/registry_config"
{- "provider": "digitalocean",
- "serverAddress": "docker.io",
- "username": "string",
- "email": "string",
- "password": "string"
}
A private docker registry can be setup to pull the docker images of custom apps.
provider required | string Enum: "aws" "digitalocean" "dockerhub" "google-cloud" "linode" "quay" "treescale" "other" "noop" Docker Registry Provider |
serverAddress | string Address of the Docker Registry |
username | string Username for authenticating with the Docker Registry |
string Email for authenticating with the Docker Registry | |
password | string Password for authenticating with the Docker Registry |
{- "provider": "digitalocean",
- "serverAddress": "docker.io",
- "username": "string",
- "email": "string",
- "password": "string"
}
{ }
Get the Directory Server configuration
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/directory_server/config"
{- "enabled": true,
- "secret": true,
- "allowlist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Set the Directory Server configuration
enabled required | boolean If Directory Server is enabled |
secret | string Password for authenticating with the Directory Server |
allowlist | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "enabled": true,
- "secret": true,
- "allowlist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
List events
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
search | string Search string |
actions | Array of strings (action) Items Enum: "app.clone" "app.configure" "app.repair" "app.install" "app.restore" "app.import" "app.uninstall" "app.update" "app.update.finish" "app.backup" "app.backup.finish" "app.login" "app.oom" "app.up" "app.down" "app.start" "app.stop" "app.restart" "backup.finish" "backup.start" "backup.cleanup.finish" "certificate.new" "certificate.cleanup" "cloudron.activate" "cloudron.provision" "cloudron.install.finish" "cloudron.start" "dashboard.domain.update" "domain.add" "domain.update" "domain.remove" "dyndns.update" "mail.location" "mail.enabled" "mail.disabled" "mail.box.add" "mail.box.remove" "mail.box.update" "mail.list.add" "mail.list.remove" "mail.list.update" "service.configure" "service.rebuild" "service.restart" "cloudron.update" "cloudron.update.finish" "user.add" "user.login" "user.login.ghost" "user.logout" "user.remove" "user.update" "volume.add" "volume.update" "volume.remount" "volume.remove" "support.ticket" "support.ssh" Example: actions=volume.add,volume.remove Comma separated list of actions |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog"
{- "eventlogs": [
- {
- "id": "7f32f714-ad40-4bea-b5e5-e71562679f0c",
- "action": "volume.add",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "source": { },
- "data": { }
}
]
}
Get event by ID
eventId required | string Event Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/eventlog/$EVENT_ID"
{- "id": "7f32f714-ad40-4bea-b5e5-e71562679f0c",
- "action": "volume.add",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "source": { },
- "data": { }
}
The External Directory connector allows users from your existing LDAP or active directory to authenticate with Cloudron.
Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/config"
{- "provider": "jumpcloud",
- "url": "docker.io",
- "baseDn": "string",
- "usernameField": "string",
- "filter": "string",
- "groupBaseDn": "string",
- "bindDn": "string",
- "bindPassword": "string"
}
Cloudron will synchronize users and groups from this external LDAP or ActiveDirectory server
provider required | string Enum: "ad" "cloudron" "jumpcloud" "okta" "univention" "other" "noop" External LDAP Provider |
url | string Address of the Docker Registry |
baseDn | string Base DN for users |
usernameField | string LDAP Field to use as the username |
filter | string LDAP Filter to use for filtering users |
groupBaseDn | string Base DN for groups |
bindDn | string LDAP authentication username |
bindPassword | string LDAP authentication password |
{- "provider": "jumpcloud",
- "url": "docker.io",
- "baseDn": "string",
- "usernameField": "string",
- "filter": "string",
- "groupBaseDn": "string",
- "bindDn": "string",
- "bindPassword": "string"
}
{ }
Trigger synchronization with external LDAP server
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/external_ldap/sync"
{- "taskId": 295
}
Gets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/blocklist"
{- "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Sets the IP address Block List. Requests originating from these addresses are blocked by the firewall (iptables).
blocklist required | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "blocklist": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
Gets the Dynamic DNS configuration. The Dynamic DNS option keeps all the DNS records in sync when the IP address changes dynamically (like in home networks).
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/dynamic_dns"
{- "enabled": true
}
Sets the Dynamic DNS configuration. The Dynamic DNS option keeps all the DNS records in sync when the IP address changes dynamically (like in home networks).
enabled required | boolean |
{- "enabled": true
}
{ }
Get the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4_config"
{- "provider": "noop"
}
Set the IPv4 configuration settings that Cloudron uses to configure to the DNS A records.
provider required | string The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:
|
{- "provider": "noop"
}
{ }
Get the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6_config"
{- "provider": "noop"
}
Set the IPv6 configuration settings that Cloudron uses to configure to the DNS AAAA records.
provider required | string The provider type determines how IP address is determined for use in IPv4 (A) or IPv6 (AAAA) records Sort order:
|
{- "provider": "noop"
}
{ }
Gets the configured IPv4 address of the server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv4"
{- "ip": "5.75.134.144"
}
Gets the configured IPv6 address of the server
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/network/ipv6"
{- "ip": "2402:3a80:423:eb84:d72e:b50:7c58:83eb"
}
Cloudron displays notifications in the dashboard for various events like: app down, app out of memory, low disk space, updates available, app update etc. The notifications can be read by clicking on the bell icon in the navigation bar.
List notifications
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
acknowledged | boolean Filter by acknowledged status |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get notification by ID
notificationId required | string Notification Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/notifications/$NOTIFICATION_ID"
{- "id": "50",
- "eventId": "051ceb23-5003-4b03-b46e-521611b02a1c",
- "title": "Reboot Required",
- "message": "To finish ubuntu security updates, a reboot is necessary.",
- "creationTime": "2022-03-05T02:30:00.000Z",
- "acknowledged": false
}
Set notification acknowledged state. Unacknowledged notifications count appears in the navbar of the Dashboard.
notificationId required | string Notification Id |
acknowledged required | boolean Set notification to acknowledged or not |
{- "acknowledged": true
}
{ }
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile"
{- "id": "string",
- "username": "messi",
- "email": "goat@football.com",
- "fallbackEmail": "goat@soccer.com",
- "displayName": "Lionel Messi",
- "twoFactorAuthenticationEnabled": true,
- "role": "owner",
- "hasBackgroundImage": true,
- "avatarUrl": "string",
- "source": "ldap"
}
Update user's profile information
string Unique email address | |
fallbackEmail | string Unique fallback email address. This is the address password reset is sent to. This requires the |
password | string When trying to change the |
displayName | string Full name of the user |
{- "email": "goat@football.com",
- "fallbackEmail": "goat@soccer.com",
- "password": "string",
- "displayName": "Lionel Messi"
}
{ }
Get the User's custom avatar (icon). This route is public. As a simple security measure, this requires the user id.
To display the user's avatar , use the avatarUrl
property of the profile endpoint. The avatarUrl
will link to this endpoint when the user has a custom icon.
userId required | string User Id |
curl "https://$CLOUDRON_DOMAIN/api/v1/profile/avatar/$USER_ID"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get the user's custom background image for the dashboard.
Use the hasBackgroundImage
property of the profile endpoint to determine if the user has a custom background image.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/backgroundImage"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Set the user's background image for the dashboard
backgroundImage required | string <binary> |
curl -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/background_image" --form backgroundImage=@localfilename.png
{ }
Update user's password
password required | string Current password |
newPassword required | string New password |
{- "password": "current_password",
- "newPassword": "new_password"
}
{ }
Sets 2FA Secret. Enabling 2FA is a two step process:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/profile/twofactorauthentication_secret"
{- "secret": "string",
- "qrcode": "string"
}
Enables Two Factor Authentication. Enabling 2FA is a two step process:
totpToken required | string Current TOTP Token based off the generate secret |
{- "totpToken": "string"
}
{ }
Disable 2FA
password required | string Current password |
{- "password": "current_password"
}
{ }
Trigger manual renewal of Let's encrypt certificates. Note that certs are automatically renewed by Cloudron, 1 month before their expiry.
rebuild | boolean Default: false When set all the nginx configurations are regenerated. |
{- "rebuild": false
}
{- "taskId": 295
}
Gets the list of proxies in front of Cloudron. Cloudron will trust the various reverse proxy headers like X-Forwarded-For
when requests originate from these proxy addresses.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/reverseproxy/trusted_ips"
{- "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
Sets the list of proxies in front of Cloudron. Cloudron will trust the various reverse proxy headers like X-Forwarded-For
when requests originate from these proxy addresses.
trustedIps required | string (IpEntries) Newline separated list of IP entries. Each entry is an IP address or an IP address range in CIDR notation. Lines starting with |
{- "trustedIps": "# This is a IPv4 range\n5.75.0.0/16\n# This is an IPv6 address\n2604:a880:1:4a::2:7000"
}
{ }
Checks whether a server reboot is required. Automatic Ubuntu updates often requires a reboot to apply changes to system libraries.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/reboot"
{- "rebootRequired": true
}
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/system/reboot"
{ }
Tasks are asynchronous operations performed in the background. Each task can be monitored separately using the task id.
List tasks
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
type | string (type) Enum: "app" "backup" "update" "checkCerts" "syncDyndns" "prepareDashboardLocation" "cleanBackups" "syncExternalLdap" "changeMailLocation" "syncDnsRecords" "updateDiskUsage" Example: type=cleanBackups Filter by Task Type |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks"
{- "tasks": [
- {
- "id": "364",
- "type": "cleanBackups",
- "percent": 1,
- "message": "Checking expired certs for removal",
- "error": {
- "message": "string",
- "code": 0
}, - "active": true,
- "pending": true,
- "creationTime": "2023-09-07T13:18:35.000Z",
- "result": { },
- "ts": "2023-09-07T13:18:35.000Z",
- "success": true
}
]
}
Get task by ID
taskId required | string Task Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID"
{- "id": "364",
- "type": "cleanBackups",
- "percent": 1,
- "message": "Checking expired certs for removal",
- "error": {
- "message": "string",
- "code": 0
}, - "active": true,
- "pending": true,
- "creationTime": "2023-09-07T13:18:35.000Z",
- "result": { },
- "ts": "2023-09-07T13:18:35.000Z",
- "success": true
}
Get task logs. Use this end point to download logs. If you want to follow logs tail -f
style, use the logstream endpoint instead.
taskId required | string Task Id |
lines | integer Default: 10 Number of lines in the log |
format | string Default: "json" Enum: "json" "short" Format of the lines in the log file |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logs?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Get task logs. Use this endpoint to stream logs (tail -f
style). If you want to download logs, use the logs endpoint instead. This endpoint implements Server Side Events. Use the EventSource interface to parse the returned stream.
taskId required | string Task Id |
lines | integer Default: 10 Number of lines in the log |
curl -H "Accept: text/event-stream" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASKS_ID/logstream?lines=100"
{- "status": "HTTP Status Message",
- "message": "Something bad happenned"
}
Stops a task
taskId required | string Task Id |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tasks/$TASK_ID/stop"
{ }
List the API tokens created by the user. Note that tokens are personal (per user) and not global.
page | integer >= 1 Default: 1 Page number |
per_page | integer >= 1 Default: 25 Items per page |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens"
{- "tokens": [
- {
- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
]
}
Create an API token
name required | string (properties-name) A label/display name for the the token |
expiresAt | integer (expires) Time (epoch) when the token expires |
scope | object (scope) Token permissions. This is a map of routes with r (read) or rw (read write) permission |
{- "name": "Token For Automation",
- "expiresAt": 1725615073184,
- "scope": {
- "*": "rw"
}
}
{- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
Get token by ID
tokenId required | string Token Id |
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"
{- "id": "tid-f3694710-ec08-4352-b8bc-b094ae40a0f4",
- "name": "Token For Automation",
- "accessToken": "yeRpaRKtJwYJMglFAouYmpoRuN8syAmWXW75ca57AdO",
- "identifier": "uid-743e4cee-448e-4f82-b880-8a530265b1e5",
- "clientId": "cid-sdk",
- "expires": 1725615073184,
- "lastUsedAt": "2023-09-07T13:18:35.000Z",
- "scope": {
- "*": "rw"
}
}
Deletes the Token. All future requests using this token will instantly fail.
tokenId required | string Token Id |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/tokens/$TOKEN_ID"
{ }
Gets information of any pending update to apps and the platform. This endpoint returns the cached update information and does not contact cloudron.io App Store. The update information could be stale and if you want the latest information use the checkForUpdates endpoint.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/updates"
{- "updates": {
- "box": {
- "version": "string",
- "changelog": [
- "string"
], - "sourceTarballUrl": "string",
- "sourceTarballSigUrl": "string",
- "boxVersionsUrl": "string",
- "boxVersionsSigUrl": "string",
- "unstable": true
}, - "appId1": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}, - "appId2": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}
}
}
Gets information of any pending update to apps and the platform by contacting cloudron.io App Store. This call can take a while since it has to get the update information of each installed app. Use the getUpdates endpoint to get the update information since the last check.
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/check_for_updates"
{- "updates": {
- "box": {
- "version": "string",
- "changelog": [
- "string"
], - "sourceTarballUrl": "string",
- "sourceTarballSigUrl": "string",
- "boxVersionsUrl": "string",
- "boxVersionsSigUrl": "string",
- "unstable": true
}, - "appId1": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}, - "appId2": {
- "id": "org.wordpress.cloudronapp",
- "creationDate": "2023-08-30T11:33:42.000Z",
- "publishState": "string",
- "ownerId": "string",
- "manifest": { },
- "iconUrl": "string",
- "unstable": true
}
}
}
Updates Cloudron to the next available release. The update is started asynchronously and can be monitored using the tasks API.
skipBackup | boolean Default: false Whether backup should be skipped before performing the update. |
{- "skipBackup": false
}
{- "taskId": 295
}
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/updater/autoupdate_pattern"
{- "pattern": "00 00 1,3,5,23 * * *"
}
Sets the automatic update schedule
pattern required | string (CronPattern) Automatic update pattern in cron format. |
{- "pattern": "00 00 1,3,5,23 * * *"
}
{ }
Get the current profile configuration for all users in the user directory.
curl -H "Content-Type: application/json" -H "Authorization: Bearer $CLOUDRON_TOKEN" "https://$CLOUDRON_DOMAIN/api/v1/user_directory/profile_config"
{- "lockUserProfiles": true,
- "mandatory2FA": true
}
Set the current profile configuration for all users in the user directory.
lockUserProfiles required | boolean If profile changes by users is disabled |
mandatory2FA required | boolean If two factor authentication for all users is enforced |
{- "lockUserProfiles": true,
- "mandatory2FA": true
}
{ }