Tickets

List Tickets - GET /projects/#{project_id}/tickets.xml

Retrieve a list of tickets for the current project. The shown ticket data is the latest updated version of the ticket. You can also pass one of two parameters:

  • ?q=abc - You can enter the same query keywords.
  • ?limit=30 - You can specify the number of tickets per page to return, the default is 30, the max limit is 100.
  • ?page=2 - You can specify a page number, we return 30 tickets per page by default, ordered by last update

Response:

<tickets>
  <ticket>
    ...
  </ticket>
  <ticket>
    ...
  </ticket>
</tickets>

Get Ticket - GET /projects/#{project_id}/tickets/#{number}.xml

This fetches not only the latest version of the ticket, but all of the previous versions. They will be listed in //ticket-versions/ticket elements and contain the same attributes as tickets.

Response:

<ticket>
  <assigned-user-id type="integer"></assigned-user-id>
  <attachments-count type="integer">1</attachments-count>
  <body>#{unprocessed, raw body content}</body>
  <body-html>#{processed and filtered for html}</body-html>
  <created-at type="datetime">2007-01-15T08:13:09Z</created-at>
  <creator-id type="integer">1</creator-id>
  <milestone-id type="integer">2</milestone-id>
  <number type="integer">84</number>
  <permalink>provide-an-unwatch-link-in-notification-emails</permalink>
  <project-id type="integer">2</project-id>
  <state>resolved</state>
  <title>Provide an unwatch link in notification emails</title>
  <updated-at type="datetime">2007-02-21T16:01:55Z</updated-at>
  <user-id type="integer">1</user-id>
  <tag>deployment high</tag>
  <watchers-ids>[134, 234, 345]</watchers-ids>
  <versions>
    <version type="Ticket::Version">
      ...
    </version>
    <version type="Ticket::Version">
      ...
    </version>
  </versions>
  <attachments type="array">
    <attachment-image type="Attachment">
      <code>212d0cc7491c6eb95f775ba6769359241d16ee64</code>
      <content-type>image/png</content-type>
      <created-at type="datetime">2009-11-23T18:16:03Z</created-at>
      <filename>mock-up.png</filename>
      <height type="integer">770</height>
      <id type="integer">329182</id>
      <size type="integer">199629</size>
      <uploader-id type="integer">64212</uploader-id>
      <width type="integer">414</width>
      <url>http://project.lighthouseapp.com/attachments/123456/mock-up.png</url>
    </attachment-image>
  </attachments>
</ticket>

New Ticket - GET /projects/#{project_id}/tickets/new.xml

This gives you the initial state for an empty ticket.

Response:
<ticket>
  <assigned-user-id type="integer"></assigned-user-id>
  <attachments-count type="integer">0</attachments-count>
  <body></body>
  <body-html></body-html>
  <created-at type="datetime"></created-at>
  <creator-id type="integer"></creator-id>
  <milestone-id type="integer"></milestone-id>
  <number type="integer"></number>
  <permalink></permalink>
  <project-id type="integer"></project-id>
  <state></state>
  <title></title>
  <updated-at type="datetime"></updated-at>
  <user-id type="integer"></user-id>
</ticket>

Create Ticket - POST /projects/#{project_id}/tickets.xml

Creates a ticket. Missing attributes will remain their default, as shown in the new ticket request above. The shown fields are the only ones you can set:

  • title
  • body - follows the same formatting rules.
  • state - Can be any one of these: new, open, resolved, hold, invalid. Optional, set to new by default for new tickets.
  • assigned-user-id - optional
  • milestone-id - optional
  • tag - space or comma delimited list of tags

Request:

<ticket>
  <assigned-user-id type="integer"></assigned-user-id>
  <body></body>
  <milestone-id type="integer"></milestone-id>
  <state></state>
  <title></title>
</ticket>

Response:

HTTP Status: 201 Created
Location: http://activereload.lighthouseapp.com/projects/5/tickets/5.xml

<ticket>
  ...
</ticket>

Update Ticket - PUT /projects/#{project_id}/tickets/#{number}.xml

Update an existing ticket. You can leave out fields to keep them unchanged.
NOTE: Every ticket update creates a new ticket version, accessible as the API resource projects/X/tickets/X/versions. Ticket versions are the same thing as comments. Updating a ticket version will update a ticket comment in-place. The ticket body is the body of the first ticket version.

Request:

<ticket>
  ...
</ticket>

Response:

HTTP Status: 200 OK

Attachments

You can upload attachments by using an HTTP Post Multipart. There is one caveat: you need to update at least one field (body, tags, milestone, ...). You can do this on creation or update, with XML, JSON or simple form fields.

Here is a simple example of updating a ticket with curl:

curl -X PUT \
   -H "X-LighthouseToken: API_KEY" \
   -F "ticket[body]=Adding an attachment" \
   -F "ticket[attachment][]=@screenshot.png" \
   https://ACCOUNT.lighthouseapp.com/projects/XXXXX/tickets/NUMBER.xml

Here is the same example but creating a ticket:

curl -X POST \
   -H "X-LighthouseToken: API_KEY" \
   -F "ticket[title]=New ticket" \
   -F "ticket[body]=Here is the error" \
   -F "ticket[attachment][]=@screenshot.png" \
   https://ACCOUNT.lighthouseapp.com/projects/XXXXX/tickets.xml

You can also POST/PUT JSON or XML directly, as long as you use the proper Content-Type for the parts. See this link for more info.

Delete Ticket - DELETE /projects/#{project_id}/tickets/#{number}.xml

Response:

HTTP Status: 200 OK

Setting watchers

When you get a ticket through the API, the parameter watchers-ids (XML) or watchers_ids (JSON) will give you the user IDs of users subscribed to the discussion: [123,234,345]

You can set the watchers by using the parameter multiple_watchers, giving it a string of user IDs separated by ,:

multiple_watchers="123,234,345"`

This will subscribe and unsubscribe users to match the new list.