New Pivotal Tracker API Now in Public Beta

The new Pivotal Tracker developer API (V5) is now open to everyone! It’s completely new, all-JSON, much more comprehensive, and full of goodies. Keep reading for highlights and an example to get started.


The recently rewritten Tracker application has been running against this new API since earlier in the year, and some of you may have already started developing against it as part of the private beta. The new API is quite stable, but officially it’s in beta status, meaning there may still be some changes based on your feedback.

Documentation for the new API can be found here, or via the Developer API link at the top of the Tracker Help page. To get started, you’ll need your API token, which can be found on your Profile page.

Here’s an example of a simple cURL request that fetches a single story:

export TOKEN='your API token'
export STORY_ID='your story ID'
curl -X GET -H "X-TrackerToken: $TOKEN" "$STORY_ID?fields=name,description,estimate,owned_by(name)"

Since the request specified the story name, description, estimate, and owner name fields only, the response contains only those fields, as well as the story and person IDs:

  "id": 12345,
  "name": "All exhaust ports should be shielded",
  "description": "ray shielded, that is.",
  "estimate": 3,
  "owned_by": {
   "id": 1,
   "name": "Clone TK421", 

Updating a story (to change its name, for example) would look like this:

export TOKEN='your API token'
export STORY_ID='your story ID'
export PROJECT_ID='your project ID'
curl -H "X-TrackerToken: $TOKEN" -X PUT -H "Content-type: application/json" -d "{"name": "That's no moon..." }"$PROJECT_ID/stories/$STORY_ID


Dive right into the developer documentation for all the gory details, but here are some noteworthy features:

  • All project data is available via the API, including epics
  • All JSON, all the time
  • Consistent pagination control and response format for endpoints that can return a large amount of data (via offset and limit parameters)
  • Fine grained control of which fields and nested resources the API returns
  • Support for cross-origin (CORS) requests, allowing JavaScript applications to make requests to the API directly, without a server proxy
  • Access to historical project activity, with full details about what changed as part of a given user activity
  • Optional “envelope” metadata structure as part of the JSON response, instead of the metadata returned in the response header
  • Much more informative and consistent error responses
  • Support for new features (for example story following) available immediately when feature launches or enters beta

There are a number of things still in the works for API V5, including the ability to have multiple activity web hooks per project (manageable via the API, of course), an interactive API console, a request “aggregator”, and more. To keep up with changes to the API, follow this blog, or keep an eye on the change log section in the API documentation.

We hope you find these features useful, and are looking forward to seeing what you end up building! We’ll soon be launching a new “App Bazaar” to showcase all of the apps/tools/integrations developed by the community (for now you can find them on the third party tools page).

Please send any questions, or feedback you might have on the new API to And if you’re not already, follow us on Twitter!




  1. Pingback: Pivotal Tracker launches new API in public beta

  2. Bartlomiej Skwira says:

    Pivotal, your current API status is:
    v3 – deprecated, use v5 instead
    v4 – not supported, use v5 instead
    v5 – beta, use at your own risk

    So which version is the stable one? o.O

    October 25, 2013 at 4:07 am

  3. Dan Podsedly says:

    Bartlomiej, thanks for pointing that out – we meant to say that V3 is no longer being enhanced and will eventually be removed. We’re clarifying the messaging in the API help docs.

    V3 is still supported, but we recommend using V5 at this point. It’s quite stable, but we’re still adding some endpoints, and may tweak some minor things before removing the “beta” label.

    V4 is mostly the same as V3, and was never officially released.

    October 25, 2013 at 9:14 am

  4. Bartlomiej Skwira says:

    So v5 is the way to go for production, thanks

    October 28, 2013 at 6:29 am

  5. Glenford Fernandes says:

    Hi Dan what is the api call to get stories based on (current, backlog, icebox) categories.. v3 had the support to make unique calls.. what has been the change for the same in v5?

    March 8, 2014 at 10:37 pm

    • Dan Podsedly says:

      Glenford, you can search for stories based on current state, but I think you’re after the iterations endpoint, which allows you to specify “scope” of current, backlog, done, etc. Check out .

      March 10, 2014 at 7:59 am

  6. Sam jacob says:

    Hi ,

    In one of my Projects, the iterations are 188. While hitting the api for story activities based on iteration, i am only getting for the first 50 iterations, is there a way i could get all the 188 iterations data at one short instead of multiple api calls with offset and limits.

    Please clarify, as i have to manipulate the entire response data to generate a chart for the trends from iteration 1 to 188.

    May 6, 2014 at 3:20 am

    • Dan Podsedly says:

      Sam, we limit the # of iterations that are returned from a single request for performance / load management reasons. To go over all 188 iterations in your project, you’ll have to page through them via offset/limit.

      May 6, 2014 at 6:59 am

  7. oliver dalton says:

    Is there a way to view an attached image in the browser ??

    At the moment I am returned a ‘file_attachments/123456789/download’
    I have been adding ‘’ infront but this only forces the browser to download the asset.

    When I inspect the thumbnails in a story I see they point to AWS.
    They seem to have a number of params being passed.

    Is there a method of generating this so I can view the image in the browser and not download it?



    February 2, 2015 at 10:28 pm

Add New Comment

Your email address will not be published.