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

Let us know how we can contact you.

Thank you!

We'll respond shortly.

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. […] Tracker just announced the availability of their API V5 in public beta, starting August 16, 2013. The launch is justified […]

  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

  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.

  4. Bartlomiej Skwira says:

    So v5 is the way to go for production, thanks

Post a Comment

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

* Copy This Password *

* Type Or Paste Password Here *