Skip to end of metadata
Go to start of metadata

The API enables cloud integration with third party applications. You can manage every aspect of your cloud through the API.  This guide is a complete reference for all API calls and includes detailed API information, code and output examples. The version of the guide corresponds to the latest OnApp API version. For comprehensive instructions on previous versions, refer to corresponding guides at

  • The OnApp API is RESTful
  • All function calls respond to XML and JSON exchange formats
  • All function calls need authorization and authentication (Basic HTTP or API key)
  • The OnApp API is backward compatible within one major version. However, a new major version might include changes that are not  backward compatible with the previous one.

API Authentication

To authenticate using HTTP Basic, just use your username/password combination. Curl example:

curl -u user:userpass 

To authenticate using API key, put your account email as a login and the key to the server as a password.

HTTP Methods

The API uses the following HTTP methods:

GET - used for retrieving information from a particular URI

POST - used for creating new object and adding new transactions into the queue

PUT - used for altering object properties

NOTE: updated_at value is changed in PUT requests even if the request fails.

DELETE - used for object deletion

HTTP response codes

The API returns appropriate HTTP status codes for every request:

200 OK

The request completed successfully

204 No content

The request completed successfully. The 204 status is returned on DELETE and PUT requests

201 Scheduled

The request has been accepted and scheduled for processing

403 Forbidden

The request is correct, but could not be processed.

404 Not Found

The requested URL is incorrect or the resource does not exist. For example, if you request to delete a user with ID {5}, but there is no such a user in the cloud, you will get a 404 error. 

422 Unprocessable Entity

The sent parameters are erroneous.

500 Internal Server Error

  An error occurred. Please contact support.

503 Service UnavailableThe request cannot be handled currently, due to a temporary overloading or maintenance of the server. This condition is temporary and the request will be handed after a certain delay.

Formatting and naming conventions

The table below represents all the existing formatting and naming conventions used in this guide:





stands for username:password combination



stands for address, where your Control Panel is located


stands for the resource ID.
Sometimes also: :resource_id



all the parameters are italicised


* (asterisk)

marks the required parameters

label *


indicates request examples in XML or JSON

GET /roles.xml

Code block indicates console requests and response examples.



An info message emphasizes or explains the information within the chapter.

Clicking the OFF button performs graceful shutdown and then powers off the VS.


A note message contains information essential for the task completion.

The maximum length of a Mount Point is 256 characters.


A warning message informs you of something you should not do or be cautious.

You won't be able to restore a VS after deleting it.

(lightbulb)The element showing new parameters added in the latest release of API.(lightbulb) limit_type – hourly or monthly limit type set for the resource


Q: Is it possible to enable API access via https?

A: We can enable https for your cloud, which can be used for both WebUI access and API access. Or you can do so yourself: the Apache config file is located at: /etc/httpd/conf.d/onapp.conf

Q: Can you create a VS on behalf of another user?

A: No. It is possible to switch VS owners, however . Refer to Change a VS owner section for details.

Q: How are passwords stored – in plain text?

A: No, passwords are not stored in plain text. Except for a login and password combination, you can use email + API key combination to authorize a user via the API. API keys can be generated and changed easily on a user's profile page (as well as through the API). For security reasons we recommend users authenticate through the API key, not the login and password.

Q: Which parameters are required, and which are optional?

A: Required parameters are marked in this guide with an asterisk *.

  • No labels
Page: Change Log Page: Add Zabbix Server Page: Alerts Page: Application Servers Page: Apps for Application Servers Page: Assets Page: Auto-Backups Page: Backups/ Snapshots Page: Backup Servers Page: Backup Server Zones Page: Baremetal Servers Page: Billing Plans Page: Blueprints Page: Blueprint Template Groups Page: Blueprint Templates Page: Catalogs Page: CDN Accelerator Page: CDN Edge Groups Page: CDN Edge Servers Page: CDN HTTP Caching Rules Page: CDN Reporting Page: CDN Resources Page: CDN SSL Certificates Page: CDN Storage Servers Page: CDN Usage Statistics Page: Check Password Strength Page: CloudBoot IP Addresses Page: Company Billing Plans Page: Company Payments Page: Compute Resources Page: Compute Zones Page: Container Servers Page: Control Panel Maintenance Page: Currencies Page: Customer Networks Page: Customer VLANs Page: Custom Recipe Variables Page: Data Stores Page: Data Store Zones Page: Disks Page: DNS Setup Page: DNS Zones Page: Edge Gateways Page: Embed Statistics Charts Page: Errors Page: Federation Page: Firewall Rules for VSs Page: Firewalls Page: High Availability Control Panel Page: Instance Packages Page: Integrated Storage Page: IP Addresses Page: IP Address Joins Page: IP Address Pools Page: ISOs Page: OVAs Page: License Page: Load Balancers Page: Locales Page: Location Groups Page: Logs Page: My Template Groups Page: Network Interfaces Page: Networks Page: Network Zones Page: OnApp Engine Page: Orchestration Models Page: Pagination Page: Payments Page: Publishing Rules Page: Recipe Groups Page: Recipes Page: Resolvers Page: Resource Pools Page: Restrictions Sets Page: Roles Page: Smart Servers Page: Software Licenses Page: SSH keys Page: Statistics Page: Storage Server Backups Page: System Configuration Page: Templates Page: Template Store Page: Top IOPS Disks Page: Transactions Page: User Additional Fields Page: User Groups Page: Users Page: Users with Config Problems Page: vApps Page: vApp Networks Page: vCloud External Networks Page: vCloud Firewall Rules Page: vCloud Network Interfaces Page: vCloud Organization Networks Page: vCloud VS Snapshots Page: Version Page: Virtual Servers Page: Whitelist IPs