Input/output

All output will be JSON formatted.

If JSON input is preferred to URL key-value pairs, JSON can be sent in the raw HTTP POST data.

Table of contents

• List available applications and application information
  
• Install an application
  
• Import an existing application (from the local server or a different server)
  
• List installed applications
  
• List installed application backups
  
• View/sync an installed application
  
• Edit an installed application
  
• Backup an installed application
  
• Clone an installed application
  
• Update an installed application
  
• Uninstall an installed application
  
• Restore a backup
  
• Delete a backup
  
• Import a backup
  
• List currently executing and recently completed tasks
  

List available applications and application information

HTTP GET or POST:

/url/to/installatron?api=json&cmd=browser
/url/to/installatron?api=json&cmd=browser&application=magento

NAME	VALUE
cmd	browser
api	json
application	optional The ID of the application to list available versions of. This can be a single application or an array of multiple applications. By default the latest version of each application is listed. Listed versions are ordered correctly.
version	optional If application is set to one application, set this to only list the specific version.
from-version	optional If application is set to one application, set this to list all versions from specified version to the latest version. Each listed version includes a "upgrade_from" member which reveals whether an install at the specified version can upgraded to the listed version (values of "none" or "manual" mean it cannot). Listed versions are ordered correctly.
versions-available-from	optional If application is set to one application, instead of the usual output this will return two lists, "versions-available" and "versions-available-minor", each listing the versions upgradable to from the specified value.
language	optional The language application information should be returned in. For example, "en" for English or "zh_tw" for Chinese Traditional. If omitted, the defined website's default language or English is assumed. See: Available Installatron Translations.

Return values:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Table of release meta data. NAME VALUE appid internal id of the app version release version branch release branch/channel name display name of the app category display category of the app (e.g., "Content Management") type app type (e.g., "blog") date date of release (YYYY-MM-DD format) license app license type (e.g., "open source", "commercial") tags list of release tags (e.g., "security", "minor", "major") description Installatron-written description of the app authordescription author-written description of the app (typically much longer) changelog author-written log of changes from previous release upgrade whether upgrading to this release is considered "minor" or "major", or "none" if upgrading is not possible install whether installing this release is possible ("auto") or not ("none") link_site link to app website link_showcase link to app showcase link_docs link to app documentation link_faq link to app FAQ link_support link to app support page link_changelog link to app release changelog requirements table of requirements. Common requirements include: NAME VALUE diskspace minimum disk space (e.g., "40M") php PHP version ramge (e.g., "5.2.5-5.5.999,7.1-") mysql MySQL version range (e.g., "5-") mysql_table_prefix default MySQL table prefix (e.g., "wp_") languages list of languages the release can be installed in fields table of fields (see below sample output) images list of release assets including images and screenshots (see below sample output)

Install an application

Note: When the install is complete, the new install owner will be emailed install login information.

HTTP GET or POST:

/url/to/installatron?api=json&cmd=install

NAME	VALUE
cmd	install
api	json
application	required The ID of the application to be installed. For example, "wordpress" or "magento". Use the browser API to get a list of available applications.
version	optional, default is the latest compatible version The version of the application to be installed.
autoup	optional Change automatic update configuration. Values: 0 = Off (default); 1 = Update to minor versions only; 2 = Update to any version.
autoup_backup	optional Automatically create a backup and automatically restore the backup if the update fails. Values: 0 = Off; 1 = On (default).
url	required The URL to where the application should be installed.
url_ip	optional, default is the IP address resolved via DNS If the DNS will not resolve the provided url to the correct IP, use this argument to provide the correct IP.
db_host	optional, if omitted a new database is automatically created The database server.
db_name	optional, if omitted a new database is automatically created The pre-created database.
db_user	optional, if omitted a new database is automatically created The pre-created database username.
db_pass	optional, if omitted a new database is automatically created The pre-created database password.
db_prefix	optional, defaults to the prefix behavior configured at Installatron Admin > Features The prefix applied to database tables.
db_host_ip	optional, typically omitted If a different MySQL host value must be temporarily used to connect to the database, use this argument to provide the temporary address. Installed application files will be written with the "db_host" value, but Installatron will use "db_host_ip" while installing.
notification	optional List of email notifications to send for the installed application (each separated with a comma). Set a value of "all" to send all notifications (limited by those that are enabled in administration » Emails), or define an empty string to send no notifications. Available notifications: install install_error clone clone_error backup backup_error restore restore_error update_available update update_error plugin_update_available plugin_update plugin_update_error A sample value could look like: "update_available,update,update_error"
background	optional When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.
dryrun	optional When defined, the request payload is validated but not executed. Dryrun set to a value of 2 checks everything, and dryrun set to a value of 1 just checks input so it can return faster.

Optional automatic backup arguments:

NAME	VALUE
autobk	optional Change automatic backup configuration. Values: custom = A custom schedule; (id) = The schedule identified by (id).
autobk_daily	optional The number of daily backups (for the "custom" option)
autobk_weekly	optional The number of weekly backups (for the "custom" option)
autobk_monthly	optional The number of monthly backups (for the "custom" option)

Optional remote backup arguments:

NAME

VALUE

bkloc

optional Set this to the URI to a backup location (which will be associated with the defined "user" for the session). Supported protocols: Protocol Example URI Notes FTP ftp://user:pass@server/directory FTPS ftps://user:pass@server/directory SFTP sftp://user:pass@server/directory SSH ssh://user:pass@server/directory SSH with public key ssh://user:public-key@server/directory WebDAV webdav://user:pass@server/backups WebDAV (HTTPS) webdavs://user:pass@server/backups Dropbox dropbox2://auth-id:token@app-id OAuth only Amazon AWS S3 s3://aws-access-key:aws-secret-key@bucket-id.region-id Examples: ftp://user:pass@server sftp://user:pass@server/backups ftp://user:pass@server/backups webdav://user:pass@server/backups

Further optional arguments that depend on the application (get a full list of fields available for a specific application/version using the browser API):

NAME	VALUE
language	optional, default is the website's default language or English The language of the application to be installed. For example, "en" for English or "zh_tw" for Chinese Traditional. Use the browser API to get a list of available languages for the installed application.
login	optional, default is randomly generated value The username for the installed application's administrative account.
passwd	optional, default is randomly generated value The password for the installed application's administrative account. If omitted, a randomized password is assumed.
sitetitle	optional, default is "My blog" or similar The site title value for the installed application.
content	optional, default is "yes" Set to "yes" for the sample/demo template. Set to "no" for the blank install template. Set to the ID of the template for a different template.

Return values:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Table of installed application information.
task	Table of task information if executed as a background process.

Import an existing application (from the local server or a different server)

HTTP GET or POST:

/url/to/installatron?api=json&cmd=import

NAME	VALUE
cmd	import
api	json
user	required/optional Import the application to a specific user on the control panel. This field is required if the import command is performed as the server administrator or a reseller but is optional if performed as a user.
application	required The ID of the application to be imported or migrated. For example, "wordpress" or "magento". See: List of applications.
version	optional, defaults to the automatically-detected version The version of the application to be imported. If omitted, the version is automatically detected.
url	required For a local Import this is the URL to where the application is current located. For a remote Import (a Migration) this is the destination URL where the copy of the source application will be constructed.
url_ip	optional, default is the IP address resolved via DNS If DNS cannot resolve the provided url to the correct IP, use this argument to provide the correct IP.
source_url	required if migrating an installed application from a remote server If migrating an installed application from a remote server, include this argument to provide the source installed application URL. For example, "http://website.com/wordpress".
source_ftu	required if migrating an installed application from a remote server If migrating an installed application from a remote server, include this argument to provide the source installed application account information. Supported filesystem protocols: FTP FTPS SFTP SSH Specifically for WordPress only, Installatron Server also provides the option to migrate an installation using only the WordPress administrative username and password. No filesystem protocol is required in this case, just the WordPress administrative username and password. To use this option, provide the username and password in this format: app://username:password Examples: ftp://user:pass@website.com sftp://user:pass@website.com/public_html ftp://user:pass@website.com/public_html/phpbb app://user:pass (WordPress only)
source_ftu_key	optional, path to a SSH key file If migrating an installed application from a remote server over SSH or SFTP, the SSH/SFTP password can be left blank and an optional SSH key file can be defined here.
source_url_ip	optional, default is the IP address resolved via DNS If migrating an installed application from a remote server, include this argument to provide Installatron the IP address that Installatron should use for the source server. Providing this value means that Installatron will not need to perform DNS lookup on the source domain.
background	optional When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.
dryrun	optional When defined, the request payload is validated but not executed. Dryrun set to a value of 2 checks everything, and dryrun set to a value of 1 just checks input so it can return faster.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Table of installed application information.

List installed applications

HTTP GET or POST:

/url/to/installatron?api=json&cmd=installs

NAME	VALUE
cmd	installs
api	json
user	optional View the installs of a specific user on the control panel. The default is the control panel administrator.
q	optional Search installed application with a query. This searches the title, url, id, installer, and owner fields.
id	optional Display a specific installed application by ID.
filter-version-available	optional When set equal to "yes", only installed applications that have any new version upgrades available will be listed.
filter-version-available-minor	optional When set equal to "yes", only installed applications that have new minor version upgrades available will be listed.
filter-ownedaccounts	optional Add this parameter (as; filter-ownedaccounts=) if you wish to also see the installs of accounts owned by this user.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Detailed list of matched installed applications.

List installed application backups

HTTP GET or POST:

/url/to/installatron?api=json&cmd=backups

NAME	VALUE
cmd	backups
api	json
user	optional View the backups of a specific user on the control panel. The default is the control panel administrator.
q	optional Search installed application backups with a query. This searches the title, url, id, installer, and owner fields.
pid	optional Display only installed application backups that belong to this installed application ID. This can be used in conjunction with the "q" argument. (added with version 4.1.5)
id	optional Display a specific installed application backup by ID.
filter-ownedaccounts	optional Add this parameter (as; filter-ownedaccounts=) if you wish to also see the backups of accounts owned by this user.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Detailed list of matched installed application backups.

View/sync an installed application

HTTP GET or POST:

/url/to/installatron?api=json&cmd=view

NAME	VALUE
cmd	view
api	json
id	required The ID of the installed application to be synced and displayed.
addons	optional Set to a value of 1 to include a list of installed plugins and themes in the result. (WordPress only)

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Application details, similar to the "installs" API return value.

Edit an installed application

Note: Optional arguments can be omitted if they should remain unchanged.

HTTP GET or POST:

/url/to/installatron?api=json&cmd=edit

NAME	VALUE
cmd	edit
api	json
id	required The ID of the installed application to be edited.
url	optional, defaults to the existing value The URL to the installed application.
autoup	optional, defaults to the existing value Change automatic update configuration. Values: 0 = Off; 1 = Update to minor versions only; 2 = Update to any version.
autoup_backup	optional, defaults to the existing value Automatically create a backup and automatically restore the backup if the update fails. Values: 0 = Off; 1 = On (default).
notification	optional, defaults to the existing value List of email notifications to send for the installed application (each separated with a comma). Omit this argument to retain the current value, set a value of "all" to send all notifications (limited by those that are enabled in administration » Emails), or define an empty string to send no notifications. Available notifications: install install_error clone clone_error backup backup_error restore restore_error update_available update update_error plugin_update_available plugin_update plugin_update_error A sample value could look like: "update_available,update,update_error"
db_host	optional, defaults to the existing value The server that hosts the installed application's database.
db_name	optional, defaults to the existing value The name of the installed application's database.
db_user	optional, defaults to the existing value The database username used to connect to the installed application's database.
db_pass	optional, defaults to the existing value The database username password.
db_prefix	optional, defaults to the existing value The prefix each database table begins with, including trailing underscore (if any).

Automatic backup arguments:

NAME	VALUE
autobk	optional, defaults to the existing value Change automatic backup configuration. Values: custom = A custom schedule; (id) = The schedule identified by (id).
autobk_daily	optional, defaults to the existing value The number of daily backups (for the "custom" option)
autobk_weekly	optional, defaults to the existing value The number of weekly backups (for the "custom" option)
autobk_monthly	optional, defaults to the existing value The number of monthly backups (for the "custom" option)

Remote backup arguments:

NAME

VALUE

bkloc

optional, defaults to the existing value Set this to the URI to a backup location (which will be associated with the defined "user" for the session). Supported protocols: Protocol Example URI Notes FTP ftp://user:pass@server/directory FTPS ftps://user:pass@server/directory SFTP sftp://user:pass@server/directory SSH ssh://user:pass@server/directory SSH with public key ssh://user:public-key@server/directory WebDAV webdav://user:pass@server/backups WebDAV (HTTPS) webdavs://user:pass@server/backups Dropbox dropbox2://auth-id:token@app-id OAuth only Amazon AWS S3 s3://aws-access-key:aws-secret-key@bucket-id.region-id Examples: ftp://user:pass@server sftp://user:pass@server/backups ftp://user:pass@server/backups webdav://user:pass@server/backups

Further arguments that depend on the application (get a full list of fields available for a specific application/version using the browser API):

NAME	VALUE
language	optional, defaults to the existing value The language of the installed application. Use the browser API to get a list of available languages for the installed application.
login	optional, defaults to the existing value The username of the installed application's administrative account.
passwd	optional, defaults to the existing value The password of the installed application's administrative account.
email	optional, defaults to the existing value The email of the installed application's administrative account.
sitetitle	optional, defaults to the existing value The site title value of the installed application.

Remove any backups connected to this installed application from the database:

NAME	VALUE
delete-backups	optional, defaults to null Set to 'true' to delete any backups connected to the installed application from the Installatron database. The backup archives will be unaffected.

Remove the installed application from the database:

NAME	VALUE
delete	optional, defaults to null Set to 'true' to delete the installed application from the Installatron database only. The installed application files and tables will be unaffected.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.

Backup an installed application

HTTP GET or POST:

/url/to/installatron?api=json&cmd=backup

NAME	VALUE
cmd	backup
api	json
id	required The ID of the installed application to be backed up.
expiry	optional, defaults to never Possible values include: "never": The created backup will never expire. This is the default value. "auto": Automatically expire the backup based on the configured backup expiration rules (the default is 14 days) Any number: The created backup will expire after the number of days identified by the provided number.
background	optional When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task. Possible values include: Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc.. A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Clone an installed application

HTTP GET or POST:

/url/to/installatron?api=json&cmd=clone

NAME	VALUE
cmd	clone
api	json
id	required The ID of the installed application to be cloned.
url	required The URL where the application should be cloned to.
url_ip	optional, default is the IP address resolved via DNS If the DNS will not resolve the provided url to the correct IP, use this argument to provide the correct IP.
db_host	optional, if omitted a new database is automatically created The database server.
db_name	optional, if omitted a new database is automatically created The pre-created database.
db_user	optional, if omitted a new database is automatically created The pre-created database username.
db_pass	optional, if omitted a new database is automatically created The pre-created database password.
db_prefix	optional If a database prefix other than the default prefix should be used, specify the value here.
background	optional When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.
dryrun	optional When defined, the request payload is validated but not executed. Dryrun set to a value of 2 checks everything, and dryrun set to a value of 1 just checks input so it can return faster.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Update an installed application

Note: It's always recommended to create a backup prior to updating any installed application.

HTTP GET or POST:

/url/to/installatron?api=json&cmd=upgrade

NAME	VALUE
cmd	upgrade
api	json
id	required The ID of the installed application to be updated.
version	optional, default is the latest compatible version The version to be updated to. Use the browser API to get a list of available versions. Note: A value of 'current' can be used to skip updating (if only plugins and themes).
revert	optional, default is "no" If set to 'yes', a backup will be created prior to attempting the upgrade, and the backup will automatically be restored if the upgrade fails.
plugin	optional If set to '*' or a comma-separated list of plugin ID's, all plugins or the listed plugins will be updated to their current version (WordPress only). Use the view API to get a list of installed plugins.
theme	optional If set to '*' or a comma-separated list of theme ID's, all themes or the listed themes will be updated to their current version (WordPress only). Use the view API to get a list of installed themes.
background	optional When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task. Possible values include: Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc.. A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.
dryrun	optional When defined, the request payload is validated but not executed. Dryrun set to a value of 2 checks everything, and dryrun set to a value of 1 just checks input so it can return faster.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Restore an installed application backup

HTTP GET or POST:

/url/to/installatron?api=json&cmd=restore

NAME	VALUE
cmd	restore
api	json
id	required The ID of the installed application backup to be restored.
db	optional Set to 'manual' to skip creating the database when it doesn't exist. Setting this to 'manual' is recommended if the database is always created prior to calling this API.
background	optional When defined, the request will exit immediately and the task will be transferred to a background process after preliminary error checking. Use the tasks API to query the status of the background task.
dryrun	optional When defined, the request payload is validated but not executed. Dryrun set to a value of 2 checks everything, and dryrun set to a value of 1 just checks input so it can return faster.

If the backup should be restored to a location different than the original location:

NAME	VALUE
url	required The URL where the backup should be restored to.
url_ip	optional, default is the IP address resolved via DNS If the DNS will not resolve the provided url to the correct IP, use this argument to provide the correct IP.
db_host	optional, if omitted a new database is automatically created The database server.
db_name	optional, if omitted a new database is automatically created The pre-created database.
db_user	optional, if omitted a new database is automatically created The pre-created database username.
db_pass	optional, if omitted a new database is automatically created The pre-created database password.
db_prefix	optional If a database prefix other than the default prefix should be used, specify the value here.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Uninstall an installed application

HTTP GET or POST:

/url/to/installatron?api=json&cmd=uninstall

NAME	VALUE
cmd	uninstall
api	json
id	required The ID of the installed application to be uninstalled.
force	optional, default is disabled Include this argument to force the uninstall even if there are connection errors.
background	optional When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task. Possible values include: Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc.. A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Delete an installed application backup

HTTP GET or POST:

/url/to/installatron?api=json&cmd=delete

NAME	VALUE
cmd	delete
api	json
id	required The ID of the installed application backup to be deleted.
force	optional, default is disabled Include this argument to force the deletion even if there are connection errors.
background	optional When defined, the request will exit and the task will be transferred to a background process. Use the tasks API to query the status of the background task. Possible values include: Any value other than "quick": The task will exit after preliminary error checking is completed to ensure there's enough disk space, etc.. A value of "quick": The task will exit immediately, withholding preliminary error checking until the process is executing in the background.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.
task	Table of task information if executed as a background process.

Import a backup

HTTP GET or POST:

/url/to/installatron?api=json&cmd=importbackup

NAME	VALUE
cmd	importbackup
api	json
user	required The user to import the backup for.
path	required The path to the installed application backup archive to be imported, relative to the path defined for the user specified.

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Further details regarding the success or failure.

List currently executing and recently completed tasks

HTTP GET or POST:

/url/to/installatron?api=json&cmd=tasks

NAME	VALUE
cmd	tasks
api	json

Return value:

NAME	VALUE
result	true on success, or false on failure.
message	Success or failure message.
data	Table of currently executing and recently completed tasks.

Sample JSON return value:

{
    "result": true,
    "message": "The task is complete.\n",
    "data": [
        {
            "id": "138207901722178300",
            "user": "dev1",
            "ws_label": "dev1",
            "url": "http://dev1.installatron.com/installdir",
            "title": "My blog (3)",
            "label": "_tasks_backuping",
            "status": "processing",
            "rate": 10150,
            "percentMin": 50,
            "percentMax": 99,
            "message": "_tasks_shared_copyingfiles",
            "cmd": "backup",
            "install": "4yhfygnd10ws0wc8skck444s",
            "time": 1382079023
        }
    ]
}