Use the Instance Provisioning API on Engine Yard Cloud

Updated: January 16th, 2013

Engine Yard Cloud API overview

This is Early Access documentation for the Engine Yard Cloud API v2. This version of the Engine Yard Cloud API v2 documentation is provided to demonstrate the instance provisioning operations.

Get help or provide feedback

If you have any issues or questions about this Early Access feature, use the Early Access Feature Feedback forum.

Expecting future changes

We reserve the right to add new methods and parameters to the API without advance notice. Breaking changes, such as removing or renaming a parameter, may happen on an existing version of the API with advance notice and deprecation. Major structural changes are anticipated only within the context of a version update.


The Engine Yard Cloud API v2 provides authentication to prevent unauthorized access to your app environment. The API access is over HTTPS and requires an API token in order to use the methods to access your environment. (Two-factor authorization is not supported.)

Headers JSON

This is a JSON API. You must include "Accept: application/json" and "Content-type: application/json" in operations as documented. You may get a text/plain response in case of error; you should be able to handle these errors.

Get started with the instance provisioning API

This document describes how to use the instance provisioning API in the Engine Yard Cloud environment:

Enable the instance provisioning API feature

You need to enable the Early Access feature before you can participate in the program.

To enable the instance provisioning API Early Access

  1. Log in to your Engine Yard Cloud account.

  2. On the dashboard, click Tools > Early Access on the toolbar.


  3. Next to the Add/Remove Instances API feature, click Enable.

    The related functionality becomes available.

Install the engineyard gem

You must have the engineyard gem installed in order to get the API token. See Engine Yard CLI User Guide for more information.

Get the API token

After the engineyard gem is installed, you need to get the API token for your Engine Yard Cloud account. This provides the necessary authentication to access and update your environments. See Install the engineyard gem for more information.

To get the API token

You can find your API token by using these commands:

ey login 
cat ~/.eyrc 
api_token: 76f2d43d79bedd9bc74654a1ded733c9

Get the environment IDs

You need your environment IDs before you can use the instance provisioning API. See Get Environment Data.

Use the instance provisioning API

You can use the instance provisioning API to add and remove utility and application instances.

These documents provide syntax, parameters, examples, and how to check status for each operation:

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.


  • Avatar
    Roger Zimmerman

    This is solid documentation.  Thanks for doing this.

    As a suggestion, it might also be worth documenting the instances GET,  since that is a nice way to programmatically tell how many instances of each type are currently running.

    Comment actions Permalink
  • Avatar
    Jason Gerry

    Out of curiosity -- is there any way to stop / start entire environments from the API? 

    Comment actions Permalink
  • Avatar
    Roger Zimmerman

    Jason, we have shut down multiple instances simultaneously with this API, so that should effect the result you are looking for, I would think.

    Comment actions Permalink
  • Avatar
    Jason Gerry

    Maybe... I'd like to be able to achieve the same state as clicking "stop"  for an environment. But be able to start it back up as if I clicked "boot". Say, stop an env at night and restart in the morning to cut costs.

    Comment actions Permalink
  • Avatar
    Marc Sardon

    We're in 2015. ¿Will ever the api allow to add/remove "solo" instances? 

    because we want to automatize our "staging" environments availability and there is no way to do it with the current API.

    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk