API Overview

The AppHarbor API lets you interact with your AppHarbor account and applications through code. This means you can automate tasks that you would otherwise have to accomplish using the web interface.

Contents

• Requests
• Responses
• Documentation Conventions
• Resources
• .NET Library
• Support

Requests

Base URL

All API requests are made over HTTPS to appharbor.com. HTTPS is required.

https://appharbor.com

Specify Content Type to Return

The API returns responses in JSON. To indicate that your API client can handle this format, specify the Accept header with the JSON content type.

Accept: application/json

POST Request Data Format

When making POST requests, include the Content-Type header and the data encoded in JSON. Example for creating a new application:

POST /applications
Content-Type: application/json

{
    "name" : "example-app",
    "region_identifier" : "amazon-web-services::us-east-1"
}

Authentication

API requests are authenticated using an OAuth access token obtained by requesting authorization from a user. Learn more about OAuth Authorization.

To authenticate your API request, include the Authorization HTTP header with the user's access token:

Authorization: BEARER <access_token>

Alternately, you can specify the access token as a URL parameter.

GET https://appharbor.com/applications?access_token=:access_token

Responses

Data Format

API response respresentations are returned in JSON with the application/json content type.

Status Codes

• 200 - Request was successful.
• 201 - Item creation was successful. The Location header returned contains the URL to the newly-created item.
• 204 - Request was successful but no content is returned.
• 400 - Bad request. The data or format of the request was invalid for the resource.
• 402 - Payment Required.
• 404 - The requested resource could not be found.
• 500 - Server error. Try again shortly.

Errors

When a non-2xx HTTP status is returned, the following error representation will be returned:

Example

Status: 403 Forbidden
Content-Type: application/json

{ 
    "error" : {
        "message" : "Forbidden"
    }
}

Documentation Conventions

URL Templates

The documentation uses the following conventions for URIs (this URI gets all the tests for a build of an application):

 GET /applications/:slug/builds/:build/tests

For :slug and :build, you are expected to replace with relevant values for the application slug and build that you're interested in. These can be obtained either by inspecting URLs used on the AppHarbor web site (eg. for one-off queries) or by successive requests that uncover resources. For example:

1. Authorize
2. Get applications: GET /applications
3. Choose an application and get builds by replacing ":application" with the slug: GET /applications/application_slug/builds
4. Use the tests_url in the response to get tests for any particular build: GET /applications/:application/builds/:build/tests

Resources

The API currently has support for the following resources:

• Applications
• Collaborators
• Configuration Variables
• Hostnames
• Service Hooks
• Builds
• Tests
• Errors
• Users

.NET Library

Nikolas Tziolis has created AppHarbor.NET (since adopted by AppHarbor), a C# AppHarbor API wrapper that is available on GitHub. AppHarbor.NET is compatible with .NET 3.5+.

Support

If you have questions on how to use the API, then please refer to AppHarbor support resources.