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

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

Hide Response
Headers
Response Body
{"username":"vader","receives_in_app_notifications":true,"email":"vader@deathstar.mil","initials":"DV","api_token":"VadersToken","name":"Darth Vader","time_zone":{"offset":"-08:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"projects":[{"project_id":98,"role":"owner","project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"membership_summary","id":108,"project_name":"Learn About the Force"},{"project_id":99,"role":"member","project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"membership_summary","id":101,"project_name":"Death Star"}],"kind":"me","id":101,"has_google_identity":false}
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
{"http_status":"200","last_notification_timestamp":1397563220000,"data":[{"created_at":"2014-04-15T12:00:15Z","notification_type":"story","action":"ownership","updated_at":"2014-04-15T12:00:20Z","story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Wilhuff Tarkin","kind":"person","id":102},"kind":"notification","id":17,"message":"Wilhuff Tarkin has made you an owner of this story:"},{"created_at":"2014-04-15T12:00:20Z","notification_type":"story","action":"rejection","updated_at":"2014-04-15T12:00:20Z","story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Darth Vader","kind":"person","id":101},"kind":"notification","id":13,"message":"Darth Vader rejected your story"},{"created_at":"2014-04-15T12:00:20Z","notification_type":"story","action":"ownership","updated_at":"2014-04-15T12:00:20Z","story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Wilhuff Tarkin","kind":"person","id":102},"kind":"notification","id":5,"message":"Wilhuff Tarkin has made you an owner of this story"},{"epic":{"name":"Rebel Home Worlds","kind":"epic","id":4},"created_at":"2014-04-15T12:00:05Z","read_at":"2014-04-15T12:00:10Z","notification_type":"comment","action":"create","updated_at":"2014-04-15T12:00:20Z","project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Darth Vader","kind":"person","id":101},"kind":"notification","id":16,"message":"Darth Vader added the comment: \"Should we send a probe to Dantooine?\""}]}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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/1396785600000"

Hide Response
Headers
Response Body
{"http_status":"200","data":[{"created_at":1397563205000,"notification_type":"story","action":"ownership","updated_at":1397563205000,"story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Wilhuff Tarkin","kind":"person","id":102},"kind":"notification","id":17,"message":"Wilhuff Tarkin has made you an owner of this story:"},{"created_at":1397563205000,"notification_type":"story","action":"rejection","updated_at":1397563205000,"story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Darth Vader","kind":"person","id":101},"kind":"notification","id":13,"message":"Darth Vader rejected your story"},{"created_at":1397563205000,"notification_type":"story","action":"ownership","updated_at":1397563205000,"story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Wilhuff Tarkin","kind":"person","id":102},"kind":"notification","id":5,"message":"Wilhuff Tarkin has made you an owner of this story"}]}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"read_at":"2014-04-15T12:00:00Z","story_id":1}' "https://www.pivotaltracker.com/services/v5/my/notifications/17"

Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","read_at":"2014-04-15T12:00:05Z","notification_type":"story","action":"ownership","updated_at":"2014-04-15T12:00:05Z","story":{"name":"All exhaust ports should be shielded","kind":"story","id":558},"project":{"name":"Death Star","kind":"project","id":99},"performer":{"name":"Wilhuff Tarkin","kind":"person","id":102},"kind":"notification","id":17,"message":"Wilhuff Tarkin has made you an owner of this story:"}
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
[{"version":2,"point_scale":"0,1,2,3","initial_velocity":10,"enable_following":true,"created_at":"2014-04-15T12:00:10Z","start_time":"2014-04-15T12:00:05Z","public":false,"enable_incoming_emails":true,"atom_enabled":true,"account_id":100,"week_start_day":"Monday","velocity_averaged_over":3,"updated_at":"2014-04-15T12:00:15Z","point_scale_is_custom":false,"name":"Learn About the Force","iteration_length":1,"bugs_and_chores_are_estimatable":false,"time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"kind":"project","id":98,"number_of_done_iterations_to_show":12,"enable_tasks":true,"current_iteration_number":1,"has_google_domain":false,"enable_planned_mode":false},{"version":62,"point_scale":"0,1,2,3","initial_velocity":10,"enable_following":true,"created_at":"2014-04-15T12:00:10Z","start_time":"2014-04-15T12:00:15Z","public":false,"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.","enable_incoming_emails":true,"atom_enabled":true,"account_id":100,"week_start_day":"Monday","velocity_averaged_over":3,"updated_at":"2014-04-15T12:00:15Z","point_scale_is_custom":false,"name":"Death Star","iteration_length":1,"bugs_and_chores_are_estimatable":false,"time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"kind":"project","id":99,"number_of_done_iterations_to_show":12,"enable_tasks":true,"current_iteration_number":15,"start_date":"2013-12-30","has_google_domain":false,"enable_planned_mode":false,"description":"Expeditionary Battle Planetoid"}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"Executioner"}' "https://www.pivotaltracker.com/services/v5/projects"

View Response
Hide Response
Headers
Response Body
{"version":1,"point_scale":"0,1,2,3","initial_velocity":10,"enable_following":true,"created_at":"2014-04-15T12:00:05Z","start_time":"2014-04-15T12:00:00Z","public":false,"enable_incoming_emails":true,"atom_enabled":false,"account_id":100,"week_start_day":"Monday","velocity_averaged_over":3,"updated_at":"2014-04-15T12:00:05Z","point_scale_is_custom":false,"name":"Executioner","iteration_length":1,"bugs_and_chores_are_estimatable":false,"time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"kind":"project","id":200,"number_of_done_iterations_to_show":12,"enable_tasks":true,"current_iteration_number":1,"has_google_domain":false,"enable_planned_mode":false}
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.
 
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.
 
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".
 
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.
 
account_id
int in the request body.
 —  The ID number for the account which contains the project.
 
atom_enabled
boolean in the request body.
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
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.
 
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.
 
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
 
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.
 
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.
 
iteration_length
int in the request body.
 —  The number of weeks in an iteration.
 
name
string[50] in the request body.
required  —  The name of the project.
 
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.
 
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.
 
enable_tasks
boolean in the request body.
 —  When true, Tracker allows individual tasks to be created and managed within each story in the project.
 
description
string[140] in the request body.
 —  A description of the project's content. Entered through the web UI on the Project Settings page.
 
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.
 
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.
 
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
{"version":62,"point_scale":"0,1,2,3","initial_velocity":10,"enable_following":true,"created_at":"2014-04-15T12:00:05Z","start_time":"2014-04-15T12:00:10Z","public":false,"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.","enable_incoming_emails":true,"atom_enabled":true,"account_id":100,"week_start_day":"Monday","velocity_averaged_over":3,"updated_at":"2014-04-15T12:00:10Z","point_scale_is_custom":false,"name":"Death Star","iteration_length":1,"bugs_and_chores_are_estimatable":false,"time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"kind":"project","id":99,"number_of_done_iterations_to_show":12,"enable_tasks":true,"current_iteration_number":15,"start_date":"2013-12-30","has_google_domain":false,"enable_planned_mode":false,"description":"Expeditionary Battle Planetoid"}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"totally a new project name"}' "https://www.pivotaltracker.com/services/v5/projects/99"

Hide Response
Headers
Response Body
{"version":64,"point_scale":"0,1,2,3","initial_velocity":10,"enable_following":true,"created_at":"2014-04-15T12:00:05Z","start_time":"2014-04-15T12:00:00Z","public":false,"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.","enable_incoming_emails":true,"atom_enabled":true,"account_id":100,"week_start_day":"Monday","velocity_averaged_over":3,"updated_at":"2014-04-15T12:00:10Z","point_scale_is_custom":false,"name":"totally a new project name","iteration_length":1,"bugs_and_chores_are_estimatable":false,"time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"kind":"project","id":99,"number_of_done_iterations_to_show":12,"enable_tasks":true,"current_iteration_number":15,"start_date":"2013-12-30","has_google_domain":false,"enable_planned_mode":false,"description":"Expeditionary Battle Planetoid"}
Successful responses to this request return the project resource.

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
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.
 
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".
 
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.
 
account_id
int in the request body.
 —  The ID number for the account which contains the project.
 
atom_enabled
boolean in the request body.
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
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.
 
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.
 
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
 
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.
 
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.
 
iteration_length
int in the request body.
 —  The number of weeks in an iteration.
 
name
string[50] in the request body.
 —  The name of the project.
 
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.
 
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.
 
enable_tasks
boolean in the request body.
 —  When true, Tracker allows individual tasks to be created and managed within each story in the project.
 
description
string[140] in the request body.
 —  A description of the project's content. Entered through the web UI on the Project Settings page.
 
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.
 
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.
 
DELETE
/projects/{project_id}

export TOKEN='your Pivotal Tracker API token'

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"project_id":99,"start":"2014-04-15T12:01:00Z","stories":[{"requested_by_id":102,"project_id":99,"external_id":"abc123","created_at":"2014-04-15T12:01:00Z","url":"http://localhost/story/show/562","owner_ids":[102,101],"estimate":3,"updated_at":"2014-04-15T12:01:00Z","current_state":"accepted","name":"Complete construction of the Expeditionary Battle Planetoid","labels":[{"project_id":99,"created_at":"2014-04-15T12:01:00Z","updated_at":"2014-04-15T12:01:00Z","name":"plans","kind":"label","id":2008}],"kind":"story","story_type":"feature","id":562,"integration_id":30,"accepted_at":"2014-04-15T12:00:05Z","owned_by_id":102,"description":"Palpatine was impressed with the PoC, make this one bigger"}],"team_strength":1,"finish":"2014-04-15T12:00:10Z","number":2,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:10Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:15Z","number":3,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:15Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:20Z","number":4,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:20Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:25Z","number":5,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:25Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:30Z","number":6,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:30Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:35Z","number":7,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:35Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:40Z","number":8,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:40Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:45Z","number":9,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:45Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:50Z","number":10,"kind":"iteration"},{"project_id":99,"start":"2014-04-15T12:00:50Z","stories":[],"team_strength":1,"finish":"2014-04-15T12:00:55Z","number":11,"kind":"iteration"}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"team_strength":0.7,"length":5}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/iteration_overrides/3"

Hide Response
Headers
Response Body
{"project_id":99,"team_strength":0.7,"number":3,"kind":"iteration_override","planned":false,"length":5}
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.
 
length
int in the request body.
 —  Iteration length in weeks.
 
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).
 

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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"project_id":99,"role":"member","person":{"username":"starkiller","email":"marek@sith.mil","initials":"GM","name":"Galen Marek","kind":"person","id":106},"wants_comment_notification_emails":true,"project_color":"ffffff","kind":"project_membership","id":16100,"will_receive_mention_notifications_or_emails":true}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

View Response
Hide Response
Headers
Response Body
{"project_id":99,"role":"member","person":{"username":"vestarak","email":"vkhai@sith.mil","initials":"VK","name":"Vestara Khai","kind":"person","id":300},"wants_comment_notification_emails":true,"project_color":"b800bb","kind":"project_membership","id":16100,"will_receive_mention_notifications_or_emails":true}
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
[{"project_id":99,"role":"owner","person":{"username":"palpatine","email":"emperor@galacticrepublic.gov","initials":"EP","name":"Emperor Palpatine","kind":"person","id":100},"wants_comment_notification_emails":false,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":100,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"member","person":{"username":"vader","email":"vader@deathstar.mil","initials":"DV","name":"Darth Vader","kind":"person","id":101},"wants_comment_notification_emails":true,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":101,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"owner","person":{"username":"tarkin","email":"governor@eriadu.gov","initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"wants_comment_notification_emails":false,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":102,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"member","person":{"username":"bast","email":"bast@deathstar.mil","initials":"MB","name":"Moradmin Bast","kind":"person","id":103},"wants_comment_notification_emails":true,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":103,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"member","person":{"username":"tk421","email":"tk421@deathstar.mil","initials":"TK421","name":"Clone TK421","kind":"person","id":104},"wants_comment_notification_emails":true,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":104,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"member","person":{"username":"i662","email":"I662@deathstar.mil","initials":"i662","name":"Robotic Maintenance Team 4","kind":"person","id":105},"wants_comment_notification_emails":true,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":105,"will_receive_mention_notifications_or_emails":true},{"project_id":99,"role":"viewer","person":{"username":"bevel","email":"bevel@sith.mil","initials":"bl","name":"Bevel Lemelisk","kind":"person","id":107},"wants_comment_notification_emails":false,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:05Z","kind":"project_membership","id":107,"will_receive_mention_notifications_or_emails":true}]
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
{"project_id":99,"role":"owner","person":{"username":"tarkin","email":"governor@eriadu.gov","initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"wants_comment_notification_emails":false,"project_color":"8100ea","last_viewed_at":"2014-04-15T12:00:00Z","kind":"project_membership","id":102,"will_receive_mention_notifications_or_emails":true}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"role":"viewer"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/memberships/103"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

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
[{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"vader","initials":"DV","name":"Darth Vader","kind":"person","id":101},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":true,"project_creator":false,"kind":"account_membership","id":101},{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"tarkin","initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":false,"project_creator":false,"kind":"account_membership","id":102},{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"bast","initials":"MB","name":"Moradmin Bast","kind":"person","id":103},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":false,"project_creator":false,"kind":"account_membership","id":103},{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"tk421","initials":"TK421","name":"Clone TK421","kind":"person","id":104},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":false,"project_creator":false,"kind":"account_membership","id":104},{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"starkiller","initials":"GM","name":"Galen Marek","kind":"person","id":106},"account_id":100,"time_enterer":false,"updated_at":"2014-04-15T12:00:00Z","timekeeper":false,"admin":false,"project_creator":false,"kind":"account_membership","id":106},{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"threedeefourx","initials":"3D4X","name":"3D-4X administrative droid","kind":"person","id":109},"account_id":100,"time_enterer":false,"updated_at":"2014-04-15T12:00:00Z","timekeeper":false,"admin":true,"project_creator":false,"kind":"account_membership","id":109},{"created_at":"2014-04-15T12:00:00Z","owner":true,"person":{"username":"palpatine","initials":"EP","name":"Emperor Palpatine","kind":"person","id":100},"account_id":100,"time_enterer":false,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":false,"project_creator":false,"kind":"account_membership","id":100}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"email":"dooku@example.com","initials":"CD","name":"Count Dooku"}' "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships"

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

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

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

View Response
Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"monmothma","initials":"MM","name":"Mon Mothma","kind":"person","id":108},"account_id":100,"time_enterer":false,"updated_at":"2014-04-15T12:00:00Z","timekeeper":false,"admin":false,"project_creator":false,"kind":"account_membership","id":19100}
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.
 
created_at
datetime in the request body.
 —  Creation time.
 
time_enterer
boolean in the request body.
 —  True if the person is expected to enter time for work on projects in the account.
 
timekeeper
boolean in the request body.
 —  True if the person is allowed to administer time entry by others on the account.
 
admin
boolean in the request body.
 —  True if the person has administrative rights on the account.
 
project_creator
boolean in the request body.
 —  True if the person is allowed to create new projects within the account.
 
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
{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"vader","initials":"DV","name":"Darth Vader","kind":"person","id":101},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:00Z","timekeeper":true,"admin":true,"project_creator":false,"kind":"account_membership","id":101}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"project_creator":true}' "https://www.pivotaltracker.com/services/v5/accounts/$ACCOUNT_ID/memberships/103"

Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","owner":false,"person":{"username":"bast","initials":"MB","name":"Moradmin Bast","kind":"person","id":103},"account_id":100,"time_enterer":true,"updated_at":"2014-04-15T12:00:05Z","timekeeper":true,"admin":false,"project_creator":true,"kind":"account_membership","id":103}
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.
 
time_enterer
boolean in the request body.
 —  True if the person is expected to enter time for work on projects in the account.
 
timekeeper
boolean in the request body.
 —  True if the person is allowed to administer time entry by others on the account.
 
admin
boolean in the request body.
 —  True if the person has administrative rights on the account.
 
project_creator
boolean in the request body.
 —  True if the person is allowed to create new projects within the account.
 
DELETE
/accounts/{account_id}/memberships/{person_id}

export TOKEN='your Pivotal Tracker API token'

export ACCOUNT_ID=100

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"created_at":"2014-04-15T12:00:05Z","updated_at":"2014-04-15T12:00:05Z","plan":"Pivotal Labs","name":"Galactic Empire","kind":"account","id":100,"status":"active"}]
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
{"created_at":"2014-04-15T12:00:05Z","updated_at":"2014-04-15T12:00:05Z","plan":"Pivotal Labs","name":"Galactic Empire","kind":"account","id":100,"status":"active"}
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
[{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"diplomatic relations","kind":"label","id":2014},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"fleet ops","kind":"label","id":2012},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"mnt","kind":"label","id":2010},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"personnel","kind":"label","id":2011},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"plans","kind":"label","id":2008},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"r&d","kind":"label","id":2013},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"rebel bases","kind":"label","id":2007},{"project_id":99,"created_at":1397563200000,"updated_at":1397563200000,"name":"turning luke","kind":"label","id":2009}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"a new hope"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels"

View Response
Hide Response
Headers
Response Body
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"a new hope","kind":"label","id":5100}
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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"diplomatic relations","kind":"label","id":2014}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"detention"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/labels/2014"

Hide Response
Headers
Response Body
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:05Z","name":"detention","kind":"label","id":2014}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"plans","kind":"label","id":2008},{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"rebel bases","kind":"label","id":2007}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"my new label","kind":"label","id":5100}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/labels/2008"

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

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

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
[{"tasks":[],"current_state":"unstarted","comments":[],"labels":[],"id":560},{"tasks":[],"current_state":"unstarted","comments":[],"labels":[{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"mnt","kind":"label","id":2010}],"id":565},{"tasks":[],"current_state":"unstarted","comments":[],"labels":[],"id":552},{"tasks":[],"current_state":"unstarted","comments":[{"created_at":"2014-04-15T12:00:00Z","person_id":101,"updated_at":"2014-04-15T12:00:00Z","story_id":555,"text":"I want them alive!","kind":"comment","id":111}],"labels":[],"id":555}]

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
[{"requested_by_id":102,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/560","owner_ids":[],"updated_at":"2014-04-15T12:00:00Z","current_state":"unstarted","name":"Tractor beam loses power intermittently","labels":[],"kind":"story","story_type":"bug","id":560}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"Exhaust ports are ray shielded"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/2300","owner_ids":[],"updated_at":"2014-04-15T12:00:00Z","current_state":"unscheduled","name":"Exhaust ports are ray shielded","labels":[],"kind":"story","story_type":"feature","id":2300}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"Exhaust ports are ray shielded","labels":[{"name":"rebel bases","id":2007},{"name":"newnew"}]}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
created_at
datetime in the request body.
 —  Creation time.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
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.
 
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.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
estimate
float in the request body.
 —  Point value of the story.
 
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.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 
name
string[5000] in the request body.
required  —  Name of the story.
 
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.
 
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.
 
follower_ids
List[int] in the request body.
 —  IDs of people currently following the story.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this 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.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 

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
{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/555","owner_ids":[],"estimate":2,"updated_at":"2014-04-15T12:00:00Z","current_state":"unstarted","name":"Bring me the passengers","labels":[],"kind":"story","story_type":"feature","id":555,"description":"ignore the droids"}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"labels":[]}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/555"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"comment":{"text":"Here are the new plans.","file_attachments":[{"width":650,"created_at":1397563200000,"type":"file_attachment","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true}]},"current_state":"rejected"}' "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
{"tasks":[],"requested_by":{"username":"vader","email":"vader@deathstar.mil","initials":"DV","name":"Darth Vader","kind":"person","id":101},"comments":[{"text":"I want them alive!","id":111,"file_attachments":[{"width":650,"created_at":"2014-04-15T12:00:05Z","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true},{"width":1000,"created_at":"2014-04-15T12:00:00Z","thumbnailable":true,"uploader_id":100,"download_url":"/attachments/0000/0020/empire_thumb.png","big_url":"/attachments/0000/0020/empire_big.png","content_type":"image/png","uploaded":true}]},{"text":"Here are the new plans.","id":300,"file_attachments":[{"width":650,"created_at":"2014-04-15T12:00:05Z","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true}]}],"labels":[],"id":555}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

View Response
Hide Response
Headers
Response Body
{"requested_by_id":101,"project_id":98,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/555","owner_ids":[],"estimate":2,"updated_at":"2014-04-15T12:00:05Z","current_state":"unstarted","name":"Bring me the passengers","labels":[],"kind":"story","story_type":"feature","id":555,"description":"ignore the droids"}
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.
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
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.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
estimate
float in the request body.
 —  Point value of the story.
 
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.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 
name
string[5000] in the request body.
 —  Name of the story.
 
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.
 
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.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this story.
 
accepted_at
datetime in the request body.
 —  Acceptance time.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 
DELETE
/projects/{project_id}/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"username":"palpatine","email":"emperor@galacticrepublic.gov","initials":"EP","name":"Emperor Palpatine","kind":"person","id":100},{"username":"bast","email":"bast@deathstar.mil","initials":"MB","name":"Moradmin Bast","kind":"person","id":103}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"id":100}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/owners"

View Response
Hide Response
Headers
Response Body
{"username":"palpatine","email":"emperor@galacticrepublic.gov","initials":"EP","name":"Emperor Palpatine","kind":"person","id":100}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
{"requested_by_id":102,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/558","owner_ids":[104],"estimate":3,"updated_at":"2014-04-15T12:00:00Z","current_state":"rejected","name":"All exhaust ports should be shielded","labels":[{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"plans","kind":"label","id":2008}],"kind":"story","story_type":"feature","id":558,"owned_by_id":104,"description":"ray shielded, that is."}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"labels":[]}' "https://www.pivotaltracker.com/services/v5/stories/555"

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

export TOKEN='your Pivotal Tracker API token'

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

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

export TOKEN='your Pivotal Tracker API token'

curl -X PUT -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"comment":{"text":"Here are the new plans.","file_attachments":[{"width":650,"created_at":1397563200000,"type":"file_attachment","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true}]},"current_state":"rejected"}' "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
{"tasks":[],"requested_by":{"username":"vader","email":"vader@deathstar.mil","initials":"DV","name":"Darth Vader","kind":"person","id":101},"comments":[{"text":"I want them alive!","id":111,"file_attachments":[{"width":650,"created_at":"2014-04-15T12:00:05Z","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true},{"width":1000,"created_at":"2014-04-15T12:00:00Z","thumbnailable":true,"uploader_id":100,"download_url":"/attachments/0000/0020/empire_thumb.png","big_url":"/attachments/0000/0020/empire_big.png","content_type":"image/png","uploaded":true}]},{"text":"Here are the new plans.","id":300,"file_attachments":[{"width":650,"created_at":"2014-04-15T12:00:05Z","thumbnailable":false,"uploader_id":101,"download_url":"/attachments/0000/0021/Corellian corvette deck plan_thumb.tiff","big_url":"/attachments/0000/0021/Corellian corvette deck plan_big.tiff","content_type":"image/tiff","uploaded":true}]}],"labels":[],"id":555}

export TOKEN='your Pivotal Tracker API token'

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

View Response
Hide Response
Headers
Response Body
{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/555","owner_ids":[],"estimate":1,"updated_at":"2014-04-15T12:00:05Z","current_state":"accepted","name":"Exhaust ports have ray shielding","labels":[],"kind":"story","story_type":"feature","id":555,"accepted_at":"2014-04-15T12:00:05Z","description":"ignore the droids"}
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
 
external_id
string[255] in the request body.
 —  The integration's specific ID for the story.
 
requested_by_id
int in the request body.
 —  The id of the person who requested the story.
 
project_id
int in the request body.
 —  id of the project.
 
cl_numbers
string in the request body.
 —  Version control 'change list' identifiers.
 
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.
 
owner_ids
List[int] in the request body.
 —  IDs of the current story owners.
 
estimate
float in the request body.
 —  Point value of the story.
 
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.
 
current_state
enumerated string in the request body.
 —  Story's state of completion.
Valid enumeration values: accepted, delivered, finished, started, rejected, unstarted, unscheduled
 
deadline
datetime in the request body.
 —  Due date/time (for a release-type story).
 
name
string[5000] in the request body.
 —  Name of the story.
 
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.
 
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.
 
story_type
enumerated string in the request body.
 —  Type of story.
Valid enumeration values: feature, bug, chore, release
 
integration_id
int in the request body.
 —  ID of the integration API that is linked to this story.
 
accepted_at
datetime in the request body.
 —  Acceptance time.
 
owned_by_id
int in the request body.
 —  The id of the person who owns the story.
 
description
string[20000] in the request body.
 —  In-depth explanation of the story requirements.
 
DELETE
/stories/{story_id}

export TOKEN='your Pivotal Tracker API token'

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"created_at":"2014-04-15T12:00:00Z","position":1,"updated_at":"2014-04-15T12:00:00Z","story_id":558,"complete":false,"kind":"task","id":5,"description":"Port 0"},{"created_at":"2014-04-15T12:00:00Z","position":2,"updated_at":"2014-04-15T12:00:00Z","story_id":558,"complete":false,"kind":"task","id":6,"description":"Port 90"}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"description":"port 270"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/stories/$STORY_ID/tasks"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

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

View Response
Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","position":1,"updated_at":"2014-04-15T12:00:00Z","story_id":558,"complete":true,"kind":"task","id":5100,"description":"port 270"}
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.
 
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.
 
complete
boolean in the request body.
 —  Flag showing the completion of the task.
 
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
{"created_at":"2014-04-15T12:00:00Z","position":1,"updated_at":"2014-04-15T12:00:00Z","story_id":558,"complete":false,"kind":"task","id":5,"description":"Port 0"}

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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"created_at":"2014-04-15T12:00:00Z","position":1,"updated_at":"2014-04-15T12:00:05Z","story_id":558,"complete":false,"kind":"task","id":5,"description":"port 360"}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=558

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

View Response
Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","position":2,"updated_at":"2014-04-15T12:00:05Z","story_id":558,"complete":true,"kind":"task","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.
 
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.
 
complete
boolean in the request body.
 —  Flag showing the completion of the task.
 
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
[{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/7","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"mnt","kind":"label","id":2010},"updated_at":"2014-04-15T12:00:00Z","name":"Maintenance","kind":"epic","id":7},{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/6","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"turning luke","kind":"label","id":2009},"updated_at":"2014-04-15T12:00:00Z","name":"Turn Luke Skywalker","kind":"epic","id":6},{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/5","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"plans","kind":"label","id":2008},"updated_at":"2014-04-15T12:00:00Z","name":"Death Star Plans","kind":"epic","id":5},{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/4","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"rebel bases","kind":"label","id":2007},"updated_at":"2014-04-15T12:00:00Z","name":"Rebel Home Worlds","kind":"epic","id":4,"description":"Identify the systems and eliminate the rebel scum."}]

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":[{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","epic_id":5,"text":"Check out these Uffel mouse droids","kind":"comment","id":110}],"id":5},{"comments":[{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","epic_id":4,"text":"Should we send a probe to Dantooine?","kind":"comment","id":109}],"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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"name":"Tractor Beams"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X POST -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/2100","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"tractor-beams","kind":"label","id":5100},"updated_at":"2014-04-15T12:00:00Z","name":"Tractor Beams","kind":"epic","id":2100,"description":"Install tractor beam systems in all landing bays. Beam systems should report to central monitoring."}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

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

View Response
Hide Response
Headers
Response Body
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/2100","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"pr","kind":"label","id":5100},"updated_at":"2014-04-15T12:00:00Z","name":"PR","kind":"epic","id":2100}
Successful responses to this request return the epic 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 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.
 
name
string[5000] in the request body.
required  —  Name of the epic.
 
before_id
int in the request body.
 —  id of the epic following the epic.
 
after_id
int in the request body.
 —  id of the epic preceding the epic.
 
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.
 
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.
 
description
string[20000] in the request body.
 —  In-depth explanation of the epic's goals, scope, etc.
 

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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/4","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"rebel bases","kind":"label","id":2007},"updated_at":"2014-04-15T12:00:00Z","name":"Rebel Home Worlds","kind":"epic","id":4,"description":"Identify the systems and eliminate the rebel scum."}

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
{"name":"Rebel Home Worlds","project":{"enable_following":true,"week_start_day":"Monday","name":"Death Star","time_zone":{"offset":"-07:00","olson_name":"America/Los_Angeles","kind":"time_zone"},"id":99},"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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"description":"new desc"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/4"

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X PUT -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"name":"Rebel Home Worlds","label_id":5100,"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.
 
name
string[5000] in the request body.
 —  Name of the epic.
 
before_id
int in the request body.
 —  id of the epic following the epic.
 
after_id
int in the request body.
 —  id of the epic preceding 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.
 
description
string[20000] in the request body.
 —  In-depth explanation of the epic's goals, scope, etc.
 
DELETE
/projects/{project_id}/epics/{epic_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/epic/show/4","label":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","updated_at":"2014-04-15T12:00:00Z","name":"rebel bases","kind":"label","id":2007},"updated_at":"2014-04-15T12:00:00Z","name":"Rebel Home Worlds","kind":"epic","id":4,"description":"Identify the systems and eliminate the rebel scum."}
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
[{"created_at":"2014-04-15T12:00:00Z","person_id":101,"updated_at":"2014-04-15T12:00:00Z","story_id":555,"text":"I want them alive!","kind":"comment","id":111}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"created_at":"2014-04-15T12:00:00Z","person_id":101,"updated_at":"2014-04-15T12:00:00Z","story_id":555,"text":"If this is a consular ship, then where is the ambassador?","kind":"comment","id":300}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

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

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

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

export STORY_ID=555

curl -X POST -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"text":"What if this were our new sigil?","file_attachments":[{"width":1000,"created_at":"2014-04-15T12:00:00Z","thumbnailable":true,"uploader_id":100,"download_url":"/attachments/0000/0024/empire_thumb.png","big_url":"/attachments/0000/0024/empire_big.png","content_type":"image/png","uploaded":true}]}' "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
{"file_attachment_ids":[24],"created_at":"2014-04-15T12:00:00Z","person_id":101,"updated_at":"2014-04-15T12:00:00Z","story_id":555,"text":"What if this were our new sigil?","kind":"comment","id":300}
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.
 
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.
 
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.
 
person_id
int in the request body.
 —  The id of the comment creator.
 
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.
 
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.
 
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
{"created_at":"2014-04-15T12:00:00Z","person_id":102,"updated_at":"2014-04-15T12:00:00Z","story_id":563,"text":"I think you overestimate their chances!","kind":"comment","id":108}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"created_at":"2014-04-15T12:00:00Z","person_id":102,"updated_at":"2014-04-15T12:00:05Z","story_id":563,"text":"updated comment text","kind":"comment","id":108}
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
[{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","epic_id":4,"text":"Should we send a probe to Dantooine?","kind":"comment","id":109}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","epic_id":4,"text":"This is my comment","kind":"comment","id":300}
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.
 
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.
 
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.
 
person_id
int in the request body.
 —  The id of the comment creator.
 
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.
 
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.
 
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","epic_id":4,"text":"Should we send a probe to Dantooine?","kind":"comment","id":109}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"text":"updated comment text"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/epics/$EPIC_ID/comments/109"

Hide Response
Headers
Response Body
{"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:05Z","epic_id":4,"text":"updated comment text","kind":"comment","id":109}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
{"created_at":"2014-04-15T12:00:00Z","thumbnail_url":"#","filename":"new-imperial-logo-6.jpg","thumbnailable":true,"uploader_id":101,"download_url":"/file_attachments/300/download","big_url":"#","content_type":"image/jpeg","uploaded":false,"kind":"file_attachment","id":300,"size":7683}
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","kind":"google_attachment","google_kind":"document"}]
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
[{"project_id":99,"name":"New Maintenance Issues","kind":"saved_search","id":4,"query":"label:\"mnt\" state:unscheduled"},{"project_id":99,"name":"Family","kind":"saved_search","id":5,"query":"luke, leia"}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"project_id":99,"name":"my saved search","kind":"saved_search","id":300,"query":"label:\"rebel bases\""}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_61","primary_resources":[{"url":"http://localhost/story/show/563","name":"Evacuate, in our moment of triumph","kind":"story","story_type":"feature","id":563},{"url":"http://localhost/story/show/561","name":"Garbage smashers on the detention level have malfunctioned","kind":"story","story_type":"bug","id":561}],"highlight":"moved","changes":[{"change_type":"update","name":"Garbage smashers on the detention level have malfunctioned","kind":"story","story_type":"bug","id":561,"new_values":{"before_id":557},"original_values":{"before_id":551}},{"change_type":"update","name":"Evacuate, in our moment of triumph","kind":"story","story_type":"feature","id":563,"new_values":{"after_id":564},"original_values":{"after_id":557}}],"project_version":61,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_move_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader moved 2 stories"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_60","primary_resources":[{"url":"http://localhost/story/show/563","name":"Evacuate, in our moment of triumph","kind":"story","story_type":"feature","id":563},{"url":"http://localhost/story/show/561","name":"Garbage smashers on the detention level have malfunctioned","kind":"story","story_type":"bug","id":561}],"highlight":"moved","changes":[{"change_type":"update","name":"Garbage smashers on the detention level have malfunctioned","kind":"story","story_type":"bug","id":561,"new_values":{"before_id":551},"original_values":{"before_id":557}},{"change_type":"update","name":"Evacuate, in our moment of triumph","kind":"story","story_type":"feature","id":563,"new_values":{"after_id":557},"original_values":{"after_id":564}}],"project_version":60,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_move_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader moved 2 stories"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_59","primary_resources":[{"url":"http://localhost/story/show/555","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555}],"highlight":"added comment:","changes":[{"change_type":"create","kind":"comment","id":111,"new_values":{"file_attachment_ids":[],"created_at":"2014-04-15T12:00:05Z","person_id":101,"updated_at":"2014-04-15T12:00:05Z","story_id":555,"google_attachment_ids":[],"text":"I want them alive!","id":111,"file_attachments":[],"google_attachments":[]}},{"change_type":"update","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555,"new_values":{"follower_ids":[101]},"original_values":{"follower_ids":[]}}],"project_version":59,"project":{"name":"Death Star","kind":"project","id":99},"kind":"comment_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added comment: \"I want them alive!\""},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_53","primary_resources":[{"url":"http://localhost/story/show/555","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555}],"highlight":"unstarted","changes":[{"change_type":"update","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555,"new_values":{"current_state":"unstarted","before_id":566,"after_id":552},"original_values":{"current_state":"unscheduled","before_id":551,"after_id":557}}],"project_version":53,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader unstarted this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_51","primary_resources":[{"url":"http://localhost/story/show/558","name":"All exhaust ports should be shielded","kind":"story","story_type":"feature","id":558}],"highlight":"rejected","changes":[{"change_type":"update","name":"All exhaust ports should be shielded","kind":"story","story_type":"feature","id":558,"new_values":{"current_state":"rejected"},"original_values":{"current_state":"delivered"}}],"project_version":51,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader rejected this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_45","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"started","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"current_state":"started","before_id":566,"after_id":559},"original_values":{"current_state":"unscheduled","before_id":555,"after_id":557}}],"project_version":45,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader started this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_44","primary_resources":[{"url":"http://localhost/story/show/559","name":"Destroy Alderaan","kind":"story","story_type":"feature","id":559}],"highlight":"accepted","changes":[{"change_type":"update","name":"Destroy Alderaan","kind":"story","story_type":"feature","id":559,"new_values":{"current_state":"accepted","accepted_at":"2014-04-15T12:00:05Z"},"original_values":{"current_state":"delivered","accepted_at":null}}],"project_version":44,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader accepted this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_40","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"edited","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"label_ids":[2008,2007],"labels":["plans","rebel bases"]},"original_values":{"label_ids":[2014],"labels":["diplomatic relations"]}}],"project_version":40,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader edited this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_9","primary_resources":[{"url":"http://localhost/story/show/557","name":"Prepare carbonite freezing chamber","kind":"story","story_type":"feature","id":557}],"highlight":"added","changes":[{"change_type":"create","name":"Prepare carbonite freezing chamber","kind":"story","story_type":"feature","id":557,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:05Z","owner_ids":[],"updated_at":"2014-04-15T12:00:05Z","label_ids":[2013],"current_state":"unscheduled","name":"Prepare carbonite freezing chamber","before_id":556,"after_id":553,"labels":["r&d"],"follower_ids":[],"story_type":"feature","id":557,"description":"Test first on Solo, we don't want the Emperor's prize damaged."}}],"project_version":9,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_8","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"added","changes":[{"change_type":"create","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:05Z","owner_ids":[101],"updated_at":"2014-04-15T12:00:05Z","label_ids":[2014],"current_state":"unscheduled","name":"Interrogate Leia Organa","before_id":555,"after_id":553,"labels":["diplomatic relations"],"follower_ids":[],"story_type":"feature","id":556,"owned_by_id":101,"description":"She is proving to be resistant to our mind probes"}}],"project_version":8,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_7","primary_resources":[{"url":"http://localhost/story/show/555","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555}],"highlight":"added","changes":[{"change_type":"create","name":"Bring me the passengers","kind":"story","story_type":"feature","id":555,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:05Z","owner_ids":[],"updated_at":"2014-04-15T12:00:05Z","label_ids":[],"current_state":"unscheduled","name":"Bring me the passengers","before_id":554,"after_id":553,"labels":[],"follower_ids":[],"story_type":"feature","id":555,"description":"ignore the droids"}}],"project_version":7,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_6","primary_resources":[{"url":"http://localhost/story/show/554","name":"Identify Bothan spies","kind":"story","story_type":"feature","id":554}],"highlight":"added","changes":[{"change_type":"create","name":"Identify Bothan spies","kind":"story","story_type":"feature","id":554,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:05Z","owner_ids":[106],"updated_at":"2014-04-15T12:00:05Z","label_ids":[],"current_state":"unscheduled","name":"Identify Bothan spies","before_id":552,"after_id":553,"labels":[],"follower_ids":[],"story_type":"feature","id":554,"owned_by_id":106,"description":"Infiltrate their spy network."}}],"project_version":6,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"99_5","primary_resources":[{"url":"http://localhost/story/show/553","name":"Build protocol droid","kind":"story","story_type":"feature","id":553}],"highlight":"added","changes":[{"change_type":"create","name":"Build protocol droid","kind":"story","story_type":"feature","id":553,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:05Z","owner_ids":[101],"estimate":3,"updated_at":"2014-04-15T12:00:05Z","label_ids":[2013,2007],"current_state":"accepted","name":"Build protocol droid","before_id":552,"labels":["r&d","rebel bases"],"follower_ids":[],"story_type":"feature","id":553,"accepted_at":"2014-04-15T12:00:05Z","owned_by_id":101,"description":"I want a friend"}}],"project_version":5,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader added this feature"},{"occurred_at":"2014-04-15T12:00:05Z","guid":"98_2","primary_resources":[{"url":"http://localhost/story/show/567","name":"Midi-chlorians","kind":"story","story_type":"feature","id":567}],"highlight":"added","changes":[{"change_type":"create","name":"Midi-chlorians","kind":"story","story_type":"feature","id":567,"new_values":{"requested_by_id":101,"project_id":98,"created_at":"2014-04-15T12:00:05Z","owner_ids":[101],"estimate":3,"updated_at":"2014-04-15T12:00:05Z","label_ids":[],"current_state":"unstarted","name":"Midi-chlorians","labels":[],"follower_ids":[],"story_type":"feature","id":567,"owned_by_id":101,"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"}}],"project_version":2,"project":{"name":"Learn About the Force","kind":"project","id":98},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"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
[{"occurred_at":"2014-04-15T12:00:10Z","guid":"99_62","primary_resources":[{"number":1,"kind":"iteration_override"}],"highlight":"changed","changes":[{"change_type":"update","number":1,"kind":"iteration_override","new_values":{"team_strength":0.9,"finish":1397563205000,"number":1,"length":2},"original_values":{"team_strength":1.0,"finish":1397563200000,"number":1,"length":"default"}}],"project_version":62,"project":{"name":"Death Star","kind":"project","id":99},"kind":"iteration_update_activity","performed_by":{"initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"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
[{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_45","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"started","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"current_state":"started","before_id":566,"after_id":559},"original_values":{"current_state":"unscheduled","before_id":555,"after_id":557}}],"project_version":45,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader started this feature"},{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_40","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"edited","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"label_ids":[2008,2007],"labels":["plans","rebel bases"]},"original_values":{"label_ids":[2014],"labels":["diplomatic relations"]}}],"project_version":40,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader edited this feature"},{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_23","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"estimated","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"estimate":2},"original_values":{"estimate":null}}],"project_version":23,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"EP","name":"Emperor Palpatine","kind":"person","id":100},"message":"Emperor Palpatine estimated this feature as 2 points"},{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_8","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"added","changes":[{"change_type":"create","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:00Z","owner_ids":[101],"updated_at":"2014-04-15T12:00:00Z","label_ids":[2014],"current_state":"unscheduled","name":"Interrogate Leia Organa","before_id":555,"after_id":553,"labels":["diplomatic relations"],"follower_ids":[],"story_type":"feature","id":556,"owned_by_id":101,"description":"She is proving to be resistant to our mind probes"}}],"project_version":8,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_create_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"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
[{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_40","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"edited","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"label_ids":[2008,2007],"labels":["plans","rebel bases"]},"original_values":{"label_ids":[2014],"labels":["diplomatic relations"]}}],"project_version":40,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"DV","name":"Darth Vader","kind":"person","id":101},"message":"Darth Vader edited this feature"},{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_23","primary_resources":[{"url":"http://localhost/story/show/556","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556}],"highlight":"estimated","changes":[{"change_type":"update","name":"Interrogate Leia Organa","kind":"story","story_type":"feature","id":556,"new_values":{"estimate":2},"original_values":{"estimate":null}}],"project_version":23,"project":{"name":"Death Star","kind":"project","id":99},"kind":"story_update_activity","performed_by":{"initials":"EP","name":"Emperor Palpatine","kind":"person","id":100},"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
[{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_57","primary_resources":[{"url":"http://localhost/epic/show/4","name":"Rebel Home Worlds","kind":"epic","id":4}],"highlight":"added comment:","changes":[{"change_type":"create","kind":"comment","id":109,"new_values":{"file_attachment_ids":[],"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","google_attachment_ids":[],"epic_id":4,"text":"Should we send a probe to Dantooine?","id":109,"file_attachments":[],"google_attachments":[]}},{"change_type":"update","name":"Rebel Home Worlds","kind":"epic","id":4,"new_values":{"follower_ids":[103]},"original_values":{"follower_ids":[]}}],"project_version":57,"project":{"name":"Death Star","kind":"project","id":99},"kind":"comment_create_activity","performed_by":{"initials":"MB","name":"Moradmin Bast","kind":"person","id":103},"message":"Moradmin Bast added comment: \"Should we send a probe to Dantooine?\""},{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_19","primary_resources":[{"url":"http://localhost/epic/show/4","name":"Rebel Home Worlds","kind":"epic","id":4}],"highlight":"added","changes":[{"change_type":"create","name":"Rebel Home Worlds","kind":"epic","id":4,"new_values":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","label":"rebel bases","updated_at":"2014-04-15T12:00:00Z","name":"Rebel Home Worlds","past_done_stories_count":1,"past_done_story_estimates":3,"label_id":2007,"follower_ids":[],"past_done_stories_no_point_count":0,"id":4,"description":"Identify the systems and eliminate the rebel scum."}}],"project_version":19,"project":{"name":"Death Star","kind":"project","id":99},"kind":"epic_create_activity","performed_by":{"initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"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
[{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_19","primary_resources":[{"url":"http://localhost/epic/show/4","name":"Rebel Home Worlds","kind":"epic","id":4}],"highlight":"added","changes":[{"change_type":"create","name":"Rebel Home Worlds","kind":"epic","id":4,"new_values":{"project_id":99,"created_at":"2014-04-15T12:00:00Z","label":"rebel bases","updated_at":"2014-04-15T12:00:00Z","name":"Rebel Home Worlds","past_done_stories_count":1,"past_done_story_estimates":3,"label_id":2007,"follower_ids":[],"past_done_stories_no_point_count":0,"id":4,"description":"Identify the systems and eliminate the rebel scum."}}],"project_version":19,"project":{"name":"Death Star","kind":"project","id":99},"kind":"epic_create_activity","performed_by":{"initials":"WT","name":"Wilhuff Tarkin","kind":"person","id":102},"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
[{"occurred_at":"2014-04-15T12:00:00Z","guid":"99_57","primary_resources":[{"url":"http://localhost/epic/show/4","name":"Rebel Home Worlds","kind":"epic","id":4}],"highlight":"added comment:","changes":[{"change_type":"create","kind":"comment","id":109,"new_values":{"file_attachment_ids":[],"created_at":"2014-04-15T12:00:00Z","person_id":103,"updated_at":"2014-04-15T12:00:00Z","google_attachment_ids":[],"epic_id":4,"text":"Should we send a probe to Dantooine?","id":109,"file_attachments":[],"google_attachments":[]}},{"change_type":"update","name":"Rebel Home Worlds","kind":"epic","id":4,"new_values":{"follower_ids":[103]},"original_values":{"follower_ids":[]}}],"project_version":57,"project":{"name":"Death Star","kind":"project","id":99},"kind":"comment_create_activity","performed_by":{"initials":"MB","name":"Moradmin Bast","kind":"person","id":103},"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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"source_commit":{"url":"http://example.com/abc123","author":"Darth Vader","commit_id":"abc123","message":"[#555] some commit"}}' "https://www.pivotaltracker.com/services/v5/source_commits"

View Response
Hide Response
Headers
Response Body
[{"requested_by_id":101,"project_id":99,"created_at":"2014-04-15T12:00:00Z","url":"http://localhost/story/show/555","owner_ids":[],"estimate":2,"updated_at":"2014-04-15T12:00:05Z","current_state":"started","name":"Bring me the passengers","labels":[],"kind":"story","story_type":"feature","id":555,"description":"ignore the droids"}]
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
[{"project_id":99,"created_at":"2014-04-15T12:00:00Z","can_import":true,"is_other":true,"updated_at":"2014-04-15T12:00:00Z","name":"Sounder Flats Computer Complex","import_api_url":"http://localhost:3000/starwars.xml","kind":"other_integration","story_name":"item","id":30,"active":true,"base_url":"http://localhost:3000"}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"type":"other","name":"something","active":false,"base_url":"http://some.th/ing"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/integrations"

View Response
Hide Response
Headers
Response Body
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","can_import":false,"is_other":true,"updated_at":"2014-04-15T12:00:00Z","name":"something","kind":"other_integration","story_name":"item","id":200,"active":false,"base_url":"http://some.th/ing"}
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.
 
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.
 
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
 
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.
 
external_api_token
string in the request body.
 —  Your Lighthouse API token.
 
filter_id
string in the request body.
 —  The ID of the saved JIRA filter to use to load stories.
 
bin_id
int in the request body.
 —  Only import tickets from the specified ticket bin.
 
basic_auth_password
string in the request body.
 —  The password to use when importing stories.
 
update_comments
boolean in the request body.
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
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.
 
name
string[40] in the request body.
 —  The name given to the particular external integration in the Project Settings pages.
 
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.
 
basic_auth_username
string in the request body.
 —  The username 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.
 
zendesk_user_email
string in the request body.
 —  The email of the Zendesk user which you want to use for integration purposes.
 
view_id
string in the request body.
 —  Only show tickets from the specified Zendesk view.
 
active
boolean in the request body.
 —  True if the integration is currently enabled for use.
 
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.
 
update_state
boolean in the request body.
 —  Adds a state change comment to the linked ticket or bug.
 
base_url
string in the request body.
 —  url used for outgoing web links in stories imported via this integration.
 
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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","can_import":true,"is_other":true,"updated_at":"2014-04-15T12:00:00Z","name":"Sounder Flats Computer Complex","import_api_url":"http://localhost:3000/starwars.xml","kind":"other_integration","story_name":"item","id":30,"active":true,"base_url":"http://localhost:3000"}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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
{"project_id":99,"created_at":"2014-04-15T12:00:00Z","can_import":true,"is_other":true,"updated_at":"2014-04-15T12:00:05Z","name":"something","import_api_url":"http://localhost:3000/starwars.xml","kind":"other_integration","story_name":"item","id":30,"active":true,"base_url":"http://some.th/ing"}
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.
 
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.
 
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.
 
external_api_token
string in the request body.
 —  Your Lighthouse API token.
 
filter_id
string in the request body.
 —  The ID of the saved JIRA filter to use to load stories.
 
bin_id
int in the request body.
 —  Only import tickets from the specified ticket bin.
 
basic_auth_password
string in the request body.
 —  The password to use when importing stories.
 
update_comments
boolean in the request body.
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
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.
 
name
string[40] in the request body.
 —  The name given to the particular external integration in the Project Settings pages.
 
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.
 
basic_auth_username
string in the request body.
 —  The username 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.
 
zendesk_user_email
string in the request body.
 —  The email of the Zendesk user which you want to use for integration purposes.
 
view_id
string in the request body.
 —  Only show tickets from the specified Zendesk view.
 
active
boolean in the request body.
 —  True if the integration is currently enabled for use.
 
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.
 
update_state
boolean in the request body.
 —  Adds a state change comment to the linked ticket or bug.
 
base_url
string in the request body.
 —  url used for outgoing web links in stories imported via this integration.
 
DELETE
/projects/{project_id}/integrations/{integration_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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
[{"external_id":"Bespin","created_at":"2014-04-15T12:00:00Z","external_requester":"Lando Calrissian","external_owner":"Darth Vader","owner_ids":[101],"estimate":0,"name":"Please let us go","kind":"external_story","story_type":"feature","integration_id":30,"owned_by_id":101}]
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_url":"http://localhost:3000/test_postbin","project_id":99,"created_at":"2014-04-15T12:00:00Z","webhook_version":"v5","updated_at":"2014-04-15T12:00:00Z","kind":"webhook","id":27}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"webhook_url":"http://localhost:3000/test_postbin","webhook_version":"v5"}' "https://www.pivotaltracker.com/services/v5/projects/$PROJECT_ID/webhooks"

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

PARAMETERS

project_id
int in the request path.
required  —  The ID of the project.
 
webhook_url
string in the request body.
 —  The location of the application listening for Tracker events.
 
webhook_version
enumerated string in the request body.
 —  The version of the API your webhook will interact with.
Valid enumeration values: v3, v5
 
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_url":"http://localhost:3000/test_postbin","project_id":99,"created_at":"2014-04-15T12:00:00Z","webhook_version":"v5","updated_at":"2014-04-15T12:00:00Z","kind":"webhook","id":27}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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_url":"http://localhost:3000/my_example_webhook","project_id":99,"created_at":"2014-04-15T12:00:00Z","webhook_version":"v5","updated_at":"2014-04-15T12:00:05Z","kind":"webhook","id":27}
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_url
string in the request body.
 —  The location of the application listening for Tracker events.
 
webhook_version
enumerated string in the request body.
 —  The version of the API your webhook will interact with.
Valid enumeration values: v3, v5
 
DELETE
/projects/{project_id}/webhooks/{webhook_id}

export TOKEN='your Pivotal Tracker API token'

export PROJECT_ID=99

curl -X DELETE -H "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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],"person_id":101,"name":"executor","kind":"workspace","id":32}]
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -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],"person_id":101,"name":"A new workspace","kind":"workspace","id":200}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" -d '{"project_ids":[99,98]}' "https://www.pivotaltracker.com/services/v5/my/workspaces/32"

Hide Response
Headers
Response Body
{"project_ids":[99,98],"person_id":101,"name":"executor","kind":"workspace","id":32}
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 "Content-Type: application/json" -H "X-TrackerToken: $TOKEN" "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

created_at
datetime
 —  Creation time. This field is read only.
 
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.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[100]
 —  The name of the account.
 
plan
string
 —  The name of the account's current subscription plan. 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.
 
over_the_limit
boolean
 —  True if the account is currently over its subscription plan limits. This field is read only.
 
kind
string
 —  The type of this object: account. This field is read only.
 
id
int
 —  Database id of the account. This field is read only.
 
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: delinquent, active, suspended, deleted, limited
 
resource

account_membership

PROPERTIES

created_at
datetime
 —  Creation time. 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.
 
account_id
int
 —  The id of the account. This field is writable only on create.
 
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.
 
time_enterer
boolean
 —  True if the person is expected to enter time for work on projects in the account.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
admin
boolean
 —  True if the person has administrative rights on the account.
 
timekeeper
boolean
 —  True if the person is allowed to administer time entry by others on the account.
 
project_creator
boolean
 —  True if the person is allowed to create new projects within the account.
 
kind
string
 —  The type of this object: account_membership. This field is read only.
 
id
int
 —  The id of the membership. This field is read only. This field is always returned.
 
resource

account_summary

PROPERTIES

name
string[100]
 —  The name of the account.
 
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.
 
over_the_limit
boolean
 —  True if the account is currently over its subscription plan limits. This field is read only.
 
kind
string
 —  The type of this object: account_summary. This field is read only.
 
id
int
 —  Database id of the account. This field is read only.
 
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: delinquent, active, suspended, deleted, limited
 
resource

activity

PROPERTIES

occurred_at
datetime
 —  Time of the activity. This field is read only.
 
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.
 
guid
string
 —  Project id and version of the activity. This field is read only. This field is always returned.
 
primary_resources
List[object]
 —  The primary resource(s) affected by this command. This field is read only.
 
changes
List[object]
 —  The set of changes. This field is read only.
 
highlight
string
 —  Boldface portion of the message. This field is read only.
 
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.
 
project_version
int
 —  The version of the activity. This field is read only. This field is always returned.
 
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.
 
message
string
 —  Description of the activity. This field is read only.
 
resource

bugzilla_integration

PROPERTIES

created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read only.
 
product
string
 —  The name of your Bugzilla Product. Use this in conjunction with the component to narrow the bugs to be imported.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
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.
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked Bugzilla bug.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
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.
 
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.
 
kind
string
 —  The type of this object: bugzilla_integration. This field is read only.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
update_state
boolean
 —  Adds a state change comment to the Bugzilla bug.
 
resource

comment

PROPERTIES

created_at
datetime
 —  Creation time. This field is read only.
 
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.
 
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.
 
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.
 
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.
 
updated_at
datetime
 —  Updated time. (Comments are updated by removing one of their attachments.) 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.
 
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.
 
text
string[20000]
 —  Content of the comment. This field is writable only on create.
 
kind
string
 —  The type of this object: comment. This field is read only.
 
id
int
 —  Database id of the comment. This field is read only. This field is always returned.
 
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.)
 
resource

counts_by_story_state

PROPERTIES

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

epic

PROPERTIES

project_id
int
 —  id of the project.
 
created_at
datetime
 —  Creation time. This field is read only.
 
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.
 
url
string
 —  The url for this epic in Tracker. This field is read only.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[5000]
required on create  —  Name of the epic. This field is required on create.
 
after_id
int
 —  id of the epic preceding the epic. This field is excluded by default.
 
before_id
int
 —  id of the epic following the epic. This field is excluded by default.
 
past_done_stories_count
int
 —  number of past_done stories. This field is read only. This field is excluded by default.
 
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.
 
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.
 
past_done_story_estimates
float
 —  total point values of the past_done stories. This field is read only. This field is excluded by default.
 
kind
string
 —  The type of this object: epic. This field is read only.
 
id
int
 —  Database id of the epic. This field is read only. This field is always returned.
 
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.
 
resource

epics_search_result

PROPERTIES

epics
List[epic]
 —  Array of epics which matched the search criteria.
 
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.
 
total_hits
int
 —  Number of non-done epics which matched the search criteria.
 
resource

external_story

PROPERTIES

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.)
 
created_at
datetime
 —  Creation time of this external_story.
 
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.
 
external_requester
string
 —  Identifier for the person who "requested" this story in the external system.
 
external_owner
string
 —  Identifier for the person who "owns" this story in the external system.
 
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.
 
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.
 
name
string
 —  Name of this external story.
 
state
int
 —  State of this external_story.
 
kind
string
 —  The type of this object: external_story. This field is read only.
 
story_type
string
 —  story_type of this external story.
 
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.
 
description
string[20000]
 —  In-depth explanation of the story requirements.
 
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.
 
resource

file_attachment

PROPERTIES

created_at
datetime
 —  Creation time. This field is read only.
 
width
int
 —  If the attachment is thumbnailable the width of it in pixels. This field is read only.
 
height
int
 —  If the attachment is thumbnailable the height of it in pixels. 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.
 
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.
 
download_url
string
 —  The URL for the original attachment on S3. This field is read only.
 
big_url
string
 —  URL to larger-size thumbnail version if attachment is an image. This field is read only.
 
content_type
string[255]
 —  The MIME type of the attachment. This field is read only.
 
uploaded
boolean
 —  Flag indicating whether the attachment has been moved to S3. This field is read only.
 
kind
string
 —  The type of this object: file_attachment. This field is read only.
 
id
int
 —  Database id of the file_attachment. This field is read only. This field is always returned.
 
size
int
 —  The size of the attachment in bytes. This field is read only.
 
resource

follower

PROPERTIES

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.
 
name
string[100]
 —  The full name of the person.
 
kind
string
 —  The type of this object: follower. This field is read only.
 
id
int
 —  Database id of the person. This field is always returned.
 
resource

following

PROPERTIES

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.
 
story_id
int
 —  The id of the story. This field is writable only on create.
 
epic_id
int
 —  The id of the epic. This field is writable only on create.
 
kind
string
 —  The type of this object: following. This field is read only.
 
id
int
 —  The id of the following. This field is read only. This field is always returned.
 
resource

get_satisfaction_integration

PROPERTIES

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

google_attachment

PROPERTIES

comment_id
int
 —  The id of the comment. 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.
 
title
string[255]
 —  The google attachment's name. 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.)
 
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.)
 
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.
 
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.
 
resource

integration

PROPERTIES

created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read 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.
 
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.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
external_api_token
string
 —  Your Lighthouse API token. This field is write only.
 
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.
 
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
 
is_other
boolean
 —  whether the integration is of type 'other'. This field is read only.
 
basic_auth_password
string
 —  The password to use when importing stories. This field is write only.
 
bin_id
int
 —  Only import tickets from the specified ticket bin. (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.)
 
update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked ticket or bug.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
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.
 
comments_private
boolean
 —  If enabled, comments made by Tracker on the external bug will be marked as private.
 
basic_auth_username
string
 —  The username to use when importing stories.
 
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.)
 
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: get_satisfaction_integration, jira_integration, other_integration, zendesk_integration, lighthouse_integration, bugzilla_integration. This field is read only.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
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.)
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
update_state
boolean
 —  Adds a state change comment to the linked ticket or bug.
 
resource

iteration

PROPERTIES

project_id
int
 —  id of the project. This field is read only.
 
start
datetime
 —  Iteration start time. This field is read only.
 
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.
 
team_strength
float
 —  Iteration team strength, 1.0 is full-strength.
 
finish
datetime
 —  Iteration finish time. This field is read only.
 
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.
 
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).
 
length
int
 —  Iteration length in weeks.
 
resource

iteration_override

PROPERTIES

project_id
int
 —  id of the project. This field is read only.
 
team_strength
float
 —  Iteration team strength, 1.0 is full-strength.
 
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.
 
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).
 
length
int
 —  Iteration length in weeks.
 
resource

jira_integration

PROPERTIES

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

label

PROPERTIES

project_id
int
 —  id of the project. This field is read only.
 
created_at
datetime
 —  Creation time. This field is read only.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[255]
required  —  The label's name.
 
kind
string
 —  The type of this object: label. This field is read only.
 
id
int
 —  Database id of the label. This field is read only. This field is always returned.
 
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.
 
resource

lighthouse_integration

PROPERTIES

created_at
datetime
 —  Creation time. This field is read only.
 
project_id
int
 —  id of the project. This field is read 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.
 
can_import
boolean
 —  true if it's possible to import stories via this integration. This field is read only.
 
external_api_token
string
required on create  —  Your Lighthouse API token. This field is write only. This field is required on create.
 
is_other
boolean
 —  whether the integration is of type 'other'. 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.)
 
update_comments
boolean
 —  If enabled, comments created in Tracker will be added to the linked Lighthouse ticket.
 
updated_at
datetime
 —  Time of last update. This field is read only.
 
name
string[40]
 —  The name given to the particular external integration in the Project Settings pages.
 
kind
string
 —  The type of this object: lighthouse_integration. This field is read only.
 
active
boolean
 —  True if the integration is currently enabled for use.
 
story_name
string
 —  The name of things imported via the integration. This field is read only.
 
id
int
 —  Database id of the integration. This field is read only. This field is always returned.
 
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.)
 
base_url
string
 —  url used for outgoing web links in stories imported via this integration.
 
update_state
boolean
 —  Adds a state change comment to the linked Lighthouse ticket.
 
resource

me

PROPERTIES

username
string[40]
 —  Authenticated user's optional 'username' for login purposes.
 
email
string[255]
 —  Authenticated user's email.
 
receives_in_app_notifications
boolean
 —  Returns wether or not user is currently receiving in app notifications. This field is read only.
 
initials
string[100]
 —  Authenticated user's initials.
 
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.
 
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.
 
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.
 
name
string[100]
 —  Name of the authenticated user.
 
time_zone
time_zone
 —  The authenticated user's time zone. In API responses, this attribute may be time_zone or time_zone.
 
kind
string
 —  The type of this object: me. This field is read only.
 
id
int
 —  Database id of the authenticated user. This field is read only. This field is always returned.
 
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.)
 
resource

membership_summary

PROPERTIES

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

notification

PROPERTIES

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.
 
read_at
datetime
 —  Time notification was read.
 
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
 
action
string
 —  Action against the resource that triggered notification. This field is read only.
 
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.
 
updated_at
datetime
 —  Update time. 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.
 
kind
string
 —  The type of this object: notification. This field is read only.
 
id
int
 —  Database id of the notification. This field is read only.
 
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.
 
context
string
 —  Context of the notification. For example, if a comment was added, this will contain the comment text. This field is read only.
 
message
string
 —  Message of the notification. This field is read only.
 
resource

other_integration

PROPERTIES

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

person

PROPERTIES

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.
 
name
string[100]
required on create  —  The full name of the person. This field is required on create.
 
kind
string
 —  The type of this object: person. This field is read only.
 
id
int
 —  Database id of the person. This field is read only. This field is always returned.
 
resource

project

PROPERTIES

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 copy of the project (if it stores one) to re-synchronize it with the server. This field is read only.
 
point_scale
string[255]
 —  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".
 
enable_following
boolean
 —  When true, Tracker allows users to follow stories and epics, as well as use @mentions in comments. This field is read only.
 
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.
 
created_at
datetime
 —  Creation time. This field is read only.
 
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.
 
public
boolean
 —  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.
 
membership_ids
List[int]
 —  IDs of the exising memberships. This field is read only. This field is excluded by default. In API responses, this attribute may be membership_ids or memberships.
 
profile_content
string[65535]
 —  A long description of the project. This is displayed on the Project Overview page in the Tracker web UI.
 
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.
 
atom_enabled
boolean
 —  When true, Tracker allows people to subscribe to the Atom (RSS, XML) feed of project changes.
 
account_id
int
 —  The ID number for the account which contains the project.
 
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.
 
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
 
shown_iterations_start_time
datetime
 —  The start time of the first iteration for which stories will be returned as part of t