Skip to content

HTTPS clone URL

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
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
POST http://heroku.com/apps/:appname/collaborators
collaborator[email]=:email
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' }
Jump to Line
Something went wrong with that request. Please try again.