Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

113 lines (70 sloc) 3.503 kb
= 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
Returns XML listing of apps belonging to the user.
Create a new app with an untitled name. Returns XML of app settings, including
the generated name.
Create a new app with the provided name. Returns XML of app settings.
Returns XML of the app settings (the same data returned after creation).
Update app settings, with input structure matching the output of the GET above.
Returns XML list of collaborators (email addresses) on the app
Add a new collaborator to the app.
Delete a collaborator from the app. Don't forget to urlencode the email, since
@ signs are not valid in URLs.
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.
Permanently destroy the app.
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/ and not the private portion (e.g. ~/.ssh/id_rsa).
Returns XML of user's current keys.
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('') do |http|
request ='/apps')
request.basic_auth '', 'mypass'
res = http.request(request, 'app[name]=foobaz')
puts res.body
Using the RestClient gem:
require 'rubygems'
require 'rest_client'
apps ='', '', 'mypass') :app => { :name => 'foobaz' }
Jump to Line
Something went wrong with that request. Please try again.