All issue endpoints are available off of their parent project.

Project Issue Listing

This endpoint provides a listing of all the issues for the specified project.

/api/projects/{project_id}/issues

GET https://example.sifterapp.com/api/projects/1/issues
 1 {
 2   "issues": [
 3     {
 4       "number": 57,
 5       "category_name": "Enhancement",
 6       "priority": "Trivial",
 7       "subject": "Donec vel neque",
 8       "description": "Nam id libero quis ipsum feugiat elementum. Vivamus vitae mauris ut ipsum mattis malesuada. Sed vel massa. Mauris lobortis. Nunc egestas, massa id scelerisque dapibus, urna mi accumsan purus, vel aliquam nunc sapien eget nisi. Quisque vitae nibh. Proin interdum mollis leo. Fusce sed nisi. Integer ut tortor.",
 9       "milestone_name": null,
10       "opener_name": "Adam Keys",
11       "opener_email": "adam@example.com",
12       "assignee_name": "Garrett Dimon",
13       "assignee_email": "garrett@example.com",
14       "status": "Open",
15       "comment_count": 2,
16       "attachment_count": 1,
17       "created_at": "2010/05/16 19:13:16 +0000",
18       "updated_at": "2010/05/16 19:13:16 +0000",
19       "url": "https://example.sifterapp.com/projects/1/issues/5",
20       "api_url": "https://example.sifterapp.com/api/projects/1/issues/5"
21     },
22     {
23       "number": 63,
24       "category_name": "Bug",
25       "priority": "Trivial",
26       "subject": "Sed lectus nunc, egestas tincidunt",
27       "description": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
28       "milestone_name": null,
29       "opener_name": "Adam Keys",
30       "opener_email": "adam@example.com",
31       "assignee_name": null,
32       "assignee_email": null,
33       "status": "Open",
34       "comment_count": 0,    
35       "attachment_count": 0,
36       "created_at": "2010/05/16 19:13:16 +0000",
37       "updated_at": "2010/05/16 19:13:16 +0000",
38       "url": "https://example.sifterapp.com/projects/1/issues/6",
39       "api_url": "https://example.sifterapp.com/api/projects/1/issues/6"
40     }
41   ],
42   "page": 1,
43   "per_page": 100,
44   "total_pages": 2,
45   "next_page_url": "https://example.sifterapp.com/api/projects/1/issues?per_page=10&page=1",
46   "previous_page_url": null
47 }

Pagination

Issue listings are paginated. Each page includes 100 issues. Use the page parameter to specify the offset to use when paging through results.

/api/projects/{project_id}/issues?per_page=5&page=2

Sorting & Filtering Issues

You can also limit the results of the issue listing to specific statuses or priorities using the s and p query string values respectively.

The following example would only return open issues.

/api/projects/{project_id}/issues?s=1

And this example would only return critical issues.

/api/projects/{project_id}/issues?p=1

You can pass multiple values for statuses and priorities by hyphenating them. For example, the following request would only return critical or high priority issues that are either open or reopened.

/api/projects/{project_id}/issues?p=1-2&s=1-2

Searching Issues

You can search issues using the q parameter. For example, you could search for the word “api”.

/api/projects/{project_id}/issues?q=api

Issue Detail

This endpoint provides the detail for a specific issue.

/api/projects/{project_id}/issues/{issue_id}

GET https://example.sifterapp.com/api/projects/1/issues/5
 1 {
 2   "issue": {
 3     "number": 63,
 4     "subject": "Sed lectus nunc, egestas tincidunt",
 5     "description": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
 6     "priority": "Trivial",
 7     "status": "Open",
 8     "category_name": "Bug",
 9     "milestone_name": null,
10     "opener_name": "Adam Keys",
11     "opener_email": "adam@example.com",
12     "assignee_name": null,
13     "assignee_email": null,
14     "comment_count": 0,
15     "attachment_count": 1,
16     "created_at": "2010/05/16 19:13:16 +0000",
17     "updated_at": "2010/05/16 19:13:16 +0000",
18     "url": "https://example.sifterapp.com/projects/1/issues/5",
19     "api_url": "https://example.sifterapp.com/api/projects/1/issues/5",
20     "comments": [
21       {
22         "body": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
23         "priority": "Trivial",
24         "status": "Open",
25         "category": "Bug",
26         "commenter": "Adam Keys",
27         "commenter_email": "adam@example.com",
28         "opener": "Adam Keys",
29         "opener_email": "adam@example.com",
30         "project": "Rhino",
31         "milestone_name": null,
32         "assignee_name": null,
33         "assignee_email": null,
34         "created_at": "2010/05/16 19:13:16 +0000",
35         "updated_at": "2010/05/16 19:13:16 +0000",
36         "attachments": [
37           {
38             "filename": "1.png",
39             "size": 16895,
40             "height": 294,
41             "width": 320,
42             "url": "http://example.sifterapp.com/attachments/1",
43             "thumb_url": "https://example.s3.amazonaws.com/attachments/1/1_thumb.png?AWSAccessKeyId=123456&Signature=123456&Expires=1351808613"
44           }
45         ]
46       }
47     ]
48   }
49 }

Creating Issues

This endpoint creates new issues for a project.

How it works…

  1. Fetch the project detail, including all the metadata.
  2. Post the new issue using the parameters from the project’s details.
  3. Process the result object or error.

1. Fetch the Project Details

In order to create an issue, you’ll need to obtain all of the available assigness, categories, milestones, statuses, and priorities for your project. You’ll probably want to cache this data using the ETag to periodically refresh your cache.

Let’s look at an example of fetching a project’s data in Sifter. You’ll want to request all the metadata for a project. We can do so with the include parameter. It’s simplest to use include=all, like so:

GET https://example.sifterapp.com/api/projects/1?include=all
  1 {
  2   "project": {
  3     "name": "Sifter",
  4     "archived": false,
  5     "primary_company_name": "Next Update",
  6     "url": "http://example.sifterapp.com/projects/1",
  7     "issues_url": "http://example.sifterapp.com/projects/1/issues",
  8     "milestones_url": "http://example.sifterapp.com/projects/1/milestones",
  9     "api_url": "http://example.sifterapp.com/api/projects/1",
 10     "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues",
 11     "api_milestones_url": "http://example.sifterapp.com/api/projects/1/milestones",
 12     "api_categories_url": "http://example.sifterapp.com/api/projects/1/categories",
 13     "api_people_url": "http://example.sifterapp.com/api/projects/1/people",
 14     "milestones": [
 15       {
 16         "name": "Alpha",
 17         "due_date": "2015-05-01",
 18         "active": true,
 19         "issues_url": "http://example.sifterapp.com/projects/1/issues?m=1",
 20         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=1"
 21       },
 22       {
 23         "name": "Beta",
 24         "due_date": "2015-05-15",
 25         "active": true,
 26         "issues_url": "http://example.sifterapp.com/projects/1/issues?m=2",
 27         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=2"
 28       },
 29       {
 30         "name": "Live",
 31         "due_date": "2015-05-30",
 32         "active": true,
 33         "issues_url": "http://example.sifterapp.com/projects/1/issues?m=3",
 34         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=3"
 35       }
 36     ],
 37     "categories": [
 38       {
 39         "name": "Backend",
 40         "issues_url": "http://example.sifterapp.com/projects/1/issues?c=1",
 41         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=1"
 42       },
 43       {
 44         "name": "Frontend",
 45         "issues_url": "http://example.sifterapp.com/projects/1/issues?c=2",
 46         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=2"
 47       },
 48       {
 49         "name": "Server",
 50         "issues_url": "http://example.sifterapp.com/projects/1/issues?c=3",
 51         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=3"
 52       },
 53       {
 54         "name": "Database",
 55         "issues_url": "http://example.sifterapp.com/projects/1/issues?c=4",
 56         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=4"
 57       }
 58     ],
 59     "people": [
 60       {
 61         "username": "akeys",
 62         "first_name": "Adam",
 63         "last_name": "Keys",
 64         "email": "adam@nextupdate.com",
 65         "issues_url": "http://example.sifterapp.com/projects/1/issues?a=2",
 66         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=2"
 67       },
 68       {
 69         "username": "gdimon",
 70         "first_name": "Garrett",
 71         "last_name": "Dimon",
 72         "email": "garrett@nextupdate.com",
 73         "issues_url": "http://example.sifterapp.com/projects/1/issues?a=1",
 74         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=1"
 75       },
 76       {
 77         "username": "keithmjacobs",
 78         "first_name": "Keith",
 79         "last_name": "Jacobs",
 80         "email": "keith@nextupdate.com",
 81         "issues_url": "http://example.sifterapp.com/projects/1/issues?a=3",
 82         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=3"
 83       },
 84       {
 85         "username": "tdimon",
 86         "first_name": "Tyler",
 87         "last_name": "Dimon",
 88         "email": "tyler@nextupdate.com",
 89         "issues_url": "http://example.sifterapp.com/projects/1/issues?a=4",
 90         "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=4"
 91       }
 92     ],
 93     "priorities": [
 94       {
 95         "name": "Critical"
 96       },
 97       {
 98         "name": "High"
 99       },
100       {
101         "name": "Normal"
102       },
103       {
104         "name": "Low"
105       },
106       {
107         "name": "Trivial"
108       }
109     ],
110     "statuses": [
111       {
112         "name": "Open"
113       },
114       {
115         "name": "Reopened"
116       },
117       {
118         "name": "Resolved"
119       },
120       {
121         "name": "Closed"
122       }
123     ]
124   }
125 }

2. Post the New Issue and Parameters

Once you’ve grabbed all of the relevant options for a project, you can use this to prompt a user for the relevant choices to create an issue or otherwise use it to automatically generate an issue by submitting the relevant parameters.

Parameters

The parameters the create API takes are subject, body, assignee_name, priority_name, milestone_name, and category_name. Subject is required, the rest are optional. For all of the _name parameters, you should use the name attribute for the object in question.
For example, priority_name should be one of “Critical”, “High”, “Normal”, “Low”, or “Trivial”.

Required

Optional

In general, we recommend not setting a status value at all. It is provided as an option to aid in importing issues from other tools.

The endpoint for posting the new issue is:

/api/projects/{project_id}/issues

A successful issue create request might look like this:

curl -X "POST" "http://example.sifterapp.com/api/projects/1/issues" \
  -H "X-Sifter-Token: 343b1b831066a40e308e0af92e0f06f0" \
  -H "Accept: application/json" \
  -d "body=Could you please make it slightly more blue just slightly" \
  -d "priority_name=Normal" \
  -d "subject=Too blue" \
  -d "category_name=Backend" \
  -d "assignee_name=akeys" \
  -d "milestone_name=Bug Fixes"

3. Process the Result or Error

After you post an issue, there’s two possible outcomes. Either the issue is accepted and created, or Sifter will return an error response.

Successful Response with Result Object

On success, the API returns the same JSON as if you fetch a single issue:

POST http://example.sifterapp.com/api/projects/1/issues
subject=Too blue body=Could you please make it slightly more blue just slightly priority_name=Normal category_name=Backend assignee_name=akeys milestone_name=Bug Fixes
 1 {
 2   "issue": {
 3     "number": 2412,
 4     "subject": "Too blue",
 5     "description": "Could you please make it slightly more blue just slightly",
 6     "created_at": "2015-02-04T02:34:48Z",
 7     "updated_at": "2015-02-04T02:34:48Z",
 8     "comment_count": -1,
 9     "attachment_count": 0,
10     "opener_name": "Adam Keys",
11     "opener_email": "adam@nextupdate.com",
12     "category_name": "Backend",
13     "milestone_name": "Bug Fixes",
14     "assignee_name": "Adam Keys",
15     "assignee_email": "adam@nextupdate.com",
16     "priority": "Normal",
17     "status": "Open",
18     "api_url": "http://example.sifterapp.com/api/projects/1/issues/1027641",
19     "url": "http://example.sifterapp.com/projects/1/issues/1027641",
20     "comments": [
21       {
22         "body": "Could you please make it slightly more blue just slightly",
23         "created_at": "2015-02-04T02:34:48Z",
24         "updated_at": "2015-02-04T02:34:48Z",
25         "milestone_name": "Bug Fixes",
26         "assignee_name": "Adam Keys",
27         "assignee_email": "adam@nextupdate.com",
28         "opener_email": "adam@nextupdate.com",
29         "commenter_email": "adam@nextupdate.com",
30         "priority": "Normal",
31         "status": "Open",
32         "project": "Sifter",
33         "opener": "Adam Keys",
34         "commenter": "Adam Keys",
35         "category": "Backend",
36         "attachments": []
37       }
38     ]
39   }
40 }

Error Response

If an invalid issue is posted, an error response is returned with error messages associated with the relevant field:

POST http://example.sifterapp.com/api/projects/1/issues
milestone_name=Bug Fixes111
 1 {
 2   "error": "Invalid issue",
 3   "detail": {
 4     "subject": [
 5       "Subject can't be blank"
 6     ],
 7     "milestone_name": [
 8       "Milestone named Bug Fixes111 not found"
 9     ]
10   }
11 }