Overview

The items API allows you to fetch items from your products via the API. It gives access to various methods of filtering, adding blockers, favoriting items, getting and item's comments, etc. Basically, if you need to query for an item, or items, and manipulate them in some manner, this is the API you'd do it with.

/api/products/{product_id}/items.json

GET

Query a product's items by various arguments. If no arguments are provided, it will only return items that are in the backlog and in-progress.

Arguments

type (string) A comma separated list of types. Specify which types of items to return. Only story, task, defect, and test are valid values. (e.g., to return both story and defect, use story,defect)

status (string) A comma separated list of statuses. Only return items that are in the statuses provided. Only someday, backlog, in-progress, completed, and accepted are valid values. (e.g., to return both someday and completed, use someday,completed)

offset (integer, default=0) A zero-index offset from which to start returning results. This, combined with limit, lets you page through all of your items.
limit (integer, default=20) How many items to return in the result. If a value higher than 500 is provided, it will override your value with a value of 500.
order_by (string) Order the result set by a specific metric. The values oldest, newest, priority and favorites are valid values. The arguments oldest and newest are ordered by the items' created timestamp. Additional values are recent, stale, active and abandoned. The recent argument will order by the most recently modified item. The stale argument will order by items modified in ascending order returning items that haven't been modified in a very long time. The active argument will order by most recently active items according to last_activity. Finally the abandoned argument will order by last_activity in ascending order.
assigned_to (integer) The user's id which the item is assigned to.
created_by (integer) The user's id who created the item.
tags (string) A comma separated list of tags (e.g. foo,bar,some other tag,baz).
children (boolean, default=false) Whether or not to include sub-items for matching stories in the response.

Example Response

[
  {
    "status": "backlog",
    "product": {
      "archived": false,
      "id": 1,
      "name": "sprint.ly"
    },
    "progress": {
      "accepted_at": "2013-06-14T22:52:07+00:00",
      "closed_at": "2013-06-14T21:53:43+00:00",
      "started_at": "2013-06-14T21:50:36+00:00"
    },
    "description": "Require people to estimate the score of an item before they can start working on it.",
    "tags": [
      "scoring",
      "backlog"
    ],
    "number": 188,
    "archived": false,
    "title": "Don't let un-scored items out of the backlog.",
    "created_by": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "score": "M",
    "sort": 1,
    "assigned_to": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "type": "task"
  },
  {
    "status": "accepted",
    "product": {
      "archived": false,
      "id": 1,
      "name": "sprint.ly"
    },
    "progress": {
      "accepted_at": "2013-06-14T22:52:07+00:00",
      "closed_at": "2013-06-14T21:53:43+00:00",
      "started_at": "2013-06-14T21:50:36+00:00"
    },
    "description": "",
    "tags": [
      "scoring",
      "backlog"
    ],
    "number": 208,
    "archived": false,
    "title": "Add the ability to reply to comments via email.",
    "created_by": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "score": "M",
    "sort": 2,
    "assigned_to": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "type": "task"
  }
]

Error Codes

404 if assigned_to or created_by are invalid or unknown users.
400 if you provide an invalid type, status, or order_by value.

POST

Create a new item for the given product. This endpoint allows you to create new items within your products. It will return the newly created item on success.

Arguments

type (string, required) What kind of item you'd like to create. Only story, task, defect, and test are valid values.
title (string, required for task, defect, and test) The title of item.
who (string, required for story) The who part of the story.
what (string, required for story) The what part of the story.
why (string, required for story) The why part of the story.
description (string) A description detailing the item. Markdown is allowed.
score (string) The initial score of the document. Only ~, S, M, L, and XL are valid values.
status (string): Status of the new item. Default is backlog. Only backlog, in-progress, completed, and accepted are valid values.
assigned_to (integer) The user's id which the item should assigned to.
tags (string) A comma separated list of tags to assign to the item (e.g. foo,bar,some other tag,baz).

Example Response

 
{
  "status": "backlog",
  "product": {
    "archived": false,
    "id": 1,
    "name": "sprint.ly"
  },
  "description": "Require people to estimate the score of an item before they can start working on it.",
  "tags": [
    "scoring",
    "backlog"
  ],
  "number": 188,
  "archived": false,
  "title": "Don't let un-scored items out of the backlog.",
  "created_by": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "score": "M",
  "assigned_to": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "type": "task"
}

Error Codes

404 if assigned_to or created_by are invalid or unknown users.
400 if you provide an invalid type, status, or order_by value.

/api/products/{product_id}/items/{item_number}.json

GET

Fetch the given item for the given product.

Arguments

This endpoint takes no arguments.

Example Response

{
  "status": "accepted",
  "product": {
    "archived": false,
    "id": 1,
    "name": "sprint.ly"
  },
  "progress": {
    "accepted_at": "2013-06-14T22:52:07+00:00",
    "closed_at": "2013-06-14T21:53:43+00:00",
    "started_at": "2013-06-14T21:50:36+00:00"
  },
  "description": "Require people to estimate the score of an item before they can start working on it.",
  "tags": [
    "scoring",
    "backlog"
  ],
  "number": 188,
  "archived": false,
  "title": "Don't let un-scored items out of the backlog.",
  "created_by": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "score": "M",
  "assigned_to": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "type": "task"
}

POST

Update the specified item.

Arguments

title (string, required for task, defect, and test) The new title of item.
who (string, required for story) The new who part of the story.
what (string, required for story) The new what part of the story.
why (string, required for story) The new why part of the story.
description (string) A new description for the item. Markdown is allowed.
score (string) The initial score of the document. Only ~, S, M, L, and XL are valid values.
status (string): Change the status of the item. Only backlog, in-progress, completed, and accepted are valid values.
assigned_to (integer) The user's id which the item should be reassigned to.
tags (string) A comma separated list of tags to assign to the item (e.g. foo,bar,some other tag,baz). WARNING: This will replace the existing tags with the tags provided.
parent (integer) A valid story number. You cannot make a story a sub-item of another story nor can you have sub-items on non-stories.

Example Response

{
  "status": "accepted",
  "product": {
    "archived": false,
    "id": 1,
    "name": "sprint.ly"
  },
  "progress": {
    "accepted_at": "2013-06-14T22:52:07+00:00",
    "closed_at": "2013-06-14T21:53:43+00:00",
    "started_at": "2013-06-14T21:50:36+00:00"
  },
  "description": "Require people to estimate the score of an item before they can start working on it.",
  "tags": [
    "scoring",
    "backlog"
  ],
  "number": 188,
  "archived": false,
  "title": "Don't let un-scored items out of the backlog.",
  "created_by": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "score": "M",
  "assigned_to": {
    "first_name": "Joe",
    "last_name": "Stump",
    "id": 1,
    "email": "joe@joestump.net"
  },
  "type": "task"
}

/api/products/{product_id}/items/{item_number}/children.json

GET

Returns any child items. NOTE: This only works on items that are of type story as they are the only type of item which are allowed to have child items.

Arguments

This endpoint takes no arguments.

Example Response

 [
  {
    "status": "backlog",
    "product": {
      "archived": false,
      "id": 1,
      "name": "sprint.ly"
    },
    "description": "Require people to estimate the score of an item before they can start working on it.",
    "tags": [
      "scoring",
      "backlog"
    ],
    "number": 188,
    "archived": false,
    "title": "Don't let un-scored items out of the backlog.",
    "created_by": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "score": "M",
    "assigned_to": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "type": "task"
  },
  {
    "status": "accepted",
    "product": {
      "archived": false,
      "id": 1,
      "name": "sprint.ly"
    },
    "description": "",
    "tags": [
      "scoring",
      "backlog"
    ],
    "number": 208,
    "archived": false,
    "title": "Add the ability to reply to comments via email.",
    "created_by": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "score": "M",
    "assigned_to": {
      "first_name": "Joe",
      "last_name": "Stump",
      "id": 1,
      "email": "joe@joestump.net"
    },
    "type": "task"
  }
]

/api/products/{product_id}/items/{item_number}/resort.json

POST

Resorts items within a given status. This only works with items int

Arguments

before — Item number that should be before the to-be-sorted item.
after —Item number that should come after the to-be-sorted item.

Example Response

{
  "assigned_to": {
    "created_at": "2015-03-30T18:01:08+00:00",
    "email": "johndoe+17@sprint.ly",
    "first_name": "John",
    "id": 18,
    "last_login": "2015-03-30T18:01:08+00:00",
    "last_name": "Doe"
  },
  "counts": {
    "blockers": 0,
    "blocking": 0,
    "comments": 0,
    "favorites": 0
  },
  "created_at": "2015-03-30T18:01:08+00:00",
  "created_by": {
    "created_at": "2015-03-30T18:01:08+00:00",
    "email": "johndoe+17@sprint.ly",
    "first_name": "John",
    "id": 18,
    "last_login": "2015-03-30T18:01:08+00:00",
    "last_name": "Doe"
  },
  "deployed_to": [],
  "description": "",
  "email": {
    "discussion": "discussion-10@items.sprint.ly",
    "files": "files-10@items.sprint.ly"
  },
  "last_modified": "2015-03-30T18:01:10+00:00",
  "number": 1,
  "product": {
    "archived": false,
    "id": 4,
    "name": "Awesome Product 3"
  },
  "score": "~",
  "short_url": "http://example.com/i/4/1/",
  "sort": 25,
  "status": "someday",
  "tags": [],
  "title": "",
  "type": "task"
}