Glad You're Ready. Let's Get Started!

Let us know how we can contact you.

Thank you!

We'll respond shortly.

Pivotal Tracker API – 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:

What’s New or Changed in V3


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">
    <id type="integer">1031</id>
    <version type="integer">175</version>
    <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 &quot;More power to shields&quot;</description>
        <id type="integer">109</id>
        <accepted_at type="datetime">2009/12/14 22:12:09 UTC</accepted_at>

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
curl -H "X-TrackerToken: TOKEN" -X GET

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.


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


  <name>Sample Project</name>
  <iteration_length type="integer">2</iteration_length>
  <account>James Kirks Account</account>
  <velocity_scheme>Average of 4 iterations</velocity_scheme>
  <last_activity_at type="datetime">2010/01/16 17:39:10 CST</last_activity_at>
        <name>James T. Kirk</name>

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.


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[move]=after&move[target]=TARGET_STORY_ID"

Or, move it before a story:

curl -H "X-TrackerToken: TOKEN"
    -X POST[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"

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:

  <id type="integer">STORY_ID</id>
  <estimate type="integer">1</estimate>
  <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>

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

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

<attachments type="array">
    <id type="integer">17</id>
    <uploaded_at type="datetime">2010/01/17 14:57:57 CST</uploaded_at>

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>$REV</url></source_commit>"
    -X POST

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

Commit comment

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:

  1. Kyle Daigle says:

    Very cool guys, looking forward to upgrading to the new API and using it in our tracker dashboards we built.

  2. Steven Yan says:

    Awesome Dan! We’ll look into upholding our end of the bargain. Love the github hooks too.

  3. Chris Bailey says:

    Great work continuing to expand the API! I wanted to mention my GitHub post-commit hook in light of the new support. I was hoping that yours would wind up replacing mine, but there’s one key difference as far as I can tell. With the Github support in the API, all commits will wind up getting attributed to a single Tracker user. This is how mine worked originally, but on a multi-person team it sucks, because it looks like all commits are coming from one developer and you don’t have any context about which developer made that commit if you have questions, etc.

    Another thing is that mine also supports changing the state of the story (say to “finished”) as part of your commit message. We’ve found this to be really nice, as your Story gets automatically set to Finished as soon as your code is in the master branch for example.

    Anyway, so if folks want a post-receive hook that you can correlate commits to Tracker users, you can try my tiny little Sinatra app that’ll do it. Commit syntax is similar, by using “[Story12345]”. To change state, use “[Story12345 state:finished]” (for example).

    You can get it here:

  4. Dan Podsedly says:

    Hey Chris…thanks for sharing that. The built in post-commit hook will actually allow you to set stories as finished based on the [finishes #123456] syntax. It won’t support arbitrary states, though. We may also try and tie the commit author to a project member, if we have time before the weekend.


  5. Chris Bailey says:

    Dan, that’s great, good to know. As for tieing to a project member, that’d be excellent of course. The one thing we’ve found tricky with that is that the emails don’t always match up (e.g. my GitHub email is different than my Tracker email). Probably a more rare case of course. Maybe Tracker itself could have alternate email addresses for a given member (I’m mentioning this as I’m sort of presuming this is how you’d do the matching, given only a single API token).

  6. Dan Podsedly says:

    For the first pass, we’ll probably just try and find a project member with the same username/email as the commit author, and if we don’t find one, just use the token user.

  7. joel meador says:

    Been waiting for the move API for along time.

    Are the two move examples revesered?

  8. Dan Podsedly says:

    They were reversed, thanks for catching that. Fixed now.

  9. Steven says:

    Interesting. It will take some time to upgrade to the new API, but I’m definitely going to do that.

  10. hani elabed says:

    Hi Dan,
    I am updating our ruby-pivotal-tracker from v1 to v3.

    While I can look at the v2 and v3 APIs online, I don’t see the v1 API. Is it possible to share with me the responses to all v1 API calls( one time only – no need to put it online – just email it to me if it is not too much trouble )?

    Othwerwise I will have to reverse engineering the ruby code and deduce what the XML resposnes are. It would be way easier to look at what the actual responses were for the v1 of the API. As you currrently show them here for the v2 and v3 APIs.

    Thanks in advance

    hani elabed

  11. Sergio says:

    just curious about the overall architecture. Do you use the exposed HTTP API also from your Web presentation layer or the API is meant only for external apps while you access the back-end functions using a different library?

  12. mark gibson says:

    Love pivotal tracker, and i love the gui. I was wondering if the source was available – in particular the javascript that does the layout/adding/removing of the panels (current/backlog…)
    thanks – mark

    • Dan Podsedly says:

      Mark, glad to hear you’re a fan of Tracker and the UI. Unfortunately none of the source is open, but we are considering open sourcing at least some of the underlying frameworks. We’ll also be posting some technical info about how we rewrote it using Backbone later this year, so keep an eye on the blog and/or twitter.

Post a Comment

Your Information (Name required. Email address will not be displayed with comment.)

* Copy This Password *

* Type Or Paste Password Here *