Issues API

The API for GitHub Issues.

Search Issues

/issues/search/:user/:repo/:state/:search_term

Where 'state' is either 'open' or 'closed'.

For example, to search for 'test' in the open issues for defunkt/github-issues repo, you can do this:

$ curl http://github.com/api/v2/json/issues/search/defunkt/github-issues/open/test
{
  "issues": [
    {
      "user": "kfl",
      "gravatar_id": "ad670e0aee0491aaa0a2d201486064b2",
      "updated_at": "2009\/04\/20 03:34:48 -0700",
      "votes": 3,
      "number": 102,
      "position": 1.0,
      "title": "Pressing question-mark does not show help",
      "body": "Pressing the '?'-key does not open the help lightbox.\r\n\r\nHowever, at least the 'j', 'k', and 'c' works (the only ones I've tested).\r\n\r\n* **OS:** Linux, ubuntu 8.04.1\r\n* **Browser:** Firefox 3.08",
      "state": "open",
      "created_at": "2009\/04\/17 12:57:52 -0700"
    }
  ]
}

List a Project's Issues

To see a list of issues for a project,

issues/list/:user/:repo/:state

where :state is either 'open' or 'closed'. You can also search with a label:

issues/list/:user/:repo/label/:label

For example, to see all the open issues I have on the schacon/simplegit project, we can run

$ curl http://github.com/api/v2/json/issues/list/schacon/showoff/open
{
  "issues": [
    {
      "gravatar_id": "b8dbb1987e8e5318584865f880036796",
      "position": 1.0,
      "number": 8,
      "votes": 3,
      "created_at": "2010/01/22 17:56:29 -0800",
      "comments": 10,
      "body": "Maybe this? \r\n\r\n",
      "title": "PDF",
      "updated_at": "2010/12/10 21:48:53 -0800",
      "closed_at": null,
      "user": "defunkt",
      "labels": [
        "feature"
      ],
      "state": "open"
    }
  ]
}

Here's a sample query of all issues labeled "2.0" in defunkt/resque:

$ curl http://github.com/api/v2/json/issues/list/defunkt/resque/label/2.0
{
  "issues": [
    {
      "gravatar_id": "b8dbb1987e8e5318584865f880036796",
      "position": 4.0,
      "number": 5,
      "votes": 1,
      "created_at": "2009/11/03 11:58:19 -0800",
      "comments": 2,
      "body": "You know you want it.",
      "title": "ERB => Mustache",
      "updated_at": "2010/05/13 13:57:53 -0700",
      "closed_at": null,
      "user": "defunkt",
      "labels": [
        "2.0",
        "feature"
      ],
      "state": "open"
    }
  ]
}

View an Issue

To get data on an individual issue by number, run

issues/show/:user/:repo/:number

So to get all the data for a issue #1 in our repo, we can run something like this:

$ curl http://github.com/api/v2/json/issues/show/schacon/showoff/1
{
  "issue": {
    "gravatar_id": "b8dbb1987e8e5318584865f880036796",
    "position": 1.0,
    "number": 1,
    "votes": 0,
    "created_at": "2010/01/21 13:45:59 -0800",
    "comments": 0,
    "body": "http://github.com/defunkt/showoff/commit/jquery14",
    "title": "Upgrade to jQuery 1.4",
    "updated_at": "2010/01/21 14:41:55 -0800",
    "closed_at": "2010/01/21 14:41:55 -0800",
    "user": "defunkt",
    "labels": [

    ],
    "state": "closed"
  }
}

List an Issue's Comments

To get a list of comments made on an issue, run

issues/comments/:user/:repo/:number

So to get all the comments for a issue #1 in our repo, we can run something like this:

$ curl http://github.com/api/v2/json/issues/comments/schacon/showoff/3
{
  "comments": [
    {
      "gravatar_id": "8194993afda83d34c94928134b729276",
      "created_at": "2010/05/05 15:15:53 -0700",
      "body": "Showing off the issues app.",
      "updated_at": "2010/05/05 15:15:53 -0700",
      "id": 230935,
      "user": "280north"
    }
  ]
}

Open and Close Issues

To open a new issue on a project, make a authorized POST to

issues/open/:user/:repo

Where you can provide POST variables:

title
body

It will return the data for the newly created ticket if it is successful. You need to provide your username and token so the system knows who you are and can assign you as the opener of the issue.

For example, I could open a new issue on my simplegit project like this:

$ curl -F 'login=schacon' -F 'token=XXX' -F 'title=new' -F 'body=my ticket' \
  http://github.com/api/v2/json/issues/open/schacon/showoff

To close or reopen an issue, you just need to supply the issue number

issues/close/:user/:repo/:number

issues/reopen/:user/:repo/:number

You need to be logged in via token as well. Here is how I would close the ticket I opened earlier:

$ curl -F 'login=schacon' -F 'token=XXX' \
  http://github.com/api/v2/json/issues/close/schacon/showoff/1

Edit Existing Issues

For the final three calls (edit, label add and label delete) you have to be authorized a collaborator on the project.

To edit an existing issue, you can POST to

issues/edit/:user/:repo/:number

Where you can provide POST variables:

title
body

This will overwrite the title or body of the issue, if you are authorized member of the project.

Listing Labels

You can list available labels for a projects issues with

issues/labels/:user/:repo

For example,

$ curl https://github.com/api/v2/json/issues/labels/schacon/showoff
{
  "labels": [
    "bug",
    "feature"
  ]
}

Add and Remove Labels

To add a label, run

issues/label/add/:user/:repo/:label/:number

This will return a list of the labels currently on that issue, your new one included. If the label is not yet in the system, it will be created.

Here is how I would add the label 'testing' to my first ticket in my simplegit project:

$ curl -F 'login=schacon' -F 'token=XXX' https://github.com/api/v2/json/issues/label/add/schacon/simplegit/testing/1

To remove a label, run:

issues/label/remove/:user/:repo/:label/:number

Again, it will return a list of the labels currently on the issue.

You can also add and remove labels generally by leaving off the Issue number. That will add a label to the system but not attach it to an issue, or remove a label from all issues.

Comment on Issues

You can comment on issues at

/issues/comment/:user/:repo/:id

Simply send it a 'comment' POST variable with the comment you'd like to make. It will attribute the comment to the user that is authenticated. Here is an example:

$ curl -F 'login=schacon' -F 'token=XXX' -F 'comment=this is amazing' \
https://github.com/api/v2/json/issues/comment/defunkt/dunder-mifflin/1
{"comment": {"gravatar_id": "9375a9529679f1b42b567a640d775e7d",
"user": "schacon", "body": "this is amazing", id: 17,
created_at: TIMESTAMP, updated_at: TIMESTAMP}