API Basics

The Lighthouse API is implemented as a REST interface, and is available over XML and JSON.

Base URL

You always call the API on the domain of your account. So if your account is https://foo.lighthouseapp.com, this will be the base URL for all your API calls, as you can only retrieve information per account.

In the rest of this documentation, we will thus only refer to the PATH of requests. So /projects effectively means https://foo.lighthouseapp.com/projects

REST

The API follows the REST conventions, and you can assume the following:

GET     /tickets.json      => get list of tickets
GET     /tickets/1.json    => get ticket #1
POST    /tickets.json      => create a ticket
PUT     /tickets/1.json    => update ticket #1
DELETE  /tickets/1.json    => delete ticket #1

Content-Type

Lighthouse supports XML and JSON. For all API calls, simply choose the content type AND extension you prefer.

For XML:

curl -H "Content-Type: application/xml" http://.../tickets.xml

For JSON:

curl -H "Content-Type: application/json" http://.../tickets.json

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

Authentication

Lighthouse allows two forms of authentication: HTTP Basic Authentication and API tokens.

HTTP Basic Authentication

Exactly what you expect:

curl -u EMAIL:PASSWORD             http://foo.lighthouseapp.com/projects.xml
curl -u foo@example:com:password   http://foo.lighthouseapp.com/projects.xml

API tokens

API tokens is the preferred mode of authentication, as you don't have to share your login and password, and they can be revoked easily. You can create tokens on your profile page (click on your name in the upper right).

There are 2 ways to provide the token in your request. As a header:

curl -H 'X-LighthouseToken: API_KEY' http://foo.lighthouseapp.com/projects.xml

As a parameter:

curl http://foo.lighthouseapp.com/projects.xml?_token=API_KEY

See also: How do I get an API token?

Validation Errors

If you try to save an invalid resource, you will get a set of errors with an HTTP status of 422 Unprocessable Entity:

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