Issues API

List issues

List all issues across all the authenticated user’s projects including owned projects, member projects, and group projects:

GET /api/v1/issues.json

List all issues across owned and member projects for the authenticated user:

GET /api/v1/user/issues.json

List all issues for a given group for the authenticated user:

GET /api/v1/group/:id/issues.json

Parameters

filter
Optional String
  • assigned: Issues assigned to you (default)
  • created: Issues created by you
  • all: All issues the authenticated user can see
status
Optional String open (default), closed
labels
Optional String list of comma separated Label names. Example: Bug,Feature,Security
sort
Optional String submitted (default), updated.
direction
Optional String asc or desc (default).
since
Optional Integer of a timestamp in Unix time format.

Response:

{
  "issues": [
    {
      "number": "serial number",
      "title": "title",
      "status": "issue status",
      "labels": [
        {
          "name": "name",
          "color": "color"
        }
      ],
      "assignee": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "url": "url to issue data page",
      "body": "body",
      "owner": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "closed_at": "closed at date and time",
      "closed_by": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "created_at": "created at date and time",
      "updated_at": "updated at date and time"
    }
  ],
  "url": "path to issues data"
}

Example:

{
  "issues": [
    {
      "number": "11",
      "title": "new feature",
      "status": "open",
      "labels": [
        {
          "name": "Feature",
          "color": "02e10c"
        }
      ],
      "assignee": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "url": "/api/v1/projects/3/issues/11.json",
      "body": "new cool feature for us",
      "owner": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "closed_at": "1348170705",
      "closed_by": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "created_at": "1348170705",
      "updated_at": "1348168705"
    }
  ],
  "url": "/api/v1/projects/3/issues.json"
}

List issues for a project

GET /api/v1/projects/:id/issues.json

Parameters

status
Optional String open (default), closed
assignee
Optional String
  • String User nickname
  • none for Issues with no assigned User.
  • * for Issues with any assigned User.
creator
Optional String User nickname.
labels
Optional String list of comma separated Label names. Example: Bug,Feature,Security
sort
Optional String submitted (default), updated.
direction
Optional String asc or desc (default).
since
Optional Integer of a timestamp in Unix time format.

Response:

{
  "issues": [
    {
      "number": "serial number",
      "title": "title",
      "status": "issue status",
      "labels": [
        {
          "name": "name",
          "color": "color"
        }
      ],
      "assignee": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "url": "url to issue data page",
      "body": "body",
      "owner": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "closed_at": "closed at date and time",
      "closed_by": {
        "id": "user id",
        "uname": "user uname",
        "name": "user name",
        "url": "api user path"
      },
      "created_at": "created at date and time",
      "updated_at": "updated at date and time"
    }
  ],
  "url": "path to issues data"
}

Example:

{
  "issues": [
    {
      "number": "11",
      "title": "new feature",
      "status": "open",
      "labels": [
        {
          "name": "Feature",
          "color": "02e10c"
        }
      ],
      "assignee": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "url": "/api/v1/projects/3/issues/11.json",
      "body": "new cool feature for us",
      "owner": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "closed_at": "1348170705",
      "closed_by": {
        "id": 1,
        "name": "Ivan Aivazovsky",
        "uname": "ivan_aivazovsky",
        "url": "/api/v1/users/1.json"
      },
      "created_at": "1348170705",
      "updated_at": "1348168705"
    }
  ],
  "url": "/api/v1/projects/3/issues.json"
}

Get a single issue

GET /api/v1/projects/:project_id/issues/:number.json

Parameters:

project_id
Required Integer identifier of current project.
number
Required Integer identifier of current issue.

Response:

{
  "issue": {
    "number": "serial number",
    "title": "title",
    "status": "issue status",
    "labels": [
      {
        "name": "name",
        "color": "color"
      }
    ],
    "assignee": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "url": "url to issue data page",
    "body": "body",
    "owner": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "closed_at": "closed at date and time",
    "closed_by": {
      "id": "user id",
      "uname": "user uname",
      "name": "user name",
      "url": "api user path"
    },
    "created_at": "created at date and time",
    "updated_at": "updated at date and time"
  }
}

Example:

{
  "issue": {
    "number": "11",
    "title": "new feature",
    "status": "open",
    "labels": [
      {
        "name": "Feature",
        "color": "02e10c"
      }
    ],
    "assignee": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "url": "/api/v1/projects/3/issues/11.json",
    "body": "new cool feature for us",
    "owner": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "closed_at": "1348170705",
    "closed_by": {
      "id": 1,
      "name": "Ivan Aivazovsky",
      "uname": "ivan_aivazovsky",
      "url": "/api/v1/users/1.json"
    },
    "created_at": "1348170705",
    "updated_at": "1348168705"
  }
}

Create an issue

Any authenticated user with read access to a project can create an issue.

POST /api/v1/projects/:id/issues.json

Input

title
Required String
body
Required String
assignee_id
Optional Integer - Id for the user that this issue should be assigned to. NOTE: Only users with push access can set the assignee for new issues. The assignee is silently dropped otherwise.
labels
Optional array of strings - Labels to associate with this issue. NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise.

Request:

{
  "issue": {
    "title": "fix security bug",
    "body": "fixed at 123456",
    "status": "closed",
    "assignee_id": 15,
    "labels": [
      "Security",
      "Bug"
    ]
  }
}

Response:

{
  "issue": {
    "number": "issue number (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "issue": {
    "number": 12,
    "message": "Issue has been created successfully"
  }
}

Update a single issue

PUT /api/v1/projects/:id/issues/:number.json

Parameters:

id
Required Integer identifier of current project.
number
Required Integer identifier of current issue.

Input:

title
Optional String
body
Optional String
assignee_id
Optional Integer - Identifier for the user that this issue should be assigned to.
status
Optional String - State of the issue: open or closed.
labels
Optional Array of Strings - Labels to associate with this issue. Pass one or more Labels to replace the set of Labels on this Issue. Send an empty array ([]) to clear all Labels from the Issue.

Request:

{
  "issue": {
    "title": "fix security bug",
    "body": "fixed at 123456",
    "status": "closed",
    "assignee_id": 15,
    "labels": [
      "Security",
      "Bug"
    ]
  }
}

Response:

{
  "issue": {
    "number": "issue number (null if failed)",
    "message": "success or fail message"
  }
}

Example:

{
  "issue": {
    "number": 12,
    "message": "Issue has been updated successfully"
  }
}