REST API endpoints for milestones

List milestones

Lists milestones for a repository.

Parameters for "List milestones"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.

Query parameters
Name, Type, Description
`state` string The state of the milestone. Either `open`, `closed`, or `all`. Default: `open` Can be one of: `open`, `closed`, `all`
`sort` string What to sort results by. Either `due_on` or `completeness`. Default: `due_on` Can be one of: `due_on`, `completeness`
`direction` string The direction of the sort. Either `asc` or `desc`. Default: `asc` Can be one of: `asc`, `desc`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List milestones"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "List milestones"

Request example

get/repos/{owner}/{repo}/milestones

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/milestones

Response

Status: 200

[
  {
    "url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1",
    "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
    "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1/labels",
    "id": 1002604,
    "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
    "number": 1,
    "state": "open",
    "title": "v1.0",
    "description": "Tracking milestone for version 1.0",
    "creator": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://HOSTNAME/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://HOSTNAME/users/octocat/followers",
      "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
      "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
      "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
      "organizations_url": "https://HOSTNAME/users/octocat/orgs",
      "repos_url": "https://HOSTNAME/users/octocat/repos",
      "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
      "received_events_url": "https://HOSTNAME/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "open_issues": 4,
    "closed_issues": 8,
    "created_at": "2011-04-10T20:09:31Z",
    "updated_at": "2014-03-03T18:58:10Z",
    "closed_at": "2013-02-12T13:22:01Z",
    "due_on": "2012-10-09T23:39:01Z"
  }
]

Create a milestone

Creates a milestone.

Parameters for "Create a milestone"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.

Body parameters
Name, Type, Description
`title` string Required The title of the milestone.
`state` string The state of the milestone. Either `open` or `closed`. Default: `open` Can be one of: `open`, `closed`
`description` string A description of the milestone.
`due_on` string The milestone due date. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP response status codes for "Create a milestone"

Status code	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create a milestone"

Request example

post/repos/{owner}/{repo}/milestones

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/milestones \
  -d '{"title":"v1.0","state":"open","description":"Tracking milestone for version 1.0","due_on":"2012-10-09T23:39:01Z"}'

Response

Status: 201

{
  "url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1",
  "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
  "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1/labels",
  "id": 1002604,
  "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
  "number": 1,
  "state": "open",
  "title": "v1.0",
  "description": "Tracking milestone for version 1.0",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "open_issues": 4,
  "closed_issues": 8,
  "created_at": "2011-04-10T20:09:31Z",
  "updated_at": "2014-03-03T18:58:10Z",
  "closed_at": "2013-02-12T13:22:01Z",
  "due_on": "2012-10-09T23:39:01Z"
}

Get a milestone

Gets a milestone using the given milestone number.

Parameters for "Get a milestone"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`milestone_number` integer Required The number that identifies the milestone.

HTTP response status codes for "Get a milestone"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "Get a milestone"

Request example

get/repos/{owner}/{repo}/milestones/{milestone_number}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/milestones/MILESTONE_NUMBER

Response

Status: 200

{
  "url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1",
  "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
  "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1/labels",
  "id": 1002604,
  "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
  "number": 1,
  "state": "open",
  "title": "v1.0",
  "description": "Tracking milestone for version 1.0",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "open_issues": 4,
  "closed_issues": 8,
  "created_at": "2011-04-10T20:09:31Z",
  "updated_at": "2014-03-03T18:58:10Z",
  "closed_at": "2013-02-12T13:22:01Z",
  "due_on": "2012-10-09T23:39:01Z"
}

Update a milestone

Parameters for "Update a milestone"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`milestone_number` integer Required The number that identifies the milestone.

Body parameters
Name, Type, Description
`title` string The title of the milestone.
`state` string The state of the milestone. Either `open` or `closed`. Default: `open` Can be one of: `open`, `closed`
`description` string A description of the milestone.
`due_on` string The milestone due date. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP response status codes for "Update a milestone"

Status code	Description
`200`	OK

Code samples for "Update a milestone"

Request example

patch/repos/{owner}/{repo}/milestones/{milestone_number}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/milestones/MILESTONE_NUMBER \
  -d '{"title":"v1.0","state":"open","description":"Tracking milestone for version 1.0","due_on":"2012-10-09T23:39:01Z"}'

Response

Status: 200

{
  "url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1",
  "html_url": "https://github.com/octocat/Hello-World/milestones/v1.0",
  "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones/1/labels",
  "id": 1002604,
  "node_id": "MDk6TWlsZXN0b25lMTAwMjYwNA==",
  "number": 1,
  "state": "open",
  "title": "v1.0",
  "description": "Tracking milestone for version 1.0",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "open_issues": 4,
  "closed_issues": 8,
  "created_at": "2011-04-10T20:09:31Z",
  "updated_at": "2014-03-03T18:58:10Z",
  "closed_at": "2013-02-12T13:22:01Z",
  "due_on": "2012-10-09T23:39:01Z"
}

Delete a milestone

Deletes a milestone using the given milestone number.

Parameters for "Delete a milestone"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository without the `.git` extension. The name is not case sensitive.
`milestone_number` integer Required The number that identifies the milestone.

HTTP response status codes for "Delete a milestone"

Status code	Description
`204`	No Content
`404`	Resource not found

Code samples for "Delete a milestone"

Request example

delete/repos/{owner}/{repo}/milestones/{milestone_number}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/milestones/MILESTONE_NUMBER

Response

Status: 204