REST API v5

Beta Release Only. This documentation and the API it describes are currently in beta. This means that any use is at your own risk. In particular, you should expect to encounter a few more bugs than in production code and all technical specifications are subject to change until the beta period concludes and this version of the Tracker API is publicly announced.

This section of the Pivotal Tracker API documentation is a reference to all of the endpoints (URL paths) the API supports, the operations (request types) that can be performed with those endpoints, and the schema of the resource data encodings they return. It is applicable to API v5 only. Information about behaviors and request/response information that is common across the API is covered in the documentation Overview.

Overview

This section of the documentation is a reference for API version 'v5'. The bulk of the documentation is made up of the references for Endpoints (all of the URL paths the API makes available and the HTTP methods supported by each) and for Resources (the supported attributes for the different data structures maintained by the Tracker server and used to exchange data between client and server). Each resource is listed independently, sorted alphabetically by name. Endpoints are listed in groups with other, related endpoints. Groups are arranged in what is intended to be a logical reading/scanning order.

Introduction

Pivotal Tracker API v5 behaves exactly as described in the API documentation's Overview. Each individual item reference below describes the deviations, if any, that that item has from the standard/default API behavior.

In particular, there are a handful of endpoints that either don't support any of the standard response-formatting parameters (their format is entirely fixed), or that don't support the date_format query parameter, see Selecting the Date/Time Format. These cases are noted in the description of each endpoint. In cases where date_format is not supported, the format is always an integer number of milliseconds since the epoch—the client is never forced to use an ISO 8601-format time value.

Changes Planned

There are still three relatively small changes that we have planned for the API, that could prove incompatible with existing clients depending on whether they are written in anticipation of the change. Each is noted in the relevant section of the documentation, as follows. The first two changes are planned in the relatively near future (before API v5 is considered non-beta), and the last will affect only CORS-using JavaScript clients after we add OAuth as an available means for authenticating API clients.

Log of Additions to API v5

  • 2014-02-04 —
  • 2013-12-12 —
  • 2013-11-12 —
    • New search string syntax features available through the UI are inherited by the API's search endpoints.
    • Introduced the /projects/{project_id}/integrations family of endpoints for manipulating the integrations configured for a project. (Note that some changes to integrations will require users viewing the affected project on the web to reload their browsers. Also, integration changes do not yet appear in activity.)
    • HTTP basic authorization is now correctly supported for GET requests to the /me endpoint, see Authenticating via Basic-Auth to Obtain API Tokens. Note that this may be an incompatible change to the API if you wrote a client to make unauthenticated requests to /me that handle only HTTP status 403 and not the correct status of 401. That section of the documentation had a warning box describing that this change was planned before the end of beta, now removed.
    • It is now possible to move a story from one project to another, by supplying the destination project_id as a body parameter in PUT requests to the /projects/{project_id}/stories/{story_id} endpoint. (The story's current project_id must still be included in the URL for the request to correctly identify the story to be moved.)
    • The account_id parameter is now included by default in API responses returning the project resource.
  • 2013-10-29 —
    • Introduced RESTful endpoints for a labels subresource underneath stories (/projects/{project_id}/stories/{story_id}/labels et al). These allow the client to obtain a list of the labels on a story without fetching the entire story, and to add or remove a story's labels individually, without already having the particular story's full label list loaded as manipulating labels by PUT'ing to the story itself requires.
    • Added support for PUT and DELETE methods to the top-level /stories/{story_id} endpoint.
  • 2013-10-26 —
  • 2013-10-22 — Introduced RESTful endpoints for manipulation of a project's "webhooks" (configured public URLs to which Tracker posts activity updates for the project), /projects/{project_id}/webhooks. With the introduction of these endpoints the Tracker service now supports having multiple configured webhooks for a single project, so project activity can be routed directly to multiple external services. (Support for this in Tracker's web UI was released subsequently.)
  • 2013-10-16 — Enhanced the /projects/{project_id}/stories/{story_id}/activity endpoint so that it returns activity information not only for operations that modified just that story (old behavior) but also activity information for multi-story operations that included the story (new behavior).
  • 2013-08-28 —
    • Fixed bug preventing CORS from working reliably.
    • Size limit on file_attachment files increased from 10MB to 50MB.
  • 2013-08-20 — Introduced the unversioned request URL https://www.pivotaltracker.com/file_attachments/{file_attachment_id}/download using API conventions (authentication, authorization) to allow downloading of the file data described by a file_attachment resource.
  • 2013-08-15 —
    • Support of PATCH HTTP method as a synonym for PUT.
    • Reduced default limit on all paginated endpoints.
    • Add support for 'X-Tracker-Warn-Unless-Project-Version-Is' request header.
    • Add 'v5' as an option for Tracker-POSTed webhooks, POST data matches .../activity endpoints' format.
  • 2013-08-06 —
  • 2013-07-15 — Opening of API version 'v5' for beta use by non-Tracker team members.

Endpoints

Me

ENDPOINT

/me

Provides information about the authenticated user.

GET
/me

In addition to authenticating this request like other API requests, this request can be made with authentication using "basic auth" to pass the user's normal Pivotal Tracker login credentials (their email address or user name plus their password). In this way, client software can use the user's name and password to obtain their API Token, and then use that token to authenticate future API requests made on behalf of that user. Obviously, the user's password should not be stored or otherwise retained.

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/me"

Hide Response
Headers
Response Body
{"receives_in_app_notifications":true,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-08:00"},"name":"Darth Vader","id":101,"kind":"me","username":"vader","api_token":"VadersToken","projects":[{"role":"owner","last_viewed_at":"2014-04-08T12:00:00Z","id":108,"project_name":"Learn About the Force","kind":"membership_summary","project_id":98,"project_color":"8100ea"},{"role":"member","last_viewed_at":"2014-04-08T12:00:00Z","id":101,"project_name":"Death Star","kind":"membership_summary","project_id":99,"project_color":"8100ea"}],"has_google_identity":false,"initials":"DV","email":"vader@deathstar.mil"}

curl -X GET --user vader:password "https://www.pivotaltracker.com/services/v5/me"

Hide Response
Headers
Response Body
{"receives_in_app_notifications":true,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-08:00"},"name":"Darth Vader","id":101,"kind":"me","username":"vader","api_token":"VadersToken","projects":[{"role":"owner","last_viewed_at":"2014-04-08T12:00:00Z","id":108,"project_name":"Learn About the Force","kind":"membership_summary","project_id":98,"project_color":"8100ea"},{"role":"member","last_viewed_at":"2014-04-08T12:00:00Z","id":101,"project_name":"Death Star","kind":"membership_summary","project_id":99,"project_color":"8100ea"}],"has_google_identity":false,"initials":"DV","email":"vader@deathstar.mil"}
Successful responses to this request return the me resource.

PARAMETERS

Only the information for the user matching the request authentication can be obtained. If a request is made to /me using basic-auth instead of an API Token, and the user does not yet have an API Token generated, Tracker will generate and store one, and return it in the response.

Notifications

ENDPOINT

/my/notifications

Provides a list of all notifications.

GET
/my/notifications

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/my/notifications?envelope=true"

Hide Response
Headers
Response Body
{"last_notification_timestamp":1396958420000,"data":[{"performer":{"name":"Wilhuff Tarkin","id":102,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":"2014-04-08T12:00:20Z","id":17,"kind":"notification","action":"ownership","message":"Wilhuff Tarkin has made you an owner of this story:","created_at":"2014-04-08T12:00:15Z"},{"performer":{"name":"Darth Vader","id":101,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":"2014-04-08T12:00:20Z","id":13,"kind":"notification","action":"rejection","message":"Darth Vader rejected your story","created_at":"2014-04-08T12:00:20Z"},{"performer":{"name":"Wilhuff Tarkin","id":102,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":"2014-04-08T12:00:20Z","id":5,"kind":"notification","action":"ownership","message":"Wilhuff Tarkin has made you an owner of this story","created_at":"2014-04-08T12:00:20Z"},{"performer":{"name":"Darth Vader","id":101,"kind":"person"},"notification_type":"comment","project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":"2014-04-08T12:00:20Z","id":16,"kind":"notification","action":"create","read_at":"2014-04-08T12:00:10Z","message":"Darth Vader added the comment: \"Should we send a probe to Dantooine?\"","epic":{"name":"Rebel Home Worlds","id":4,"kind":"epic"},"created_at":"2014-04-08T12:00:05Z"}],"http_status":"200"}
Successful responses to this request return an array containing zero or more instances of the notification resource.

PARAMETERS

created_after
datetime in the request query.
 —  Show notifications created after this date/time. If this parameter is not provided, the default is 10 days prior to the request time.
 
ENDPOINT

/my/notifications/mark_read

Marks all notifications read before a notification id.

PUT
/my/notifications/mark_read

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/my/notifications/mark_read?before=10"

Hide Response
Headers

PARAMETERS

before
int in the request query.
required  —  Mark all notifications before this id as read (inclusive)
 
ENDPOINT

/people/{person_id}/notifications/since/{timestamp}

Provides a list of notifications. Unlike most endpoints that allow you to control the response format with url parameters, this endpoint will always return responses with an envelope and a date_format in milliseconds.

GET
/people/{person_id}/notifications/since/{timestamp}

export TOKEN='your Pivotal Tracker API token'

export PERSON_ID=104

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/people/$PERSON_ID/notifications/since/1396180800000"

Hide Response
Headers
Response Body
{"data":[{"performer":{"name":"Wilhuff Tarkin","id":102,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":1396958405000,"id":17,"kind":"notification","action":"ownership","message":"Wilhuff Tarkin has made you an owner of this story:","created_at":1396958405000},{"performer":{"name":"Darth Vader","id":101,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":1396958405000,"id":13,"kind":"notification","action":"rejection","message":"Darth Vader rejected your story","created_at":1396958405000},{"performer":{"name":"Wilhuff Tarkin","id":102,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":1396958405000,"id":5,"kind":"notification","action":"ownership","message":"Wilhuff Tarkin has made you an owner of this story","created_at":1396958405000}],"http_status":"200"}
Successful responses to this request return an array containing zero or more instances of the notification resource.

PARAMETERS

person_id
int in the request path.
required  —  The ID of the person.
 
timestamp
datetime in the request path.
required  —  Show notifications created after this timestamp. Note that this datetime must be specified in number of milliseconds since the epoch; it does not support ISO 8601 like other datetimes.
 
The standard formatting parameters cannot be included in requests for this operation. In particular, envelope= is prohibited and Tracker behaves as if envelope=true had been provided.
ENDPOINT

/my/notifications/{notification_id}

Access the notification specified by the notification_id value in the URL.

PUT
/my/notifications/{notification_id}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"story_id":1,"read_at":"2014-04-08T12:00:00Z"}' "https://www.pivotaltracker.com/services/v5/my/notifications/17"

Hide Response
Headers
Response Body
{"performer":{"name":"Wilhuff Tarkin","id":102,"kind":"person"},"notification_type":"story","story":{"name":"All exhaust ports should be shielded","id":558,"kind":"story"},"project":{"name":"Death Star","id":99,"kind":"project"},"updated_at":"2014-04-08T12:00:05Z","id":17,"kind":"notification","action":"ownership","read_at":"2014-04-08T12:00:05Z","message":"Wilhuff Tarkin has made you an owner of this story:","created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the notification resource.

PARAMETERS

notification_id
int in the request path.
required  —  The ID of the notification.
 
read_at
datetime in the request body.
 —  Time notification was read.
 

Projects

ENDPOINT

/projects

Access a user's projects

GET
/projects

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects"

Hide Response
Headers
Response Body
[{"point_scale_is_custom":false,"iteration_length":1,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"start_time":"2014-04-08T12:00:05Z","initial_velocity":10,"enable_incoming_emails":true,"bugs_and_chores_are_estimatable":false,"atom_enabled":true,"name":"Learn About the Force","week_start_day":"Monday","updated_at":"2014-04-08T12:00:15Z","id":98,"enable_planned_mode":false,"kind":"project","number_of_done_iterations_to_show":12,"version":2,"public":false,"current_iteration_number":1,"has_google_domain":false,"enable_tasks":true,"velocity_averaged_over":3,"point_scale":"0,1,2,3","enable_following":true,"account_id":100,"created_at":"2014-04-08T12:00:10Z"},{"point_scale_is_custom":false,"iteration_length":1,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"start_time":"2014-04-08T12:00:15Z","initial_velocity":10,"enable_incoming_emails":true,"bugs_and_chores_are_estimatable":false,"atom_enabled":true,"name":"Death Star","week_start_day":"Monday","updated_at":"2014-04-08T12:00:15Z","id":99,"enable_planned_mode":false,"kind":"project","description":"Expeditionary Battle Planetoid","number_of_done_iterations_to_show":12,"version":62,"public":false,"current_iteration_number":15,"has_google_domain":false,"enable_tasks":true,"velocity_averaged_over":3,"profile_content":"This is a machine of war such as the universe has never known. It's colossal, the size of a class-four moon. And it possesses firepower unequaled in the history of warfare.","point_scale":"0,1,2,3","enable_following":true,"account_id":100,"start_date":"2013-12-23","created_at":"2014-04-08T12:00:10Z"}]
Successful responses to this request return an array containing zero or more instances of the project resource.
POST
/projects

export TOKEN='your Pivotal Tracker API token'

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Executioner"}' "https://www.pivotaltracker.com/services/v5/projects"

View Response
Hide Response
Headers
Response Body
{"point_scale_is_custom":false,"iteration_length":1,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"start_time":"2014-04-08T12:00:00Z","initial_velocity":10,"enable_incoming_emails":true,"bugs_and_chores_are_estimatable":false,"atom_enabled":false,"name":"Executioner","week_start_day":"Monday","updated_at":"2014-04-08T12:00:05Z","id":200,"enable_planned_mode":false,"kind":"project","number_of_done_iterations_to_show":12,"version":1,"public":false,"current_iteration_number":1,"has_google_domain":false,"enable_tasks":true,"velocity_averaged_over":3,"point_scale":"0,1,2,3","enable_following":true,"account_id":100,"created_at":"2014-04-08T12:00:05Z"}
Successful responses to this request return the project resource.

PARAMETERS

no_owner
boolean in the request body.
 —  By default, the user whose credentials are supplied will be added as a project owner. To leave the project without this owner, supply the no_owner key.
 
iteration_length
int in the request body.
 —  The number of weeks in an iteration.
 
initial_velocity
int in the request body.
 —  The number which should be used as the project's velocity when there are not enough recent iterations with Done stories for an actual velocity to be computed.
 
enable_incoming_emails
boolean in the request body.
 —  When true, the project will accept incoming email responses to Tracker notification emails and convert them to comments on the appropriate stories.
 
time_zone
time_zone in the request body.
 —  The "native" time zone for the project, independent of the time zone(s) from which members of the project view or modify it.
 
bugs_and_chores_are_estimatable
boolean in the request body.
 —  When true, Tracker will allow estimates to be set on Bug- and Chore-type stories. This is strongly not recommended. Please see the FAQ for more information.
 
atom_enabled
boolean in the request body.
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
name
string[50] in the request body.
required  —  The name of the project.
 
enable_planned_mode
boolean in the request body.
 —  When true, Tracker suspends the emergent planning of iterations based on the project's velocity, and allows users to manually control the set of unstarted stories included in the Current iteration. See the FAQ for more information.
 
week_start_day
enumerated string in the request body.
 —  The day in the week the project's iterations are to start on.
Valid enumeration values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
 
description
string[140] in the request body.
 —  A description of the project's content. Entered through the web UI on the Project Settings page.
 
number_of_done_iterations_to_show
int in the request body.
 —  There are areas within the Tracker UI and the API in which sets of stories automatically exclude the Done stories contained in older iterations. For example, in the web UI, the DONE panel doesn't necessarily show all Done stories by default, and provides a link to click to cause the full story set to be loaded/displayed. The value of this attribute is the maximum number of Done iterations that will be loaded/shown/included in these areas.
 
public
boolean in the request body.
 —  When true, Tracker will allow any user on the web to view the content of the project. The project will not count toward the limits of a paid subscription, and may be included on Tracker's Public Projects listing page.
 
enable_tasks
boolean in the request body.
 —  When true, Tracker allows individual tasks to be created and managed within each story in the project.
 
account_id
int in the request body.
 —  The ID number for the account which contains the project.
 
profile_content
string[65535] in the request body.
 —  A long description of the project. This is displayed on the Project Overview page in the Tracker web UI.
 
velocity_averaged_over
int in the request body.
 —  The number of iterations that should be used when averaging the number of points of Done stories in order to compute the project's velocity.
 
point_scale
string[255] in the request body.
 —  The specification for the "point scale" available for entering story estimates within the project. It is specified as a comma-delimited series of values--any value that would be acceptable on the Project Settings page of the Tracker web application may be used here. If an exact match to one of the built-in point scales, the project will use that point scale. If another comma-separated point-scale string is passed, it will be treated as a "custom" point scale. The built-in scales are "0,1,2,3", "0,1,2,4,8", and "0,1,2,3,5,8".
 
start_date
date in the request body.
 —  The first day that should be in an iteration of the project. If both this and "week_start_day" are supplied, they must be consistent. It is specified as a string in the format "YYYY-MM-DD" with "01" for January. If this is not supplied, it will remain blank (null), but "start_time" will have a default value based on the stories in the project.
 
The new project is created with the currently-authenticated user as its original Owner. The server will supply a default value for any optional parameter that the request doesn't include. The default values are not defined as part of the API--they may change from time to time without an increase in the current API version number. Additionally, new project attributes may be added at any time without advance notice. The client will know what values the server has supplied from the response to the request. If the value set for a project attribute is important to an application, it should be included explicitly in the request without relying on the server to supply the default.

Project

ENDPOINT

/projects/{project_id}

Access the project specified by the project_id value in the URL.

GET
/projects/{project_id}

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/99"

Hide Response
Headers
Response Body
{"point_scale_is_custom":false,"iteration_length":1,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"start_time":"2014-04-08T12:00:10Z","initial_velocity":10,"enable_incoming_emails":true,"bugs_and_chores_are_estimatable":false,"atom_enabled":true,"name":"Death Star","week_start_day":"Monday","updated_at":"2014-04-08T12:00:10Z","id":99,"enable_planned_mode":false,"kind":"project","description":"Expeditionary Battle Planetoid","number_of_done_iterations_to_show":12,"version":62,"public":false,"current_iteration_number":15,"has_google_domain":false,"enable_tasks":true,"velocity_averaged_over":3,"profile_content":"This is a machine of war such as the universe has never known. It's colossal, the size of a class-four moon. And it possesses firepower unequaled in the history of warfare.","point_scale":"0,1,2,3","enable_following":true,"account_id":100,"start_date":"2013-12-23","created_at":"2014-04-08T12:00:05Z"}
Successful responses to this request return the project resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
PUT
/projects/{project_id}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"totally a new project name"}' "https://www.pivotaltracker.com/services/v5/projects/99"

Hide Response
Headers
Response Body
{"point_scale_is_custom":false,"iteration_length":1,"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"start_time":"2014-04-08T12:00:00Z","initial_velocity":10,"enable_incoming_emails":true,"bugs_and_chores_are_estimatable":false,"atom_enabled":true,"name":"totally a new project name","week_start_day":"Monday","updated_at":"2014-04-08T12:00:10Z","id":99,"enable_planned_mode":false,"kind":"project","description":"Expeditionary Battle Planetoid","number_of_done_iterations_to_show":12,"version":64,"public":false,"current_iteration_number":15,"has_google_domain":false,"enable_tasks":true,"velocity_averaged_over":3,"profile_content":"This is a machine of war such as the universe has never known. It's colossal, the size of a class-four moon. And it possesses firepower unequaled in the history of warfare.","point_scale":"0,1,2,3","enable_following":true,"account_id":100,"start_date":"2013-12-23","created_at":"2014-04-08T12:00:05Z"}
Successful responses to this request return the project resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
iteration_length
int in the request body.
 —  The number of weeks in an iteration.
 
initial_velocity
int in the request body.
 —  The number which should be used as the project's velocity when there are not enough recent iterations with Done stories for an actual velocity to be computed.
 
enable_incoming_emails
boolean in the request body.
 —  When true, the project will accept incoming email responses to Tracker notification emails and convert them to comments on the appropriate stories.
 
time_zone
time_zone in the request body.
 —  The "native" time zone for the project, independent of the time zone(s) from which members of the project view or modify it.
 
bugs_and_chores_are_estimatable
boolean in the request body.
 —  When true, Tracker will allow estimates to be set on Bug- and Chore-type stories. This is strongly not recommended. Please see the FAQ for more information.
 
atom_enabled
boolean in the request body.
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
name
string[50] in the request body.
 —  The name of the project.
 
enable_planned_mode
boolean in the request body.
 —  When true, Tracker suspends the emergent planning of iterations based on the project's velocity, and allows users to manually control the set of unstarted stories included in the Current iteration. See the FAQ for more information.
 
week_start_day
enumerated string in the request body.
 —  The day in the week the project's iterations are to start on.
Valid enumeration values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
 
description
string[140] in the request body.
 —  A description of the project's content. Entered through the web UI on the Project Settings page.
 
number_of_done_iterations_to_show
int in the request body.
 —  There are areas within the Tracker UI and the API in which sets of stories automatically exclude the Done stories contained in older iterations. For example, in the web UI, the DONE panel doesn't necessarily show all Done stories by default, and provides a link to click to cause the full story set to be loaded/displayed. The value of this attribute is the maximum number of Done iterations that will be loaded/shown/included in these areas.
 
public
boolean in the request body.
 —  When true, Tracker will allow any user on the web to view the content of the project. The project will not count toward the limits of a paid subscription, and may be included on Tracker's Public Projects listing page.
 
enable_tasks
boolean in the request body.
 —  When true, Tracker allows individual tasks to be created and managed within each story in the project.
 
account_id
int in the request body.
 —  The ID number for the account which contains the project.
 
profile_content
string[65535] in the request body.
 —  A long description of the project. This is displayed on the Project Overview page in the Tracker web UI.
 
velocity_averaged_over
int in the request body.
 —  The number of iterations that should be used when averaging the number of points of Done stories in order to compute the project's velocity.
 
point_scale
string[255] in the request body.
 —  The specification for the "point scale" available for entering story estimates within the project. It is specified as a comma-delimited series of values--any value that would be acceptable on the Project Settings page of the Tracker web application may be used here. If an exact match to one of the built-in point scales, the project will use that point scale. If another comma-separated point-scale string is passed, it will be treated as a "custom" point scale. The built-in scales are "0,1,2,3", "0,1,2,4,8", and "0,1,2,3,5,8".
 
start_date
date in the request body.
 —  The first day that should be in an iteration of the project. If both this and "week_start_day" are supplied, they must be consistent. It is specified as a string in the format "YYYY-MM-DD" with "01" for January. If this is not supplied, it will remain blank (null), but "start_time" will have a default value based on the stories in the project.
 
DELETE
/projects/{project_id}

export TOKEN='your Pivotal Tracker API token'

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/99"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 

Iterations

ENDPOINT

/projects/{project_id}/iterations

Allows iterations to be retrieved, with optional scope, limit and offset. For the 'Done' scope, a negative offset can be passed, which specifies the number of iterations preceding the 'Current' iteration. Note that iterations are ordered with the oldest (lowest iteration number) first.

GET
/projects/{project_id}/iterations

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/iterations?limit=10&offset=1"

Hide Response
Headers
Response Body
[{"stories":[{"estimate":3,"labels":[{"name":"plans","updated_at":"2014-04-08T12:01:00Z","id":2008,"kind":"label","project_id":99,"created_at":"2014-04-08T12:01:00Z"}],"name":"Complete construction of the Expeditionary Battle Planetoid","external_id":"abc123","current_state":"accepted","accepted_at":"2014-04-08T12:00:05Z","updated_at":"2014-04-08T12:01:00Z","id":562,"kind":"story","description":"Palpatine was impressed with the PoC, make this one bigger","url":"http://localhost/story/show/562","requested_by_id":102,"owner_ids":[102,101],"integration_id":30,"story_type":"feature","owned_by_id":102,"project_id":99,"created_at":"2014-04-08T12:01:00Z"}],"start":"2014-04-08T12:01:00Z","finish":"2014-04-08T12:00:10Z","team_strength":1,"number":2,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:10Z","finish":"2014-04-08T12:00:15Z","team_strength":1,"number":3,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:15Z","finish":"2014-04-08T12:00:20Z","team_strength":1,"number":4,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:20Z","finish":"2014-04-08T12:00:25Z","team_strength":1,"number":5,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:25Z","finish":"2014-04-08T12:00:30Z","team_strength":1,"number":6,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:30Z","finish":"2014-04-08T12:00:35Z","team_strength":1,"number":7,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:35Z","finish":"2014-04-08T12:00:40Z","team_strength":1,"number":8,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:40Z","finish":"2014-04-08T12:00:45Z","team_strength":1,"number":9,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:45Z","finish":"2014-04-08T12:00:50Z","team_strength":1,"number":10,"kind":"iteration","project_id":99},{"stories":[],"start":"2014-04-08T12:00:50Z","finish":"2014-04-08T12:00:55Z","team_strength":1,"number":11,"kind":"iteration","project_id":99}]
Successful responses to this request return an array containing zero or more instances of the iteration resource. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
offset
int in the request query.
 —  The offset of first iteration to return, relative to the set of iterations specified by 'scope', with zero being the first iteration in the scope. Defaults to zero. For the 'Done' scope, negative numbers can be passed, which specifies the number of iterations preceding the 'Current' iteration.
 
limit
int in the request query.
 —  The number of iterations to return relative to the offset.
 
scope
enumerated string in the request query.
 —  Restricts the state of iterations to return. If not specified, it defaults to all iterations including done.
Valid enumeration values: done, current, backlog, current_backlog
 
ENDPOINT

/projects/{project_id}/iteration_overrides/{iteration_number}

Operations on an individual iteration's overrides.

PUT
/projects/{project_id}/iteration_overrides/{iteration_number}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"team_strength":0.7,"length":5}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/iteration_overrides/3"

Hide Response
Headers
Response Body
{"team_strength":0.7,"planned":false,"number":3,"kind":"iteration_override","length":5,"project_id":99}
Successful responses to this request return the iteration_override resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
iteration_number
int in the request path.
required  —  The ID of the iteration.
 
team_strength
float in the request body.
 —  Iteration team strength, 1.0 is full-strength.
 
planned
boolean in the request body.
 —  Included in iterations when their project has enable_planned_mode true. The value will be false for all iterations other than Current. For the Current iteration, it may be false (indicating that the iteration currently contains stories based on emergent iterations and the project's velocity) or true (indicating that the Current iteration is in "planned" mode and its content is determined by the stories that have been explicitly added and removed from it).
 
length
int in the request body.
 —  Iteration length in weeks.
 

Project Memberships

ENDPOINT

/projects/{project_id}/memberships

Membership operations.

POST
/projects/{project_id}/memberships

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"role":"member","person_id":106,"project_color":"ffffff"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships"

View Response
Hide Response
Headers
Response Body
{"role":"member","wants_comment_notification_emails":true,"id":16100,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Galen Marek","id":106,"kind":"person","username":"starkiller","initials":"GM","email":"marek@sith.mil"},"kind":"project_membership","project_id":99,"project_color":"ffffff"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"role":"member","email":"marek@sith.mil"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships"

View Response
Hide Response
Headers
Response Body
{"role":"member","wants_comment_notification_emails":true,"id":16100,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Galen Marek","id":106,"kind":"person","username":"starkiller","initials":"GM","email":"marek@sith.mil"},"kind":"project_membership","project_id":99,"project_color":"b800bb"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"role":"member","name":"Vestara Khai","initials":"VK","email":"vkhai@sith.mil"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships"

View Response
Hide Response
Headers
Response Body
{"role":"member","wants_comment_notification_emails":true,"id":16100,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Vestara Khai","id":300,"kind":"person","username":"vestarak","initials":"VK","email":"vkhai@sith.mil"},"kind":"project_membership","project_id":99,"project_color":"b800bb"}
Successful responses to this request return the project_membership resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
person_id
int in the request query.
 —  The ID of the Tracker user to be added to the project.
 
role
enumerated string in the request query.
 —  The role the user will assume on the project.
Valid enumeration values: owner, member, viewer
 
email
string in the request query.
 —  The email address of a new/existing Tracker user to be added to this project.
 
name
string in the request query.
 —  The name to be given to a new Tracker user, should a user with the given email address not already exist.
 
initials
string in the request query.
 —  The initials to be given to a new Tracker user, should a user with the given email address not already exist.
 
project_color
string in the request query.
 —  The hex-value color to give the project in multi-project views
 
GET
/projects/{project_id}/memberships

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships"

Hide Response
Headers
Response Body
[{"role":"owner","wants_comment_notification_emails":false,"last_viewed_at":"2014-04-08T12:00:00Z","id":100,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Emperor Palpatine","id":100,"kind":"person","username":"palpatine","initials":"EP","email":"emperor@galacticrepublic.gov"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"member","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":101,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Darth Vader","id":101,"kind":"person","username":"vader","initials":"DV","email":"vader@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"owner","wants_comment_notification_emails":false,"last_viewed_at":"2014-04-08T12:00:00Z","id":102,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Wilhuff Tarkin","id":102,"kind":"person","username":"tarkin","initials":"WT","email":"governor@eriadu.gov"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"member","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":103,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB","email":"bast@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"member","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":104,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Clone TK421","id":104,"kind":"person","username":"tk421","initials":"TK421","email":"tk421@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"member","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":105,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Robotic Maintenance Team 4","id":105,"kind":"person","username":"i662","initials":"i662","email":"I662@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"},{"role":"viewer","wants_comment_notification_emails":false,"last_viewed_at":"2014-04-08T12:00:05Z","id":107,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Bevel Lemelisk","id":107,"kind":"person","username":"bevel","initials":"bl","email":"bevel@sith.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"}]
Successful responses to this request return the project_membership resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
ENDPOINT

/projects/{project_id}/memberships/{membership_id}

Membership operations.

GET
/projects/{project_id}/memberships/{membership_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships/102"

Hide Response
Headers
Response Body
{"role":"owner","wants_comment_notification_emails":false,"last_viewed_at":"2014-04-08T12:00:00Z","id":102,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Wilhuff Tarkin","id":102,"kind":"person","username":"tarkin","initials":"WT","email":"governor@eriadu.gov"},"kind":"project_membership","project_id":99,"project_color":"8100ea"}
Successful responses to this request return the project_membership resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
membership_id
int in the request path.
required  —  The ID of the membership.
 
DELETE
/projects/{project_id}/memberships/{membership_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships/103"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
membership_id
int in the request path.
required  —  The ID of the membership.
 
PUT
/projects/{project_id}/memberships/{membership_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"role":"viewer"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships/103"

Hide Response
Headers
Response Body
{"role":"viewer","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":103,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB","email":"bast@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"8100ea"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"project_color":"ffffff"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships/103"

Hide Response
Headers
Response Body
{"role":"member","wants_comment_notification_emails":true,"last_viewed_at":"2014-04-08T12:00:00Z","id":103,"will_receive_mention_notifications_or_emails":true,"person":{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB","email":"bast@deathstar.mil"},"kind":"project_membership","project_id":99,"project_color":"ffffff"}

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
membership_id
int in the request path.
required  —  The ID of the membership.
 
role
enumerated string in the request body.
 —  The role the user will assume on the project
Valid enumeration values: owner, member, viewer
 
project_color
string in the request body.
 —  The hex-value color to give the project in multi-project views
 

Account Memberships

ENDPOINT

/accounts/{account_id}/memberships

Membership operations.

GET
/accounts/{account_id}/memberships

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships"

Hide Response
Headers
Response Body
[{"timekeeper":true,"project_creator":false,"admin":true,"updated_at":"2014-04-08T12:00:00Z","id":101,"time_enterer":true,"person":{"name":"Darth Vader","id":101,"kind":"person","username":"vader","initials":"DV"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":true,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":102,"time_enterer":true,"person":{"name":"Wilhuff Tarkin","id":102,"kind":"person","username":"tarkin","initials":"WT"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":true,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":103,"time_enterer":true,"person":{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":true,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":104,"time_enterer":true,"person":{"name":"Clone TK421","id":104,"kind":"person","username":"tk421","initials":"TK421"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":false,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":106,"time_enterer":false,"person":{"name":"Galen Marek","id":106,"kind":"person","username":"starkiller","initials":"GM"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":false,"project_creator":false,"admin":true,"updated_at":"2014-04-08T12:00:00Z","id":109,"time_enterer":false,"person":{"name":"3D-4X administrative droid","id":109,"kind":"person","username":"threedeefourx","initials":"3D4X"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"},{"timekeeper":true,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":100,"time_enterer":false,"person":{"name":"Emperor Palpatine","id":100,"kind":"person","username":"palpatine","initials":"EP"},"kind":"account_membership","owner":true,"account_id":100,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return the account_membership resource.

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 
POST
/accounts/{account_id}/memberships

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Count Dooku","initials":"CD","email":"dooku@example.com"}' "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships"

View Response
Hide Response
Headers
Response Body
{"timekeeper":false,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":19100,"time_enterer":false,"person":{"name":"Count Dooku","id":300,"kind":"person","username":"countd","initials":"CD"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"person_id":108}' "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships"

View Response
Hide Response
Headers
Response Body
{"timekeeper":false,"project_creator":false,"admin":false,"updated_at":"2014-04-08T12:00:00Z","id":19100,"time_enterer":false,"person":{"name":"Mon Mothma","id":108,"kind":"person","username":"monmothma","initials":"MM"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the account_membership resource.

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 
person_id
int in the request body.
 —  The ID of the Tracker user to be added to the account.
 
email
string in the request body.
 —  The email address of a new/existing Tracker user to be added to this account.
 
name
string in the request body.
 —  The name to be given to a new Tracker user, should a user with the given email address not already exist.
 
initials
string in the request body.
 —  The initials to be given to a new Tracker user, should a user with the given email address not already exist.
 
timekeeper
boolean in the request body.
 —  True if the person is allowed to administer time entry by others on the account.
 
project_creator
boolean in the request body.
 —  True if the person is allowed to create new projects within the account.
 
admin
boolean in the request body.
 —  True if the person has administrative rights on the account.
 
time_enterer
boolean in the request body.
 —  True if the person is expected to enter time for work on projects in the account.
 
created_at
datetime in the request body.
 —  Creation time.
 
ENDPOINT

/accounts/{account_id}/memberships/{person_id}

Get an individual account membership, requested by the person_id.

GET
/accounts/{account_id}/memberships/{person_id}

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships/101"

Hide Response
Headers
Response Body
{"timekeeper":true,"project_creator":false,"admin":true,"updated_at":"2014-04-08T12:00:00Z","id":101,"time_enterer":true,"person":{"name":"Darth Vader","id":101,"kind":"person","username":"vader","initials":"DV"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the account_membership resource.

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 
person_id
int in the request path.
required  —  The ID of the person.
 
PUT
/accounts/{account_id}/memberships/{person_id}

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"project_creator":true}' "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships/103"

Hide Response
Headers
Response Body
{"timekeeper":true,"project_creator":true,"admin":false,"updated_at":"2014-04-08T12:00:05Z","id":103,"time_enterer":true,"person":{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB"},"kind":"account_membership","owner":false,"account_id":100,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the account_membership resource.

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 
person_id
int in the request path.
required  —  The ID of the person.
 
timekeeper
boolean in the request body.
 —  True if the person is allowed to administer time entry by others on the account.
 
project_creator
boolean in the request body.
 —  True if the person is allowed to create new projects within the account.
 
admin
boolean in the request body.
 —  True if the person has administrative rights on the account.
 
time_enterer
boolean in the request body.
 —  True if the person is expected to enter time for work on projects in the account.
 
DELETE
/accounts/{account_id}/memberships/{person_id}

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships/104"

Hide Response
Headers

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 
person_id
int in the request path.
required  —  The ID of the person.
 

Accounts

ENDPOINT

/accounts

Access a user's accounts

GET
/accounts

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/accounts"

Hide Response
Headers
Response Body
[{"status":"active","name":"Galactic Empire","updated_at":"2014-04-08T12:00:05Z","plan":"Pivotal Labs","id":100,"kind":"account","created_at":"2014-04-08T12:00:05Z"}]
Successful responses to this request return an array containing zero or more instances of the account resource.

Account

ENDPOINT

/accounts/{account_id}

Access the account specified by the account_id value in the URL.

GET
/accounts/{account_id}

Retrieving account resources via this endpoint is restricted to Owners and Administrators for the Account specified. Non authorized users will receive an error.

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/accounts/100"

Hide Response
Headers
Response Body
{"status":"active","name":"Galactic Empire","updated_at":"2014-04-08T12:00:05Z","plan":"Pivotal Labs","id":100,"kind":"account","created_at":"2014-04-08T12:00:05Z"}
Successful responses to this request return the account resource.

PARAMETERS

account_id
int in the request path.
required  —  The ID of the account.
 

Labels

ENDPOINT

/projects/{project_id}/labels

Access the project's labels.

GET
/projects/{project_id}/labels

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels?date_format=millis"

Hide Response
Headers
Response Body
[{"name":"diplomatic relations","updated_at":1396958400000,"id":2014,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"fleet ops","updated_at":1396958400000,"id":2012,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"mnt","updated_at":1396958400000,"id":2010,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"personnel","updated_at":1396958400000,"id":2011,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"plans","updated_at":1396958400000,"id":2008,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"r&d","updated_at":1396958400000,"id":2013,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"rebel bases","updated_at":1396958400000,"id":2007,"kind":"label","project_id":99,"created_at":1396958400000},{"name":"turning luke","updated_at":1396958400000,"id":2009,"kind":"label","project_id":99,"created_at":1396958400000}]
Successful responses to this request return an array containing zero or more instances of the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
POST
/projects/{project_id}/labels

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"a new hope"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels"

View Response
Hide Response
Headers
Response Body
{"name":"a new hope","updated_at":"2014-04-08T12:00:00Z","id":5100,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
name
string[255] in the request body.
 —  The label's name.
 
ENDPOINT

/projects/{project_id}/labels/{label_id}

Access the project's labels.

GET
/projects/{project_id}/labels/{label_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels/2014"

Hide Response
Headers
Response Body
{"name":"diplomatic relations","updated_at":"2014-04-08T12:00:00Z","id":2014,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
label_id
int in the request path.
required  —  The ID of the label.
 
PUT
/projects/{project_id}/labels/{label_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"detention"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels/2014"

Hide Response
Headers
Response Body
{"name":"detention","updated_at":"2014-04-08T12:00:05Z","id":2014,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
label_id
int in the request path.
required  —  The ID of the label.
 
name
string[255] in the request body.
 —  The label's name.
 
DELETE
/projects/{project_id}/labels/{label_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels/2014"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
label_id
int in the request path.
required  —  The ID of the label.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/labels

Operations on a story's labels

GET
/projects/{project_id}/stories/{story_id}/labels

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=556

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/labels"

View Response
Hide Response
Headers
Response Body
[{"name":"plans","updated_at":"2014-04-08T12:00:00Z","id":2008,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},{"name":"rebel bases","updated_at":"2014-04-08T12:00:00Z","id":2007,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
POST
/projects/{project_id}/stories/{story_id}/labels

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=556

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"my new label"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/labels"

View Response
Hide Response
Headers
Response Body
{"name":"my new label","updated_at":"2014-04-08T12:00:00Z","id":5100,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the label resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
id
int in the request body.
 —  The id of a label that already exists within the project, which should be added to the selected story.
 
name
string[255] in the request body.
 —  The label's name.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/labels/{label_id}

Operations on a story label

DELETE
/projects/{project_id}/stories/{story_id}/labels/{label_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=556

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/labels/2008"

View Response
Hide Response
Headers
Response Body
{"name":"plans","updated_at":"2014-04-08T12:00:00Z","id":2008,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
label_id
int in the request path.
required  —  The ID of the label.
 

Stories

ENDPOINT

/projects/{project_id}/stories

Fetch some or all stories for the specified project.

GET
/projects/{project_id}/stories

Note that labels or strings with a space must be quoted, and multiple filters must be separated with a space, and everything must be URL-escaped. You can also search on multiple values within the same search term, for example, 'filter=id:1,2,3' will return resources with the id 1, 2 or 3.

Searches can be refined with all of the modifications listed here: How can a search be refined?

On endpoints that support filters, 'filter' can only be combined with project_id, date_format, limit and offset. All other parameters will result in an error.

state:started requester:OWK label:"jedi stuff" keyword

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories?date_format=millis&with_state=unstarted"

Hide Response
Headers
Response Body
[{"labels":[],"name":"Tractor beam loses power intermittently","current_state":"unstarted","updated_at":1396958400000,"id":560,"kind":"story","url":"http://localhost/story/show/560","requested_by_id":102,"owner_ids":[],"story_type":"bug","project_id":99,"created_at":1396958400000},{"labels":[{"name":"mnt","updated_at":1396958400000,"id":2010,"kind":"label","project_id":99,"created_at":1396958400000}],"name":"Repair CommLink","current_state":"unstarted","updated_at":1396958400000,"id":565,"kind":"story","description":"It's malfunctioning.","url":"http://localhost/story/show/565","requested_by_id":104,"owner_ids":[],"story_type":"chore","project_id":99,"created_at":1396958400000},{"labels":[],"name":"Battlestation fully operational","current_state":"unstarted","updated_at":1396958400000,"id":552,"kind":"story","description":"Everything is proceeding as I have foreseen.","url":"http://localhost/story/show/552","requested_by_id":100,"owner_ids":[],"story_type":"release","project_id":99,"deadline":1396958405000,"created_at":1396958400000},{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"unstarted","updated_at":1396958400000,"id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":1396958400000}]

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories?fields=current_state%2Clabels%2Ccomments%2Ctasks&with_state=unstarted"

Hide Response
Headers
Response Body
[{"labels":[],"comments":[],"current_state":"unstarted","id":560,"tasks":[]},{"labels":[{"name":"mnt","updated_at":"2014-04-08T12:00:00Z","id":2010,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}],"comments":[],"current_state":"unstarted","id":565,"tasks":[]},{"labels":[],"comments":[],"current_state":"unstarted","id":552,"tasks":[]},{"labels":[],"comments":[{"story_id":555,"updated_at":"2014-04-08T12:00:00Z","id":111,"kind":"comment","text":"I want them alive!","person_id":101,"created_at":"2014-04-08T12:00:00Z"}],"current_state":"unstarted","id":555,"tasks":[]}]

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories?filter=id%3A558%2C560&limit=1&offset=1"

Hide Response
Headers
Response Body
[{"labels":[],"name":"Tractor beam loses power intermittently","current_state":"unstarted","updated_at":"2014-04-08T12:00:00Z","id":560,"kind":"story","url":"http://localhost/story/show/560","requested_by_id":102,"owner_ids":[],"story_type":"bug","project_id":99,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of the story resource. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
with_label
string in the request query.
 —  A label name which all returned stories must match.
 
with_state
enumerated string in the request query.
 —  A story's current_state which all returned stories must match.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
accepted_before
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are accepted before.
 
accepted_after
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are accepted after.
 
created_before
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are created before.
 
created_after
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are created after.
 
updated_before
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are updated before.
 
updated_after
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) which all returned stories are updated after.
 
deadline_before
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) that release dates fall before.
 
deadline_after
datetime in the request query.
 —  A date and time (ISO 8601 format or milliseconds) that release dates fall after.
 
limit
int in the request query.
 —  The number of stories you want returned.
 
offset
int in the request query.
 —  With the first story in your priority list as 0, the index of the first story you want returned.
 
filter
string in the request query.
 —  This parameter supplies a search string; only stories that match the search criteria are returned. Cannot be used together with any other parameters. How can a search be refined?
 
POST
/projects/{project_id}/stories

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Exhaust ports are ray shielded"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

View Response
Hide Response
Headers
Response Body
{"labels":[],"name":"Exhaust ports are ray shielded","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"before_id":566,"name":"Replace the lining in Darth Vader's helmet","after_id":555}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

View Response
Hide Response
Headers
Response Body
{"labels":[],"name":"Replace the lining in Darth Vader's helmet","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"estimate":1,"name":"Exhaust ports are ray shielded","current_state":"accepted"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

View Response
Hide Response
Headers
Response Body
{"estimate":1,"labels":[],"name":"Exhaust ports are ray shielded","current_state":"accepted","accepted_at":"2014-04-08T12:00:00Z","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Exhaust ports are ray shielded","description":null}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

View Response
Hide Response
Headers
Response Body
{"labels":[],"name":"Exhaust ports are ray shielded","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"comments":[{"text":"Just ray shielding? What about proton weapons?"}],"name":"Exhaust ports are ray shielded"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories?fields=%3Adefault%2Ccomments"

View Response
Hide Response
Headers
Response Body
{"labels":[],"comments":[{"story_id":2300,"updated_at":"2014-04-08T12:00:00Z","id":300,"kind":"comment","text":"Just ray shielding? What about proton weapons?","person_id":101,"created_at":"2014-04-08T12:00:00Z"}],"name":"Exhaust ports are ray shielded","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"comments":[{"text":"Make sure the stamp on the latest shipment of seals matches the new Imperial logo (attached).","file_attachments":[{"content_type":"image/png","big_url":"/attachments/0000/0020/empire_big.png","uploader_id":100,"uploaded":true,"width":1000,"thumbnailable":true,"type":"file_attachment","download_url":"/attachments/0000/0020/empire_thumb.png","created_at":1396958400000}]}],"name":"replace seals on trash compactors","story_type":"chore"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

View Response
Hide Response
Headers
Response Body
{"labels":[],"name":"replace seals on trash compactors","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":2300,"kind":"story","url":"http://localhost/story/show/2300","requested_by_id":101,"owner_ids":[],"story_type":"chore","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the story resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
comments
List[comment] in the request body.
 —  This parameter allows creation of new comments implicitly as part of the basic request. See the 'comment_ids' attribute of the story resource for how the resources relate. See the parameters of the POST to /projects/{project_id}/stories/{story_id}/comments operation for keys that can be included in the nested hash in the parameters. The nested comments must not contain an id.
 
estimate
float in the request body.
 —  Point value of the story.
 
before_id
int in the request body.
 —  ID of the story that the current story is located before. Null if story is last one in the project.
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
tasks
List[task] in the request body.
 —  This parameter allows creation of new tasks implicitly as part of the basic request. See the 'task_ids' attribute of the story resource for how the resources relate. See the parameters of the POST to /projects/{project_id}/stories/{story_id}/tasks operation for keys that can be included in the nested hash in the parameters. The nested tasks must not contain an id.
 
accepted_at
datetime in the request body.
 —  Acceptance time.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
name
string[5000] in the request body.
required  —  Name of the story.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
labels
List[label] in the request body.
 —  This parameter allows labels to be selected by content or to be created implicitly as part of the basic request. See the 'label_ids' attribute of the story resource. The labels' ids must not be included if creating a new one.
 
label_ids
List[int] in the request body.
 —  IDs of labels currently applied to story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 
planned_iteration_number
int in the request body.
 —  Included in stories when their project has enable_planned_mode true. The value will be null for all stories not in the Current iteration, and for Current-iteration stories when the Current iteration is not planned. Stories contained in a planned Current iteration will have the iteration's number in this field.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
follower_ids
List[int] in the request body.
 —  IDs of people currently following the story.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this story.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
after_id
int in the request body.
 —  ID of the story that the current story is located after. Null if story is the first one in the project.
 
created_at
datetime in the request body.
 —  Creation time.
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 

Story

ENDPOINT

/projects/{project_id}/stories/{story_id}

Operations on an individual story.

GET
/projects/{project_id}/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"unstarted","updated_at":"2014-04-08T12:00:00Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the story resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
PUT
/projects/{project_id}/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"labels":[]}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"unstarted","updated_at":"2014-04-08T12:00:00Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"estimate":1,"before_id":556,"current_state":"started"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/566"

View Response
Hide Response
Headers
Response Body
{"estimate":1,"labels":[{"name":"mnt","updated_at":"2014-04-08T12:00:00Z","id":2010,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}],"name":"Clean Cell Block 1138","current_state":"started","updated_at":"2014-04-08T12:00:05Z","id":566,"kind":"story","description":"The large, hairy _Thing_ is being transferred away","url":"http://localhost/story/show/566","requested_by_id":104,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"current_state":"rejected","comment":{"text":"Here are the new plans.","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"type":"file_attachment","download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":1396958400000}]}}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555?fields=requested_by%2Cowned_by%2Clabels%2Ccomments%28text%2Cfile_attachments%29%2Ctasks"

View Response
Hide Response
Headers
Response Body
{"labels":[],"comments":[{"id":111,"text":"I want them alive!","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":"2014-04-08T12:00:05Z"},{"content_type":"image/png","big_url":"/attachments/0000/0020/empire_big.png","uploader_id":100,"uploaded":true,"width":1000,"thumbnailable":true,"download_url":"/attachments/0000/0020/empire_thumb.png","created_at":"2014-04-08T12:00:00Z"}]},{"id":300,"text":"Here are the new plans.","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":"2014-04-08T12:00:05Z"}]}],"id":555,"requested_by":{"name":"Darth Vader","id":101,"kind":"person","username":"vader","initials":"DV","email":"vader@deathstar.mil"},"tasks":[]}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"estimate":1,"name":"Exhaust ports have ray shielding","current_state":"accepted"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":1,"labels":[],"name":"Exhaust ports have ray shielding","current_state":"accepted","accepted_at":"2014-04-08T12:00:05Z","updated_at":"2014-04-08T12:00:05Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"before_id":null,"group":"scheduled","project_id":98,"after_id":567}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"unstarted","updated_at":"2014-04-08T12:00:05Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":98,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the story resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment
object in the request body.
 —  The content for a new comment to create. May contain nested attachments, but must not contain id values.
 
follower_ids
List[int] in the request body.
 —  The ids of the users you would like to follow the story.
 
group
enumerated string in the request body.
 —  Should be supplied when specifying the story's before_id and/or after_id.
Valid enumeration values: scheduled, unscheduled
 
project_id
int in the request body.
 —  The value that the story's project_id should be updated to. Has the effect of moving the story being updated into that project from its current one.
 
estimate
float in the request body.
 —  Point value of the story.
 
before_id
int in the request body.
 —  ID of the story that the current story is located before. Null if story is last one in the project.
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
accepted_at
datetime in the request body.
 —  Acceptance time.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
name
string[5000] in the request body.
 —  Name of the story.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
labels
List[label] in the request body.
 —  This parameter allows labels to be selected by content or to be created implicitly as part of the basic request. See the 'label_ids' attribute of the story resource. The labels' ids must not be included if creating a new one.
 
label_ids
List[int] in the request body.
 —  IDs of labels currently applied to story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 
planned_iteration_number
int in the request body.
 —  Included in stories when their project has enable_planned_mode true. The value will be null for all stories not in the Current iteration, and for Current-iteration stories when the Current iteration is not planned. Stories contained in a planned Current iteration will have the iteration's number in this field.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this story.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
after_id
int in the request body.
 —  ID of the story that the current story is located after. Null if story is the first one in the project.
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 
DELETE
/projects/{project_id}/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/owners

Operations on a story's owners

GET
/projects/{project_id}/stories/{story_id}/owners

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/owners"

View Response
Hide Response
Headers
Response Body
[{"name":"Emperor Palpatine","id":100,"kind":"person","username":"palpatine","initials":"EP","email":"emperor@galacticrepublic.gov"},{"name":"Moradmin Bast","id":103,"kind":"person","username":"bast","initials":"MB","email":"bast@deathstar.mil"}]
Successful responses to this request return an array containing zero or more instances of the person resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
POST
/projects/{project_id}/stories/{story_id}/owners

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"id":100}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/owners"

View Response
Hide Response
Headers
Response Body
{"name":"Emperor Palpatine","id":100,"kind":"person","username":"palpatine","initials":"EP","email":"emperor@galacticrepublic.gov"}
Successful responses to this request return an array containing zero or more instances of the person resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
id
int in the request body.
 —  ID of the person to be added
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/owners/{person_id}

Operations on a story's owners

DELETE
/projects/{project_id}/stories/{story_id}/owners/{person_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/owners/100"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
person_id
int in the request path.
required  —  The ID of the person.
 
ENDPOINT

/stories/{story_id}

Operations on an individual story.

GET
/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/stories/558"

View Response
Hide Response
Headers
Response Body
{"estimate":3,"labels":[{"name":"plans","updated_at":"2014-04-08T12:00:00Z","id":2008,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}],"name":"All exhaust ports should be shielded","current_state":"rejected","updated_at":"2014-04-08T12:00:00Z","id":558,"kind":"story","description":"ray shielded, that is.","url":"http://localhost/story/show/558","requested_by_id":102,"owner_ids":[104],"story_type":"feature","owned_by_id":104,"project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the story resource.

PARAMETERS

story_id
int in the request path.
required  —  The ID of the story.
 
PUT
/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"labels":[]}' "https://www.pivotaltracker.com/services/v5/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"unstarted","updated_at":"2014-04-08T12:00:00Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"estimate":1,"before_id":556,"current_state":"started"}' "https://www.pivotaltracker.com/services/v5/stories/566"

View Response
Hide Response
Headers
Response Body
{"estimate":1,"labels":[{"name":"mnt","updated_at":"2014-04-08T12:00:00Z","id":2010,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"}],"name":"Clean Cell Block 1138","current_state":"started","updated_at":"2014-04-08T12:00:05Z","id":566,"kind":"story","description":"The large, hairy _Thing_ is being transferred away","url":"http://localhost/story/show/566","requested_by_id":104,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"current_state":"rejected","comment":{"text":"Here are the new plans.","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"type":"file_attachment","download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":1396958400000}]}}' "https://www.pivotaltracker.com/services/v5/stories/555?fields=requested_by%2Cowned_by%2Clabels%2Ccomments%28text%2Cfile_attachments%29%2Ctasks"

View Response
Hide Response
Headers
Response Body
{"labels":[],"comments":[{"id":111,"text":"I want them alive!","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":"2014-04-08T12:00:05Z"},{"content_type":"image/png","big_url":"/attachments/0000/0020/empire_big.png","uploader_id":100,"uploaded":true,"width":1000,"thumbnailable":true,"download_url":"/attachments/0000/0020/empire_thumb.png","created_at":"2014-04-08T12:00:00Z"}]},{"id":300,"text":"Here are the new plans.","file_attachments":[{"content_type":"image/tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","uploader_id":101,"uploaded":true,"width":650,"thumbnailable":false,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","created_at":"2014-04-08T12:00:05Z"}]}],"id":555,"requested_by":{"name":"Darth Vader","id":101,"kind":"person","username":"vader","initials":"DV","email":"vader@deathstar.mil"},"tasks":[]}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"estimate":1,"name":"Exhaust ports have ray shielding","current_state":"accepted"}' "https://www.pivotaltracker.com/services/v5/stories/555"

View Response
Hide Response
Headers
Response Body
{"estimate":1,"labels":[],"name":"Exhaust ports have ray shielding","current_state":"accepted","accepted_at":"2014-04-08T12:00:05Z","updated_at":"2014-04-08T12:00:05Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the story resource.

PARAMETERS

story_id
int in the request path.
required  —  The ID of the story.
 
comment
object in the request body.
 —  The content for a new comment to create. May contain nested attachments, but must not contain id values.
 
follower_ids
List[int] in the request body.
 —  The ids of the users you would like to follow the story.
 
group
enumerated string in the request body.
 —  Should be supplied when specifying the story's before_id and/or after_id.
Valid enumeration values: scheduled, unscheduled
 
estimate
float in the request body.
 —  Point value of the story.
 
before_id
int in the request body.
 —  ID of the story that the current story is located before. Null if story is last one in the project.
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
accepted_at
datetime in the request body.
 —  Acceptance time.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
name
string[5000] in the request body.
 —  Name of the story.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
labels
List[label] in the request body.
 —  This parameter allows labels to be selected by content or to be created implicitly as part of the basic request. See the 'label_ids' attribute of the story resource. The labels' ids must not be included if creating a new one.
 
label_ids
List[int] in the request body.
 —  IDs of labels currently applied to story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 
planned_iteration_number
int in the request body.
 —  Included in stories when their project has enable_planned_mode true. The value will be null for all stories not in the Current iteration, and for Current-iteration stories when the Current iteration is not planned. Stories contained in a planned Current iteration will have the iteration's number in this field.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this story.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
after_id
int in the request body.
 —  ID of the story that the current story is located after. Null if story is the first one in the project.
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 
project_id
int in the request body.
 —  id of the project.
 
DELETE
/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/stories/555"

View Response
Hide Response
Headers

PARAMETERS

story_id
int in the request path.
required  —  The ID of the story.
 

Story Tasks

ENDPOINT

/projects/{project_id}/stories/{story_id}/tasks

Operations on a story's tasks

GET
/projects/{project_id}/stories/{story_id}/tasks

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks"

View Response
Hide Response
Headers
Response Body
[{"story_id":558,"complete":false,"updated_at":"2014-04-08T12:00:00Z","id":5,"position":1,"kind":"task","description":"Port 0","created_at":"2014-04-08T12:00:00Z"},{"story_id":558,"complete":false,"updated_at":"2014-04-08T12:00:00Z","id":6,"position":2,"kind":"task","description":"Port 90","created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of the task resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
POST
/projects/{project_id}/stories/{story_id}/tasks

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"description":"port 270"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks"

View Response
Hide Response
Headers
Response Body
{"story_id":558,"complete":false,"updated_at":"2014-04-08T12:00:00Z","id":5100,"position":3,"kind":"task","description":"port 270","created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"complete":true,"position":1,"description":"port 270"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks"

View Response
Hide Response
Headers
Response Body
{"story_id":558,"complete":true,"updated_at":"2014-04-08T12:00:00Z","id":5100,"position":1,"kind":"task","description":"port 270","created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the task resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
complete
boolean in the request body.
 —  Flag showing the completion of the task.
 
position
int in the request body.
 —  Offset from the top of the task list. Positions start counting from 1 for the first task on a story.
 
description
string[1000] in the request body.
required  —  Content of the task.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/tasks/{task_id}

Operations on a task

GET
/projects/{project_id}/stories/{story_id}/tasks/{task_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks/5"

View Response
Hide Response
Headers
Response Body
{"story_id":558,"complete":false,"updated_at":"2014-04-08T12:00:00Z","id":5,"position":1,"kind":"task","description":"Port 0","created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks/5?fields=description%2Ccomplete"

View Response
Hide Response
Headers
Response Body
{"complete":false,"id":5,"description":"Port 0"}
Successful responses to this request return the task resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
task_id
int in the request path.
required  —  The ID of the task.
 
DELETE
/projects/{project_id}/stories/{story_id}/tasks/{task_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks/5"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
task_id
int in the request path.
required  —  The ID of the task.
 
PUT
/projects/{project_id}/stories/{story_id}/tasks/{task_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"description":"port 360"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks/5"

View Response
Hide Response
Headers
Response Body
{"story_id":558,"complete":false,"updated_at":"2014-04-08T12:00:05Z","id":5,"position":1,"kind":"task","description":"port 360","created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"complete":true,"position":2}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks/5"

View Response
Hide Response
Headers
Response Body
{"story_id":558,"complete":true,"updated_at":"2014-04-08T12:00:05Z","id":5,"position":2,"kind":"task","description":"Port 0","created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the task resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
task_id
int in the request path.
required  —  The ID of the task.
 
complete
boolean in the request body.
 —  Flag showing the completion of the task.
 
position
int in the request body.
 —  Offset from the top of the task list. Positions start counting from 1 for the first task on a story.
 
description
string[1000] in the request body.
 —  Content of the task.
 

Epics

ENDPOINT

/projects/{project_id}/epics

Epic operations.

GET
/projects/{project_id}/epics

Note that labels or strings with a space must be quoted, and multiple filters must be separated with a space, and everything must be URL-escaped. You can also search on multiple values within the same search term, for example, 'filter=id:1,2,3' will return resources with the id 1, 2 or 3.

Searches can be refined with all of the modifications listed here: How can a search be refined?

On endpoints that support filters, 'filter' can only be combined with project_id, date_format, limit and offset. All other parameters will result in an error.

label:"jedi stuff" keyword
keyword created_since:11/16/2009 has_attachment:

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics"

Hide Response
Headers
Response Body
[{"label":{"name":"mnt","updated_at":"2014-04-08T12:00:00Z","id":2010,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Maintenance","updated_at":"2014-04-08T12:00:00Z","id":7,"kind":"epic","url":"http://localhost/epic/show/7","project_id":99,"created_at":"2014-04-08T12:00:00Z"},{"label":{"name":"turning luke","updated_at":"2014-04-08T12:00:00Z","id":2009,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Turn Luke Skywalker","updated_at":"2014-04-08T12:00:00Z","id":6,"kind":"epic","url":"http://localhost/epic/show/6","project_id":99,"created_at":"2014-04-08T12:00:00Z"},{"label":{"name":"plans","updated_at":"2014-04-08T12:00:00Z","id":2008,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Death Star Plans","updated_at":"2014-04-08T12:00:00Z","id":5,"kind":"epic","url":"http://localhost/epic/show/5","project_id":99,"created_at":"2014-04-08T12:00:00Z"},{"label":{"name":"rebel bases","updated_at":"2014-04-08T12:00:00Z","id":2007,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:00Z","id":4,"kind":"epic","description":"Identify the systems and eliminate the rebel scum.","url":"http://localhost/epic/show/4","project_id":99,"created_at":"2014-04-08T12:00:00Z"}]

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics?fields=id%2Ccomments"

Hide Response
Headers
Response Body
[{"comments":[],"id":7},{"comments":[],"id":6},{"comments":[{"updated_at":"2014-04-08T12:00:00Z","id":110,"kind":"comment","text":"Check out these Uffel mouse droids","person_id":103,"epic_id":5,"created_at":"2014-04-08T12:00:00Z"}],"id":5},{"comments":[{"updated_at":"2014-04-08T12:00:00Z","id":109,"kind":"comment","text":"Should we send a probe to Dantooine?","person_id":103,"epic_id":4,"created_at":"2014-04-08T12:00:00Z"}],"id":4}]
Successful responses to this request return an array containing zero or more instances of the epic resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
filter
string in the request query.
 —  This parameter supplies a search string; only epics that match the search criteria are returned. How can a search be refined?
 
POST
/projects/{project_id}/epics

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"Tractor Beams"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics"

View Response
Hide Response
Headers
Response Body
{"label":{"name":"tractor beams","updated_at":"2014-04-08T12:00:00Z","id":5100,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Tractor Beams","updated_at":"2014-04-08T12:00:00Z","id":2100,"kind":"epic","url":"http://localhost/epic/show/2100","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"label":{"name":"tractor-beams"},"name":"Tractor Beams","description":"Install tractor beam systems in all landing bays. Beam systems should report to central monitoring."}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics"

View Response
Hide Response
Headers
Response Body
{"label":{"name":"tractor-beams","updated_at":"2014-04-08T12:00:00Z","id":5100,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Tractor Beams","updated_at":"2014-04-08T12:00:00Z","id":2100,"kind":"epic","description":"Install tractor beam systems in all landing bays. Beam systems should report to central monitoring.","url":"http://localhost/epic/show/2100","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"comments":[{"text":"Use this image on all external comms","file_attachments":[{"content_type":"image/png","id":20,"big_url":"#","uploader_id":101,"uploaded":false,"height":804,"thumbnail_url":"#","size":82382,"width":1000,"thumbnailable":true,"filename":"empire.png","download_url":"#","created_at":"2006/05/04 12:36:00 +0000"}]}],"name":"PR"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics"

View Response
Hide Response
Headers
Response Body
{"label":{"name":"pr","updated_at":"2014-04-08T12:00:00Z","id":5100,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"PR","updated_at":"2014-04-08T12:00:00Z","id":2100,"kind":"epic","url":"http://localhost/epic/show/2100","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the epic resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
label
label in the request body.
 —  This parameter allows a label to be selected by content or to be created implicitly as part of the basic request. See the 'label_id' attribute of the epic resource. The label's id must not be included if creating a new one.
 
label_id
int in the request body.
 —  id of the epic's label.
 
comments
List[comment] in the request body.
 —  This parameter allows creation of new comments implicitly as part of the basic request. See the 'comment_ids' attribute of the epic resource for how the resources relate. See the parameters of the POST to /projects/{project_id}/epics/{epic_id}/comments operation for keys that can be included in the nested hash in the parameters. The nested comments must not contain an id.
 
before_id
int in the request body.
 —  id of the epic following the epic.
 
name
string[5000] in the request body.
required  —  Name of the epic.
 
description
string[20000] in the request body.
 —  In-depth explanation of the epic's goals, scope, etc.
 
followers
List[follower] in the request body.
 —  This parameter allows followers to be selected by content or to be created implicitly as part of the basic request. See the 'follower_ids' attribute of the epic resource. The followers' ids must not be included if creating a new one.
 
follower_ids
List[int] in the request body.
 —  IDs of people currently following the story.
 
after_id
int in the request body.
 —  id of the epic preceding the epic.
 

Epic

ENDPOINT

/projects/{project_id}/epics/{epic_id}

Operations on an individual epic.

GET
/projects/{project_id}/epics/{epic_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4"

Hide Response
Headers
Response Body
{"label":{"name":"rebel bases","updated_at":"2014-04-08T12:00:00Z","id":2007,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:00Z","id":4,"kind":"epic","description":"Identify the systems and eliminate the rebel scum.","url":"http://localhost/epic/show/4","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4?fields=name%2Cproject%28enable_following%2Ctime_zone%2Cweek_start_day%2Cname%29"

Hide Response
Headers
Response Body
{"project":{"time_zone":{"olson_name":"America/Los_Angeles","kind":"time_zone","offset":"-07:00"},"name":"Death Star","week_start_day":"Monday","id":99,"enable_following":true},"name":"Rebel Home Worlds","id":4}
Successful responses to this request return the epic resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
PUT
/projects/{project_id}/epics/{epic_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"description":"new desc"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4"

Hide Response
Headers
Response Body
{"label":{"name":"rebel bases","updated_at":"2014-04-08T12:00:00Z","id":2007,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:05Z","id":4,"kind":"epic","description":"new desc","url":"http://localhost/epic/show/4","project_id":99,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"label":{"name":"find-rebels"}}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4?fields=name%2Clabel_id"

Hide Response
Headers
Response Body
{"label_id":5100,"name":"Rebel Home Worlds","id":4}
Successful responses to this request return the epic resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
follower_ids
List[int] in the request body.
 —  The ids of the project members to follow the epic.
 
label
label in the request body.
 —  This parameter allows a label to be selected by content or to be created implicitly as part of the basic request. See the 'label_id' attribute of the epic resource. The label's id must not be included if creating a new one.
 
label_id
int in the request body.
 —  id of the epic's label.
 
before_id
int in the request body.
 —  id of the epic following the epic.
 
name
string[5000] in the request body.
 —  Name of the epic.
 
description
string[20000] in the request body.
 —  In-depth explanation of the epic's goals, scope, etc.
 
after_id
int in the request body.
 —  id of the epic preceding the epic.
 
DELETE
/projects/{project_id}/epics/{epic_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
ENDPOINT

/epics/{epic_id}

Get an individual epic.

GET
/epics/{epic_id}

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/epics/4"

Hide Response
Headers
Response Body
{"label":{"name":"rebel bases","updated_at":"2014-04-08T12:00:00Z","id":2007,"kind":"label","project_id":99,"created_at":"2014-04-08T12:00:00Z"},"name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:00Z","id":4,"kind":"epic","description":"Identify the systems and eliminate the rebel scum.","url":"http://localhost/epic/show/4","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the epic resource.

PARAMETERS

epic_id
int in the request path.
required  —  The ID of the epic.
 

Comments

ENDPOINT

/projects/{project_id}/stories/{story_id}/comments

Index of comments on an individual story.

GET
/projects/{project_id}/stories/{story_id}/comments

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments"

View Response
Hide Response
Headers
Response Body
[{"story_id":555,"updated_at":"2014-04-08T12:00:00Z","id":111,"kind":"comment","text":"I want them alive!","person_id":101,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
POST
/projects/{project_id}/stories/{story_id}/comments

Note that to include file_attachments or google_attachments in a new comment, they must be identified using complete nested resources (JSON hashes, like the one in the response from performing an upload to /projects/{project_id}/uploads) rather than solely by ID. When attaching an uploaded file, the client should include the entire file_attachment resource hash that was received from the server in response to uploading the file—this includes the file_attachment resource's id attribute. When attaching a "file" from Google Apps, the complete google_attachment resource hash selected from the list in the server's response from the /google_attachments endpoint must be included. google_attachment resources received from /google_attachments do not contain an id, and the client should not attempt to insert/create one. Each use of a google_attachment resource in a comment is assigned a unique ID during comment creation, which can be returned to the client in response to this request.

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"If this is a consular ship, then where is the ambassador?"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments"

View Response
Hide Response
Headers
Response Body
{"story_id":555,"updated_at":"2014-04-08T12:00:00Z","id":300,"kind":"comment","text":"If this is a consular ship, then where is the ambassador?","person_id":101,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"commit_type":"github","commit_identifier":"abc123"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments?fields=commit_identifier"

View Response
Hide Response
Headers
Response Body
{"id":300,"commit_identifier":"abc123"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"Blame the clone for saying this.","person_id":104}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments"

View Response
Hide Response
Headers
Response Body
{"story_id":555,"updated_at":"2014-04-08T12:00:00Z","id":300,"kind":"comment","text":"Blame the clone for saying this.","person_id":104,"created_at":"2014-04-08T12:00:00Z"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"What if this were our new sigil?","file_attachments":[{"content_type":"image/png","big_url":"/attachments/0000/0024/empire_big.png","uploader_id":100,"uploaded":true,"width":1000,"thumbnailable":true,"download_url":"/attachments/0000/0024/empire_thumb.png","created_at":"2014-04-08T12:00:00Z"}]}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments?fields=%3Adefault%2Cfile_attachment_ids"

View Response
Hide Response
Headers
Response Body
{"story_id":555,"file_attachment_ids":[24],"updated_at":"2014-04-08T12:00:00Z","id":300,"kind":"comment","text":"What if this were our new sigil?","person_id":101,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
google_attachments
List[google_attachment] in the request body.
 —  This parameter allows creation of new google_attachments implicitly as part of the basic request. See the 'google_attachment_ids' attribute of the comment resource. The nested google_attachments must not contain an id.
 
commit_type
string[255] in the request body.
 —  String identifying the type of remote source control system if Pivotal Tracker can determine it. Present only on comments that were created by a POST to the source commits API endpoint.
 
file_attachments
List[file_attachment] in the request body.
 —  This parameter allows file_attachments to be selected by content as part of the basic request. See the 'file_attachment_ids' attribute of the comment resource. The file_attachments' ids must be included.
 
text
string[20000] in the request body.
 —  Content of the comment.
 
commit_identifier
string[255] in the request body.
 —  Commit Id on the remote source control system for the comment. Present only on comments that were created by a POST to the source commits API endpoint.
 
person_id
int in the request body.
 —  The id of the comment creator.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/comments/{comment_id}

Operations on an individual comment.

DELETE
/projects/{project_id}/stories/{story_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=563

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments/108"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
GET
/projects/{project_id}/stories/{story_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=563

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments/108"

View Response
Hide Response
Headers
Response Body
{"story_id":563,"updated_at":"2014-04-08T12:00:00Z","id":108,"kind":"comment","text":"I think you overestimate their chances!","person_id":102,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
PUT
/projects/{project_id}/stories/{story_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=563

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"updated comment text"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments/108"

View Response
Hide Response
Headers
Response Body
{"story_id":563,"updated_at":"2014-04-08T12:00:05Z","id":108,"kind":"comment","text":"updated comment text","person_id":102,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
text
string in the request body.
 —  The updated text for the comment
 
ENDPOINT

/projects/{project_id}/epics/{epic_id}/comments

Index of comments on an individual epic.

GET
/projects/{project_id}/epics/{epic_id}/comments

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=4

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments"

Hide Response
Headers
Response Body
[{"updated_at":"2014-04-08T12:00:00Z","id":109,"kind":"comment","text":"Should we send a probe to Dantooine?","person_id":103,"epic_id":4,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
POST
/projects/{project_id}/epics/{epic_id}/comments

Note that to include file_attachments or google_attachments in a new comment, they must be identified using complete nested resources (JSON hashes, like the one in the response from performing an upload to /projects/{project_id}/uploads) rather than solely by ID. When attaching an uploaded file, the client should include the entire file_attachment resource hash that was received from the server in response to uploading the file—this includes the file_attachment resource's id attribute. When attaching a "file" from Google Apps, the complete google_attachment resource hash selected from the list in the server's response from the /google_attachments endpoint must be included. google_attachment resources received from /google_attachments do not contain an id, and the client should not attempt to insert/create one. Each use of a google_attachment resource in a comment is assigned a unique ID during comment creation, which can be returned to the client in response to this request.

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=4

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"This is my comment"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments"

View Response
Hide Response
Headers
Response Body
{"updated_at":"2014-04-08T12:00:00Z","id":300,"kind":"comment","text":"This is my comment","person_id":103,"epic_id":4,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
google_attachments
List[google_attachment] in the request body.
 —  This parameter allows creation of new google_attachments implicitly as part of the basic request. See the 'google_attachment_ids' attribute of the comment resource. The nested google_attachments must not contain an id.
 
commit_type
string[255] in the request body.
 —  String identifying the type of remote source control system if Pivotal Tracker can determine it. Present only on comments that were created by a POST to the source commits API endpoint.
 
file_attachments
List[file_attachment] in the request body.
 —  This parameter allows file_attachments to be selected by content as part of the basic request. See the 'file_attachment_ids' attribute of the comment resource. The file_attachments' ids must be included.
 
text
string[20000] in the request body.
 —  Content of the comment.
 
commit_identifier
string[255] in the request body.
 —  Commit Id on the remote source control system for the comment. Present only on comments that were created by a POST to the source commits API endpoint.
 
person_id
int in the request body.
 —  The id of the comment creator.
 
ENDPOINT

/projects/{project_id}/epics/{epic_id}/comments/{comment_id}

Operations on an individual comment.

DELETE
/projects/{project_id}/epics/{epic_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=4

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/109"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
GET
/projects/{project_id}/epics/{epic_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=4

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/109"

Hide Response
Headers
Response Body
{"updated_at":"2014-04-08T12:00:00Z","id":109,"kind":"comment","text":"Should we send a probe to Dantooine?","person_id":103,"epic_id":4,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
PUT
/projects/{project_id}/epics/{epic_id}/comments/{comment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=4

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"text":"updated comment text"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/109"

Hide Response
Headers
Response Body
{"updated_at":"2014-04-08T12:00:05Z","id":109,"kind":"comment","text":"updated comment text","person_id":103,"epic_id":4,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the comment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
text
string in the request body.
 —  The updated text for the comment
 

Attachments

ENDPOINT

/projects/{project_id}/stories/{story_id}/comments/{comment_id}/file_attachments/{file_attachment_id}

Operations on an individual file attachment.

DELETE
/projects/{project_id}/stories/{story_id}/comments/{comment_id}/file_attachments/{file_attachment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

export COMMENT_ID=111

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments/$COMMENT_ID/file_attachments/21"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
file_attachment_id
int in the request path.
required  —  The ID of the file_attachment.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/comments/{comment_id}/google_attachments/{google_attachment_id}

Operations on an individual google attachment.

DELETE
/projects/{project_id}/stories/{story_id}/comments/{comment_id}/google_attachments/{google_attachment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

export COMMENT_ID=111

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/comments/$COMMENT_ID/google_attachments/50"

View Response
Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
google_attachment_id
int in the request path.
required  —  The ID of the google_attachment.
 
ENDPOINT

/projects/{project_id}/epics/{epic_id}/comments/{comment_id}/file_attachments/{file_attachment_id}

Operations on an individual file attachment.

DELETE
/projects/{project_id}/epics/{epic_id}/comments/{comment_id}/file_attachments/{file_attachment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=5

export COMMENT_ID=110

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/$COMMENT_ID/file_attachments/22"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
file_attachment_id
int in the request path.
required  —  The ID of the file_attachment.
 
ENDPOINT

/projects/{project_id}/epics/{epic_id}/comments/{comment_id}/google_attachments/{google_attachment_id}

Operations on an individual google attachment.

DELETE
/projects/{project_id}/epics/{epic_id}/comments/{comment_id}/google_attachments/{google_attachment_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export EPIC_ID=5

export COMMENT_ID=110

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/$COMMENT_ID/google_attachments/51"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
comment_id
int in the request path.
required  —  The ID of the comment.
 
google_attachment_id
int in the request path.
required  —  The ID of the google_attachment.
 
ENDPOINT

/projects/{project_id}/uploads

Upload content for a new file_attachment object.

POST
/projects/{project_id}/uploads

export TOKEN='your Pivotal Tracker API token'

export FILE_PATH='/home/vader/art-projects/new-imperial-logo-6.jpg'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -F file=@"$FILE_PATH" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/uploads"

View Response
Hide Response
Headers
Response Body
{"content_type":"image/jpeg","id":300,"big_url":"#","kind":"file_attachment","uploader_id":101,"uploaded":false,"thumbnail_url":"#","size":7683,"thumbnailable":true,"filename":"new-imperial-logo-6.jpg","download_url":"/file_attachments/300/download","created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the file_attachment resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
comment
object in the request body.
 —  The comment with which the file attachment will be associated.
 
file
binary form data in the request body.
required  —  The content of the file being uploaded. It is expected to be incorporated in the multipart data with a 'Content-Disposition' of 'form-data; name="file"; filename="imperial_banner.png"'. A Content-Type that describes the file being uploaded should be supplied if possible.
 
The HTTP body for this request should not be JSON-encoded. Instead, the request's Content-type should be multipart/form-data.
ENDPOINT

https://www.pivotaltracker.com/file_attachments/{file_attachment_id}/download

Download the original file content of an attachment.

GET
https://www.pivotaltracker.com/file_attachments/{file_attachment_id}/download

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/file_attachments/21/download"

Hide Response
Headers
Response Body
"[binary data goes here]"

PARAMETERS

file_attachment_id
int in the request path.
required  —  The ID of the file_attachment.
 
inline
boolean in the request query.
 —  Determines if server should include response headers that would cause a browser to show the attachment in a new tab or window (inline=true) or show a Save dialog box (inline=false). Default is false.
 
ENDPOINT

/google_attachments

Provides a list of all the Google resources currently available to the authenticated user as potential attachments.

GET
/google_attachments

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/google_attachments"

Hide Response
Headers
Response Body
[{"title":"Death Star Plans","google_kind":"document","kind":"google_attachment"}]
Successful responses to this request return an array containing zero or more instances of the google_attachment resource.
For a non-empty list to be returned, the user's login must be associated with a Google identity with access to one or more Google 'documents'.

Search

Saved Search

ENDPOINT

/projects/{project_id}/my/searches

Access the saved searches for the currently logged-in person.

GET
/projects/{project_id}/my/searches

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/my/searches"

Hide Response
Headers
Response Body
[{"name":"New Maintenance Issues","id":4,"kind":"saved_search","query":"label:\"mnt\" state:unscheduled","project_id":99},{"name":"Family","id":5,"kind":"saved_search","query":"luke, leia","project_id":99}]
Successful responses to this request return an array containing zero or more instances of the saved_search resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
POST
/projects/{project_id}/my/searches

Note that labels or strings with a space must be quoted, and multiple filters must be separated with a space, and everything must be URL-escaped. You can also search on multiple values within the same search term, for example, 'filter=id:1,2,3' will return resources with the id 1, 2 or 3.

Searches can be refined with all of the modifications listed here: How can a search be refined?

On endpoints that support filters, 'filter' can only be combined with project_id, date_format, limit and offset. All other parameters will result in an error.

label:"jedi stuff" keyword
keyword created_since:11/16/2009 has_attachment:

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"my saved search","query":"label:\"rebel bases\""}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/my/searches"

View Response
Hide Response
Headers
Response Body
{"name":"my saved search","id":300,"kind":"saved_search","query":"label:\"rebel bases\"","project_id":99}
Successful responses to this request return the saved_search resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
name
string[255] in the request body.
required  —  Name of the saved search.
 
query
string[1000] in the request body.
required  —  The search criteria string containing search terms and options which were specified for this saved search. How can a search be refined?
 
ENDPOINT

/projects/{project_id}/my/searches/{search_id}

Deleted a saved search for the currently logged-in person.

DELETE
/projects/{project_id}/my/searches/{search_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/my/searches/5"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
search_id
int in the request path.
required  —  The ID of the search.
 

Activity

ENDPOINT

/my/activity

Provides a list of all the activity performed by you.

GET
/my/activity

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/my/activity"

Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"before_id":557},"change_type":"update","name":"Garbage smashers on the detention level have malfunctioned","original_values":{"before_id":551},"id":561,"kind":"story","story_type":"bug"},{"new_values":{"after_id":564},"change_type":"update","name":"Evacuate, in our moment of triumph","original_values":{"after_id":557},"id":563,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Evacuate, in our moment of triumph","id":563,"kind":"story","url":"http://localhost/story/show/563","story_type":"feature"},{"name":"Garbage smashers on the detention level have malfunctioned","id":561,"kind":"story","url":"http://localhost/story/show/561","story_type":"bug"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_move_activity","highlight":"moved","guid":"99_61","project_version":61,"message":"Darth Vader moved 2 stories"},{"changes":[{"new_values":{"before_id":551},"change_type":"update","name":"Garbage smashers on the detention level have malfunctioned","original_values":{"before_id":557},"id":561,"kind":"story","story_type":"bug"},{"new_values":{"after_id":557},"change_type":"update","name":"Evacuate, in our moment of triumph","original_values":{"after_id":564},"id":563,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Evacuate, in our moment of triumph","id":563,"kind":"story","url":"http://localhost/story/show/563","story_type":"feature"},{"name":"Garbage smashers on the detention level have malfunctioned","id":561,"kind":"story","url":"http://localhost/story/show/561","story_type":"bug"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_move_activity","highlight":"moved","guid":"99_60","project_version":60,"message":"Darth Vader moved 2 stories"},{"changes":[{"new_values":{"story_id":555,"google_attachment_ids":[],"file_attachment_ids":[],"updated_at":"2014-04-08T12:00:05Z","id":111,"google_attachments":[],"text":"I want them alive!","person_id":101,"file_attachments":[],"created_at":"2014-04-08T12:00:05Z"},"change_type":"create","id":111,"kind":"comment"},{"new_values":{"follower_ids":[101]},"change_type":"update","name":"Bring me the passengers","original_values":{"follower_ids":[]},"id":555,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Bring me the passengers","id":555,"kind":"story","url":"http://localhost/story/show/555","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"comment_create_activity","highlight":"added comment:","guid":"99_59","project_version":59,"message":"Darth Vader added comment: \"I want them alive!\""},{"changes":[{"new_values":{"before_id":566,"current_state":"unstarted","after_id":552},"change_type":"update","name":"Bring me the passengers","original_values":{"before_id":551,"current_state":"unscheduled","after_id":557},"id":555,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Bring me the passengers","id":555,"kind":"story","url":"http://localhost/story/show/555","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_update_activity","highlight":"unstarted","guid":"99_53","project_version":53,"message":"Darth Vader unstarted this feature"},{"changes":[{"new_values":{"current_state":"rejected"},"change_type":"update","name":"All exhaust ports should be shielded","original_values":{"current_state":"delivered"},"id":558,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"All exhaust ports should be shielded","id":558,"kind":"story","url":"http://localhost/story/show/558","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_update_activity","highlight":"rejected","guid":"99_51","project_version":51,"message":"Darth Vader rejected this feature"},{"changes":[{"new_values":{"before_id":566,"current_state":"started","after_id":559},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"before_id":555,"current_state":"unscheduled","after_id":557},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_update_activity","highlight":"started","guid":"99_45","project_version":45,"message":"Darth Vader started this feature"},{"changes":[{"new_values":{"current_state":"accepted","accepted_at":"2014-04-08T12:00:05Z"},"change_type":"update","name":"Destroy Alderaan","original_values":{"current_state":"delivered","accepted_at":null},"id":559,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Destroy Alderaan","id":559,"kind":"story","url":"http://localhost/story/show/559","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_update_activity","highlight":"accepted","guid":"99_44","project_version":44,"message":"Darth Vader accepted this feature"},{"changes":[{"new_values":{"labels":["plans","rebel bases"],"label_ids":[2008,2007]},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"labels":["diplomatic relations"],"label_ids":[2014]},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_update_activity","highlight":"edited","guid":"99_40","project_version":40,"message":"Darth Vader edited this feature"},{"changes":[{"new_values":{"labels":["r&d"],"before_id":556,"name":"Prepare carbonite freezing chamber","current_state":"unscheduled","updated_at":"2014-04-08T12:00:05Z","id":557,"label_ids":[2013],"description":"Test first on Solo, we don't want the Emperor's prize damaged.","requested_by_id":101,"owner_ids":[],"follower_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:05Z","after_id":553},"change_type":"create","name":"Prepare carbonite freezing chamber","id":557,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Prepare carbonite freezing chamber","id":557,"kind":"story","url":"http://localhost/story/show/557","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"99_9","project_version":9,"message":"Darth Vader added this feature"},{"changes":[{"new_values":{"labels":["diplomatic relations"],"before_id":555,"name":"Interrogate Leia Organa","current_state":"unscheduled","updated_at":"2014-04-08T12:00:05Z","id":556,"label_ids":[2014],"description":"She is proving to be resistant to our mind probes","requested_by_id":101,"owner_ids":[101],"follower_ids":[],"story_type":"feature","owned_by_id":101,"project_id":99,"created_at":"2014-04-08T12:00:05Z","after_id":553},"change_type":"create","name":"Interrogate Leia Organa","id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"99_8","project_version":8,"message":"Darth Vader added this feature"},{"changes":[{"new_values":{"labels":[],"before_id":554,"name":"Bring me the passengers","current_state":"unscheduled","updated_at":"2014-04-08T12:00:05Z","id":555,"label_ids":[],"description":"ignore the droids","requested_by_id":101,"owner_ids":[],"follower_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:05Z","after_id":553},"change_type":"create","name":"Bring me the passengers","id":555,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Bring me the passengers","id":555,"kind":"story","url":"http://localhost/story/show/555","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"99_7","project_version":7,"message":"Darth Vader added this feature"},{"changes":[{"new_values":{"labels":[],"before_id":552,"name":"Identify Bothan spies","current_state":"unscheduled","updated_at":"2014-04-08T12:00:05Z","id":554,"label_ids":[],"description":"Infiltrate their spy network.","requested_by_id":101,"owner_ids":[106],"follower_ids":[],"story_type":"feature","owned_by_id":106,"project_id":99,"created_at":"2014-04-08T12:00:05Z","after_id":553},"change_type":"create","name":"Identify Bothan spies","id":554,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Identify Bothan spies","id":554,"kind":"story","url":"http://localhost/story/show/554","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"99_6","project_version":6,"message":"Darth Vader added this feature"},{"changes":[{"new_values":{"estimate":3,"labels":["r&d","rebel bases"],"before_id":552,"name":"Build protocol droid","current_state":"accepted","accepted_at":"2014-04-08T12:00:05Z","updated_at":"2014-04-08T12:00:05Z","id":553,"label_ids":[2013,2007],"description":"I want a friend","requested_by_id":101,"owner_ids":[101],"follower_ids":[],"story_type":"feature","owned_by_id":101,"project_id":99,"created_at":"2014-04-08T12:00:05Z"},"change_type":"create","name":"Build protocol droid","id":553,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Build protocol droid","id":553,"kind":"story","url":"http://localhost/story/show/553","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"99_5","project_version":5,"message":"Darth Vader added this feature"},{"changes":[{"new_values":{"estimate":3,"labels":[],"name":"Midi-chlorians","current_state":"unstarted","updated_at":"2014-04-08T12:00:05Z","id":567,"label_ids":[],"description":"Without the midi-chlorians, life could not exist, and we would have no knowledge of the Force. They continually speak to us, telling us the will of the Force. When you learn to quiet your mind, you'll hear them speaking to you","requested_by_id":101,"owner_ids":[101],"follower_ids":[],"story_type":"feature","owned_by_id":101,"project_id":98,"created_at":"2014-04-08T12:00:05Z"},"change_type":"create","name":"Midi-chlorians","id":567,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Midi-chlorians","id":567,"kind":"story","url":"http://localhost/story/show/567","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Learn About the Force","id":98,"kind":"project"},"occurred_at":"2014-04-08T12:00:05Z","kind":"story_create_activity","highlight":"added","guid":"98_2","project_version":2,"message":"Darth Vader added this feature"}]
Successful responses to this request return an array containing zero or more instances of an activity-type resource. In particular, any mix of any of the following: comment_create_activity, comment_delete_activity, comment_update_activity, epic_create_activity, epic_delete_activity, epic_move_activity, epic_update_activity, follower_create_activity, follower_delete_activity, iteration_update_activity, label_create_activity, label_delete_activity, label_update_activity, project_membership_create_activity, project_membership_delete_activity, project_membership_update_activity, story_c2genericcommand_activity, story_create_activity, story_delete_activity, story_move_activity, story_move_from_project_activity, story_move_into_project_activity, story_move_into_project_and_prioritize_activity, story_update_activity, task_create_activity, task_delete_activity, task_update_activity. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

limit
int[pos] in the request query.
 —  The number of activity items you want returned.
 
offset
int[pos] in the request query.
 —  Index of the first activity item you want, starting from zero.
 
occurred_before
datetime in the request query.
 —  Activity will be returned only for operations that occurred before the time specified by this parameter.
 
occurred_after
datetime in the request query.
 —  Activity will be returned only for operations that occurred after the time specified by this parameter.
 
ENDPOINT

/projects/{project_id}/activity

Provides a list of all the activity performed on a project.

GET
/projects/{project_id}/activity

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/activity?limit=1"

Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"finish":1396958405000,"team_strength":0.9,"number":1,"length":2},"change_type":"update","original_values":{"finish":1396958400000,"team_strength":1.0,"number":1,"length":"default"},"number":1,"kind":"iteration_override"}],"primary_resources":[{"number":1,"kind":"iteration_override"}],"performed_by":{"name":"Wilhuff Tarkin","id":102,"kind":"person","initials":"WT"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:10Z","kind":"iteration_update_activity","highlight":"changed","guid":"99_62","project_version":62,"message":"Wilhuff Tarkin changed iteration 1's length from default to 2 weeks"}]
Successful responses to this request return an array containing zero or more instances of an activity-type resource. In particular, any mix of any of the following: comment_create_activity, comment_delete_activity, comment_update_activity, epic_create_activity, epic_delete_activity, epic_move_activity, epic_update_activity, follower_create_activity, follower_delete_activity, iteration_update_activity, label_create_activity, label_delete_activity, label_update_activity, project_membership_create_activity, project_membership_delete_activity, project_membership_update_activity, story_c2genericcommand_activity, story_create_activity, story_delete_activity, story_move_activity, story_move_from_project_activity, story_move_into_project_activity, story_move_into_project_and_prioritize_activity, story_update_activity, task_create_activity, task_delete_activity, task_update_activity. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
limit
int[pos] in the request query.
 —  The number of activity items you want returned.
 
offset
int[pos] in the request query.
 —  Index of the first activity item you want, starting from zero.
 
occurred_before
datetime in the request query.
 —  Activity will be returned only for operations that occurred before the time specified by this parameter.
 
occurred_after
datetime in the request query.
 —  Activity will be returned only for operations that occurred after the time specified by this parameter.
 
since_version
int in the request query.
 —  Activity will be returned only for operations that occurred after the specified version.
 
ENDPOINT

/projects/{project_id}/stories/{story_id}/activity

Provides a list of all the activity performed on the story.

GET
/projects/{project_id}/stories/{story_id}/activity

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=556

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/activity"

View Response
Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"before_id":566,"current_state":"started","after_id":559},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"before_id":555,"current_state":"unscheduled","after_id":557},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_update_activity","highlight":"started","guid":"99_45","project_version":45,"message":"Darth Vader started this feature"},{"changes":[{"new_values":{"labels":["plans","rebel bases"],"label_ids":[2008,2007]},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"labels":["diplomatic relations"],"label_ids":[2014]},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_update_activity","highlight":"edited","guid":"99_40","project_version":40,"message":"Darth Vader edited this feature"},{"changes":[{"new_values":{"estimate":2},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"estimate":null},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Emperor Palpatine","id":100,"kind":"person","initials":"EP"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_update_activity","highlight":"estimated","guid":"99_23","project_version":23,"message":"Emperor Palpatine estimated this feature as 2 points"},{"changes":[{"new_values":{"labels":["diplomatic relations"],"before_id":555,"name":"Interrogate Leia Organa","current_state":"unscheduled","updated_at":"2014-04-08T12:00:00Z","id":556,"label_ids":[2014],"description":"She is proving to be resistant to our mind probes","requested_by_id":101,"owner_ids":[101],"follower_ids":[],"story_type":"feature","owned_by_id":101,"project_id":99,"created_at":"2014-04-08T12:00:00Z","after_id":553},"change_type":"create","name":"Interrogate Leia Organa","id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_create_activity","highlight":"added","guid":"99_8","project_version":8,"message":"Darth Vader added this feature"}]

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=556

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/activity?limit=2&offset=1"

View Response
Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"labels":["plans","rebel bases"],"label_ids":[2008,2007]},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"labels":["diplomatic relations"],"label_ids":[2014]},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Darth Vader","id":101,"kind":"person","initials":"DV"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_update_activity","highlight":"edited","guid":"99_40","project_version":40,"message":"Darth Vader edited this feature"},{"changes":[{"new_values":{"estimate":2},"change_type":"update","name":"Interrogate Leia Organa","original_values":{"estimate":null},"id":556,"kind":"story","story_type":"feature"}],"primary_resources":[{"name":"Interrogate Leia Organa","id":556,"kind":"story","url":"http://localhost/story/show/556","story_type":"feature"}],"performed_by":{"name":"Emperor Palpatine","id":100,"kind":"person","initials":"EP"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"story_update_activity","highlight":"estimated","guid":"99_23","project_version":23,"message":"Emperor Palpatine estimated this feature as 2 points"}]
Successful responses to this request return an array containing zero or more instances of an activity-type resource. In particular, any mix of any of the following: comment_create_activity, comment_delete_activity, comment_update_activity, epic_create_activity, epic_delete_activity, epic_move_activity, epic_update_activity, follower_create_activity, follower_delete_activity, iteration_update_activity, label_create_activity, label_delete_activity, label_update_activity, project_membership_create_activity, project_membership_delete_activity, project_membership_update_activity, story_c2genericcommand_activity, story_create_activity, story_delete_activity, story_move_activity, story_move_from_project_activity, story_move_into_project_activity, story_move_into_project_and_prioritize_activity, story_update_activity, task_create_activity, task_delete_activity, task_update_activity. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_id
int in the request path.
required  —  The ID of the story.
 
limit
int[pos] in the request query.
 —  The number of activity items you want returned.
 
offset
int[pos] in the request query.
 —  Index of the first activity item you want, starting from zero.
 
occurred_before
datetime in the request query.
 —  Activity will be returned only for operations that occurred before the time specified by this parameter.
 
occurred_after
datetime in the request query.
 —  Activity will be returned only for operations that occurred after the time specified by this parameter.
 
since_version
int in the request query.
 —  Activity will be returned only for operations that occurred after the specified version.
 
ENDPOINT

/projects/{project_id}/epics/{epic_id}/activity

Provides a list of all the activity performed on the epic.

GET
/projects/{project_id}/epics/{epic_id}/activity

export PROJECT_ID=99

export EPIC_ID=4

curl -X GET "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/activity"

Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"google_attachment_ids":[],"file_attachment_ids":[],"updated_at":"2014-04-08T12:00:00Z","id":109,"google_attachments":[],"text":"Should we send a probe to Dantooine?","person_id":103,"epic_id":4,"file_attachments":[],"created_at":"2014-04-08T12:00:00Z"},"change_type":"create","id":109,"kind":"comment"},{"new_values":{"follower_ids":[103]},"change_type":"update","name":"Rebel Home Worlds","original_values":{"follower_ids":[]},"id":4,"kind":"epic"}],"primary_resources":[{"name":"Rebel Home Worlds","id":4,"kind":"epic","url":"http://localhost/epic/show/4"}],"performed_by":{"name":"Moradmin Bast","id":103,"kind":"person","initials":"MB"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"comment_create_activity","highlight":"added comment:","guid":"99_57","project_version":57,"message":"Moradmin Bast added comment: \"Should we send a probe to Dantooine?\""},{"changes":[{"new_values":{"past_done_story_estimates":3,"label_id":2007,"label":"rebel bases","name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:00Z","past_done_stories_no_point_count":0,"past_done_stories_count":1,"id":4,"description":"Identify the systems and eliminate the rebel scum.","follower_ids":[],"project_id":99,"created_at":"2014-04-08T12:00:00Z"},"change_type":"create","name":"Rebel Home Worlds","id":4,"kind":"epic"}],"primary_resources":[{"name":"Rebel Home Worlds","id":4,"kind":"epic","url":"http://localhost/epic/show/4"}],"performed_by":{"name":"Wilhuff Tarkin","id":102,"kind":"person","initials":"WT"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"epic_create_activity","highlight":"added","guid":"99_19","project_version":19,"message":"Wilhuff Tarkin added this epic"}]

export PROJECT_ID=99

export EPIC_ID=4

curl -X GET "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/activity?limit=42&offset=1"

Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"past_done_story_estimates":3,"label_id":2007,"label":"rebel bases","name":"Rebel Home Worlds","updated_at":"2014-04-08T12:00:00Z","past_done_stories_no_point_count":0,"past_done_stories_count":1,"id":4,"description":"Identify the systems and eliminate the rebel scum.","follower_ids":[],"project_id":99,"created_at":"2014-04-08T12:00:00Z"},"change_type":"create","name":"Rebel Home Worlds","id":4,"kind":"epic"}],"primary_resources":[{"name":"Rebel Home Worlds","id":4,"kind":"epic","url":"http://localhost/epic/show/4"}],"performed_by":{"name":"Wilhuff Tarkin","id":102,"kind":"person","initials":"WT"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"epic_create_activity","highlight":"added","guid":"99_19","project_version":19,"message":"Wilhuff Tarkin added this epic"}]

export PROJECT_ID=99

export EPIC_ID=4

curl -X GET "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/activity?since_version=55"

Hide Response
Headers
Response Body
[{"changes":[{"new_values":{"google_attachment_ids":[],"file_attachment_ids":[],"updated_at":"2014-04-08T12:00:00Z","id":109,"google_attachments":[],"text":"Should we send a probe to Dantooine?","person_id":103,"epic_id":4,"file_attachments":[],"created_at":"2014-04-08T12:00:00Z"},"change_type":"create","id":109,"kind":"comment"},{"new_values":{"follower_ids":[103]},"change_type":"update","name":"Rebel Home Worlds","original_values":{"follower_ids":[]},"id":4,"kind":"epic"}],"primary_resources":[{"name":"Rebel Home Worlds","id":4,"kind":"epic","url":"http://localhost/epic/show/4"}],"performed_by":{"name":"Moradmin Bast","id":103,"kind":"person","initials":"MB"},"project":{"name":"Death Star","id":99,"kind":"project"},"occurred_at":"2014-04-08T12:00:00Z","kind":"comment_create_activity","highlight":"added comment:","guid":"99_57","project_version":57,"message":"Moradmin Bast added comment: \"Should we send a probe to Dantooine?\""}]
Successful responses to this request return an array containing zero or more instances of an activity-type resource. In particular, any mix of any of the following: comment_create_activity, comment_delete_activity, comment_update_activity, epic_create_activity, epic_delete_activity, epic_move_activity, epic_update_activity, follower_create_activity, follower_delete_activity, iteration_update_activity, label_create_activity, label_delete_activity, label_update_activity, project_membership_create_activity, project_membership_delete_activity, project_membership_update_activity, story_c2genericcommand_activity, story_create_activity, story_delete_activity, story_move_activity, story_move_from_project_activity, story_move_into_project_activity, story_move_into_project_and_prioritize_activity, story_update_activity, task_create_activity, task_delete_activity, task_update_activity. The response from this request is paginated, see Paginating List Responses.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
epic_id
int in the request path.
required  —  The ID of the epic.
 
limit
int[pos] in the request query.
 —  The number of activity items you want returned.
 
offset
int[pos] in the request query.
 —  Index of the first activity item you want, starting from zero.
 
occurred_before
datetime in the request query.
 —  Activity will be returned only for operations that occurred before the time specified by this parameter.
 
occurred_after
datetime in the request query.
 —  Activity will be returned only for operations that occurred after the time specified by this parameter.
 
since_version
int in the request query.
 —  Activity will be returned only for operations that occurred after the specified version.
 

Source Commits

ENDPOINT

/source_commits

Provides integration with commits in a Source Control system.

The Tracker API supports integration with post-commit hooks of Source Control Management (SCM) systems such as Subversion, Git, etc. When a commit is made to the SCM, a trigger can call the Tracker API to add a story comment with the commit ID, author and message. It can also optionally change story state.

To associate an SCM commit with a specific Tracker story, you must include a special syntax in the commit message to indicate one or more story IDs and (optionally) a state change for the story. Your commit message should have square brackets containing a hash mark followed by the story ID. If a story was not already started (it was in the "not started" state), a commit message will automatically start it.

To automatically finish a story by using a commit message, include "fixed", "completed" or "finished" in the square brackets in addition to the story ID. You may also use different cases or forms of these verbs, such as "Fix" or "FIXES", and they may appear before or after the story ID. Note: For features, this will put the story in the 'finished' state. For chores, it will put the story in the 'accepted' state.

In some environments, code that is committed is automatically deployed. For this situation, include "delivers" and feature stories will be put in the 'delivered' state.

POST
/source_commits

export TOKEN='your Pivotal Tracker API token'

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"source_commit":{"author":"Darth Vader","commit_id":"abc123","url":"http://example.com/abc123","message":"[#555] some commit"}}' "https://www.pivotaltracker.com/services/v5/source_commits"

View Response
Hide Response
Headers
Response Body
[{"estimate":2,"labels":[],"name":"Bring me the passengers","current_state":"started","updated_at":"2014-04-08T12:00:05Z","id":555,"kind":"story","description":"ignore the droids","url":"http://localhost/story/show/555","requested_by_id":101,"owner_ids":[],"story_type":"feature","project_id":99,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return the story resource.

PARAMETERS

source_commit
source_commit in the request body.
 —  The source commit object
 

Exports

ENDPOINT

/projects/{project_id}/export

Export the specified project to CSV

POST
/projects/{project_id}/export

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
story_ids
List[int] in the request body.
required  —  A list of stories to fetch
 
Note that the response content type for this request is CSV and not JSON.
ENDPOINT

/stories/export

Export the specified stories (from any number of projects) to CSV

POST
/stories/export

PARAMETERS

ids
List[int] in the request body.
required  —  A list of stories to fetch
 
Note that the response content type for this request is CSV and not JSON.

Project Integrations

ENDPOINT

/projects/{project_id}/integrations

Operations on a project's integrations.

GET
/projects/{project_id}/integrations

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations"

Hide Response
Headers
Response Body
[{"name":"Sounder Flats Computer Complex","is_other":true,"import_api_url":"http://localhost:3000/starwars.xml","active":true,"updated_at":"2014-04-08T12:00:00Z","story_name":"item","id":30,"base_url":"http://localhost:3000","kind":"other_integration","can_import":true,"project_id":99,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of an integration-type resource. In particular, any mix of any of the following: bugzilla_integration, get_satisfaction_integration, jira_integration, lighthouse_integration, other_integration, zendesk_integration.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
POST
/projects/{project_id}/integrations

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"something","active":false,"base_url":"http://some.th/ing","type":"other"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations"

View Response
Hide Response
Headers
Response Body
{"name":"something","is_other":true,"active":false,"updated_at":"2014-04-08T12:00:00Z","story_name":"item","id":200,"base_url":"http://some.th/ing","kind":"other_integration","can_import":false,"project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return an integration-type resource. In particular, any one of the following: bugzilla_integration, get_satisfaction_integration, jira_integration, lighthouse_integration, other_integration, zendesk_integration.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
zendesk_user_password
string in the request body.
 —  The password of the Zendesk user which you want to use for integration purposes.
 
product
string in the request body.
 —  The name of your Bugzilla Product. Use this in conjunction with the component to narrow the bugs to be imported.
 
update_comments
boolean in the request body.
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
view_id
string in the request body.
 —  Only show tickets from the specified Zendesk view.
 
company
string in the request body.
 —  Can be found in the URL in your company's community on Satisfaction. For example - http://www.getsatisfaction.com/yourcompany.
 
import_api_url
string in the request body.
 —  The URL to import stories from.
 
update_state
boolean in the request body.
 —  Adds a state change comment to the linked ticket or bug.
 
name
string[40] in the request body.
 —  The name given to the particular external integration in the Project Settings pages.
 
active
boolean in the request body.
 —  True if the integration is currently enabled for use.
 
api_password
string in the request body.
 —  The password to use to access the external API.
 
component
string in the request body.
 —  The name of your Bugzilla Component. Use this in conjunction with product to narrow the bugs to be imported.
 
base_url
string in the request body.
 —  url used for outgoing web links in stories imported via this integration.
 
zendesk_user_email
string in the request body.
 —  The email of the Zendesk user which you want to use for integration purposes.
 
filter_id
string in the request body.
 —  The ID of the saved JIRA filter to use to load stories.
 
external_project_id
int in the request body.
 —  The unique ID of your Lighthouse project, which can be found in a project URL, for example http://yourcompany.lighthouseapp.com/projects/1234-project-name/overview.
 
basic_auth_username
string in the request body.
 —  The username to use when importing stories.
 
basic_auth_password
string in the request body.
 —  The password to use when importing stories.
 
comments_private
boolean in the request body.
 —  If enabled, comments made by Tracker on the external bug will be marked as private.
 
api_username
string in the request body.
 —  The username to use to access the external API.
 
statuses_to_exclude
string in the request body.
 —  A comma separated list of status names that should be excluded from the imported bugs. If left blank, all bugs will be imported.
 
account
string in the request body.
 —  Your Lighthouse account name, and can be found in the first part of your Lighthouse URL, for example http://yourcompany.lighthouseapp.com.
 
external_api_token
string in the request body.
 —  Your Lighthouse API token.
 
type
enumerated string in the request body.
required  —  The name of the type of external integration that this resource represents.
Valid enumeration values: bugzilla, get_satisfaction, jira, lighthouse, other, zendesk
 
bin_id
int in the request body.
 —  Only import tickets from the specified ticket bin.
 
ENDPOINT

/projects/{project_id}/integrations/{integration_id}

Operations on a single project integration.

GET
/projects/{project_id}/integrations/{integration_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations/30"

Hide Response
Headers
Response Body
{"name":"Sounder Flats Computer Complex","is_other":true,"import_api_url":"http://localhost:3000/starwars.xml","active":true,"updated_at":"2014-04-08T12:00:00Z","story_name":"item","id":30,"base_url":"http://localhost:3000","kind":"other_integration","can_import":true,"project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return an integration-type resource. In particular, any one of the following: bugzilla_integration, get_satisfaction_integration, jira_integration, lighthouse_integration, other_integration, zendesk_integration.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
integration_id
int in the request path.
required  —  The ID of the integration.
 
PUT
/projects/{project_id}/integrations/{integration_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"name":"something","base_url":"http://some.th/ing"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations/30"

Hide Response
Headers
Response Body
{"name":"something","is_other":true,"import_api_url":"http://localhost:3000/starwars.xml","active":true,"updated_at":"2014-04-08T12:00:05Z","story_name":"item","id":30,"base_url":"http://some.th/ing","kind":"other_integration","can_import":true,"project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return an integration-type resource. In particular, any one of the following: bugzilla_integration, get_satisfaction_integration, jira_integration, lighthouse_integration, other_integration, zendesk_integration.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
integration_id
int in the request path.
required  —  The ID of the integration.
 
zendesk_user_password
string in the request body.
 —  The password of the Zendesk user which you want to use for integration purposes.
 
product
string in the request body.
 —  The name of your Bugzilla Product. Use this in conjunction with the component to narrow the bugs to be imported.
 
update_comments
boolean in the request body.
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
view_id
string in the request body.
 —  Only show tickets from the specified Zendesk view.
 
company
string in the request body.
 —  Can be found in the URL in your company's community on Satisfaction. For example - http://www.getsatisfaction.com/yourcompany.
 
import_api_url
string in the request body.
 —  The URL to import stories from.
 
update_state
boolean in the request body.
 —  Adds a state change comment to the linked ticket or bug.
 
name
string[40] in the request body.
 —  The name given to the particular external integration in the Project Settings pages.
 
active
boolean in the request body.
 —  True if the integration is currently enabled for use.
 
api_password
string in the request body.
 —  The password to use to access the external API.
 
component
string in the request body.
 —  The name of your Bugzilla Component. Use this in conjunction with product to narrow the bugs to be imported.
 
base_url
string in the request body.
 —  url used for outgoing web links in stories imported via this integration.
 
zendesk_user_email
string in the request body.
 —  The email of the Zendesk user which you want to use for integration purposes.
 
filter_id
string in the request body.
 —  The ID of the saved JIRA filter to use to load stories.
 
external_project_id
int in the request body.
 —  The unique ID of your Lighthouse project, which can be found in a project URL, for example http://yourcompany.lighthouseapp.com/projects/1234-project-name/overview.
 
basic_auth_username
string in the request body.
 —  The username to use when importing stories.
 
basic_auth_password
string in the request body.
 —  The password to use when importing stories.
 
comments_private
boolean in the request body.
 —  If enabled, comments made by Tracker on the external bug will be marked as private.
 
api_username
string in the request body.
 —  The username to use to access the external API.
 
statuses_to_exclude
string in the request body.
 —  A comma separated list of status names that should be excluded from the imported bugs. If left blank, all bugs will be imported.
 
account
string in the request body.
 —  Your Lighthouse account name, and can be found in the first part of your Lighthouse URL, for example http://yourcompany.lighthouseapp.com.
 
external_api_token
string in the request body.
 —  Your Lighthouse API token.
 
bin_id
int in the request body.
 —  Only import tickets from the specified ticket bin.
 
DELETE
/projects/{project_id}/integrations/{integration_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations/200"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
integration_id
int in the request path.
required  —  The ID of the integration.
 
ENDPOINT

/projects/{project_id}/integrations/{integration_id}/stories

Fetch story information from the selected integration.

GET
/projects/{project_id}/integrations/{integration_id}/stories

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export INTEGRATION_ID=30

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations/$INTEGRATION_ID/stories"

Hide Response
Headers
Response Body
[{"estimate":0,"name":"Please let us go","external_id":"Bespin","kind":"external_story","external_requester":"Lando Calrissian","owner_ids":[101],"integration_id":30,"story_type":"feature","owned_by_id":101,"external_owner":"Darth Vader","created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of the external_story resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
integration_id
int in the request path.
required  —  The ID of the integration.
 
exclude_linked
boolean in the request query.
 —  When this parameter is present and true, response will not include external stories which already have matching Pivotal Tracker stories.
 
Automatically filters out all information from the selected integration that corresponds to an existing story in the project.

Project Webhooks

ENDPOINT

/projects/{project_id}/webhooks

Lets the user access the project's list of webhooks.

GET
/projects/{project_id}/webhooks

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks"

Hide Response
Headers
Response Body
[{"webhook_version":"v5","updated_at":"2014-04-08T12:00:00Z","id":27,"kind":"webhook","webhook_url":"http://localhost:3000/test_postbin","project_id":99,"created_at":"2014-04-08T12:00:00Z"}]
Successful responses to this request return an array containing zero or more instances of the webhook resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
POST
/projects/{project_id}/webhooks

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"webhook_version":"v5","webhook_url":"http://localhost:3000/test_postbin"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks"

View Response
Hide Response
Headers
Response Body
{"webhook_version":"v5","updated_at":"2014-04-08T12:00:00Z","id":100,"kind":"webhook","webhook_url":"http://localhost:3000/test_postbin","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the webhook resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
webhook_version
enumerated string in the request body.
 —  The version of the API your webhook will interact with.
Valid enumeration values: v3, v5
 
webhook_url
string in the request body.
 —  The location of the application listening for Tracker events.
 
ENDPOINT

/projects/{project_id}/webhooks/{webhook_id}

Lets the user access a single project webhook

GET
/projects/{project_id}/webhooks/{webhook_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks/27"

Hide Response
Headers
Response Body
{"webhook_version":"v5","updated_at":"2014-04-08T12:00:00Z","id":27,"kind":"webhook","webhook_url":"http://localhost:3000/test_postbin","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the webhook resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
webhook_id
int in the request path.
required  —  The ID of the webhook.
 
PUT
/projects/{project_id}/webhooks/{webhook_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"webhook_url":"http://localhost:3000/my_example_webhook"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks/27"

Hide Response
Headers
Response Body
{"webhook_version":"v5","updated_at":"2014-04-08T12:00:05Z","id":27,"kind":"webhook","webhook_url":"http://localhost:3000/my_example_webhook","project_id":99,"created_at":"2014-04-08T12:00:00Z"}
Successful responses to this request return the webhook resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
webhook_id
int in the request path.
required  —  The ID of the webhook.
 
webhook_version
enumerated string in the request body.
 —  The version of the API your webhook will interact with.
Valid enumeration values: v3, v5
 
webhook_url
string in the request body.
 —  The location of the application listening for Tracker events.
 
DELETE
/projects/{project_id}/webhooks/{webhook_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks/27"

Hide Response
Headers

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
webhook_id
int in the request path.
required  —  The ID of the webhook.
 

Workspaces

ENDPOINT

/my/workspaces

Provides a list of all of the workspaces owned by you.

GET
/my/workspaces

export TOKEN='your Pivotal Tracker API token'

curl -X GET -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/my/workspaces"

Hide Response
Headers
Response Body
[{"project_ids":[99],"name":"executor","id":32,"kind":"workspace","person_id":101}]
Successful responses to this request return an array containing zero or more instances of the workspace resource.
POST
/my/workspaces

export TOKEN='your Pivotal Tracker API token'

curl -X POST -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"project_ids":[99,98],"name":"A new workspace"}' "https://www.pivotaltracker.com/services/v5/my/workspaces"

View Response
Hide Response
Headers
Response Body
{"project_ids":[99,98],"name":"A new workspace","id":200,"kind":"workspace","person_id":101}
Successful responses to this request return the workspace resource.

PARAMETERS

project_ids
List[int] in the request body.
 —  Array of projects contained in the workspace.
 
name
string[255] in the request body.
 —  The name of the workspace.
 
ENDPOINT

/my/workspaces/{workspace_id}

Updates the specified workspace owned by you.

PUT
/my/workspaces/{workspace_id}

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" -d '{"project_ids":[99,98]}' "https://www.pivotaltracker.com/services/v5/my/workspaces/32"

Hide Response
Headers
Response Body
{"project_ids":[99,98],"name":"executor","id":32,"kind":"workspace","person_id":101}
Successful responses to this request return the workspace resource.

PARAMETERS

workspace_id
int in the request path.
required  —  The ID of the workspace.
 
project_ids
List[int] in the request query.
 —  The list of projects to associate with this workspace.
 
DELETE
/my/workspaces/{workspace_id}

export TOKEN='your Pivotal Tracker API token'

curl -X DELETE -H "X-TrackerToken: $TOKEN" -H "Content-Type: application/json" "https://www.pivotaltracker.com/services/v5/my/workspaces/32"

Hide Response
Headers

PARAMETERS

workspace_id
int in the request path.
required  —  The ID of the workspace.
 

Request Aggregator

ENDPOINT

/aggregator

The POST body included in an aggregator request is a JSON array of strings, each a relative URL (excludes server, includes query parameters) for a GET request. Response body is a JSON hash with keys equal to the relative URLs and values equal to the matching response bodies.

POST
/aggregator

Resources

resource

account

PROPERTIES

project_ids
List[int]
 —  IDs of the project(s) that are associated with the account. This field is read only. This field is excluded by default. In API responses, this attribute may be project_ids or projects.
 
name
string[100]
 —  The name of the account.
 
status
enumerated string
 —  This string gives the subscription status of the account that contains the project. In particular, conditions that can cause the project to be read-only will be included here. This field is read only.
Valid enumeration values: active, suspended, deleted, limited, delinquent
 
over_the_limit
boolean
 —  True if the account is currently over its subscription plan limits. This field is read only.
 
id
int
 —  Database id of the account. This field is read only.
 
plan
string
 —  The name of the account's current subscription plan. This field is read only.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
kind
string
 —  The type of this object: account. This field is read only.
 
days_left
int
 —  The number of days remaining in the account's Free Trial period, or 0 if it has expired. This field is read only.
 
created_at
datetime
 —  Creation time. This field is read only.
 
resource

account_membership

PROPERTIES

timekeeper
boolean
 —  True if the person is allowed to administer time entry by others on the account.
 
admin
boolean
 —  True if the person has administrative rights on the account.
 
project_creator
boolean
 —  True if the person is allowed to create new projects within the account.
 
id
int
 —  The id of the membership. This field is read only. This field is always returned.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
time_enterer
boolean
 —  True if the person is expected to enter time for work on projects in the account.
 
kind
string
 —  The type of this object: account_membership. This field is read only.
 
person_id
int
 —  The id of the user. This field is writable only on create. By default this will be included in responses as a nested structure, using the key person. In API responses, this attribute may be person_id or person.
 
account_id
int
 —  The id of the account. This field is writable only on create.
 
owner
boolean
 —  True if the person is the current Owner of the acount. The account Owner can be selected only through the Tracker web site and this parameter will be ignored if sent through the API. This field is read only.
 
created_at
datetime
 —  Creation time. This field is writable only on create.
 
resource

account_summary

PROPERTIES

name
string[100]
 —  The name of the account.
 
status
enumerated string
 —  This string gives the subscription status of the account that contains the project. In particular, conditions that can cause the project to be read-only will be included here. This field is read only.
Valid enumeration values: active, suspended, deleted, limited, delinquent
 
over_the_limit
boolean
 —  True if the account is currently over its subscription plan limits. This field is read only.
 
id
int
 —  Database id of the account. This field is read only.
 
kind
string
 —  The type of this object: account_summary. This field is read only.
 
days_left
int
 —  The number of days remaining in the account's Free Trial period, or 0 if it has expired. This field is read only.
 
resource

activity

PROPERTIES

changes
List[object]
 —  The set of changes. This field is read only.
 
primary_resources
List[object]
 —  The primary resource(s) affected by this command. This field is read only.
 
occurred_at
datetime
 —  Time of the activity. This field is read only.
 
kind
string
 —  The value of 'kind' will reflect the specific type of activity that an activity resource represents. The value will be a string that ends in '_activity' and which starts with a name based on the change which occurred. This field is read only.
 
highlight
string
 —  Boldface portion of the message. This field is read only.
 
guid
string
 —  Project id and version of the activity. This field is read only. This field is always returned.
 
performed_by_id
int
 —  id of the person who performed this change. This field is read only. By default this will be included in responses as a nested structure, using the key performed_by.
 
message
string
 —  Description of the activity. This field is read only.
 
project_version
int
 —  The version of the activity. This field is read only. This field is always returned.
 
project_id
int
 —  id of the project. This field is read only. By default this will be included in responses as a nested structure, using the key project.
 
resource

bugzilla_integration

PROPERTIES

update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked Bugzilla bug.
 
product
string
 —  The name of your Bugzilla Product. Use this in conjunction with the component to narrow the bugs to be imported.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
update_state
boolean
 —  Adds a state change comment to the Bugzilla bug.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
component
string
 —  The name of your Bugzilla Component. Use this in conjunction with product to narrow the bugs to be imported.
 
api_password
string
 —  The password to use to access Bugzilla. This field is write only.
 
kind
string
 —  The type of this object: bugzilla_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
comments_private
boolean
 —  If enabled, comments will be marked as private. Note: the user that is used for the integration must be a member of an 'insidergroup' for this to work.
 
statuses_to_exclude
string
 —  A comma separated list of status names that should be excluded from the imported bugs. If left blank, all bugs will be imported.
 
api_username
string
 —  The username to use to access Bugzilla.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

comment

PROPERTIES

story_id
int
 —  The id of the story to which the comment is attached (will be absent if comment attached to an epic. This field is read only.
 
google_attachment_ids
List[int]
 —  IDs of any google attachments associated with the comment. This field is writable only on create. This field is excluded by default. In API responses, this attribute may be google_attachment_ids or google_attachments.
 
commit_type
string[255]
 —  String identifying the type of remote source control system if Pivotal Tracker can determine it. Present only on comments that were created by a POST to the source commits API endpoint. This field is writable only on create.
 
file_attachment_ids
List[int]
 —  IDs of any file attachments associated with the comment. This field is writable only on create. This field is excluded by default. In API responses, this attribute may be file_attachment_ids or file_attachments.
 
id
int
 —  Database id of the comment. This field is read only. This field is always returned.
 
updated_at
datetime
 —  Updated time. (Comments are updated by removing one of their attachments.) This field is read only.
 
kind
string
 —  The type of this object: comment. This field is read only.
 
text
string[20000]
 —  Content of the comment. This field is writable only on create.
 
epic_id
int
 —  The id of the epic to which the comment is attached (will be absent if comment attached to a story. This field is read only.
 
person_id
int
 —  The id of the comment creator. This field is writable only on create. In API responses, this attribute may be person_id or person.
 
commit_identifier
string[255]
 —  Commit Id on the remote source control system for the comment. Present only on comments that were created by a POST to the source commits API endpoint. This field is writable only on create. (Note that this attribute does not indicate an association to another resource.)
 
created_at
datetime
 —  Creation time. This field is read only.
 
resource

counts_by_story_state

PROPERTIES

rejected
float
 —  The count for rejected stories in the epic.
 
accepted
float
 —  The count for accepted stories (in the Current iteration) in the epic.
 
delivered
float
 —  The count for delivered stories in the epic.
 
unstarted
float
 —  The count for unstarted stories in the epic.
 
kind
string
 —  The type of this object: counts_by_story_state. This field is read only.
 
unscheduled
float
 —  The count for unscheduled stories in the epic.
 
started
float
 —  The count for started stories in the epic.
 
finished
float
 —  The count for finished stories in the epic.
 
done
float
 —  The count for done stories (accepted stories in an iteration before the Current iteration) in the epic.
 
resource

epic

PROPERTIES

label_id
int
 —  id of the epic's label. By default this will be included in responses as a nested structure, using the key label. In API responses, this attribute may be label_id or label.
 
past_done_story_estimates
float
 —  total point values of the past_done stories. This field is read only. This field is excluded by default.
 
comment_ids
List[int]
 —  IDs of comments currently on the epic. This field is writable only on create. This field is excluded by default. In API responses, this attribute may be comment_ids or comments.
 
before_id
int
 —  id of the epic following the epic. This field is excluded by default.
 
name
string[5000]
required on create  —  Name of the epic. This field is required on create.
 
id
int
 —  Database id of the epic. This field is read only. This field is always returned.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
past_done_stories_count
int
 —  number of past_done stories. This field is read only. This field is excluded by default.
 
past_done_stories_no_point_count
int
 —  number of past_done stories without estimates. This field is read only. This field is excluded by default.
 
description
string[20000]
 —  In-depth explanation of the epic's goals, scope, etc.
 
kind
string
 —  The type of this object: epic. This field is read only.
 
url
string
 —  The url for this epic in Tracker. This field is read only.
 
follower_ids
List[int]
 —  IDs of people currently following the story. This field is excluded by default. In API responses, this attribute may be follower_ids or followers.
 
project_id
int
 —  id of the project.
 
created_at
datetime
 —  Creation time. This field is read only.
 
after_id
int
 —  id of the epic preceding the epic. This field is excluded by default.
 
resource

epics_search_result

PROPERTIES

total_hits_with_done
int
 —  Number of epics, including done, which matched the search criteria.
 
kind
string
 —  The type of this object: epics_search_result. This field is read only.
 
epics
List[epic]
 —  Array of epics which matched the search criteria.
 
total_hits
int
 —  Number of non-done epics which matched the search criteria.
 
resource

external_story

PROPERTIES

extra
object
 —  A hash containing arbitrary extra fields which are specific to the type of integration with which this story is associated.
 
estimate
float
 —  estimate of this external story.
 
name
string
 —  Name of this external story.
 
external_id
string
 —  Unique ID of the issue/ticket in the external system for this integration. (Note that this attribute does not indicate an association to another resource.)
 
state
int
 —  State of this external_story.
 
description
string[20000]
 —  In-depth explanation of the story requirements.
 
external_requester
string
 —  Identifier for the person who "requested" this story in the external system.
 
kind
string
 —  The type of this object: external_story. This field is read only.
 
requested_by_id
int
 —  id of the person who requested this story in Tracker. Only shows in the hash if the 'external_requester' matches the name of a member of the project. In API responses, this attribute may be requested_by_id or requested_by.
 
owner_ids
List[int]
 —  IDs of the current story owners. By default this will be included in responses as an array of nested structures, using the key owners. In API responses, this attribute may be owner_ids or owners.
 
integration_id
int
 —  ID of the Tracker external integration with which this external_story is associated. In API responses, this attribute may be integration_id or integration.
 
external_owner
string
 —  Identifier for the person who "owns" this story in the external system.
 
owned_by_id
int
 —  id of the person who owns this story in Tracker. Only shows in the hash if the 'external_owner' matches the name of a member of the project. In API responses, this attribute may be owned_by_id or owned_by.
 
story_type
string
 —  story_type of this external story.
 
created_at
datetime
 —  Creation time of this external_story.
 
resource

file_attachment

PROPERTIES

content_type
string[255]
 —  The MIME type of the attachment. This field is read only.
 
id
int
 —  Database id of the file_attachment. This field is read only. This field is always returned.
 
big_url
string
 —  URL to larger-size thumbnail version if attachment is an image. This field is read only.
 
kind
string
 —  The type of this object: file_attachment. This field is read only.
 
uploader_id
int
 —  The id of the person who uploaded the file. This field is read only. In API responses, this attribute may be uploader_id or uploader.
 
height
int
 —  If the attachment is thumbnailable the height of it in pixels. This field is read only.
 
uploaded
boolean
 —  Flag indicating whether the attachment has been moved to S3. This field is read only.
 
size
int
 —  The size of the attachment in bytes. This field is read only.
 
thumbnail_url
string
 —  URL to small-size thumbnail version if attachment is an image. This field is read only.
 
filename
string[255]
 —  The file's name. This field is read only.
 
thumbnailable
boolean
 —  Flag indicating whether Tracker knows how to make a thumbnail image from the attachment. This field is read only.
 
width
int
 —  If the attachment is thumbnailable the width of it in pixels. This field is read only.
 
created_at
datetime
 —  Creation time. This field is read only.
 
download_url
string
 —  The URL for the original attachment on S3. This field is read only.
 
resource

follower

PROPERTIES

name
string[100]
 —  The full name of the person.
 
id
int
 —  Database id of the person. This field is always returned.
 
kind
string
 —  The type of this object: follower. This field is read only.
 
username
string
 —  The username of the person.
 
email
string[255]
 —  The email address of the person. This field may be omitted for security reasons depending on the request from which it is being returned. For example, the content of a public project can be retrieved through the API without user authentication, but in this case the email is not included in person resources contained in the project's 'members' list.
 
initials
string[100]
 —  The initials of the person.
 
resource

following

PROPERTIES

story_id
int
 —  The id of the story. This field is writable only on create.
 
id
int
 —  The id of the following. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: following. This field is read only.
 
person_id
int
 —  The id of the follower. This field is writable only on create. By default this will be included in responses as a nested structure, using the key person.
 
epic_id
int
 —  The id of the epic. This field is writable only on create.
 
resource

get_satisfaction_integration

PROPERTIES

product
string
 —  Can be found in your company's Satisfaction URL, when you're looking at topics for a specific product. For example - http://www.getsatisfaction.com/yourcompany/products/yourproduct.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
company
string
 —  Can be found in the URL in your company's community on Satisfaction. For example - http://www.getsatisfaction.com/yourcompany.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: get_satisfaction_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

google_attachment

PROPERTIES

comment_id
int
 —  The id of the comment. This field is read only.
 
title
string[255]
 —  The google attachment's name. This field is writable only on create.
 
id
int
 —  Database id of the google_attachment. This field is read only. This field is always returned.
 
google_kind
string[255]
 —  The Google 'kind' string for this attachment. This field is writable only on create.
 
google_id
string[255]
 —  The link to the file on Google's servers. This field is writable only on create. (Note that this attribute does not indicate an association to another resource.)
 
alternate_link
string[255]
 —  An alternate link to the file on Google's servers. This field is writable only on create.
 
kind
string
 —  The type of this object: google_attachment. This field is read only.
 
person_id
int
 —  The id of the linked Google Drive user. This field is writable only on create. In API responses, this attribute may be person_id or person.
 
resource_id
string[255]
 —  Google's unique identifier for the file. This field is writable only on create. (Note that this attribute does not indicate an association to another resource.)
 
resource

integration

PROPERTIES

update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
product
string
 —  The name of your Bugzilla Product. Use this in conjunction with the component to narrow the bugs to be imported.
 
zendesk_user_password
string
 —  The password of the Zendesk user which you want to use for integration purposes. This field is write only.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
update_state
boolean
 —  Adds a state change comment to the linked ticket or bug.
 
import_api_url
string
 —  The URL to import stories from.
 
company
string
 —  Can be found in the URL in your company's community on Satisfaction. For example - http://www.getsatisfaction.com/yourcompany.
 
view_id
string
 —  Only show tickets from the specified Zendesk view. (Note that this attribute does not indicate an association to another resource.)
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
component
string
 —  The name of your Bugzilla Component. Use this in conjunction with product to narrow the bugs to be imported.
 
api_password
string
 —  The password to use to access the external API. This field is write only.
 
zendesk_user_email
string
 —  The email of the Zendesk user which you want to use for integration purposes.
 
kind
string
 —  The type of this object. One of the following strings: jira_integration, zendesk_integration, lighthouse_integration, other_integration, bugzilla_integration, get_satisfaction_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
comments_private
boolean
 —  If enabled, comments made by Tracker on the external bug will be marked as private.
 
basic_auth_password
string
 —  The password to use when importing stories. This field is write only.
 
basic_auth_username
string
 —  The username to use when importing stories.
 
external_project_id
int
 —  The unique ID of your Lighthouse project, which can be found in a project URL, for example http://yourcompany.lighthouseapp.com/projects/1234-project-name/overview. (Note that this attribute does not indicate an association to another resource.)
 
filter_id
string
 —  The ID of the saved JIRA filter to use to load stories. (Note that this attribute does not indicate an association to another resource.)
 
external_api_token
string
 —  Your Lighthouse API token. This field is write only.
 
account
string
 —  Your Lighthouse account name, and can be found in the first part of your Lighthouse URL, for example http://yourcompany.lighthouseapp.com.
 
statuses_to_exclude
string
 —  A comma separated list of status names that should be excluded from the imported bugs. If left blank, all bugs will be imported.
 
api_username
string
 —  The username to use to access the external API.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
bin_id
int
 —  Only import tickets from the specified ticket bin. (Note that this attribute does not indicate an association to another resource.)
 
type
enumerated string
required on create  —  The name of the type of external integration that this resource represents. This field is writable only on create. This field is required on create.
Valid enumeration values: bugzilla, get_satisfaction, jira, lighthouse, other, zendesk
 
resource

iteration

PROPERTIES

start
datetime
 —  Iteration start time. This field is read only.
 
finish
datetime
 —  Iteration finish time. This field is read only.
 
team_strength
float
 —  Iteration team strength, 1.0 is full-strength.
 
planned
boolean
 —  Included in iterations when their project has enable_planned_mode true. The value will be false for all iterations other than Current. For the Current iteration, it may be false (indicating that the iteration currently contains stories based on emergent iterations and the project's velocity) or true (indicating that the Current iteration is in "planned" mode and its content is determined by the stories that have been explicitly added and removed from it).
 
number
int
 —  Iteration number starting from 1 for the first iteration in the project. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: iteration. This field is read only.
 
length
int
 —  Iteration length in weeks.
 
story_ids
List[int]
 —  Array of stories contained in the iteration. This field is read only. By default this will be included in responses as an array of nested structures, using the key stories. In API responses, this attribute may be story_ids or stories.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

iteration_override

PROPERTIES

team_strength
float
 —  Iteration team strength, 1.0 is full-strength.
 
planned
boolean
 —  Included in iterations when their project has enable_planned_mode true. The value will be false for all iterations other than Current. For the Current iteration, it may be false (indicating that the iteration currently contains stories based on emergent iterations and the project's velocity) or true (indicating that the Current iteration is in "planned" mode and its content is determined by the stories that have been explicitly added and removed from it).
 
number
int
 —  Iteration number, starting from 1 for the first iteration in the project. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: iteration_override. This field is read only.
 
length
int
 —  Iteration length in weeks.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

jira_integration

PROPERTIES

update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked Jira ticket.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
update_state
boolean
 —  Adds a state change comment to the linked Jira ticket.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
api_password
string
 —  Password of the JIRA user. This field is write only.
 
kind
string
 —  The type of this object: jira_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
filter_id
string
 —  The ID of the saved JIRA filter to use to load stories. (Note that this attribute does not indicate an association to another resource.)
 
api_username
string
 —  The username of a JIRA user that has read/write access to your JIRA instance, via the JIRA API.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

label

PROPERTIES

counts
story_counts
 —  Summary of numbers of stories and points contained in the epic. This field is read only. This field is excluded by default.
 
name
string[255]
required  —  The label's name.
 
id
int
 —  Database id of the label. This field is read only. This field is always returned.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
kind
string
 —  The type of this object: label. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
created_at
datetime
 —  Creation time. This field is read only.
 
resource

lighthouse_integration

PROPERTIES

update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked Lighthouse ticket.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
update_state
boolean
 —  Adds a state change comment to the linked Lighthouse ticket.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: lighthouse_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
external_project_id
int
 —  The unique ID of your Lighthouse project, which can be found in a project URL, for example http://yourcompany.lighthouseapp.com/projects/1234-project-name/overview. (Note that this attribute does not indicate an association to another resource.)
 
external_api_token
string
required on create  —  Your Lighthouse API token. This field is write only. This field is required on create.
 
account
string
 —  Your Lighthouse account name, and can be found in the first part of your Lighthouse URL, for example http://yourcompany.lighthouseapp.com.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
bin_id
int
 —  Only import tickets from the specified ticket bin. (Note that this attribute does not indicate an association to another resource.)
 
resource

me

PROPERTIES

receives_in_app_notifications
boolean
 —  Returns wether or not user is currently receiving in app notifications. This field is read only.
 
time_zone
time_zone
 —  The authenticated user's time zone. In API responses, this attribute may be time_zone or time_zone.
 
project_ids
List[int]
 —  IDs of the project(s) that the authenticated user is a member of. By default this will be included in responses as an array of nested structures, using the key projects. In API responses, this attribute may be project_ids or projects.
 
name
string[100]
 —  Name of the authenticated user.
 
id
int
 —  Database id of the authenticated user. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: me. This field is read only.
 
username
string[40]
 —  Authenticated user's optional 'username' for login purposes.
 
api_token
string[32]
 —  A string that can be used as the API authentication token (X-TrackerToken) to authenticate future API requests as being on behalf of the current user.
 
has_google_identity
boolean
 —  True if the authenticated user's profile is associated with a Google OpenID or Google Apps identity. (Note that this attribute does not indicate an association to another resource.)
 
workspace_ids
List[int]
 —  IDs of the workspaces(s) that the authenticated user owns. This field is excluded by default. In API responses, this attribute may be workspace_ids or workspaces.
 
initials
string[100]
 —  Authenticated user's initials.
 
email
string[255]
 —  Authenticated user's email.
 
resource

membership_summary

PROPERTIES

role
enumerated string
 —  The relationship between the authenticated user making the request and the project.
Valid enumeration values: owner, member, viewer, inactive
 
last_viewed_at
datetime
 —  The last (approximate) time at which the authenticated user accessed the project.
 
id
int
 —  The id of the membership. This field is read only. This field is always returned.
 
project_name
string
 —  The name of the project.
 
kind
string
 —  The type of this object: membership_summary. This field is read only.
 
project_id
int
 —  The id of the project.
 
project_color
string
 —  The color of the project on the member's views.
 
resource

notification

PROPERTIES

story_id
int
 —  ID of the story this notification is about. This field is read only. By default this will be included in responses as a nested structure, using the key story. In API responses, this attribute may be story_id or story.
 
performer_id
int
 —  id of the person who triggered the notification. This field is read only. By default this will be included in responses as a nested structure, using the key performer. In API responses, this attribute may be performer_id or performer.
 
notification_type
enumerated string
 —  Resource or activity that generated the notification. This field is read only.
Valid enumeration values: story, epic, comment, comment_with_mention
 
id
int
 —  Database id of the notification. This field is read only.
 
updated_at
datetime
 —  Update time. This field is read only.
 
kind
string
 —  The type of this object: notification. This field is read only.
 
context
string
 —  Context of the notification. For example, if a comment was added, this will contain the comment text. This field is read only.
 
action
string
 —  Action against the resource that triggered notification. This field is read only.
 
message
string
 —  Message of the notification. This field is read only.
 
epic_id
int
 —  ID of the epic this notification is about. This field is read only. By default this will be included in responses as a nested structure, using the key epic. In API responses, this attribute may be epic_id or epic.
 
read_at
datetime
 —  Time notification was read.
 
project_id
int
 —  id of the project. This field is read only. By default this will be included in responses as a nested structure, using the key project.
 
created_at
datetime
 —  Creation time. This field is read only.
 
resource

other_integration

PROPERTIES

active
boolean
 —  True if the integration is currently enabled for use.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
import_api_url
string
 —  The URL to import stories from.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: other_integration. This field is read only.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
basic_auth_password
string
 —  The password to use when importing stories. This field is write only.
 
basic_auth_username
string
 —  The username to use when importing stories.
 
created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
resource

person

PROPERTIES

name
string[100]
required on create  —  The full name of the person. This field is required on create.
 
id
int
 —  Database id of the person. This field is read only. This field is always returned.
 
kind
string
 —  The type of this object: person. This field is read only.
 
username
string
 —  The username of the person.
 
email
string[255]
required on create  —  The email address of the person. This field may be omitted for security reasons depending on the request from which it is being returned. For example, the content of a public project can be retrieved through the API without user authentication, but in this case the email is not included in person resources contained in the project's 'members' list. This field is required on create.
 
initials
string[100]
 —  The initials of the person.
 
resource

project

PROPERTIES

iteration_length
int
 —  The number of weeks in an iteration.
 
point_scale_is_custom
boolean
 —  True if the value of the point_scale string represents a custom, user-defined point scale rather than one of the ones built into Pivotal Tracker. This is important because of restrictions on moving stories from projects using a custom point scale into one using a standard point scale. Note that the set of built-in point scales is not considered part of the definition of an API version. Clients should be capable of processing any point_scale string that adheres to the format described above, and rely on this flag (rather than any explicit list that the client contains) to determine whether the project's point_scale is custom or standard. This field is read only.
 
bugs_and_chores_are_estimatable
boolean
 —  When true, Tracker will allow estimates to be set on Bug- and Chore-type stories. This is strongly not recommended. Please see the FAQ for more information.
 
time_zone
time_zone
 —  The "native" time zone for the project, independent of the time zone(s) from which members of the project view or modify it.
 
start_time
datetime
 —  The computed start time of the project, based on the other project attributes and the stories contained in the project. If they are provided, the value of start_time will be based on week_start_day and/or start_date. However, if the project contains stories with accepted_at dates before the time that would otherwise be computed, the value returned in start_time will be adjusted accordingly. This field is read only.
 
enable_incoming_emails
boolean
 —  When true, the project will accept incoming email responses to Tracker notification emails and convert them to comments on the appropriate stories.
 
initial_velocity
int
 —  The number which should be used as the project's velocity when there are not enough recent iterations with Done stories for an actual velocity to be computed.
 
atom_enabled
boolean
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
epic_ids
List[int]
 —  IDs of epics currently in the project. This field is read only. This field is excluded by default. In API responses, this attribute may be epic_ids or epics.
 
name
string[50]
required on create  —  The name of the project. This field is required on create.
 
integration_ids
List[int]
 —  IDs of integrations currently configured for the project. Note that integration information must be retrieved by getting project information with integrations included as a nested resource; there is currently no independent RESTy endpoint for accessing integrations. This field is read only. This field is excluded by default. In API responses, this attribute may be integration_ids or integrations.
 
id
int
 —  Database id of the project. This field is read only. This field is always returned.
 
week_start_day
enumerated string
 —  The day in the week the project's iterations are to start on.
Valid enumeration values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
 
enable_planned_mode
boolean
 —  When true, Tracker suspends the emergent planning of iterations based on the project's velocity, and allows users to manually control the set of unstarted stories included in the Current iteration. See the FAQ for more information.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
description
string[140]
 —  A description of the project's content. Entered through the web UI on the Project Settings page.
 
label_ids
List[int]
 —  IDs of labels currently in the project. This field is read only. This field is excluded by default. In API responses, this attribute may be label_ids or labels.
 
kind
string
 —  The type of this object: project. This field is read only.
 
number_of_done_iterations_to_show
int
 —  There are areas within the Tracker UI and the API in which sets of stories automatically exclude the Done stories contained in older iterations. For example, in the web UI, the DONE panel doesn't necessarily show all Done stories by default, and provides a link to click to cause the full story set to be loaded/displayed. The value of this attribute is the maximum number of Done iterations that will be loaded/shown/included in these areas.
 
iteration_override_numbers
List[int]
 —  IDs of iteration overrides currently configured for the project. Note that iteration override information must be retrieved by getting project information with iteration overrides included as a nested resource; there is currently no independent RESTy endpoint for accessing iteration overrides, but there is one for iterations, which contains the same info plus additional dynamic fields related to emergent iteration calculation. This field is read only. This field is excluded by default. In API responses, this attribute may be iteration_override_numbers or iteration_override_numbers.
 
version
int
 —  A counter that is incremented each time something is changed within a project. The project version is used to track whether a client is 'up to date' with respect to the current content of the project on the server, and to identify what updates have to be made to the client's local cop