Heroku REST API

Typically the command-line program is used for manually manipulating Heroku apps; or from a Ruby script (like a Rakefile), one uses the Heroku::Client class. This document describes the underlying REST API used by both.

Authentication

Use HTTP basic auth to provide the Heroku username (email) and password with each request.

Content Types

Actions that take additional input besides the verb and URL fall into two categories: XML/formencoded, or plaintext. Actions that take multiple input parameters (such as updating the app settings) accept either an XML input body, or form variables as an input body in x-www-form-urlencoded format. Actions that take a block of code or text data (such as uploading an ssh key) expect a plaintext input body.

Most actions return XML, except for a few that return plaintext (such as the output of rake).

Resources & Actions

  GET http://heroku.com/apps

Returns XML listing of apps belonging to the user.

  POST http://heroku.com/apps

Create a new app with an untitled name. Returns XML of app settings, including the generated name.

  POST http://heroku.com/apps
    app[name]=:appname

Create a new app with the provided name. Returns XML of app settings.

  GET http://heroku.com/apps/:appname

Returns XML of the app settings (the same data returned after creation).

  PUT http://heroku.com/apps/:appname

Update app settings, with input structure matching the output of the GET above.

  GET http://heroku.com/apps/:appname/collaborators

Returns XML list of collaborators (email addresses) on the app, including the edit/view access setting for each.

  POST http://heroku.com/apps/:appname/collaborators
    collaborator[email]=:email
    collaborator[access]=(edit|view)

Add a new collaborator to the app.

  DELETE http://heroku.com/apps/:appname/collaborators/:email

Delete a collaborator from the app. Don‘t forget to urlencode the email, since @ signs are not valid in URLs.

  POST http://heroku.com/apps/:appname/rake

Execute a rake command on the app. The input body should be plaintext containing the command. Returns a plaintext output body with the rake output.

  DELETE http://heroku.com/apps/:appname

Permanently destroy the app.

  POST http://heroku.com/user/keys

Upload an ssh public key. The input body is plaintext containing the key contents, usually around 200 bytes for an RSA key and 600 bytes for a DSA key. Make sure you are uploading the public portion of the key (e.g., ~/.ssh/id_rsa.pub) and not the private portion (e.g. ~/.ssh/id_rsa).

  GET http://heroku.com/user/keys

Returns XML of user‘s current keys.

  DELETE http://heroku.com/user/keys/:keyname

Delete one key by its name. The name is the portion at the end of the key, e.g. a key like "ssh-rsa AAAAB3NzaC1yc2EAlmn+I0= joe@joe-smiths-computer.local" has a keyname of joe@joe-smiths-computer.local. Remember to urlencode the keyname, since @ is not a valid URL character.

Example

Although one would normally use Heroku::Client from a Ruby program, here‘s some sample code for reference. It creates an app named foobaz by posting to /apps.

Using Net::HTTP:

  require 'net/http'

  Net::HTTP.start('heroku.com') do |http|
    request = Net::HTTP.Post.new('/apps')
    request.basic_auth 'me@example.com', 'mypass'
    res = http.request(request, 'app[name]=foobaz')
    puts res.body
  end

Using the RestClient gem:

  require 'rubygems'
  require 'rest_client'

  apps = RestClient::Resource.new('http://heroku.com/apps', 'me@example.com', 'mypass')
  apps.post :app => { :name => 'foobaz' }