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" "/services/v5/stories/$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..." }" /services/v5/projects/$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 email any questions, or feedback you might have on the new API. And if you’re not already, follow us on Twitter!