The Basics of the Lighthouse API

Choosing the correct API address

All API calls will be made against the domain that your account is accessed from. For instance, if you want to get a list of all projects for the activereload account, you should access http://activereload.lighthouseapp.com/projects.xml. The docs will only show the relative path starting from the first slash.

Setting up your requests

The Lighthouse API uses standard HTTP requests. It follows a common convention for the various resources. Each resource will typically have a GET request to list records (GET /tickets.xml), and a GET request to list a specific record (GET /tickets/1.xml). POST requests are used to create new records (POST /tickets.xml). You use PUT requests to update tickets (PUT /tickets/1.xml). Finally, you can issue a DELETE request to destroy a resource (DELETE /tickets/1.xml).

All requests must send a proper Content-Type header of 'application/xml'. Otherwise, Lighthouse won't interpret your request as an API request, and you'll likely get a 500 error back.

Authenticating your requests

Lighthouse allows two forms of authentication. The first is HTTP Basic Authentication, using the same email and password you use to log into the site.

curl -u rick@email.com:mypassword http://foo.lighthouseapp.com/projects.xml

You can also create API tokens in the Lighthouse site that allow you to use that. This is so you don't have to store your actual Lighthouse login credentials with 3rd-party beacons. You can provide a unique key that gives access to only a specific project or account. This token can either be passed as a custom X-LighthouseToken header, sent as a basic authentication login, using the fake password 'x', or by appending a _token parameter to your requests.

curl -H 'X-LighthouseToken: YOUR_API_KEY' http://foo.lighthouseapp.com/projects.xml
curl -u MYKEY:x 
curl http://foo.lighthouseapp.com/projects.xml?_token=YOUR_API_KEY

Dealing with Validation Errors

If you try to save an invalid resource, the API will return a set of validation methods, along with an HTTP status of 422 Unprocessable Entity:

<errors>
  <error>Permalink can't be blank</error>
  <error>Name can't be blank</error>
</errors>