Pivotal Tracker API and new version (V3) to be released on Jan. 23

We’re planning a Pivotal Tracker upgrade on Jan 23. As part of this release, we will be introducing a new API version (V3), which will make it easier to follow project activity, allow you to add file attachments, move (re-prioritize) stories, associate source commits with stories, and more.

The current API version (V2) will not change, but V1 will no longer work. If you’re still using V1, you will need to change your client code to use V2 or V3.

To find out what’s changing in V3, continue reading.

How to tell what version of the API you’re using?

The API version identifier is part of the request URLs. For example, this is a V2 request:

http://www.pivotaltracker.com/services/v2/projects

What’s New or Changed in V3

Activity

The response for the activity queries will change significantly. It will include a version # (to allow you to keep track of unique events and their order), event type, when the activity occurred (with time zone), and a nested element with all story attributes that changed as part of the activity. Example:

<activities type="array">
  <activity>
    <id type="integer">1031</id>
    <version type="integer">175</version>
    <event_type>story_update</event_type>
    <occurred_at type="datetime">2009/12/14 14:12:09 PST</occurred_at>
    <author>James Kirk</author>
    <project_id type="integer">26</project_id>
    <description>James Kirk accepted "More power to shields"</description>
    <stories>
      <story>
        <id type="integer">109</id>
        <url>/services/v3/projects/26/stories/109</url>
        <accepted_at type="datetime">2009/12/14 22:12:09 UTC</accepted_at>
        <current_state>accepted</current_state>
      </story>
    </stories>
  </activity>
</activities>

You’ll also be able to query for all activity since a particular date or version #, and you limit how many entries to return (up to 100):

curl -H "X-TrackerToken: TOKEN" -X GET http://www.pivotaltracker.com/services/v3/activities?newer_than_version=13
curl -H "X-TrackerToken: TOKEN" -X GET http://www.pivotaltracker.com/services/v3/activities?occurred_since_date=2009/12/14&limit=50

Activity Web Hook

This will allow you to specify a URL per project (in project settings), which Tracker will post story activity to, in the same XML format as above. You’ll be able to “pull” story activity out of Tracker via normal API GET requests, or have it POSTed to your client as it occurs via the activity web hook.

Projects

The project XML response will include the current and initial velocity, last activity date, and a list of all labels in the project.

Example:

<project>
  <id>1</id>
  <name>Sample Project</name>
  <iteration_length type="integer">2</iteration_length>
  <week_start_day>Monday</week_start_day>
  <point_scale>0,1,2,3</point_scale>
  <account>James Kirks Account</account>
  <velocity_scheme>Average of 4 iterations</velocity_scheme>
  <initial_velocity>10</initial_velocity>
  <last_activity_at type="datetime">2010/01/16 17:39:10 CST</last_activity_at>
  <number_of_done_iterations_to_show>12</number_of_done_iterations_to_show>
  <labels>shields,transporter</labels>
  <allow_attachments>true</allow_attachments>
  <public>false</public>
  <use_https>true</use_https>
  <bugs_and_chores_are_estimatable>false</bugs_and_chores_are_estimatable>
  <commit_mode>false</commit_mode>
  <memberships>
    <membership>
      <id>1006</id>
      <person>
        <email>kirkybaby@earth.ufp</email>
        <name>James T. Kirk</name>
        <initials>JTK</initials>
      </person>
      <role>Owner</role>
    </membership>
  </memberships>
</project>

When creating a project via the API, the user represented by the API token will be made an owner of that project by default. To leave the new project without an owner (because your client is acting on behalf of a different user, for example), you’ll need to include <no_owner type="boolean">true</no_owner> in the post data.

Stories

You’ll be able to move (re-prioritize) stories via the API. To move a story to after another story:

curl -H "X-TrackerToken: TOKEN"
    -X POST http://www.pivotaltracker.com/services/v3/projects/PROJECT_ID/stories/STORY_ID/moves?move[move]=after&move[target]=TARGET_STORY_ID"

Or, move it before a story:

curl -H "X-TrackerToken: TOKEN"
    -X POST http://www.pivotaltracker.com/services/v3/projects/PROJECT_ID/stories/STORY_ID/moves?move[move]=before&move[target]=TARGET_STORY_ID

As part of the new integrations feature (watch for more on that later), you’ll be able to associate a story with a ticket or issue in an external system, such as Lighthouse or JIRA. You’ll need to specify a ticket/issue ID, and optionally which specific integration to use (a project may be set up with multiple):

curl -H "X-TrackerToken: TOKEN" -H "Content-type: application/xml"
    -d "<story><lighthouse_id>54</lighthouse_id></story>"
    -X PUT http://www.pivotaltracker.com/services/v3/projects/PROJECT_ID/stories/STORY_ID"

Stories that are linked to a ticket or issue in an external system (for example JIRA or Lighthouse) will include the external ID as an attribute, as well as the URL to the linked ticket/issue:

<story>
  <id type="integer">STORY_ID</id>
  <story_type>feature</story_type>
  <url>http://www.pivotaltracker.com/story/show/STORY_ID</url>
  <estimate type="integer">1</estimate>
  <current_state>unstarted</current_state>
  <lighthouse_id>43</lighthouse_id>
  <lighthouse_url>http://mylighthouseapp.com/projects/100/tickets/43</lighthouse_url>
  <name>More power to shields</name>
  <requested_by>James Kirk</requested_by>
  <created_at type="datetime">2008/12/10 00:00:00 UTC</created_at>
</story>

File attachments

Here’s how you’ll be able to upload a file attachment to a story:

curl -H "X-TrackerToken: TOKEN" -X POST -F Filedata=@/path/to/file http://www.pivotaltracker.com/services/v3/projects/PROJECT_ID/stories/STORY_ID/attachments

The story response will include information about file attachments in this nested XML element:

<attachments type="array">
  <attachment>
    <id type="integer">17</id>
    <filename>Picture_36.png</filename>
    <description></description>
    <uploaded_by>Rob</uploaded_by>
    <uploaded_at type="datetime">2010/01/17 14:57:57 CST</uploaded_at>
  </attachment>
</attachments>

Note: Attachments in the story response XML will most likely not include a URL to the actual AWS S3 file, since these URLs are only valid temporarily. You’ll need to make a separate API call (details TBD) to get the S3 URL for a given story file attachment.

Source Control Post-Commit Hooks

This will allow you to set up post-commit hooks in git, github, subversion, etc., to link commits to stories (and optionally mark them as finished) based on this message syntax:

“Torpedoes now sufficiently powered [fixes #123456]”.

Curl example, of what you might do in a custom post-commit hook script for subversion or git:

curl -H "X-TrackerToken: TOKEN" -H "Content-type: application/xml"
    -d "<source_commit><message>$MESSAGE</message><author>$AUTHOR</author><commit_id>$REV</commit_id><url>http://trac.yourcompany.com/browser/?rev=$REV</url></source_commit>"
    -X POST http://www.pivotaltracker.com/services/v3/source_commits

Stories will show associated source commits as comments, with a link to the commit if you include a URL in the post body:

GitHub Support

The V3 version of the API will also support native Github post-commit hooks, allowing you to configure your Github repo to send commit information directly to Tracker, along with the [fixes #12345] message syntax.

The format of the Github post-commit request will be:

/services/v3/github_commits?token=API_TOKEN_OF_THE_USER_TO_ATTRIBUTE_ACTIONS_TO