Acquia Cloud API

The Acquia Cloud API allows developers to extend, enhance, and customize Acquia Cloud. There are two major components to Cloud API:

Cloud API is currently in private beta test. Any Acquia Cloud customer can use it by submitting a Support ticket asking for it to be enabled. Once enabled, for Cloud API credentials, Drush aliases, and the Acquia Cloud Drush command file, log in to the Acquia Network and visit the Cloud > Drush and API page for your site.

Additional resources:

API overview

Just the facts:

Current version:v1
Endpoint:https://cloudapi.acquia.com/v1
Format:JSON. All resource URLs must specify a ".json" suffix.
Authentication:HTTP Basic Auth over SSL.
Credentials:Available on the "Drush and API" page of the Acquia Cloud UI.
Status codes:Standard.
Rate limit:360 calls per hour

API functions are listed below, first summarized by category, then followed with complete documentation including arguments, return values, and an example call.

Sites and environments (collapse)

Servers (collapse)

SSH keys (collapse)

SVN users (collapse)

Databases, database instances, and backups (collapse)

Workflow (collapse)

Tasks (collapse)

Domains (collapse)

Instance Method Details

- DELETE /sites/:site/dbs/:db

Delete a database.

Parameters:

  • :site
    the site name
  • :db
    the database name

Query parameters:

  • :backup
    (OPTIONAL) A final backup of the database instance in each environment is made before deletion unless this query parameter has value 0.

Returns:

  • the task record for deleting the database

Drush command:

  • drush @site.env ac-database-delete db

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/dbs/newdb.json?backup=1

- DELETE /sites/:site/envs/:env/dbs/:db/backups/:backup

Delete a site environment database instance backup.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name
  • :backup
    the backup id

Returns:

  • the task record for deleting the backup

Drush command:

  • drush @site.env ac-database-instance-backup-delete db backup

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups/22.json
 {
     "completed": null, 
     "created": "1331258289", 
     "description": "Delete backup 22 of database mysite in dev environment.", 
     "id": "1117", 
     "percentage": null, 
     "queue": "delete-db-backup", 
     "recipient": "backup-17.bjaspan.hosting.acquia.com\n", 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "received"
 }

- DELETE /sites/:site/envs/:env/domains/:domain

Delete a domain

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :domain
    the domain name to delete

Returns:

  • the task record for deleting the domain

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/envs/prod/domains/foo.com.json

- DELETE /sites/:site/envs/:env/domains/:domain/cache

Purge the Varnish cache for a domain

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :domain
    the domain name to purge

Returns:

  • the task record for purging the cache

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/envs/prod/domains/foo.com/cache.json

- DELETE /sites/:site/sshkeys/:sshkeyid

Delete an SSH key.

Parameters:

  • :site
    Site name
  • :sshkeyid
    Key id

Returns:

  • the task record for deleting the key

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/sshkeys/1.json

- DELETE /sites/:site/svnusers/:svnuserid

Delete an SVN user

Parameters:

  • :site
    Site name
  • :svnuserid
    SVN user id

Returns:

  • the task record for deleting the user

Examples:

$ curl -s -u user:pass -X DELETE https://cloudapi.acquia.com/v1/sites/mysite/svnusers/1.json

- GET '/sites'

List all sites accessible by the caller.

Returns:

  • An array of sites you can access

Drush command:

  • drush @site.env ac-site-list

Examples:

$ curl -u user:pass https://cloudapi.acquia.com/v1/sites.json
["mysite"]

- GET /sites/:site

Get a site record.

Parameters:

  • :site
    the site name

Returns:

  • A hash with information about the selected site.

Drush command:

  • drush @site.env ac-site-info

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite.json
{
    "title": "My Site",
    "name": "mysite", 
    "production_mode": "0", 
    "unix_username": "mysite", 
    "vcs_type": "git", 
    "vcs_url": "mysite@svn-3.bjaspan.hosting.acquia.com:mysite.git"
}

- GET /sites/:site/dbs

List a site’s databases.

Parameters:

  • :site
    the site name

Returns:

  • An array of the site’s databases.

Drush command:

  • drush @site.env ac-database-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/dbs.json
[
    {
        "name": "mysite", 
    }
]

- GET /sites/:site/dbs/:db

Get a database record. 


  {
      "name": "mysite",
  }

Parameters:

  • :site
    the site name
  • :db
    the database name

Returns:

  • An hash containing information about the database.

Drush command:

  • drush @site.env ac-database-info db

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/dbs/mysite.json

- GET /sites/:site/envs

List a site’s environments.

Parameters:

  • :site
    the site name

Returns:

  • An array of the site’s environments.

Drush command:

  • drush @site.env ac-environment-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs.json
[
    {
        "name": "prod", 
        "vcs_path": "tags/WELCOME",
        "ssh_host": "srv-1.devcloud.hosting.acquia.com"
    }, 
    {
        "name": "dev", 
        "vcs_path": "master",
        "ssh_host": "srv-1.devcloud.hosting.acquia.com"
    }
]

- GET /sites/:site/envs/:env

Get an environment record.

Parameters:

  • :site
    the site name
  • :env
    the environment name

Returns:

  • An hash with information about the selected environment

Drush command:

  • drush @site.env ac-environment-info

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev.json
{
    "name": "dev", 
    "vcs_path": "master",
    "ssh_host": "srv-1.devcloud.hosting.acquia.com"
}

- GET /sites/:site/envs/:env/dbs

List a site environment’s database instances.

Parameters:

  • :site
    the site name
  • :env
    the environment name

Query parameters:

  • :db_cluster[]
    (OPTIONAL) Only return database instances in one of these db_clusters.

Returns:

  • An array of the database instances within a site’s environment.

Drush command:

  • drush @site.env ac-database-instance-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs.json
[
    {
        "host": "srv-4", 
        "instance_name": "mysitedev", 
        "name": "mysite", 
        "password": "UeytUwwZxpfqutH", 
        "username": "mysitedev"
    }
]

- GET /sites/:site/envs/:env/dbs/:db

Get a database instance. 


  {
      "host": "srv-4",
      "instance_name": "mysitedev",
      "name": "mysite",
      "password": "UeytUwwZxpfqutH",
      "username": "mysitedev"
  }

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name

Returns:

  • An hash containing information about the database instance.

Drush command:

  • drush @site.env ac-database-instance-info db

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite.json

- GET /sites/:site/envs/:env/dbs/:db/backups

List a site environment’s database instance backups.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name

Returns:

  • an array of database backup records

Drush command:

  • drush @site.env ac-database-instance-backup-list db

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups.json
[
    {
        "checksum": "042f31bebd595b6f2c84b3532d4f1a3b", 
        "completed": "1331110381", 
        "deleted": "0", 
        "id": "22", 
        "name": "mysite", 
        "path": "backups/dev-mysite-mysitedev-2012-03-07.sql.gz", 
        "started": "1331110381", 
        "type": "daily",
        "link": "http://mysite.devcloud.acquia-sites.com/AH_DOWNLOAD?t=1342468716&prod=7386761671e68e517a74b7b790ef74d8a8fba7336dbc891cfef133bd29a7b238&d=/mnt/files/mysite.prod/backups/prod-mysite-mysite-2012-07-15.sql.gz"
    }, 
]

- GET /sites/:site/envs/:env/dbs/:db/backups/:backup

Get details about a database instance backup.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name
  • :backup
    the backup id

Returns:

  • a hash with details about the database instance backup

Drush command:

  • drush @site.env ac-database-instance-backup-info db backup

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups/22.json
 {
     "checksum": "042f31bebd595b6f2c84b3532d4f1a3b", 
     "completed": "1331110381", 
     "deleted": "0", 
     "id": "22", 
     "name": "mysite", 
     "path": "backups/dev-mysite-mysitedev-2012-03-07.sql.gz", 
     "started": "1331110381", 
     "type": "daily",
     "link": "http://mysite.devcloud.acquia-sites.com/AH_DOWNLOAD?t=1342468716&prod=7386761671e68e517a74b7b790ef74d8a8fba7336dbc891cfef133bd29a7b238&d=/mnt/files/mysite.prod/backups/prod-mysite-mysite-2012-07-15.sql.gz"
 }

- GET /sites/:site/envs/:env/dbs/:db/backups/:backup/download

Download a database instance backup from server.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name
  • :backup
    the backup id

Returns:

  • redirects to the URL for downloading the backup

Drush command:

  • drush @site.env ac-database-instance-backup-download db backup

Examples:

$ curl -L -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups/22/download.json -o backup.sql.gz

- GET /sites/:site/envs/:env/domains

List an environment’s domains.

Parameters:

  • :site
    the site name
  • :env
    the environment name

Returns:

  • An array of the environment’s domain names.

Drush command:

  • drush @site.env ac-domain-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/prod/domains.json
[
   {
     "name": "foo.com"
   },
   {
     "name": "bar.com"
   },
   {
     "name": "mysite.devcloud.acquia-sites.com"
   }
]

- GET /sites/:site/envs/:env/domains/:domain

Get a domain record.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :domain
    the domain name

Returns:

  • A domain record

Drush command:

  • drush @site.env ac-domain-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/prod/domains/foo.com.json
 {
   "name": "foo.com"
 }

- GET /sites/:site/envs/:env/servers

List a site environment’s servers.

Parameters:

  • :site
    the site name
  • :env
    the environment name

Returns:

  • An array of hashes with information about the servers

Drush command:

  • drush @site.env ac-server-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/servers.json
[
    {
       "name": "web-1",
       "fqdn": "web-1.domain.tld"
       "services": {"web": {"status": "online", "env_status": "inactive"}},
       "status": "online",
       "ami_type": "c1.medium",
       "ec2_region": "us-east-1",
       "ec2_availability_zone": "us-east-1d",
    }, 
]

- GET /sites/:site/envs/:env/servers/:server

Get a server record.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :server
    the server name

Returns:

  • A hash with information about the selected server

Drush command:

  • drush @site.env ac-server-info servername

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/servers/server.json
{
   "name": "web-1",
   "fqdn": "web-1.domain.tld"
   "services": {"web": {"status": "online", "env_status": "inactive"}},
   "status": "online",
   "ami_type": "c1.medium",
   "ec2_region": "us-east-1",
   "ec2_availability_zone": "us-east-1d",
}

- GET /sites/:site/sshkeys

List a site’s SSH keys.

Parameters:

  • :site
    Site name

Returns:

  • An array of the site’s SSH keys.

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/sshkeys.json
[
 {
    "ssh_pub_key":"ssh-rsa AAAAB...",
    "nickname":"user8",
    "id":"8",
 },
]

- GET /sites/:site/sshkeys/:sshkeyid

Get an SSH key.

Parameters:

  • :site
    Site name
  • :sshkeyid
    SSH key id

Returns:

  • SSH key record

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/sshkeys/8.json
 {
    "ssh_pub_key":"ssh-rsa AAAAB...",
    "nickname":"Joe's key",
    "id":"8",
 }

- GET /sites/:site/svnusers

List a site’s SVN users. 


 ]

Parameters:

  • :site
    the site name

Returns:

  • An array of SVN user records.

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/svnusers.json
[
 {
    "name":"user1",
    "id":"12",
}

- GET /sites/:site/svnusers/:svnuserid

Get an SVN user.

Parameters:

  • :site
    Site name
  • :svnuserid
    SVN user id.

Returns:

  • SVN user record.

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/svnuserid/1.json
 {
    "username":"user1",
    "id":"12",
}

- GET /sites/:site/tasks

List a site’s tasks.

Parameters:

  • :site
    the site name

Returns:

  • an array of hashes that represent the tasks

Drush command:

  • drush @site.env ac-task-list

Examples:

$ curl -s -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/tasks.json
 [
     {
         "completed": "1331254866", 
         "created": "1331254863", 
         "description": "Backup database mysite in dev environment.", 
         "id": "988", 
         "logs": "[01:01:04] [01:01:04] Started\n[01:01:06] [01:01:06] Done\n", 
         "queue": "create-db-backup-ondemand", 
         "result": "{\"backupid\":\"37\"}", 
         "sender": "cloud_api", 
         "started": "1331254864", 
         "state": "done"
     }, 
 ]

- GET /sites/:site/tasks/:task

Get a task record.

Parameters:

  • :site
    the site name
  • :task
    the task id

Returns:

  • a hash with information about the task

Drush command:

  • drush ac-task-info task

Examples:

$ curl -u user:pass https://cloudapi.acquia.com/v1/sites/mysite/tasks/289466.json
 {
     "completed": null, 
     "created": "1331259657", 
     "description": "Copy files from dev to prod", 
     "id": "1213", 
     "logs": "[02:20:58] [02:20:58] Started\n[02:21:00] [02:21:00] Failure\n", 
     "queue": "files-migrate", 
     "result": "", 
     "sender": "cloud_api", 
     "started": "1331259658", 
     "state": "error"
 }

- POST /sites/:site/code-deploy/:source/:target

Deploy code from one site environment to another.

Parameters:

  • :site
    the site name
  • :source
    the source environment name
  • :target
    the target environment name

Returns:

  • the task record for deploying the code

Drush command:

  • drush @mysite.dev ac-code-deploy test

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/code-deploy/dev/staging.json
 {
     "completed": null, 
     "created": "1331259148", 
     "description": "Deploy code to prod", 
     "id": "1137", 
     "percentage": null, 
     "queue": "code-push", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/dbs

Add a database.

Parameters:

  • :site
    the site name

Body fields:

  • :db
    (REQUIRED) the database name
  • :options
    Reserved.

Returns:

  • the task record for adding the database

Drush command:

  • drush @site.env ac-database-add db

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/dbs/newdb.json

- POST /sites/:site/dbs/:db/db-copy/:source/:target

Copy a database from one site environment to another

Parameters:

  • :site
    the site name
  • :db
    the database name
  • :source
    the source environment name
  • :target
    the target environment name

Returns:

  • the task record for deploying the code

Drush command:

  • drush @mysite.prod ac-database-copy db test

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/dbs/mysite/db-copy/dev/staging.json
 {
     "completed": null, 
     "created": "1331259523", 
     "description": "Copy database mysite from dev to prod", 
     "id": "1210", 
     "percentage": null, 
     "queue": "db-migrate", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/domain-move/:source/:target

Move domain(s) from one site environment to another

Parameters:

  • :site
    the site name
  • :source
    the source environment name
  • :target
    the target environment name

Body fields:

  • :domains
    (REQUIRED) Array of domains or String * for all domains in the source environment

Returns:

  • the task record for moving the domain(s)

Drush command:

  • drush @mysite.dev ac-domain-move staging example1.com,example2.com

Examples:

$ curl -s -u user:pass -X POST --data-binary '{"domains": ["example1.com", "example2.com"]}' https://cloudapi.acquia.com/v1/sites/mysite/domain-move/dev/staging.json
 {
   "completed": null,
   "created": "1331259523",
   "description": "Move domains from dev to staging.",
   "hidden":"0",
   "id": "1210",
   "percentage": null,
   "queue": "site-update",
   "recipient": null,
   "result": null,
   "sender": "cloud_api",
   "started": null,
   "state": "waiting"
 }

- POST /sites/:site/envs/:env/code-deploy

Deploy a specific VCS branch or tag to an environment.

Parameters:

  • :site
    the site name
  • :env
    the environment name

Query parameters:

  • :path
    (REQUIRED) the name of the branch or tag (e.g. master or tags/tagname)

Returns:

  • the task record for deploying the code

Drush command:

  • drush @site.env ac-code-path-deploy master

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/code-deploy.json?path=tags%2F2012-03-09
 {
     "completed": null, 
     "created": "1331259344", 
     "description": "Deploy code to dev", 
     "id": "1171", 
     "percentage": null, 
     "queue": "code-push", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/envs/:env/dbs/:db/backups

Create a database instance backup.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name

Returns:

  • the task record for creating the backup

Drush command:

  • drush @site.env ac-database-instance-backup db

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups.json
 {
     "completed": null, 
     "created": "1331258105", 
     "description": "Backup database mysite in dev environment.", 
     "id": "1116", 
     "percentage": null, 
     "queue": "create-db-backup-ondemand", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/envs/:env/dbs/:db/backups/:backup/restore

Restore a site environment database instance backup.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :db
    the database name
  • :backup
    the backup id

Returns:

  • the task record for restoring the backup

Drush command:

  • drush @site.env ac-database-instance-backup-restore db backup

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/envs/dev/dbs/mysite/backups/22/restore.json
 {
     "completed": null, 
     "created": "1331258397", 
     "description": "Restore backup 22 of database mysite in dev environment.", 
     "id": "1118", 
     "percentage": null, 
     "queue": "restore-db-backup", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/envs/:env/domains/:domain

Add a domain name.

Parameters:

  • :site
    the site name
  • :env
    the environment name
  • :domain
    the domain name to add

Returns:

  • the task record for adding the domain name

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/mysite/envs/prod/domains/foo.com.json

- POST /sites/:site/envs/:env/install/:type

Install a Drupal distro or Drush Make file into an environment.

Parameters:

  • :type
    distro_name, distro_url, or make_url

Query parameters:

  • :source
    (REQUIRED) Depending on :type:
    distro_name:One of Acquia Cloud’s built-in supported distros
    distro_url:A publicly accessible URL to any Drupal distribution in standard format.
    make_url:A publicly accessible URL to a Drush Make file.

Returns:

  • An hash with the task ID performing the action.

Drush command:

  • drush @site.env ah-distro-install type source

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/cloud/v1/sites/mysite/envs/dev/install/distro_url?source=http:%2F%2Fftp.drupal.org%2Ffiles%2Fprojects%2Fdrupal-7.12.tar.gz

- POST /sites/:site/files-copy/:source/:target

Copy files from one site environment to another

Parameters:

  • :site
    the site name
  • :source
    the source environment name
  • :target
    the target environment name

Returns:

  • the task record for copying the files

Drush command:

  • drush @mysite.prod ac-files-copy test

Examples:

$ curl -s -u user:pass -X POST https://cloudapi.acquia.com/v1/sites/files-copy/dev/staging.json
 {
     "completed": null, 
     "created": "1331259657", 
     "description": "Copy files from dev to prod", 
     "id": "1213", 
     "percentage": null, 
     "queue": "files-migrate", 
     "recipient": null, 
     "result": null, 
     "sender": "cloud_api", 
     "started": null, 
     "state": "waiting"
 }

- POST /sites/:site/sshkeys

Add an SSH key

Parameters:

  • :site
    Site name

Query parameters:

  • :nickname
    (REQUIRED) Key nickname

Body fields:

  • :ssh_pub_key
    (REQUIRED) SSH public key

Returns:

  • the task record for adding the key

Examples:

$ curl -s -u user:pass -X POST --data-binary '{"ssh_pub_key":"ssh-rsa AAAA..."}' https://cloudapi.acquia.com/v1/sites/mysite/sshkeys.json?nickname=Joe%27s+key

- POST /sites/:site/svnusers/:username

Add an SVN user.

Parameters:

  • :site
    the site name
  • :username
    svn username

Body fields:

  • :password
    (REQUIRED) User svn password

Returns:

  • the task record for adding the user

Examples:

$ curl -s -u user:pass -X POST --data-binary '{"password":"mysecret"}' https://cloudapi.acquia.com/v1/sites/mysite/svnusers/dmitry.json