location: <string>, // subdomain on which app is installed
fqdn: <string>, // the FQDN of this app
altDomain: <string> // alternate domain from which this app can be reached
accessRestriction: null || { // list of users and groups who can access this application
users: [ ],
groups: [ ]
},
lastBackupId: <string>, // last known backup of this app
manifest: <manifest>, // the application manifest
portBindings: { // mapping from application ports to public ports
},
iconUrl: <url>, // a relative url providing the icon
memoryLimit: <number> // memory constraint in bytes
}
```
`id` is an unique id for this application.
`appStoreId` is the Cloudron Store id of this application. Cloudron will use this id to look for updates to this application. This can be null if none was provided at installation time.
`manifest` is the [Cloudron Manifest](/references/manifest.html) of the app.
`installationState` is one of the values below:
*`pending_install` - The app is being installed. Use the `installationProgress` field to track the progress.
*`pending_configure` - The app is being re-configured. For example, if the app was moved to a new location or the port bindings was changed.
*`pending_uinstall` - The app is being uninstalled.
*`pending_restore` - The app is being restored from a previous backup.
*`pending_update` - The app is being updated.
*`pending_force_update` - The app is being force-updated.
*`pending_backup` - The app is being backed up.
*`error` - There was an error executing one of the above pending commands.
*`installed` - The app is installed. Use the `runState` and `health` to determine if the app is running and healthy.
`installationProgress` is a string indicating the progress when the app's `installationState` is one of the `pending_*` states. It is
of the format `<percent>, <message>`.
`runState` is one of the values below:
*`pending_start` - The app is being started.
*`pending_stop` - The app is being stopped.
*`stopped` - The app was stopped.
*`running` - The app is running.
`health` is one of the values below:
*`healthy` - The app is responding to health checks and is healthy.
*`unhealthy` - The app is not responding to health checks.
*`error` - There was an error checking the health of the app.
*`dead` - The app is dead. Most likely it was stopped or being uninstalled.
`location` is the subdomain on which the app is installed. This can be empty if the app was installed on the naked domain. The app can be
accessed from `fqdn` i.e `https//<fqdn>`. If `altDomain` is set, the app should be accessed from `https://<altDomain>`.
monotonicTimestamp: <number>, // time passed since boot
message: [ <byte>,... ], // utf8 buffer
source: <process name> // source of this message
}
```
Logs are aggregated from one or more `source`s. The application logs have the `source` set to `main`.
Other sources include `scheduler`.
### Get log stream
GET `/api/v1/apps/:appId/logstream` <scope>admin</scope>
Stream the logs of an application with id `appId` as a `text/event-stream`. See the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
interface documentation for details.
The `lines` query parameter can be used to specify the number of log lines to prefetch.
box: <semver>, // Set to the next available Cloudron version
apps: {
<appid>: <semver>. // Set to next available app version
...
}
},
progress: { // See progress API
},
isCustomDomain: <boolean>, // false if the cloudron is on a .cloudron.me subdomain. true otherwise
developerMode: <boolean>,
region: <string>, // the geo-region of this Cloudron
size: <string>, // the size of this Cloudron
billing: <boolean>, // true if the user has setup billing
memory: <string>, // the physical memory
provider: <string>,
cloudronName: <string> // the name of this cloudron
}
```
## Eventlog
### List events
GET `/api/v1/eventlog` <scope>admin</scope>
Lists all the past events.
The `action` query parameter can be used to list events of a specific action.
The `search` query parameter can be used to do a wildcard ('*search*') on the data field.
This API supports [pagination](/references/api.html#pagination) - use the `page` and `per_page` query parameters to get specific pages.
Response (200):
```
{
eventlogs: [
{
id: <string>, // unique id for the event
action: <enum>, // see below
source: <object>, // originator of this event
data: <object>, // value depends on action. see below
creationTime: <date> // ISO-8601 date in UTC
},
....
]
}
```
`action` is one of the values below:
* cloudron.activate
* app.configure
* app.install
* app.restore
* app.uninstall
* app.update
* backup.finish
* backup.start
* certificate.renew
* settings.climode
* cloudron.start
* cloudron.update
* user.add
* user.login
* user.remove
* user.update
`source` contains information on the originator of the action. For example, for user.login, this contains the IP address, the appId and the authType (ldap or simpleauth or oauth).
`data` contains information on the event itself. For example, for user.login, this contains the userId that logged in. For app.install, it contains the manifest and location of the app that was installed.
To list all the app installation events:
```
curl -X GET -H 'Authorization: Bearer cb0463455a6606482be7956fc3abd53330ae23244e3492cda3914a2c5154c47e' https://my-demo.cloudron.me/api/v1/eventlog?action=app.install
```
## Groups
Cloudron groups are a mechanism to restrict application access to a subset of users. You can add one or more users
to a group and assign one or more groups to an application. Only users that are members of any of the groups can access the application.
Group membership is dynamic. Users instantly lose or gain access to an application based on their group
membership.
### Create group
POST `/api/v1/groups` <scope>admin</scope>
Creates a new group.
Request:
```
{
name: <string>
}
```
`name` must be atleast 2 characters. The special built-in group named `admin` has all the
Cloudron administrators.
Response (200):
```
{
id: <string>,
name: <string>
}
```
### Get group
GET `/api/v1/groups/:groupId` <scope>admin</scope>
Gets an existing group with id `groupId`.
Response (200):
```
{
id: <string>,
name: <string>,
userIds: [ <string>, ... ] // list of users that are part of this group
GET `/api/v1/settings/cloudron_name` <scope>admin</scope>
Gets the name of the Cloudron.
Note that the name is also available without authentication using the [Get status](/references/api.html#get-status) API.
```
Response (200):
{
name: <string>
}
```
### Set name
POST `/api/v1/settings/cloudron_name` <scope>admin</scope>
Sets the name of the Cloudron.
The Cloudron name is shown in the title bar and all the login screens. It has a maximum length of 32 characters.
Request:
```
{
name: <string>
}
```
### Get timezone
GET `/api/v1/settings/time_zone` <scope>admin</scope>
Gets the timezone of the Cloudron.
Timezone is automatically set based on the IP address from where the Cloudron was activated. This timezone is used with the [auto update pattern](/references/api.html#get-auto-update-pattern) to trigger updates at the
correct time.
```
Response (200):
{
timeZone: <string> // the timezone
}
```
### Set timezone
POST `/api/v1/settings/time_zone` <scope>admin</scope>
Sets the time zone of the Cloudron.
Timezone is automatically set based on the IP address from where the Cloudron was activated. This timezone is used with the [auto update pattern](/references/api.html#get-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.
Request:
```
{
timeZone: <string>
}
```
## Users
### Create user
POST `/api/v1/users` <scope>admin</scope>
Creates a new user.
Request:
```
{
email: <email>, // required
invite: <boolean>, // required
username: <string>, // optional
displayName: <string> // optional
}
```
`invite` indicates if the user should be sent an invitation email. The invitation email allows the user
to setup a username and password. Set this to `false` to send out a custom invitation email of your own
to the user. The invitation link can be constructed based on the `resetToken` in the response.
`username` has to be at least two characters long and must be alphanumeric. If unspecified, the new user
can pick any available name on first sign up. For security, `username` cannot be changed once set.
Some apps (incorrectly) use the `username` as their unique identifier. As a result, it might mistake a newly created user as a previous user with the same username. If you want to reset the username, delete the existing
the user and create a new one again.
`displayName` may consist of one or more words to specify the first name and surname.
Response (201):
```
{
id: <string>,
username: <string>,
displayName: <string>,
email: <email>,
groupIds: [ <string>, ... ]
resetToken: <string> // User can sign up at https://my-demo.cloudron.me/api/v1/session/account/setup.html?reset_token=<resetToken>
}
```
### Get user
GET `/api/v1/users/:userId` <scope>admin</scope>
Gets detailed information about a specific user with id `userId`.
Response (200):
```
{
id: <string>,
username: <string>,
email: <email>,
groupIds: [ <string>, ... ], // list of groups this user is part of
admin: <boolean>, // a boolean indicating if this user is an admin
displayName: <string>
}
```
### List users
GET `/api/v1/users` <scope>admin</scope>
Lists all users.
Response (200):
```
{
users: [
{
id: <string>,
username: <string>,
email: <email>,
displayName: <string>,
groupIds: [ <string>, ... ], // list of groups this user is part of
admin: <boolean> // a boolean indicating if this user is an admin
},
...
]
}
```
### Update user
POST `/api/v1/users/:userId` <scope>admin</scope>
Modify user's email or display name. As noted in [Create user](/references/api.html#create-user), username
cannot be changed.
Request:
```
{
email: <email>, // optional
displayName: <displayName> // optional
}
```
Response (204):
```
{}
```
### Re-invite user
POST `/api/v1/users/:userId/invite` <scope>admin</scope>
Resends the invitation link to an existing user.
A re-invite call invalidates any previous invite links. The invitation link can be constructed based on the resetToken in the response.
Request:
```
{}
```
Response (200):
```
{
resetToken: <string> // // User can sign up at https://my-demo.cloudron.me/api/v1/session/account/setup.html?reset_token=<resetToken>
}
```
### Set groups
PUT `/api/v1/users/:userId/groups` <scope>admin</scope>
Sets the groups for the user with id `userId`.
Groups are identified by groupIds which can be retrieved using the
