From 0988fdffad056bc503b67a29c137a18af269698b Mon Sep 17 00:00:00 2001 From: Paige Paquette Date: Fri, 14 Oct 2016 13:00:08 -0700 Subject: [PATCH 01/62] remove "io" --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ecf1f06..7ef77dd 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ This document outlines the setup and usage of ZenHub's API: a RESTful API with J ## Authentication -### For ZenHub IO users +### For ZenHub users All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. Note: Each user may only have one token, so generating a new token will make any previous tokens invalid. From 41435eb5c669168b84a2581866a13a33d9b33bc6 Mon Sep 17 00:00:00 2001 From: Paige Paquette Date: Fri, 14 Oct 2016 13:18:00 -0700 Subject: [PATCH 02/62] CamelCase everything. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7ef77dd..527cf2a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -# Zenhub API +# ZenHub API This document outlines the setup and usage of ZenHub's API: a RESTful API with JSON responses. @@ -41,7 +41,7 @@ GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). -Issue number is the same as displayed in your GitHub Issues page. For example, to fetch the [Zenhub Public API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. +Issue number is the same as displayed in your GitHub Issues page. For example, to fetch the [ZenHub API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. The endpoint returns that issue's assigned _Time Estimate_ (if applicable), its _Pipeline_ in the Board, an _is epic_ flag (true/false), as well as any _+1s_. @@ -75,7 +75,7 @@ GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). -Issue number is the same one displayed in your GitHub Issues page. For example, to fetch the [Zenhub Public API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. +Issue number is the same one displayed in your GitHub Issues page. For example, to fetch the [ZenHub Public API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. The endpoint returns that issue's events, sorted by most recent. Each event contains the _User ID_ of the person who performed the change, the _Creation Date_ of the event, and _Type_. Type can be either `estimateIssue` or `transferIssue`. Old and new values are included for both event types. From 82a3e9b632769f83ef1836aef6f7b3557983db14 Mon Sep 17 00:00:00 2001 From: Leo Zhang Date: Mon, 7 Nov 2016 11:29:45 -0800 Subject: [PATCH 03/62] Add note that the board doesn't include closed issues --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 527cf2a..4f7d2b2 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ The endpoint returns the Board's pipelines, plus the issues contained within eac Even if the issues are returned in the right order, the _position_ can't be guessed from its index. Notice some issues won't have _position_ – this is because they have not been prioritized on your Board. -Note: Closed issues might take up to one minute to show up in the Closed pipeline. Similarly, reopened issues might take up to one minute to show in the right pipeline. +Note: The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the [GitHub API](https://developer.github.com/v3/issues/#list-issues). Reopened issues might take up to one minute to appear in the correct pipeline. This is an example of returned JSON data: ```json From 218697a297365ed060c0db5ca4be0fe233d23d59 Mon Sep 17 00:00:00 2001 From: Fabio Kenji Date: Tue, 14 Mar 2017 17:39:05 -0300 Subject: [PATCH 04/62] add public endpoints --- .idea/API.iml | 12 + .idea/encodings.xml | 6 + .idea/markdown-navigator.xml | 69 +++++ .../markdown-navigator/profiles_settings.xml | 3 + .idea/modules.xml | 8 + .idea/vcs.xml | 6 + .idea/workspace.xml | 290 ++++++++++++++++++ README.md | 200 +++++++++++- 8 files changed, 591 insertions(+), 3 deletions(-) create mode 100644 .idea/API.iml create mode 100644 .idea/encodings.xml create mode 100644 .idea/markdown-navigator.xml create mode 100644 .idea/markdown-navigator/profiles_settings.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/vcs.xml create mode 100644 .idea/workspace.xml diff --git a/.idea/API.iml b/.idea/API.iml new file mode 100644 index 0000000..24643cc --- /dev/null +++ b/.idea/API.iml @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/encodings.xml b/.idea/encodings.xml new file mode 100644 index 0000000..97626ba --- /dev/null +++ b/.idea/encodings.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/.idea/markdown-navigator.xml b/.idea/markdown-navigator.xml new file mode 100644 index 0000000..573f955 --- /dev/null +++ b/.idea/markdown-navigator.xml @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/markdown-navigator/profiles_settings.xml b/.idea/markdown-navigator/profiles_settings.xml new file mode 100644 index 0000000..57927c5 --- /dev/null +++ b/.idea/markdown-navigator/profiles_settings.xml @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..0ffd292 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/.idea/workspace.xml b/.idea/workspace.xml new file mode 100644 index 0000000..7b5b18d --- /dev/null +++ b/.idea/workspace.xml @@ -0,0 +1,290 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get Epic + Get Epic data + pleaseN + move issue bet + + + + + + + + + + + true + DEFINITION_ORDER + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + project + + + + + + + + + + + + + + + + project + + + true + + + + DIRECTORY + + false + + + + + + + + + 1489510942500 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/README.md b/README.md index 4f7d2b2..424c477 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,11 @@ This document outlines the setup and usage of ZenHub's API: a RESTful API with J repository](#get-the-zenhub-board-data-for-a-repository) - [Get Epics for a repository](#get-epics-for-a-repository) - [Get Epic data](#get-epic-data) + - [Move issue between pipelines](#move-issue-between-pipelines) + - [Set estimate for issue](#set-estimate-for-issue) + - [Convert Issue to Epic](#convert-issue-to-epic) + - [Convert Epic to Issue](#convert-epic-to-issue) + - [Add or remove issues to Epic](#add-or-remove-issues-to-epic) - [API limits](#api-limits) - [Errors](#errors) - [Webhooks](#webhooks) @@ -29,10 +34,10 @@ Please follow the instruction in https://{{zenhub_enterprise_host}}/setup/howto/ ## Endpoints -### Get issue data - Here are the current endpoints available for ZenHub's API. +### Get issue data + ``` GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number @@ -145,7 +150,7 @@ The endpoint returns the Board's pipelines, plus the issues contained within eac Even if the issues are returned in the right order, the _position_ can't be guessed from its index. Notice some issues won't have _position_ – this is because they have not been prioritized on your Board. -Note: The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the [GitHub API](https://developer.github.com/v3/issues/#list-issues). Reopened issues might take up to one minute to appear in the correct pipeline. +Note: The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the [GitHub API](https://developer.github.com/v3/issues/#list-issues). Reopened issues might take up to one minute to appear in the correct pipeline. This is an example of returned JSON data: ```json @@ -312,7 +317,196 @@ NOTE: If an issue is from a different repository than the epic it belongs to, th } ``` +### Move issue between pipelines + +Moves an issue between the pipelines in your repository. + +``` +POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves +``` + +Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). + +`issue_number` is the desired issue or epic that will be moved between pipelines. + +#### Request Body +``` +{ + "pipeline_id": "58bf13aba426771426665e60, + "position": "top" +} +``` + +`pipeline_id` is the id for one of the pipelines in your repository (i.e: `In Progress`, `Done`, `QA`). In order to obtain this id, you can use the [Get the ZenHub Board data for a repository](#get-the-zenhub-board-data-for-a-repository) endpoint. + +`position` can be either a String with the values `top` or `bottom`, which will move the issue to the top or the bottom of the specified pipeline. They can also be specified as numbers (i.e `"position": 3`), which will define the desired slot that the issue should take in the pipeline. This number is based off a zero index, which means 0 is equal to the `top` of the pipeline. + +#### Response +- `200` if the move was successful. + +`Does not return any body in the response.` + +### Set estimate for issue + +Sets an estimate value for an issue. + +``` +PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate +``` + +Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). + +`issue_number` is the issue that we want to set the estimate for. + +#### Request Body + +``` +{ + "estimate": 15 +} +``` + +`estimate` is a number that represents the value that we want to set as estimate. + +#### Response +- `200` if the estimate was set successfully. +``` +{ + "estimate": 15 +} +``` + +`estimate` is the estimate number that was set for the specified issue. + +### Convert Issue to Epic + +Converts an issue to an epic, along with any issues that should be part of it. + +``` +POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic +``` + +Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). + +`issue_number` refers to the issue that we want to convert to an epic. + +#### Request body + +``` +{ + "issues": [ + { + "repo_id": 13550592, + "issue_number": 3 + }, + { + "repo_id": 13550592, + "issue_number": 1 + } + ] +} +``` + +`issues` are the issues that we want to be added to the epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. + +#### Response + +- `200` if the issue was converted to epic successfully + +`Does not return any body in the response.` + +- `400` if the informed issue is already an epic + +### Convert Epic to Issue + +Converts an epic back to an issue. + +``` +POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue +``` + +Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). + +`issue_number` refers to the epic that we want to convert back to an issue. + +#### Response + +- `200` if the epic was converted to issue successfully + +`Does not return any body in the response.` + +### Add or remove issues to Epic + +Bulk add or remove issues to an epic. The result returns which issue was added or removed from the epic. + +``` +POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues +``` + +Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). + +`issue_number` is the epic's issue number which we want to add or remove issues from. + +#### Request Body + +``` +{ + "remove_issues": [ + { + "repo_id": 13550592, + "issue_number": 3 + } + ], + "add_issues": [ + { + "repo_id": 13550592, + "issue_number": 2 + }, + { + "repo_id": 13550592, + "issue_number": 1 + } + ] +} +``` + +`remove_issues` is an array that indicates with issues we want to remove from the specified epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. +`add_issues` is an array that indicates with issues we want to add to the specified epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. + +#### Response + +- `200` if the issue was updated. + +``` +{ + "removed_issues": [ + { + "repo_id": 3887883, + "issue_number": 3 + } + ], + "added_issues": [ + { + "repo_id": 3887883, + "issue_number": 2 + }, + { + "repo_id": 3887883, + "issue_number": 1 + } + ] +} +``` + +`removed_issues` shows which issues were removed in this operation. +`add_issues` shows which issues were added in this operation. +- `404` if the epic does not exist ## API limits From 73dcc87ff8047942d12c45c3094e32a3f390a57f Mon Sep 17 00:00:00 2001 From: Fabio Kenji Date: Tue, 14 Mar 2017 18:07:03 -0300 Subject: [PATCH 05/62] remove webstorm files --- .idea/API.iml | 12 - .idea/encodings.xml | 6 - .idea/markdown-navigator.xml | 69 ----- .../markdown-navigator/profiles_settings.xml | 3 - .idea/modules.xml | 8 - .idea/vcs.xml | 6 - .idea/workspace.xml | 290 ------------------ 7 files changed, 394 deletions(-) delete mode 100644 .idea/API.iml delete mode 100644 .idea/encodings.xml delete mode 100644 .idea/markdown-navigator.xml delete mode 100644 .idea/markdown-navigator/profiles_settings.xml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/vcs.xml delete mode 100644 .idea/workspace.xml diff --git a/.idea/API.iml b/.idea/API.iml deleted file mode 100644 index 24643cc..0000000 --- a/.idea/API.iml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/.idea/encodings.xml b/.idea/encodings.xml deleted file mode 100644 index 97626ba..0000000 --- a/.idea/encodings.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/.idea/markdown-navigator.xml b/.idea/markdown-navigator.xml deleted file mode 100644 index 573f955..0000000 --- a/.idea/markdown-navigator.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/.idea/markdown-navigator/profiles_settings.xml b/.idea/markdown-navigator/profiles_settings.xml deleted file mode 100644 index 57927c5..0000000 --- a/.idea/markdown-navigator/profiles_settings.xml +++ /dev/null @@ -1,3 +0,0 @@ - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 0ffd292..0000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 94a25f7..0000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/.idea/workspace.xml b/.idea/workspace.xml deleted file mode 100644 index 7b5b18d..0000000 --- a/.idea/workspace.xml +++ /dev/null @@ -1,290 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Get Epic - Get Epic data - pleaseN - move issue bet - - - - - - - - - - - true - DEFINITION_ORDER - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - project - - - - - - - - - - - - - - - - project - - - true - - - - DIRECTORY - - false - - - - - - - - - 1489510942500 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file From 2a83fe0c8ac883a2a0b5528bcfb19600ce3bda1a Mon Sep 17 00:00:00 2001 From: Fabio Kenji Date: Thu, 16 Mar 2017 14:06:11 -0300 Subject: [PATCH 06/62] add json tag --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 424c477..27cafc5 100644 --- a/README.md +++ b/README.md @@ -331,7 +331,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith `issue_number` is the desired issue or epic that will be moved between pipelines. #### Request Body -``` +```json { "pipeline_id": "58bf13aba426771426665e60, "position": "top" @@ -372,7 +372,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith #### Response - `200` if the estimate was set successfully. -``` +```json { "estimate": 15 } @@ -395,7 +395,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith #### Request body -``` +```json { "issues": [ { @@ -454,7 +454,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith #### Request Body -``` +```json { "remove_issues": [ { @@ -482,7 +482,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith - `200` if the issue was updated. -``` +```json { "removed_issues": [ { From 4f557101ec33c202d53276378fa23d7f90e6c724 Mon Sep 17 00:00:00 2001 From: Fabio Kenji Date: Thu, 16 Mar 2017 14:07:43 -0300 Subject: [PATCH 07/62] add json tag --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27cafc5..1379143 100644 --- a/README.md +++ b/README.md @@ -362,7 +362,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith #### Request Body -``` +```json { "estimate": 15 } From ae00c435d7d10c8a7c0a2a5f7b51dc78480904ec Mon Sep 17 00:00:00 2001 From: Fabio Kenji Date: Thu, 16 Mar 2017 18:20:21 -0300 Subject: [PATCH 08/62] pretty print json --- README.md | 76 +++++++++++++++++++++++++++---------------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 1379143..31c11ca 100644 --- a/README.md +++ b/README.md @@ -333,8 +333,8 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith #### Request Body ```json { - "pipeline_id": "58bf13aba426771426665e60, - "position": "top" + "pipeline_id":"58bf13aba426771426665e60", + "position":"top" } ``` @@ -364,7 +364,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith ```json { - "estimate": 15 + "estimate":15 } ``` @@ -374,7 +374,7 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith - `200` if the estimate was set successfully. ```json { - "estimate": 15 + "estimate":15 } ``` @@ -397,16 +397,16 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith ```json { - "issues": [ - { - "repo_id": 13550592, - "issue_number": 3 - }, - { - "repo_id": 13550592, - "issue_number": 1 - } - ] + "issues":[ + { + "repo_id":13550592, + "issue_number":3 + }, + { + "repo_id":13550592, + "issue_number":1 + } + ] } ``` @@ -456,22 +456,22 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith ```json { - "remove_issues": [ - { - "repo_id": 13550592, - "issue_number": 3 - } - ], - "add_issues": [ - { - "repo_id": 13550592, - "issue_number": 2 - }, - { - "repo_id": 13550592, - "issue_number": 1 - } - ] + "remove_issues":[ + { + "repo_id":13550592, + "issue_number":3 + } + ], + "add_issues":[ + { + "repo_id":13550592, + "issue_number":2 + }, + { + "repo_id":13550592, + "issue_number":1 + } + ] } ``` @@ -484,20 +484,20 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith ```json { - "removed_issues": [ + "removed_issues":[ { - "repo_id": 3887883, - "issue_number": 3 + "repo_id":3887883, + "issue_number":3 } ], - "added_issues": [ + "added_issues":[ { - "repo_id": 3887883, - "issue_number": 2 + "repo_id":3887883, + "issue_number":2 }, { - "repo_id": 3887883, - "issue_number": 1 + "repo_id":3887883, + "issue_number":1 } ] } From 928f7cea47a5deb0b5214dcabda44a819f44ca80 Mon Sep 17 00:00:00 2001 From: Jurie Wessels Date: Thu, 19 Oct 2017 15:15:29 -0700 Subject: [PATCH 09/62] Restructure and add new public API endpoints --- README.md | 928 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 684 insertions(+), 244 deletions(-) diff --git a/README.md b/README.md index 31c11ca..d727301 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,71 @@ +# Authentication -# ZenHub API - -This document outlines the setup and usage of ZenHub's API: a RESTful API with JSON responses. - -- [Authentication](#authentication) -- [Endpoints](#endpoints) - - [Get issue data](#get-issue-data) - - [Get issue events](#get-issue-events) - - [Get the ZenHub Board data for a - repository](#get-the-zenhub-board-data-for-a-repository) - - [Get Epics for a repository](#get-epics-for-a-repository) - - [Get Epic data](#get-epic-data) - - [Move issue between pipelines](#move-issue-between-pipelines) - - [Set estimate for issue](#set-estimate-for-issue) - - [Convert Issue to Epic](#convert-issue-to-epic) - - [Convert Epic to Issue](#convert-epic-to-issue) - - [Add or remove issues to Epic](#add-or-remove-issues-to-epic) -- [API limits](#api-limits) -- [Errors](#errors) -- [Webhooks](#webhooks) -- [Contact us](#contact-us) - -## Authentication - -### For ZenHub users +## For ZenHub users All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. + Note: Each user may only have one token, so generating a new token will make any previous tokens invalid. -The token is sent in the `X-Authentication-Token` header. For example, using `curl` it'd be `curl -H 'X-Authentication-Token: TOKEN' URL`. Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add ```?access_token=TOKEN``` to any url. +The token is sent in the `X-Authentication-Token` header. + +For example, using `curl` it'd be: + +`curl -H 'X-Authentication-Token: TOKEN' URL`. + +Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add ```?access_token=TOKEN``` to any url. -### For ZenHub Enterprise users + +## For ZenHub Enterprise users Please follow the instruction in https://{{zenhub_enterprise_host}}/setup/howto/api -## Endpoints +# API limits -Here are the current endpoints available for ZenHub's API. +We allow 100 requests per minute to our API. All requests responses include some headers related to this limitation. -### Get issue data +Header | Meaning +------ | ------- +X-RateLimit-Limit | Total number of requests allowed before the reset time +X-RateLimit-Used | Number of requests sent in the current cycle. Will be set to 0 at the reset time. +X-RateLimit-Reset | Time in UTC epoch seconds when the usage gets reset. +To avoid time differences between your computer and our servers, we suggest to use the `Date` header in the response to know exactly when the limit is reset. -``` -GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number -``` +# Errors + +The ZenHub API can return the following errors: -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. +Status Code | Meaning +----------- | ------- +401 | The token is not valid. See [Authentication](#authentication). +403 | Reached request limit to the API. See [API Limits](#api-limits). +404 | Not found. + +# Endpoints + + +## Notes +- `repo_id` i +s the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). -Issue number is the same as displayed in your GitHub Issues page. For example, to fetch the [ZenHub API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. -The endpoint returns that issue's assigned _Time Estimate_ (if applicable), its _Pipeline_ in the Board, an _is epic_ flag (true/false), as well as any _+1s_. +## Issues + +### Get Issue Data + +Get the data for a specific issue. -NOTE: Closed issues might take up to one minute to show up in the Closed pipeline. Similarly, reopened issues might take up to one minute to show in the right pipeline. +**Endpoint:** +`GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number` -Here is an example of returned JSON data: +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required + + +**Example Response:** ```json { "estimate": { @@ -71,20 +84,27 @@ Here is an example of returned JSON data: } ``` -### Get issue events -``` -GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events -``` +**Notes:** -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +- Closed issues might take up to one minute to show up in the Closed pipeline. Similarly, reopened issues might take up to one minute to show in the right pipeline. + +### Get Issue Events -Issue number is the same one displayed in your GitHub Issues page. For example, to fetch the [ZenHub Public API](https://github.com/ZenHubIO/support/issues/172) issue information, the URL would be `https://api.zenhub.io/p1/repositories/13550592/issues/172`. +Get the events for an issue. -The endpoint returns that issue's events, sorted by most recent. Each event contains the _User ID_ of the person who performed the change, the _Creation Date_ of the event, and _Type_. Type can be either `estimateIssue` or `transferIssue`. Old and new values are included for both event types. +**Endpoint:** +`GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events` -Here is an example of returned JSON data: +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required + + +**Example Response:** ```json [ { @@ -136,103 +156,105 @@ Here is an example of returned JSON data: ] ``` -### Get the ZenHub Board data for a repository +**Notes:** -``` -GET https://api.zenhub.io/p1/repositories/:repo_id/board -``` +- Returns issue events, sorted by most recent. +- Each event contains the _User ID_ of the person who performed the change, the _Creation Date_ of the event, and _Type_. +- Type can be either `estimateIssue` or `transferIssue`. Old and new values are included for both event types. -Note: The `repo_id` is the ID of the repository, not the full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. Use [GitHub's API](https://developer.github.com/v3/repos/#get) to find out your repository's ID. -For example, the URL to fetch the [ZenHubIO/support](https://github.com/ZenHubIO/support#boards) board would be `https://api.zenhub.io/p1/repositories/13550592/board`. +### Move Issue between pipelines + +Moves an issue between the pipelines in your repository. + + + +**Endpoint:** +`POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required -The endpoint returns the Board's pipelines, plus the issues contained within each pipeline. It returns each issues' _issue number_, its _position_ in the board, an _is epic_ flag(true/false), and its _Time Estimate_ (if one is assigned). -Even if the issues are returned in the right order, the _position_ can't be guessed from its index. Notice some issues won't have _position_ – this is because they have not been prioritized on your Board. +**Body Parameters:** -Note: The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the [GitHub API](https://developer.github.com/v3/issues/#list-issues). Reopened issues might take up to one minute to appear in the correct pipeline. +|Name|Type|Comments +------------ | ------ | ------- +|`pipeline_id`|String|Required +|`position`|String/Number| Required -This is an example of returned JSON data: +Notes: + +- `pipeline_id` is the id for one of the pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this id, you can use the Get the ZenHub Board data for a repository endpoint. +- `position` can be specified as `top` or `bottom`, or a 0 based position in the pipline such as `1`, which would be the second position in the pipeline. + + + +**Example Request Body** ```json { - "pipelines": [ - { - "name": "New Issues", - "issues": [ - { - "issue_number": 279, - "estimate": { - "value": 40 - }, - "position": 0, - "is_epic": true - }, - { - "issue_number": 142, - "is_epic": false - } - ] - }, - { - "name": "Backlog", - "issues": [ - { - "issue_number": 303, - "estimate": { - "value": 40 - }, - "position": 3, - "is_epic": false - } - ] - }, - { - "name": "To Do", - "issues": [ - { - "issue_number": 380, - "estimate": { - "value": 1 - }, - "position": 0, - "is_epic": true - }, - { - "issue_number": 284, - "position": 2, - "is_epic": false - }, - { - "issue_number": 329, - "estimate": { - "value": 8 - }, - "position": 7, - "is_epic": false - } - ] - } - ] + "pipeline_id":"58bf13aba426771426665e60", + "position":"top" } ``` -### Get Epics for a repository +**Example Response:** + +Status `200` for a successful move. No response body. + +### Set Issue estimate +**Endpoint:** +`PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required + + +**Body Parameters:** +|Name|Type|Comments +------------ | ------ | ------- +|`estimate`|Number|Required, number representing estimate value + +**Example Request Body** +```json +{ + "estimate":15 +} ``` -GET https://api.zenhub.io/p1/repositories/:repo_id/epics + +**Example Response:** +```json +{ + "estimate":15 +} ``` -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +## Epics + +### Get Epics for a repository -For example, the URL to fetch the [ZenHubIO/support](https://github.com/ZenHubIO/issues) epics would be `https://api.zenhub.io/p1/repositories/13550592/epics`. +Get all Epics for a repository -The endpoint returns an array of the repository's epics. For each epic, _issue number_, _repository ID_, and the _GitHub issue URL_ is provided. +**Endpoint:** +`GET https://api.zenhub.io/p1/repositories/:repo_id/epics` -Note: If an issue is only an issue belonging to an epic (and not a parent epic), it is not considered an epic and won't be included in the return array. +**URL Parameters:** -Here is an example of returned JSON data: +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required + +**Example Response:** ```json { "epic_issues": [ @@ -250,20 +272,32 @@ Here is an example of returned JSON data: } ``` -### Get Epic data +**Notes:** -``` -GET https://api.zenhub.io/p1/repositories/:repo_id/epics/:epic_id -``` -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +- The endpoint returns an array of the repository's epics. For each epic, issue number, repository ID, and the GitHub issue URL is provided. +- If an issue is only an issue belonging to an epic (and not a parent epic), it is not considered an epic and won't be included in the return array. + +### Get Epic Data + +Get the data for an Epic + +Endpoint description -`epic_id` is the GitHub issue number (you may fetch the list of epics using **Get Epics for a repository** endpoint). +**Endpoint:** +`GET https://api.zenhub.io/p1/repositories/:repo_id/epics/:epic_id` -The endpoint returns the _total estimate epic value_ (the sum of the epic's estimate, plus all estimates contained within it), the _estimate of the epic_, _pipeline name_ the epic is in, and the _issues_ belonging to it. For each issue belonging to the epic, its _issue number_, _repo id_, _estimate value_, _is epic_ flag (true/false) are provided; in addition, if the issue is from the same repository as the epic, the ZenHub Board's _pipeline name_ (from the repo the epic is in) is attached. +**URL Parameters:** -NOTE: If an issue is from a different repository than the epic it belongs to, the pipeline name is not attached. +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`epic_id`|Number|Required, Github issue number +Notes: + +- `epic_id` Is the GitHub issue number. You may fetch the list of epics using Get Epics for a repository endpoint. + +**Example Response:** ```json { "total_epic_estimates": { @@ -317,84 +351,68 @@ NOTE: If an issue is from a different repository than the epic it belongs to, th } ``` -### Move issue between pipelines - -Moves an issue between the pipelines in your repository. +**Notes:** -``` -POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves -``` +The endpoint returns : -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +- the total estimate epic value (the sum of the epic's estimate, plus all estimates contained within it) +- the estimate of the epic +- pipeline name the epic is in +- issues belonging to the epic. -`issue_number` is the desired issue or epic that will be moved between pipelines. +For each issue belonging to the epic: -#### Request Body -```json -{ - "pipeline_id":"58bf13aba426771426665e60", - "position":"top" -} -``` +- issue number +- repo id +- estimate value +- epic flag (true/false) +- if the issue is from the same repository as the epic, the ZenHub Board's pipeline name (from the repo the epic is in) is attached. -`pipeline_id` is the id for one of the pipelines in your repository (i.e: `In Progress`, `Done`, `QA`). In order to obtain this id, you can use the [Get the ZenHub Board data for a repository](#get-the-zenhub-board-data-for-a-repository) endpoint. -`position` can be either a String with the values `top` or `bottom`, which will move the issue to the top or the bottom of the specified pipeline. They can also be specified as numbers (i.e `"position": 3`), which will define the desired slot that the issue should take in the pipeline. This number is based off a zero index, which means 0 is equal to the `top` of the pipeline. +### Convert an Epic to an Issue -#### Response -- `200` if the move was successful. +Converts an epic back to an issue. -`Does not return any body in the response.` +**Endpoint:** +`POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue` -### Set estimate for issue +**URL Parameters:** -Sets an estimate value for an issue. +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required, the issue to be converted -``` -PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate -``` -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +**Example Response:** -`issue_number` is the issue that we want to set the estimate for. +- 200 if the issue was converted to epic successfully -#### Request Body +Does not return any body in the response. -```json -{ - "estimate":15 -} -``` - -`estimate` is a number that represents the value that we want to set as estimate. +### Convert Issue to Epic -#### Response -- `200` if the estimate was set successfully. -```json -{ - "estimate":15 -} -``` +Converts an issue to an epic, along with any issues that should be part of it. -`estimate` is the estimate number that was set for the specified issue. +**Endpoint:** +`POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic` -### Convert Issue to Epic +**URL Parameters:** -Converts an issue to an epic, along with any issues that should be part of it. +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required -``` -POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic -``` -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +**Body Parameters:** -`issue_number` refers to the issue that we want to convert to an epic. +|Name|Type|Comments +------------ | ------ | ------- +|`issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` -#### Request body +**Example Request Body** ```json { "issues":[ @@ -410,50 +428,31 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith } ``` -`issues` are the issues that we want to be added to the epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. +**Response** -#### Response +Does not return any body in the response. - `200` if the issue was converted to epic successfully +- `400` if the supplied issue is already an epic -`Does not return any body in the response.` - -- `400` if the informed issue is already an epic - -### Convert Epic to Issue - -Converts an epic back to an issue. - -``` -POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue -``` - -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). - -`issue_number` refers to the epic that we want to convert back to an issue. - -#### Response - -- `200` if the epic was converted to issue successfully - -`Does not return any body in the response.` ### Add or remove issues to Epic Bulk add or remove issues to an epic. The result returns which issue was added or removed from the epic. -``` -POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues -``` - -Please note: `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). +**Endpoint:** +`POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues` -`issue_number` is the epic's issue number which we want to add or remove issues from. +**URL Parameters:** -#### Request Body +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`issue_number`|Number|Required +|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` +|`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` +**Example Request Body** ```json { "remove_issues":[ @@ -475,13 +474,11 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith } ``` -`remove_issues` is an array that indicates with issues we want to remove from the specified epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. -`add_issues` is an array that indicates with issues we want to add to the specified epic. They should be specified as an array containing objects with the issue's `repo_id` and `issue_number`. -#### Response - -- `200` if the issue was updated. +- `remove_issues` is an array that indicates with issues we want to remove from the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. +- `add_issues` is an array that indicates with issues we want to add to the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. +**Example Response:** ```json { "removed_issues":[ @@ -503,35 +500,478 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith } ``` -`removed_issues` shows which issues were removed in this operation. -`add_issues` shows which issues were added in this operation. +- `removed_issues` shows which issues were removed in this operation. +- `add_issues` shows which issues were added in this operation. -- `404` if the epic does not exist +**Notes:** +- Returns a `404` if the epic does not exist -## API limits -We allow 100 requests per minute to our API. All requests responses include some headers related to this limitation. +## Boards -Header | Meaning ------- | ------- -X-RateLimit-Limit | Total number of requests allowed before the reset time -X-RateLimit-Used | Number of requests sent in the current cycle. Will be set to 0 at the reset time. -X-RateLimit-Reset | Time in UTC epoch seconds when the usage gets reset. +### Get the ZenHub Board data for a repository -To avoid time differences between your computer and our servers, we suggest to use the `Date` header in the response to know exactly when the limit is reset. +**Endpoint:** +`GET https://api.zenhub.io/p1/repositories/:repo_id/board` -## Errors +**URL Parameters:** -The ZenHub API can return the following errors: +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required -Status Code | Meaning ------------ | ------- -401 | The token is not valid. See [Authentication](#authentication). -403 | Reached request limit to the API. See [API Limits](#api-limits). -404 | Not found. +**Example Response:** +```json +{ + "pipelines": [ + { + "name": "New Issues", + "issues": [ + { + "issue_number": 279, + "estimate": { + "value": 40 + }, + "position": 0, + "is_epic": true + }, + { + "issue_number": 142, + "is_epic": false + } + ] + }, + { + "name": "Backlog", + "issues": [ + { + "issue_number": 303, + "estimate": { + "value": 40 + }, + "position": 3, + "is_epic": false + } + ] + }, + { + "name": "To Do", + "issues": [ + { + "issue_number": 380, + "estimate": { + "value": 1 + }, + "position": 0, + "is_epic": true + }, + { + "issue_number": 284, + "position": 2, + "is_epic": false + }, + { + "issue_number": 329, + "estimate": { + "value": 8 + }, + "position": 7, + "is_epic": false + } + ] + } + ] +} +``` + +**Notes:** + +- The endpoint returns the Board's pipelines, plus the issues contained within each pipeline. It returns each issues' issue number, its position in the board, an is epic flag(true/false), and its Estimate (if one is assigned). + +- Even if the issues are returned in the right order, the position can't be guessed from its index. Notice some issues won't have position – this is because they have not been prioritized on your Board. + +- The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the GitHub API. Reopened issues might take up to one minute to appear in the correct pipeline. + + +## Milestones + +### Set milestone start date +**Endpoint:** +`POST /p1/repositories/:repo_id/milestones/:milestone_number/start_date` + +**Request Headers:** +`x-authentication-token: ` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`milestone_id`|Number|Required + +**Body Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`start_date`| ISO8601 date string|Required + +**Example Request Body** +```json +{ "start_date": "2010-11-13T01:38:56.842Z" } +``` + +**Example Response:** +```json +{ "start_date": "2010-11-13T01:38:56.842Z" } +``` + +**Notes:** +* The controller for this endpoint will fetch the milestone from Github to validate that the Github milestone `due_on` date is greater than the Zenhub milestone `start_date`. Some issues have been observed with the Github interaction when trying to share controller code across both the public and private APIs. See Issue [9282](https://github.com/axiomzen/zenhub/issues/9289). -## Webhooks +### Get milestone start date +**Endpoint:** +`GET /p1/repositories/:repo_id/milestones/:milestone_number/start_date` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required +|`milestone_id`|Number|Required + +**Example Response:** +```json +{ "start_date":"2010-11-13T01:38:56.842Z" } +``` + +## Release Reports +### Create a release report +**Endpoint:** + `POST /p1/repositories/:repo_id/reports/release` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|repo_id|number|Required, use the repo id, not the repo name + +**Body Parameters:** +|`title`|string|Required +|`description`| String| Optional +|`start_date`| ISO8601 date string|Optional +|`desired_end_date`| ISO8601 date string| Optional +|`repositories`| [repository ids]| Optional + +**Example Request Body** +```json +{ + "title": "Great title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00Z", + "desired_end_date": "2007-01-01T00:00:00Z", + "repositories": [103707262] +} +``` + +**Example Response:** + +```json +{ + "release_id": "59dff4f508399a35a276a1ea", + "title": "Great title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00.000Z", + "desired_end_date": "2007-01-01T00:00:00.000Z", + "created_at": "2017-10-12T23:04:21.795Z", + "closed_at": null, + "state": "open", + "repositories": [ + 103707262 + ] +} +``` + +**Notes:** +* The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a board. +* Additional repository ids can be passed in the body `repositories` param. +* Any boards not associated with the URL `repo_id` param, but associated with repositories in the request body `repositories` param will also be associated to the release report. +* The user creating the release requires permission to the repositories in the request. + +### Get a release report +**Endpoint:** +`GET /p1/reports/release/:release_id` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`release_id`|String|Required + +**Example Response:** +```json +{ + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 105683718 + ] +} +``` + +### Get release reports for a repository +**Endpoint:** + `GET /p1/repositories/:repo_id/reports/releases` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|Number|Required + +**Example Response:** +```json +[ + { + "release_id": "59cbf2fde010f7a5207406e8", + "title": "Great title for release 1", + "description": "Great description for release", + "start_date": "2000-10-10T00:00:00.000Z", + "desired_end_date": "2010-10-10T00:00:00.000Z", + "created_at": "2017-09-27T18:50:37.418Z", + "closed_at": null, + "state": "open" + }, + { + "release_id": "59cbf2fde010f7a5207406e8", + "title": "Great title for release 2", + "description": "Great description for release", + "start_date": "2000-10-10T00:00:00.000Z", + "desired_end_date": "2010-10-10T00:00:00.000Z", + "created_at": "2017-09-27T18:50:37.418Z", + "closed_at": null, + "state": "open" + } +] +``` + + +### Edit a release report +**Endpoint:** + `PATCH /p1/reports/release/:release_id` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|release_id|String|Required + +**Body Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|title|String|Required +|description|String|Optional +|start_date|ISO8601 date string|Optional +|desired_end_date| ISO8601 date string| Optional +|state| String|Optional, 'open' or 'closed' + +**Example Request Body** +```json +{ + "title": "Amazing title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00Z", + "desired_end_date": "2007-01-01T00:00:00Z", + "state": "closed" +} +``` + +**Example Response:** +```json +{ + "release_id": "59d3d6438b3f16667f9e7174", + "title": "Amazing title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00.000Z", + "desired_end_date": "2007-01-01T00:00:00.000Z", + "created_at": "2017-10-03T18:26:11.700Z", + "closed_at": "2017-10-03T18:26:11.700Z", + "state": "closed", + "repositories": [ + 105683567, + 105683718 + ] +} +``` + +### Add workspaces to a release report +**Endpoint:** + `PATCH /p1/reports/release/:release_id/workspaces/add` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|release_id|String|Required + +**Body Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|repositories|[Number]|Required, an array of repo ids + +**Example Request Body** +```json +{ + "repositories": [103707262] +} +``` + + +**Example Response:** +```json +{ + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 103707262, + 105683718 + ] +} +``` + + +### Remove workspaces from release report +**Endpoint:** + `PATCH /p1/reports/release/:release_id/workspaces/remove` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|release_id|String|Required + +**Body Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|repositories|[Number]|Required, an array of repo ids + +**Example Request Body** +```json +{ + "repositories": [103707262] +} +``` + + +**Example Response:** +```json +{ + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 105683718 + ] +} +``` + + + +## Release Report Issues +### Get all issues for a release report +**Endpoint:** + `GET /p1/reports/release/:release_id/issues` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|release_id|String|Required + +**Example Response:** +```json +[ + { + "repo_id": 103707262, + "issue_number": 2 + }, + { + "repo_id": 103707262, + "issue_number": 3 + } +] +``` + +### Add or remove issues to/from a release report +**Endpoint:** + `PATCH /p1/reports/release/:release_id/issues` + +**URL Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|release_id|String|Required + +**Body Parameters:** + +|Name|Type|Comments +------------ | ------ | ------- +|add_issues|[Number]|Required, an array of repo ids +|remove_issues|[{repo_id: Number, issue_number: Number}]|Required, an array of Objects with `repo_id` and `issue_number` + +*Both the add_issues and remove_issues keys are required, but can be and empty array when not used.* + +**Example Body Request:** +```json +{ + "add_issues": [ + { + "repo_id": 103707262, + "issue_number": 3 + } + ], + "remove_issues": [] +} +``` + + +**Example Response:** +```json +{ + "added": [ + { + "repo_id": 103707262, + "issue_number": 3 + } + ], + "removed": [] +} +``` + +**Note:** +Adding and removing issues can be done in the same request by populating with the `add_issues` and `remove_issues` keys. + +### Webhooks You can use our webhooks to fetch or store your ZenHub data, in real time, across services like Slack, Gitter, Spark, HipChat, or something custom! @@ -610,7 +1050,7 @@ Our custom webhook sends a POST request to your webhook for multiple events that As an example, here's a simple Node/Express app that would be able receive the webhooks(using ngrok): -``` +```javascript var express = require('express'); var http = require('http'); var bodyParser = require('body-parser'); @@ -629,6 +1069,6 @@ app.post('*', function( req, res) { ``` -## Contact us +# Contact us We'd love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support](https://github.com/ZenHubIO/support/issues#boards) repo or find us on [Twitter](http://www.twitter.com/zenhubio). From dc96bb3f4552f6583bb1b405e69bc595e2f08652 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Thu, 19 Oct 2017 15:49:47 -0700 Subject: [PATCH 10/62] Minor formatting changes --- README.md | 307 +++++++++++++++++++++++++++--------------------------- 1 file changed, 155 insertions(+), 152 deletions(-) diff --git a/README.md b/README.md index d727301..c1d4096 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,30 @@ # Authentication -## For ZenHub users All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. -Note: Each user may only have one token, so generating a new token will make any previous tokens invalid. +**Note**: Each user may only have one token, so generating a new token will invalidate previously created tokens. -The token is sent in the `X-Authentication-Token` header. +The token is sent in the `X-Authentication-Token` header. For example, using `curl` it'd be: -For example, using `curl` it'd be: - -`curl -H 'X-Authentication-Token: TOKEN' URL`. +```sh +curl -H 'X-Authentication-Token: TOKEN' URL +``` -Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add ```?access_token=TOKEN``` to any url. +Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add `?access_token=TOKEN` to any URL. +## For ZenHub Enterprise -## For ZenHub Enterprise users -Please follow the instruction in https://{{zenhub_enterprise_host}}/setup/howto/api +Please follow the instructions in `https:///setup/howto/api` -# API limits +# API Rate Limit -We allow 100 requests per minute to our API. All requests responses include some headers related to this limitation. +We allow a maximum of 100 requests per minute to our API. All requests responses include some headers related to this limitation. Header | Meaning ------ | ------- -X-RateLimit-Limit | Total number of requests allowed before the reset time -X-RateLimit-Used | Number of requests sent in the current cycle. Will be set to 0 at the reset time. -X-RateLimit-Reset | Time in UTC epoch seconds when the usage gets reset. +`X-RateLimit-Limit` | Total number of requests allowed before the reset time +`X-RateLimit-Used` | Number of requests sent in the current cycle. Will be set to 0 at the reset time. +`X-RateLimit-Reset` | Time in UTC epoch seconds when the usage gets reset. To avoid time differences between your computer and our servers, we suggest to use the `Date` header in the response to know exactly when the limit is reset. @@ -35,18 +34,15 @@ The ZenHub API can return the following errors: Status Code | Meaning ----------- | ------- -401 | The token is not valid. See [Authentication](#authentication). -403 | Reached request limit to the API. See [API Limits](#api-limits). -404 | Not found. +`401` | The token is not valid. See [Authentication](#authentication). +`403` | Reached request limit to the API. See [API Limits](#api-rate-limits). +`404` | Not found. # Endpoints +##### Notes -## Notes -- `repo_id` i -s the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/support` repository is `13550592`. -To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get). - +- `repo_id` Is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). ## Issues @@ -54,18 +50,19 @@ To find out the ID of your repository, use [GitHub's API](https://developer.gith Get the data for a specific issue. -**Endpoint:** +##### Endpoint + `GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required +##### Example Response -**Example Response:** ```json { "estimate": { @@ -84,19 +81,19 @@ Get the data for a specific issue. } ``` +##### Notes -**Notes:** - -- Closed issues might take up to one minute to show up in the Closed pipeline. Similarly, reopened issues might take up to one minute to show in the right pipeline. +- Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. ### Get Issue Events Get the events for an issue. -**Endpoint:** +##### Endpoint + `GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -104,7 +101,8 @@ Get the events for an issue. |`issue_number`|Number|Required -**Example Response:** +##### Example Response + ```json [ { @@ -156,85 +154,83 @@ Get the events for an issue. ] ``` -**Notes:** - -- Returns issue events, sorted by most recent. -- Each event contains the _User ID_ of the person who performed the change, the _Creation Date_ of the event, and _Type_. -- Type can be either `estimateIssue` or `transferIssue`. Old and new values are included for both event types. +##### Notes +- Returns issue events, sorted by creation time, most recent first. +- Each event contains the _User ID_ of the user who performed the change, the _Creation Date_ of the event, and the event _Type_. +- Type can be either `estimateIssue` or `transferIssue`. The values before and after the event are included in the event data. ### Move Issue between pipelines Moves an issue between the pipelines in your repository. +##### Endpoint - -**Endpoint:** `POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required - -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`pipeline_id`|String|Required |`position`|String/Number| Required -Notes: +##### Notes - `pipeline_id` is the id for one of the pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this id, you can use the Get the ZenHub Board data for a repository endpoint. -- `position` can be specified as `top` or `bottom`, or a 0 based position in the pipline such as `1`, which would be the second position in the pipeline. +- `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the pipeline. - - -**Example Request Body** +##### Example Request Body ```json { - "pipeline_id":"58bf13aba426771426665e60", - "position":"top" + "pipeline_id": "58bf13aba426771426665e60", + "position": "top" } ``` -**Example Response:** +##### Example Response Status `200` for a successful move. No response body. -### Set Issue estimate -**Endpoint:** +### Set Issue Estimate + +##### Endpoint + `PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required - -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`estimate`|Number|Required, number representing estimate value -**Example Request Body** +##### Example Request + ```json { - "estimate":15 + "estimate": 15 } ``` -**Example Response:** +##### Example Response + ```json { - "estimate":15 + "estimate": 15 } ``` @@ -244,17 +240,17 @@ Status `200` for a successful move. No response body. Get all Epics for a repository -**Endpoint:** +##### Endpoint + `GET https://api.zenhub.io/p1/repositories/:repo_id/epics` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required - -**Example Response:** +##### Example Response ```json { "epic_issues": [ @@ -272,32 +268,31 @@ Get all Epics for a repository } ``` -**Notes:** +##### Notes -- The endpoint returns an array of the repository's epics. For each epic, issue number, repository ID, and the GitHub issue URL is provided. -- If an issue is only an issue belonging to an epic (and not a parent epic), it is not considered an epic and won't be included in the return array. +- The endpoint returns an array of the repository’s epics. For each epic, issue number, repository ID, and the GitHub issue URL is provided. +- If an issue is only an issue belonging to an epic (and not a parent epic), it is not considered an epic and won’t be included in the return array. ### Get Epic Data -Get the data for an Epic +Get the data for an Epic issue. -Endpoint description +##### Endpoint -**Endpoint:** `GET https://api.zenhub.io/p1/repositories/:repo_id/epics/:epic_id` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`epic_id`|Number|Required, Github issue number -Notes: +##### Notes -- `epic_id` Is the GitHub issue number. You may fetch the list of epics using Get Epics for a repository endpoint. +- `epic_id` is the GitHub issue number. You may fetch the list of epics using Get Epics for a repository endpoint. -**Example Response:** +##### Example Response ```json { "total_epic_estimates": { @@ -351,11 +346,11 @@ Notes: } ``` -**Notes:** +##### Notes -The endpoint returns : +The endpoint returns: -- the total estimate epic value (the sum of the epic's estimate, plus all estimates contained within it) +- the total estimate epic value (the sum of the epic’s estimate, plus all estimates contained within it) - the estimate of the epic - pipeline name the epic is in - issues belonging to the epic. @@ -366,17 +361,17 @@ For each issue belonging to the epic: - repo id - estimate value - epic flag (true/false) -- if the issue is from the same repository as the epic, the ZenHub Board's pipeline name (from the repo the epic is in) is attached. - +- if the issue is from the same repository as the epic, the ZenHub Board’s pipeline name (from the repo the epic is in) is attached. ### Convert an Epic to an Issue Converts an epic back to an issue. -**Endpoint:** +##### Endpoint + `POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -384,7 +379,7 @@ Converts an epic back to an issue. |`issue_number`|Number|Required, the issue to be converted -**Example Response:** +##### Example Response - 200 if the issue was converted to epic successfully @@ -394,25 +389,25 @@ Does not return any body in the response. Converts an issue to an epic, along with any issues that should be part of it. -**Endpoint:** +##### Endpoint + `POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required - -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` +##### Example Request Body -**Example Request Body** ```json { "issues":[ @@ -428,22 +423,22 @@ Converts an issue to an epic, along with any issues that should be part of it. } ``` -**Response** +##### Response Does not return any body in the response. - `200` if the issue was converted to epic successfully - `400` if the supplied issue is already an epic - ### Add or remove issues to Epic Bulk add or remove issues to an epic. The result returns which issue was added or removed from the epic. -**Endpoint:** +##### Endpoint + `POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -452,33 +447,36 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` |`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` -**Example Request Body** +##### Example Request Body + ```json { - "remove_issues":[ + "remove_issues": [ { - "repo_id":13550592, - "issue_number":3 + "repo_id": 13550592, + "issue_number": 3 } ], - "add_issues":[ + "add_issues": [ { - "repo_id":13550592, - "issue_number":2 + "repo_id": 13550592, + "issue_number": 2 }, { - "repo_id":13550592, - "issue_number":1 + "repo_id": 13550592, + "issue_number": 1 } ] } ``` +##### Notes - `remove_issues` is an array that indicates with issues we want to remove from the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. - `add_issues` is an array that indicates with issues we want to add to the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. -**Example Response:** +##### Example Response + ```json { "removed_issues":[ @@ -500,27 +498,27 @@ Bulk add or remove issues to an epic. The result returns which issue was added o } ``` +##### Notes + - `removed_issues` shows which issues were removed in this operation. - `add_issues` shows which issues were added in this operation. - -**Notes:** - Returns a `404` if the epic does not exist - ## Boards ### Get the ZenHub Board data for a repository -**Endpoint:** +##### Endpoint + `GET https://api.zenhub.io/p1/repositories/:repo_id/board` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -**Example Response:** +##### Example Response ```json { "pipelines": [ @@ -596,20 +594,20 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ## Milestones ### Set milestone start date -**Endpoint:** +##### Endpoint `POST /p1/repositories/:repo_id/milestones/:milestone_number/start_date` **Request Headers:** `x-authentication-token: ` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`milestone_id`|Number|Required -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -620,7 +618,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o { "start_date": "2010-11-13T01:38:56.842Z" } ``` -**Example Response:** +##### Example Response ```json { "start_date": "2010-11-13T01:38:56.842Z" } ``` @@ -630,33 +628,33 @@ Bulk add or remove issues to an epic. The result returns which issue was added o * The controller for this endpoint will fetch the milestone from Github to validate that the Github milestone `due_on` date is greater than the Zenhub milestone `start_date`. Some issues have been observed with the Github interaction when trying to share controller code across both the public and private APIs. See Issue [9282](https://github.com/axiomzen/zenhub/issues/9289). ### Get milestone start date -**Endpoint:** +##### Endpoint `GET /p1/repositories/:repo_id/milestones/:milestone_number/start_date` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`milestone_id`|Number|Required -**Example Response:** +##### Example Response ```json { "start_date":"2010-11-13T01:38:56.842Z" } ``` ## Release Reports ### Create a release report -**Endpoint:** +##### Endpoint `POST /p1/repositories/:repo_id/reports/release` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |repo_id|number|Required, use the repo id, not the repo name -**Body Parameters:** +##### Body Parameters |`title`|string|Required |`description`| String| Optional |`start_date`| ISO8601 date string|Optional @@ -674,7 +672,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o } ``` -**Example Response:** +##### Example Response ```json { @@ -699,16 +697,16 @@ Bulk add or remove issues to an epic. The result returns which issue was added o * The user creating the release requires permission to the repositories in the request. ### Get a release report -**Endpoint:** +##### Endpoint `GET /p1/reports/release/:release_id` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -**Example Response:** +##### Example Response ```json { "release_id": "59d3cd520a430a6344fd3bdb", @@ -726,16 +724,16 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` ### Get release reports for a repository -**Endpoint:** +##### Endpoint `GET /p1/repositories/:repo_id/reports/releases` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -**Example Response:** +##### Example Response ```json [ { @@ -763,16 +761,16 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ### Edit a release report -**Endpoint:** +##### Endpoint `PATCH /p1/reports/release/:release_id` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |release_id|String|Required -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -793,7 +791,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o } ``` -**Example Response:** +##### Example Response ```json { "release_id": "59d3d6438b3f16667f9e7174", @@ -812,16 +810,16 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` ### Add workspaces to a release report -**Endpoint:** +##### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/add` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |release_id|String|Required -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -835,7 +833,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` -**Example Response:** +##### Example Response ```json { "release_id": "59d3cd520a430a6344fd3bdb", @@ -855,16 +853,16 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ### Remove workspaces from release report -**Endpoint:** +##### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/remove` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |release_id|String|Required -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -878,7 +876,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` -**Example Response:** +##### Example Response ```json { "release_id": "59d3cd520a430a6344fd3bdb", @@ -898,17 +896,19 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ## Release Report Issues + ### Get all issues for a release report -**Endpoint:** + +##### Endpoint `GET /p1/reports/release/:release_id/issues` -**URL Parameters:** +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |release_id|String|Required -**Example Response:** +##### Example Response ```json [ { @@ -923,16 +923,18 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` ### Add or remove issues to/from a release report -**Endpoint:** - `PATCH /p1/reports/release/:release_id/issues` -**URL Parameters:** +##### Endpoint + +`PATCH /p1/reports/release/:release_id/issues` + +##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |release_id|String|Required -**Body Parameters:** +##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -941,30 +943,31 @@ Bulk add or remove issues to an epic. The result returns which issue was added o *Both the add_issues and remove_issues keys are required, but can be and empty array when not used.* -**Example Body Request:** +##### Example Body Request + ```json { "add_issues": [ { - "repo_id": 103707262, - "issue_number": 3 + "repo_id": 103707262, + "issue_number": 3 } ], "remove_issues": [] } ``` +##### Example Response -**Example Response:** ```json { - "added": [ - { - "repo_id": 103707262, - "issue_number": 3 - } - ], - "removed": [] + "added": [ + { + "repo_id": 103707262, + "issue_number": 3 + } + ], + "removed": [] } ``` From d0c4cd0adf992a28c819f2e2efdc7ab0a9ef26af Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:07:01 -0700 Subject: [PATCH 11/62] Minor formatting changes --- README.md | 526 +++++++++++++++++++++++++----------------------------- 1 file changed, 241 insertions(+), 285 deletions(-) diff --git a/README.md b/README.md index c1d4096..e50d12c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Authentication +# Overview -All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. +This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). -**Note**: Each user may only have one token, so generating a new token will invalidate previously created tokens. +## Authentication -The token is sent in the `X-Authentication-Token` header. For example, using `curl` it'd be: +All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL @@ -12,11 +12,12 @@ curl -H 'X-Authentication-Token: TOKEN' URL Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add `?access_token=TOKEN` to any URL. -## For ZenHub Enterprise +##### Note -Please follow the instructions in `https:///setup/howto/api` +- Each user may only have one token, so generating a new token will invalidate previously created tokens. +- For ZenHub Enterprise users, please follow the instructions in `https:///setup/howto/api` -# API Rate Limit +## API Rate Limit We allow a maximum of 100 requests per minute to our API. All requests responses include some headers related to this limitation. @@ -28,21 +29,21 @@ Header | Meaning To avoid time differences between your computer and our servers, we suggest to use the `Date` header in the response to know exactly when the limit is reset. -# Errors +## Errors The ZenHub API can return the following errors: -Status Code | Meaning +Status Code | Description ----------- | ------- `401` | The token is not valid. See [Authentication](#authentication). `403` | Reached request limit to the API. See [API Limits](#api-rate-limits). `404` | Not found. -# Endpoints +# Endpoint Reference ##### Notes -- `repo_id` Is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub's API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). +- `repo_id` Is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). ## Issues @@ -160,7 +161,7 @@ Get the events for an issue. - Each event contains the _User ID_ of the user who performed the change, the _Creation Date_ of the event, and the event _Type_. - Type can be either `estimateIssue` or `transferIssue`. The values before and after the event are included in the event data. -### Move Issue between pipelines +### Move an Issue Between Pipelines Moves an issue between the pipelines in your repository. @@ -185,9 +186,10 @@ Moves an issue between the pipelines in your repository. ##### Notes - `pipeline_id` is the id for one of the pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this id, you can use the Get the ZenHub Board data for a repository endpoint. -- `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the pipeline. +- `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. ##### Example Request Body + ```json { "pipeline_id": "58bf13aba426771426665e60", @@ -221,17 +223,13 @@ Status `200` for a successful move. No response body. ##### Example Request ```json -{ - "estimate": 15 -} +{ "estimate": 15 } ``` ##### Example Response ```json -{ - "estimate": 15 -} +{ "estimate": 15 } ``` ## Epics @@ -251,6 +249,7 @@ Get all Epics for a repository |`repo_id`|Number|Required ##### Example Response + ```json { "epic_issues": [ @@ -270,8 +269,8 @@ Get all Epics for a repository ##### Notes -- The endpoint returns an array of the repository’s epics. For each epic, issue number, repository ID, and the GitHub issue URL is provided. -- If an issue is only an issue belonging to an epic (and not a parent epic), it is not considered an epic and won’t be included in the return array. +- The endpoint returns an array of the repository’s epics. For each Epic, issue number, repository ID, and the GitHub issue URL is provided. +- If an issue is only an issue belonging to an Epic (and not a parent Epic), it is not considered an Epic and won’t be included in the return array. ### Get Epic Data @@ -295,31 +294,23 @@ Get the data for an Epic issue. ##### Example Response ```json { - "total_epic_estimates": { - "value": 60 - }, + "total_epic_estimates": { "value": 60 }, + "estimate": { "value": 10 }, + "pipeline": { "name": "Backlog" }, "issues": [ { "issue_number": 3161, "is_epic": true, "repo_id": 1099029, - "estimate": { - "value": 40 - }, - "pipeline": { - "name": "New Issues" - } + "estimate": { "value": 40 }, + "pipeline": { "name": "New Issues" } }, { "issue_number": 2, "is_epic": false, "repo_id": 1234567, - "estimate": { - "value": 10 - }, - "pipeline": { - "name": "New Issues" - } + "estimate": { "value": 10 }, + "pipeline": { "name": "New Issues" } }, { "issue_number": 1, @@ -336,13 +327,7 @@ Get the data for an Epic issue. "is_epic": true, "repo_id": 9876543 } - ], - "estimate": { - "value": 10 - }, - "pipeline": { - "name": "Backlog" - } + ] } ``` @@ -350,22 +335,22 @@ Get the data for an Epic issue. The endpoint returns: -- the total estimate epic value (the sum of the epic’s estimate, plus all estimates contained within it) -- the estimate of the epic -- pipeline name the epic is in -- issues belonging to the epic. +- the total estimate Epic value (the sum of the Epic’s Estimate, plus all Estimates contained within it) +- the Estimate of the Epic +- the Pipeline name the Epic is in +- issues belonging to the Epic -For each issue belonging to the epic: +For each issue belonging to the Epic: - issue number - repo id -- estimate value -- epic flag (true/false) -- if the issue is from the same repository as the epic, the ZenHub Board’s pipeline name (from the repo the epic is in) is attached. +- Estimate value +- Is epic flag (`true` or `false`) +- if the issue is from the same repository as the Epic, the ZenHub Board’s Pipeline name (from the repo the Epic is in) is attached. ### Convert an Epic to an Issue -Converts an epic back to an issue. +Converts an Epic back to a regular issue. ##### Endpoint @@ -376,18 +361,17 @@ Converts an epic back to an issue. |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -|`issue_number`|Number|Required, the issue to be converted - +|`issue_number`|Number|Required, the number of the issue to be converted ##### Example Response -- 200 if the issue was converted to epic successfully +- `200` if the issue was converted to epic successfully Does not return any body in the response. ### Convert Issue to Epic -Converts an issue to an epic, along with any issues that should be part of it. +Converts an issue to an Epic, along with any issues that should be part of it. ##### Endpoint @@ -404,21 +388,15 @@ Converts an issue to an epic, along with any issues that should be part of it. |Name|Type|Comments ------------ | ------ | ------- -|`issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` +|`issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` ##### Example Request Body ```json { - "issues":[ - { - "repo_id":13550592, - "issue_number":3 - }, - { - "repo_id":13550592, - "issue_number":1 - } + "issues": [ + { "repo_id": 13550592, "issue_number": 3 }, + { "repo_id": 13550592, "issue_number": 1 } ] } ``` @@ -427,12 +405,12 @@ Converts an issue to an epic, along with any issues that should be part of it. Does not return any body in the response. -- `200` if the issue was converted to epic successfully -- `400` if the supplied issue is already an epic +- `200` if the issue was converted to Epic successfully +- `400` if the supplied issue is already an Epic ### Add or remove issues to Epic -Bulk add or remove issues to an epic. The result returns which issue was added or removed from the epic. +Bulk add or remove issues to an Epic. The result returns which issue was added or removed from the Epic. ##### Endpoint @@ -444,56 +422,38 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required -|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` -|`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, an Array of Objects with `repo_id` and `issue_number` +|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` ##### Example Request Body ```json { "remove_issues": [ - { - "repo_id": 13550592, - "issue_number": 3 - } + { "repo_id": 13550592, "issue_number": 3 } ], "add_issues": [ - { - "repo_id": 13550592, - "issue_number": 2 - }, - { - "repo_id": 13550592, - "issue_number": 1 - } + { "repo_id": 13550592, "issue_number": 2 }, + { "repo_id": 13550592, "issue_number": 1 } ] } ``` ##### Notes -- `remove_issues` is an array that indicates with issues we want to remove from the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. -- `add_issues` is an array that indicates with issues we want to add to the specified epic. They should be specified as an array containing objects with the issue's repo_id and issue_number. +- `remove_issues` is an array that indicates with issues we want to remove from the specified Epic. They should be specified as an array containing objects with the issue’s `repo_id` and `issue_number`. +- `add_issues` is an array that indicates with issues we want to add to the specified Epic. They should be specified as an array containing objects with the issue’s `repo_id` and `issue_number`. ##### Example Response ```json { "removed_issues":[ - { - "repo_id":3887883, - "issue_number":3 - } + { "repo_id": 3887883, "issue_number": 3 } ], "added_issues":[ - { - "repo_id":3887883, - "issue_number":2 - }, - { - "repo_id":3887883, - "issue_number":1 - } + { "repo_id": 3887883, "issue_number": 2 }, + { "repo_id": 3887883, "issue_number": 1 } ] } ``` @@ -502,7 +462,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o - `removed_issues` shows which issues were removed in this operation. - `add_issues` shows which issues were added in this operation. -- Returns a `404` if the epic does not exist +- Returns a `404` if the Epic doesn’t exist ## Boards @@ -519,6 +479,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |`repo_id`|Number|Required ##### Example Response + ```json { "pipelines": [ @@ -527,9 +488,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o "issues": [ { "issue_number": 279, - "estimate": { - "value": 40 - }, + "estimate": { "value": 40 }, "position": 0, "is_epic": true }, @@ -544,9 +503,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o "issues": [ { "issue_number": 303, - "estimate": { - "value": 40 - }, + "estimate": { "value": 40 }, "position": 3, "is_epic": false } @@ -557,9 +514,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o "issues": [ { "issue_number": 380, - "estimate": { - "value": 1 - }, + "estimate": { "value": 1 }, "position": 0, "is_epic": true }, @@ -570,9 +525,7 @@ Bulk add or remove issues to an epic. The result returns which issue was added o }, { "issue_number": 329, - "estimate": { - "value": 8 - }, + "estimate": { "value": 8 }, "position": 7, "is_epic": false } @@ -582,23 +535,19 @@ Bulk add or remove issues to an epic. The result returns which issue was added o } ``` -**Notes:** - -- The endpoint returns the Board's pipelines, plus the issues contained within each pipeline. It returns each issues' issue number, its position in the board, an is epic flag(true/false), and its Estimate (if one is assigned). - -- Even if the issues are returned in the right order, the position can't be guessed from its index. Notice some issues won't have position – this is because they have not been prioritized on your Board. - -- The Board returned by the endpoint doesn't include closed issues. To get closed issues for a repository, you can use the GitHub API. Reopened issues might take up to one minute to appear in the correct pipeline. +##### Notes +- The endpoint returns the Board’s pipelines, plus the issues contained within each Pipeline. It returns the issue number of each issue, their position in the Board, the is Epic flag (`true` or `false`), and its Estimate (if set). +- Even if the issues are returned in the right order, the position can’t be guessed from its index. Note that some issues won’t have position – this is because they have not been prioritized on your Board. +- The Board returned by the endpoint doesn’t include closed issues. To get closed issues for a repository, you can use the GitHub API. Reopened issues might take up to one minute to appear in the correct Pipeline. ## Milestones ### Set milestone start date + ##### Endpoint -`POST /p1/repositories/:repo_id/milestones/:milestone_number/start_date` -**Request Headers:** -`x-authentication-token: ` +`POST /p1/repositories/:repo_id/milestones/:milestone_number/start_date` ##### URL Parameters @@ -613,22 +562,22 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ------------ | ------ | ------- |`start_date`| ISO8601 date string|Required -**Example Request Body** +##### Example Request Body + ```json { "start_date": "2010-11-13T01:38:56.842Z" } ``` ##### Example Response + ```json { "start_date": "2010-11-13T01:38:56.842Z" } ``` -**Notes:** - -* The controller for this endpoint will fetch the milestone from Github to validate that the Github milestone `due_on` date is greater than the Zenhub milestone `start_date`. Some issues have been observed with the Github interaction when trying to share controller code across both the public and private APIs. See Issue [9282](https://github.com/axiomzen/zenhub/issues/9289). - ### Get milestone start date + ##### Endpoint + `GET /p1/repositories/:repo_id/milestones/:milestone_number/start_date` ##### URL Parameters @@ -639,36 +588,45 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |`milestone_id`|Number|Required ##### Example Response + ```json -{ "start_date":"2010-11-13T01:38:56.842Z" } +{ "start_date": "2010-11-13T01:38:56.842Z" } ``` ## Release Reports -### Create a release report + +### Create a Release Report + ##### Endpoint - `POST /p1/repositories/:repo_id/reports/release` + +`POST /p1/repositories/:repo_id/reports/release` ##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- -|repo_id|number|Required, use the repo id, not the repo name +|`repo_id`|Number|Required ##### Body Parameters -|`title`|string|Required + +|Name|Type|Comments +------------ | ------ | ------- +|`title`|String|Required |`description`| String| Optional |`start_date`| ISO8601 date string|Optional |`desired_end_date`| ISO8601 date string| Optional -|`repositories`| [repository ids]| Optional +|`repositories`| [Number]| Optional -**Example Request Body** +##### Example Request Body ```json { "title": "Great title", "description": "Amazing description", "start_date": "2007-01-01T00:00:00Z", "desired_end_date": "2007-01-01T00:00:00Z", - "repositories": [103707262] + "repositories": [ + 103707262 + ] } ``` @@ -676,28 +634,31 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ```json { - "release_id": "59dff4f508399a35a276a1ea", - "title": "Great title", - "description": "Amazing description", - "start_date": "2007-01-01T00:00:00.000Z", - "desired_end_date": "2007-01-01T00:00:00.000Z", - "created_at": "2017-10-12T23:04:21.795Z", - "closed_at": null, - "state": "open", - "repositories": [ - 103707262 - ] + "release_id": "59dff4f508399a35a276a1ea", + "title": "Great title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00.000Z", + "desired_end_date": "2007-01-01T00:00:00.000Z", + "created_at": "2017-10-12T23:04:21.795Z", + "closed_at": null, + "state": "open", + "repositories": [ + 103707262 + ] } ``` -**Notes:** -* The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a board. -* Additional repository ids can be passed in the body `repositories` param. -* Any boards not associated with the URL `repo_id` param, but associated with repositories in the request body `repositories` param will also be associated to the release report. -* The user creating the release requires permission to the repositories in the request. +##### Notes + +- The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a Board +- Additional repository ids can be passed in the body `repositories` parameter +- Any Boards not associated with the URL `repo_id` parameter, but associated with repositories in the request body `repositories` parameter will also be associated to the Release Report. +- The user creating the release requires push permission to the repositories in the request. + +### Get a Release Report -### Get a release report ##### Endpoint + `GET /p1/reports/release/:release_id` ##### URL Parameters @@ -707,25 +668,28 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |`release_id`|String|Required ##### Example Response + ```json { - "release_id": "59d3cd520a430a6344fd3bdb", - "title": "Test release", - "description": "", - "start_date": "2017-10-01T19:00:00.000Z", - "desired_end_date": "2017-10-03T19:00:00.000Z", - "created_at": "2017-10-03T17:48:02.701Z", - "closed_at": null, - "state": "open", - "repositories": [ - 105683718 - ] + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 105683718 + ] } ``` -### Get release reports for a repository +### Get Release Reports for a repository + ##### Endpoint - `GET /p1/repositories/:repo_id/reports/releases` + +`GET /p1/repositories/:repo_id/reports/releases` ##### URL Parameters @@ -734,53 +698,56 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |`repo_id`|Number|Required ##### Example Response + ```json [ - { - "release_id": "59cbf2fde010f7a5207406e8", - "title": "Great title for release 1", - "description": "Great description for release", - "start_date": "2000-10-10T00:00:00.000Z", - "desired_end_date": "2010-10-10T00:00:00.000Z", - "created_at": "2017-09-27T18:50:37.418Z", - "closed_at": null, - "state": "open" - }, - { - "release_id": "59cbf2fde010f7a5207406e8", - "title": "Great title for release 2", - "description": "Great description for release", - "start_date": "2000-10-10T00:00:00.000Z", - "desired_end_date": "2010-10-10T00:00:00.000Z", - "created_at": "2017-09-27T18:50:37.418Z", - "closed_at": null, - "state": "open" - } + { + "release_id": "59cbf2fde010f7a5207406e8", + "title": "Great title for release 1", + "description": "Great description for release", + "start_date": "2000-10-10T00:00:00.000Z", + "desired_end_date": "2010-10-10T00:00:00.000Z", + "created_at": "2017-09-27T18:50:37.418Z", + "closed_at": null, + "state": "open" + }, + { + "release_id": "59cbf2fde010f7a5207406e8", + "title": "Great title for release 2", + "description": "Great description for release", + "start_date": "2000-10-10T00:00:00.000Z", + "desired_end_date": "2010-10-10T00:00:00.000Z", + "created_at": "2017-09-27T18:50:37.418Z", + "closed_at": null, + "state": "open" + } ] ``` +### Edit a Release Report -### Edit a release report ##### Endpoint - `PATCH /p1/reports/release/:release_id` + +`PATCH /p1/reports/release/:release_id` ##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- -|release_id|String|Required +|`release_id`|String|Required ##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|title|String|Required -|description|String|Optional -|start_date|ISO8601 date string|Optional -|desired_end_date| ISO8601 date string| Optional -|state| String|Optional, 'open' or 'closed' +|`title`|String|Required +|`description`|String|Optional +|`start_date`|ISO8601 date string|Optional +|`desired_end_date`| ISO8601 date string| Optional +|`state`| String|Optional, 'open' or 'closed' + +##### Example Request Body -**Example Request Body** ```json { "title": "Amazing title", @@ -792,137 +759,132 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ``` ##### Example Response + ```json { - "release_id": "59d3d6438b3f16667f9e7174", - "title": "Amazing title", - "description": "Amazing description", - "start_date": "2007-01-01T00:00:00.000Z", - "desired_end_date": "2007-01-01T00:00:00.000Z", - "created_at": "2017-10-03T18:26:11.700Z", - "closed_at": "2017-10-03T18:26:11.700Z", - "state": "closed", - "repositories": [ - 105683567, - 105683718 - ] + "release_id": "59d3d6438b3f16667f9e7174", + "title": "Amazing title", + "description": "Amazing description", + "start_date": "2007-01-01T00:00:00.000Z", + "desired_end_date": "2007-01-01T00:00:00.000Z", + "created_at": "2017-10-03T18:26:11.700Z", + "closed_at": "2017-10-03T18:26:11.700Z", + "state": "closed", + "repositories": [ + 105683567, + 105683718 + ] } ``` -### Add workspaces to a release report +### Add Workspaces to a Release Report + ##### Endpoint - `PATCH /p1/reports/release/:release_id/workspaces/add` + +`PATCH /p1/reports/release/:release_id/workspaces/add` ##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- -|release_id|String|Required +|`release_id`|String|Required ##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|repositories|[Number]|Required, an array of repo ids +|`repositories`|[Number]|Required, an array of repo ids + +##### Example Request Body -**Example Request Body** ```json -{ - "repositories": [103707262] -} +{ "repositories": [ 103707262 ] } ``` - ##### Example Response + ```json { - "release_id": "59d3cd520a430a6344fd3bdb", - "title": "Test release", - "description": "", - "start_date": "2017-10-01T19:00:00.000Z", - "desired_end_date": "2017-10-03T19:00:00.000Z", - "created_at": "2017-10-03T17:48:02.701Z", - "closed_at": null, - "state": "open", - "repositories": [ - 103707262, - 105683718 - ] + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 103707262, + 105683718 + ] } ``` +### Remove Workspaces from Release Report -### Remove workspaces from release report ##### Endpoint - `PATCH /p1/reports/release/:release_id/workspaces/remove` + +`PATCH /p1/reports/release/:release_id/workspaces/remove` ##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- -|release_id|String|Required +|`release_id`|String|Required ##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|repositories|[Number]|Required, an array of repo ids +|`repositories`|[Number]|Required, array of repository IDs + +##### Example Request Body -**Example Request Body** ```json -{ - "repositories": [103707262] -} +{ "repositories": [ 103707262 ] } ``` - ##### Example Response ```json { - "release_id": "59d3cd520a430a6344fd3bdb", - "title": "Test release", - "description": "", - "start_date": "2017-10-01T19:00:00.000Z", - "desired_end_date": "2017-10-03T19:00:00.000Z", - "created_at": "2017-10-03T17:48:02.701Z", - "closed_at": null, - "state": "open", - "repositories": [ - 105683718 - ] + "release_id": "59d3cd520a430a6344fd3bdb", + "title": "Test release", + "description": "", + "start_date": "2017-10-01T19:00:00.000Z", + "desired_end_date": "2017-10-03T19:00:00.000Z", + "created_at": "2017-10-03T17:48:02.701Z", + "closed_at": null, + "state": "open", + "repositories": [ + 105683718 + ] } ``` - - ## Release Report Issues -### Get all issues for a release report +### Get all the Issues for a Release Report ##### Endpoint - `GET /p1/reports/release/:release_id/issues` + +`GET /p1/reports/release/:release_id/issues` ##### URL Parameters |Name|Type|Comments ------------ | ------ | ------- -|release_id|String|Required +|`release_id`|String|Required ##### Example Response + ```json [ - { - "repo_id": 103707262, - "issue_number": 2 - }, - { - "repo_id": 103707262, - "issue_number": 3 - } + { "repo_id": 103707262, "issue_number": 2 }, + { "repo_id": 103707262, "issue_number": 3 } ] ``` -### Add or remove issues to/from a release report +### Add or Remove Issues to or from a Release Report ##### Endpoint @@ -932,26 +894,25 @@ Bulk add or remove issues to an epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|release_id|String|Required +|`release_id`|String|Required ##### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|add_issues|[Number]|Required, an array of repo ids -|remove_issues|[{repo_id: Number, issue_number: Number}]|Required, an array of Objects with `repo_id` and `issue_number` +|`add_issues`|[Number]|Required, an array of repo ids +|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` + +##### Note -*Both the add_issues and remove_issues keys are required, but can be and empty array when not used.* +- Both the `add_issues` and `remove_issues` keys are required, but can be and empty array when not used ##### Example Body Request ```json { "add_issues": [ - { - "repo_id": 103707262, - "issue_number": 3 - } + { "repo_id": 103707262, "issue_number": 3 } ], "remove_issues": [] } @@ -962,17 +923,15 @@ Bulk add or remove issues to an epic. The result returns which issue was added o ```json { "added": [ - { - "repo_id": 103707262, - "issue_number": 3 - } + { "repo_id": 103707262, "issue_number": 3 } ], "removed": [] } ``` -**Note:** -Adding and removing issues can be done in the same request by populating with the `add_issues` and `remove_issues` keys. +##### Note + +- Adding and removing issues can be done in the same request by populating with the `add_issues` and `remove_issues` keys. ### Webhooks @@ -982,7 +941,7 @@ To set up an integration, head on over to our [Dashboard](https://dashboard.zenh For instructions, you'll notice the `How to create a webhook` link changes dynamically based on the service you select. Simply choose a repository with which to connect, add an optional description, paste your webhook, and click "Add" to save your new integration. -ZenHub +ZenHub integrations ### Custom webhooks @@ -1050,28 +1009,25 @@ Our custom webhook sends a POST request to your webhook for multiple events that } ``` - -As an example, here's a simple Node/Express app that would be able receive the webhooks(using ngrok): +As an example, here's a simple Node/Express app that would be able receive the webhooks (using ngrok): ```javascript -var express = require('express'); -var http = require('http'); -var bodyParser = require('body-parser'); -var app = express(); +var express = require('express'); +var http = require('http'); +var bodyParser = require('body-parser'); +var app = express(); -http.createServer(app).listen('6000', function(){ +http.createServer(app).listen('6000', function() { console.log('Listening on 6000'); }); app.use(bodyParser()); - -app.post('*', function( req, res) { +app.post('*', function(req, res) { console.dir(req.body); }); ``` - # Contact us -We'd love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support](https://github.com/ZenHubIO/support/issues#boards) repo or find us on [Twitter](http://www.twitter.com/zenhubio). +We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support](https://github.com/ZenHubIO/support/issues#boards) repo or find us on [Twitter](http://www.twitter.com/zenhubio). From 276bb78369ae75352e197a8cfc240cc89feb01fc Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:12:20 -0700 Subject: [PATCH 12/62] Add table of contents --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e50d12c..9630c50 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,15 @@ This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). +[Overview](https://github.com/ZenHubIO/API/tree/master#overview) + +- [Authentication](https://github.com/ZenHubIO/API/tree/master#authentication) +- [API Rate Limit](https://github.com/ZenHubIO/API/tree/master#api-rate-limit) +- [Errors](https://github.com/ZenHubIO/API/tree/master#errors) + +[Endpoint Reference](https://github.com/ZenHubIO/API/tree/master#endpoint-reference) +- [Issues](https://github.com/ZenHubIO/API/tree/master#issues) + ## Authentication All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: @@ -12,7 +21,7 @@ curl -H 'X-Authentication-Token: TOKEN' URL Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add `?access_token=TOKEN` to any URL. -##### Note +#### Notes - Each user may only have one token, so generating a new token will invalidate previously created tokens. - For ZenHub Enterprise users, please follow the instructions in `https:///setup/howto/api` From 14e5373e9bc3fa30d4e4adb04d71c3c88ecc903a Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:22:41 -0700 Subject: [PATCH 13/62] Complete table of contents --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 9630c50..a302389 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,39 @@ This describes the current version of the public ZenHub API. If you have any que - [Errors](https://github.com/ZenHubIO/API/tree/master#errors) [Endpoint Reference](https://github.com/ZenHubIO/API/tree/master#endpoint-reference) + - [Issues](https://github.com/ZenHubIO/API/tree/master#issues) + - [Get Issue Data](https://github.com/ZenHubIO/API/tree/master#get-issue-data) + - [Get Issue Events](https://github.com/ZenHubIO/API/tree/master#get-issue-events) + - [Move an Issue Between Pipelines](https://github.com/ZenHubIO/API/tree/master#move-an-issue-between-pipelines) + - [Set Issue Estimate](https://github.com/ZenHubIO/API/tree/master#set-issue-estimate) +- [Epics](https://github.com/ZenHubIO/API/tree/master#epics) + - [Get Epics for a Repository](https://github.com/ZenHubIO/API/tree/master#get-epics-for-a-repository) + - [Get Epic Data](https://github.com/ZenHubIO/API/tree/master#get-epic-data) + - [Convert an Epic to an Issue](https://github.com/ZenHubIO/API/tree/master#convert-an-epic-to-an-issue) + - [Convert an Issue to Epic](https://github.com/ZenHubIO/API/tree/master#convert-issue-to-epic) + - [Add or Remove Issues from an Epic](https://github.com/ZenHubIO/API/tree/master#add-or-remove-issues-to-epic) +- [Boards](https://github.com/ZenHubIO/API/tree/master#boards) + - [Get Board Data for a Repository](https://github.com/ZenHubIO/API/tree/master#get-the-zenhub-board-data-for-a-repository) +- [Milestones](https://github.com/ZenHubIO/API/tree/master#milestones) + - [Set the Milestone Start Date](https://github.com/ZenHubIO/API/tree/master#set-milestone-start-date) + - [Get the Milestone Start Date](https://github.com/ZenHubIO/API/tree/master#get-milestone-start-date) +- [Release Reports](https://github.com/ZenHubIO/API/tree/master#release-reports) + - [Create a Release Report](https://github.com/ZenHubIO/API/tree/master#create-a-release-report) + - [Get a Release Report](https://github.com/ZenHubIO/API/tree/master#get-a-release-report) + - [Get Release Reports for a Repository](https://github.com/ZenHubIO/API/tree/master#get-release-reports-for-a-repository) + - [Edit a Release Report](https://github.com/ZenHubIO/API/tree/master#edit-a-release-report) + - [Add Workspaces to a Release Report](https://github.com/ZenHubIO/API/tree/master#add-workspaces-to-a-release-report) + - [Remove Workspaces from a Release Report](https://github.com/ZenHubIO/API/tree/master#remove-workspaces-from-release-report) +- [Release Report Issues](https://github.com/ZenHubIO/API/tree/master#release-report-issues) + - [Get all the Issues in a Release Report](https://github.com/ZenHubIO/API/tree/master#get-all-the-issues-for-a-release-report) + - [Add or Remove Issues from a Release Report](https://github.com/ZenHubIO/API/tree/master#add-or-remove-issues-to-or-from-a-release-report) + +[Webhooks](https://github.com/ZenHubIO/API/tree/master#webhooks) + + -[Custom Webhooks](https://github.com/ZenHubIO/API/tree/master#custom-webhooks) + +[Contact Us](https://github.com/ZenHubIO/API/tree/master#contact-us) ## Authentication From c4cba30ffd481772aa6ffd7d7c886a98a0113f1d Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:23:22 -0700 Subject: [PATCH 14/62] Fix list format --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a302389..6077ab8 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ This describes the current version of the public ZenHub API. If you have any que [Webhooks](https://github.com/ZenHubIO/API/tree/master#webhooks) - -[Custom Webhooks](https://github.com/ZenHubIO/API/tree/master#custom-webhooks) +- [Custom Webhooks](https://github.com/ZenHubIO/API/tree/master#custom-webhooks) [Contact Us](https://github.com/ZenHubIO/API/tree/master#contact-us) From e8453bbe2bdab3f8f99aea06f91669e37e2ebcb6 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:24:47 -0700 Subject: [PATCH 15/62] Change heading level for item details --- README.md | 184 +++++++++++++++++++++++++++--------------------------- 1 file changed, 92 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 6077ab8..371825c 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ Status Code | Description # Endpoint Reference -##### Notes +#### Notes - `repo_id` Is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). @@ -92,18 +92,18 @@ Status Code | Description Get the data for a specific issue. -##### Endpoint +#### Endpoint `GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required -##### Example Response +#### Example Response ```json { @@ -123,7 +123,7 @@ Get the data for a specific issue. } ``` -##### Notes +#### Notes - Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. @@ -131,11 +131,11 @@ Get the data for a specific issue. Get the events for an issue. -##### Endpoint +#### Endpoint `GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -143,7 +143,7 @@ Get the events for an issue. |`issue_number`|Number|Required -##### Example Response +#### Example Response ```json [ @@ -196,7 +196,7 @@ Get the events for an issue. ] ``` -##### Notes +#### Notes - Returns issue events, sorted by creation time, most recent first. - Each event contains the _User ID_ of the user who performed the change, the _Creation Date_ of the event, and the event _Type_. @@ -206,30 +206,30 @@ Get the events for an issue. Moves an issue between the pipelines in your repository. -##### Endpoint +#### Endpoint `POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`pipeline_id`|String|Required |`position`|String/Number| Required -##### Notes +#### Notes - `pipeline_id` is the id for one of the pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this id, you can use the Get the ZenHub Board data for a repository endpoint. - `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. -##### Example Request Body +#### Example Request Body ```json { @@ -238,36 +238,36 @@ Moves an issue between the pipelines in your repository. } ``` -##### Example Response +#### Example Response Status `200` for a successful move. No response body. ### Set Issue Estimate -##### Endpoint +#### Endpoint `PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`estimate`|Number|Required, number representing estimate value -##### Example Request +#### Example Request ```json { "estimate": 15 } ``` -##### Example Response +#### Example Response ```json { "estimate": 15 } @@ -279,17 +279,17 @@ Status `200` for a successful move. No response body. Get all Epics for a repository -##### Endpoint +#### Endpoint `GET https://api.zenhub.io/p1/repositories/:repo_id/epics` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -##### Example Response +#### Example Response ```json { @@ -308,7 +308,7 @@ Get all Epics for a repository } ``` -##### Notes +#### Notes - The endpoint returns an array of the repository’s epics. For each Epic, issue number, repository ID, and the GitHub issue URL is provided. - If an issue is only an issue belonging to an Epic (and not a parent Epic), it is not considered an Epic and won’t be included in the return array. @@ -317,22 +317,22 @@ Get all Epics for a repository Get the data for an Epic issue. -##### Endpoint +#### Endpoint `GET https://api.zenhub.io/p1/repositories/:repo_id/epics/:epic_id` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`epic_id`|Number|Required, Github issue number -##### Notes +#### Notes - `epic_id` is the GitHub issue number. You may fetch the list of epics using Get Epics for a repository endpoint. -##### Example Response +#### Example Response ```json { "total_epic_estimates": { "value": 60 }, @@ -372,7 +372,7 @@ Get the data for an Epic issue. } ``` -##### Notes +#### Notes The endpoint returns: @@ -393,18 +393,18 @@ For each issue belonging to the Epic: Converts an Epic back to a regular issue. -##### Endpoint +#### Endpoint `POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required, the number of the issue to be converted -##### Example Response +#### Example Response - `200` if the issue was converted to epic successfully @@ -414,24 +414,24 @@ Does not return any body in the response. Converts an issue to an Epic, along with any issues that should be part of it. -##### Endpoint +#### Endpoint `POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` -##### Example Request Body +#### Example Request Body ```json { @@ -442,7 +442,7 @@ Converts an issue to an Epic, along with any issues that should be part of it. } ``` -##### Response +#### Response Does not return any body in the response. @@ -453,11 +453,11 @@ Does not return any body in the response. Bulk add or remove issues to an Epic. The result returns which issue was added or removed from the Epic. -##### Endpoint +#### Endpoint `POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -466,7 +466,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` |`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` -##### Example Request Body +#### Example Request Body ```json { @@ -480,12 +480,12 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Notes +#### Notes - `remove_issues` is an array that indicates with issues we want to remove from the specified Epic. They should be specified as an array containing objects with the issue’s `repo_id` and `issue_number`. - `add_issues` is an array that indicates with issues we want to add to the specified Epic. They should be specified as an array containing objects with the issue’s `repo_id` and `issue_number`. -##### Example Response +#### Example Response ```json { @@ -499,7 +499,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Notes +#### Notes - `removed_issues` shows which issues were removed in this operation. - `add_issues` shows which issues were added in this operation. @@ -509,17 +509,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Get the ZenHub Board data for a repository -##### Endpoint +#### Endpoint `GET https://api.zenhub.io/p1/repositories/:repo_id/board` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -##### Example Response +#### Example Response ```json { @@ -576,7 +576,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Notes +#### Notes - The endpoint returns the Board’s pipelines, plus the issues contained within each Pipeline. It returns the issue number of each issue, their position in the Board, the is Epic flag (`true` or `false`), and its Estimate (if set). - Even if the issues are returned in the right order, the position can’t be guessed from its index. Note that some issues won’t have position – this is because they have not been prioritized on your Board. @@ -586,30 +586,30 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Set milestone start date -##### Endpoint +#### Endpoint `POST /p1/repositories/:repo_id/milestones/:milestone_number/start_date` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`milestone_id`|Number|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`start_date`| ISO8601 date string|Required -##### Example Request Body +#### Example Request Body ```json { "start_date": "2010-11-13T01:38:56.842Z" } ``` -##### Example Response +#### Example Response ```json { "start_date": "2010-11-13T01:38:56.842Z" } @@ -617,18 +617,18 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Get milestone start date -##### Endpoint +#### Endpoint `GET /p1/repositories/:repo_id/milestones/:milestone_number/start_date` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required |`milestone_id`|Number|Required -##### Example Response +#### Example Response ```json { "start_date": "2010-11-13T01:38:56.842Z" } @@ -638,17 +638,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Create a Release Report -##### Endpoint +#### Endpoint `POST /p1/repositories/:repo_id/reports/release` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -658,7 +658,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |`desired_end_date`| ISO8601 date string| Optional |`repositories`| [Number]| Optional -##### Example Request Body +#### Example Request Body ```json { "title": "Great title", @@ -671,7 +671,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Example Response +#### Example Response ```json { @@ -689,7 +689,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Notes +#### Notes - The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a Board - Additional repository ids can be passed in the body `repositories` parameter @@ -698,17 +698,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Get a Release Report -##### Endpoint +#### Endpoint `GET /p1/reports/release/:release_id` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Example Response +#### Example Response ```json { @@ -728,17 +728,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Get Release Reports for a repository -##### Endpoint +#### Endpoint `GET /p1/repositories/:repo_id/reports/releases` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -##### Example Response +#### Example Response ```json [ @@ -767,17 +767,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Edit a Release Report -##### Endpoint +#### Endpoint `PATCH /p1/reports/release/:release_id` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- @@ -787,7 +787,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |`desired_end_date`| ISO8601 date string| Optional |`state`| String|Optional, 'open' or 'closed' -##### Example Request Body +#### Example Request Body ```json { @@ -799,7 +799,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Example Response +#### Example Response ```json { @@ -820,29 +820,29 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Add Workspaces to a Release Report -##### Endpoint +#### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/add` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`repositories`|[Number]|Required, an array of repo ids -##### Example Request Body +#### Example Request Body ```json { "repositories": [ 103707262 ] } ``` -##### Example Response +#### Example Response ```json { @@ -863,29 +863,29 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Remove Workspaces from Release Report -##### Endpoint +#### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/remove` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`repositories`|[Number]|Required, array of repository IDs -##### Example Request Body +#### Example Request Body ```json { "repositories": [ 103707262 ] } ``` -##### Example Response +#### Example Response ```json { "release_id": "59d3cd520a430a6344fd3bdb", @@ -906,17 +906,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Get all the Issues for a Release Report -##### Endpoint +#### Endpoint `GET /p1/reports/release/:release_id/issues` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Example Response +#### Example Response ```json [ @@ -927,28 +927,28 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Add or Remove Issues to or from a Release Report -##### Endpoint +#### Endpoint `PATCH /p1/reports/release/:release_id/issues` -##### URL Parameters +#### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|String|Required -##### Body Parameters +#### Body Parameters |Name|Type|Comments ------------ | ------ | ------- |`add_issues`|[Number]|Required, an array of repo ids |`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` -##### Note +#### Note - Both the `add_issues` and `remove_issues` keys are required, but can be and empty array when not used -##### Example Body Request +#### Example Body Request ```json { @@ -959,7 +959,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Example Response +#### Example Response ```json { @@ -970,7 +970,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -##### Note +#### Note - Adding and removing issues can be done in the same request by populating with the `add_issues` and `remove_issues` keys. From 29a007c5719defad5295dd1ccf83559970d4aa4e Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:26:16 -0700 Subject: [PATCH 16/62] Use relative links --- README.md | 82 +++++++++++++++++++++++++++---------------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 371825c..3673467 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,46 @@ This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). -[Overview](https://github.com/ZenHubIO/API/tree/master#overview) - -- [Authentication](https://github.com/ZenHubIO/API/tree/master#authentication) -- [API Rate Limit](https://github.com/ZenHubIO/API/tree/master#api-rate-limit) -- [Errors](https://github.com/ZenHubIO/API/tree/master#errors) - -[Endpoint Reference](https://github.com/ZenHubIO/API/tree/master#endpoint-reference) - -- [Issues](https://github.com/ZenHubIO/API/tree/master#issues) - - [Get Issue Data](https://github.com/ZenHubIO/API/tree/master#get-issue-data) - - [Get Issue Events](https://github.com/ZenHubIO/API/tree/master#get-issue-events) - - [Move an Issue Between Pipelines](https://github.com/ZenHubIO/API/tree/master#move-an-issue-between-pipelines) - - [Set Issue Estimate](https://github.com/ZenHubIO/API/tree/master#set-issue-estimate) -- [Epics](https://github.com/ZenHubIO/API/tree/master#epics) - - [Get Epics for a Repository](https://github.com/ZenHubIO/API/tree/master#get-epics-for-a-repository) - - [Get Epic Data](https://github.com/ZenHubIO/API/tree/master#get-epic-data) - - [Convert an Epic to an Issue](https://github.com/ZenHubIO/API/tree/master#convert-an-epic-to-an-issue) - - [Convert an Issue to Epic](https://github.com/ZenHubIO/API/tree/master#convert-issue-to-epic) - - [Add or Remove Issues from an Epic](https://github.com/ZenHubIO/API/tree/master#add-or-remove-issues-to-epic) -- [Boards](https://github.com/ZenHubIO/API/tree/master#boards) - - [Get Board Data for a Repository](https://github.com/ZenHubIO/API/tree/master#get-the-zenhub-board-data-for-a-repository) -- [Milestones](https://github.com/ZenHubIO/API/tree/master#milestones) - - [Set the Milestone Start Date](https://github.com/ZenHubIO/API/tree/master#set-milestone-start-date) - - [Get the Milestone Start Date](https://github.com/ZenHubIO/API/tree/master#get-milestone-start-date) -- [Release Reports](https://github.com/ZenHubIO/API/tree/master#release-reports) - - [Create a Release Report](https://github.com/ZenHubIO/API/tree/master#create-a-release-report) - - [Get a Release Report](https://github.com/ZenHubIO/API/tree/master#get-a-release-report) - - [Get Release Reports for a Repository](https://github.com/ZenHubIO/API/tree/master#get-release-reports-for-a-repository) - - [Edit a Release Report](https://github.com/ZenHubIO/API/tree/master#edit-a-release-report) - - [Add Workspaces to a Release Report](https://github.com/ZenHubIO/API/tree/master#add-workspaces-to-a-release-report) - - [Remove Workspaces from a Release Report](https://github.com/ZenHubIO/API/tree/master#remove-workspaces-from-release-report) -- [Release Report Issues](https://github.com/ZenHubIO/API/tree/master#release-report-issues) - - [Get all the Issues in a Release Report](https://github.com/ZenHubIO/API/tree/master#get-all-the-issues-for-a-release-report) - - [Add or Remove Issues from a Release Report](https://github.com/ZenHubIO/API/tree/master#add-or-remove-issues-to-or-from-a-release-report) - -[Webhooks](https://github.com/ZenHubIO/API/tree/master#webhooks) - -- [Custom Webhooks](https://github.com/ZenHubIO/API/tree/master#custom-webhooks) - -[Contact Us](https://github.com/ZenHubIO/API/tree/master#contact-us) +[Overview](#overview) + +- [Authentication](#authentication) +- [API Rate Limit](#api-rate-limit) +- [Errors](#errors) + +[Endpoint Reference](#endpoint-reference) + +- [Issues](#issues) + - [Get Issue Data](#get-issue-data) + - [Get Issue Events](#get-issue-events) + - [Move an Issue Between Pipelines](#move-an-issue-between-pipelines) + - [Set Issue Estimate](#set-issue-estimate) +- [Epics](#epics) + - [Get Epics for a Repository](#get-epics-for-a-repository) + - [Get Epic Data](#get-epic-data) + - [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) + - [Convert an Issue to Epic](#convert-issue-to-epic) + - [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) +- [Boards](#boards) + - [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) +- [Milestones](#milestones) + - [Set the Milestone Start Date](#set-milestone-start-date) + - [Get the Milestone Start Date](#get-milestone-start-date) +- [Release Reports](#release-reports) + - [Create a Release Report](#create-a-release-report) + - [Get a Release Report](#get-a-release-report) + - [Get Release Reports for a Repository](#get-release-reports-for-a-repository) + - [Edit a Release Report](#edit-a-release-report) + - [Add Workspaces to a Release Report](#add-workspaces-to-a-release-report) + - [Remove Workspaces from a Release Report](#remove-workspaces-from-release-report) +- [Release Report Issues](#release-report-issues) + - [Get all the Issues in a Release Report](#get-all-the-issues-for-a-release-report) + - [Add or Remove Issues from a Release Report](#add-or-remove-issues-to-or-from-a-release-report) + +[Webhooks](#webhooks) + +- [Custom Webhooks](#custom-webhooks) + +[Contact Us](#contact-us) ## Authentication @@ -62,7 +62,7 @@ Alternatively, you can send the token in the URL using the `access_token` query We allow a maximum of 100 requests per minute to our API. All requests responses include some headers related to this limitation. -Header | Meaning +Header | Description ------ | ------- `X-RateLimit-Limit` | Total number of requests allowed before the reset time `X-RateLimit-Used` | Number of requests sent in the current cycle. Will be set to 0 at the reset time. From 71843c3871e4374f95c578578d5e2d8133da5236 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:30:45 -0700 Subject: [PATCH 17/62] Add table of contents for each section --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index 3673467..47d9464 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,11 @@ Status Code | Description ## Issues +- [Get Issue Data](#get-issue-data) +- [Get Issue Events](#get-issue-events) +- [Move an Issue Between Pipelines](#move-an-issue-between-pipelines) +- [Set Issue Estimate](#set-issue-estimate) + ### Get Issue Data Get the data for a specific issue. @@ -275,6 +280,12 @@ Status `200` for a successful move. No response body. ## Epics +- [Get Epics for a Repository](#get-epics-for-a-repository) +- [Get Epic Data](#get-epic-data) +- [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) +- [Convert an Issue to Epic](#convert-issue-to-epic) +- [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) + ### Get Epics for a repository Get all Epics for a repository @@ -507,6 +518,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ## Boards +- [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) + ### Get the ZenHub Board data for a repository #### Endpoint @@ -584,6 +597,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ## Milestones +- [Set the Milestone Start Date](#set-milestone-start-date) +- [Get the Milestone Start Date](#get-milestone-start-date) + ### Set milestone start date #### Endpoint @@ -636,6 +652,13 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ## Release Reports +- [Create a Release Report](#create-a-release-report) +- [Get a Release Report](#get-a-release-report) +- [Get Release Reports for a Repository](#get-release-reports-for-a-repository) +- [Edit a Release Report](#edit-a-release-report) +- [Add Workspaces to a Release Report](#add-workspaces-to-a-release-report) +- [Remove Workspaces from a Release Report](#remove-workspaces-from-release-report) + ### Create a Release Report #### Endpoint @@ -904,6 +927,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ## Release Report Issues +- [Get all the Issues in a Release Report](#get-all-the-issues-for-a-release-report) +- [Add or Remove Issues from a Release Report](#add-or-remove-issues-to-or-from-a-release-report) + ### Get all the Issues for a Release Report #### Endpoint From 2a12fa0fb13a7c2ec38f68b9729ee2ab01ef6125 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:32:56 -0700 Subject: [PATCH 18/62] Fix link to the Board --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 47d9464..abc2903 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ This describes the current version of the public ZenHub API. If you have any que - [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) - [Convert an Issue to Epic](#convert-issue-to-epic) - [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) -- [Boards](#boards) +- [Board](#board) - [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) - [Milestones](#milestones) - [Set the Milestone Start Date](#set-milestone-start-date) @@ -516,7 +516,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - `add_issues` shows which issues were added in this operation. - Returns a `404` if the Epic doesn’t exist -## Boards +## Board - [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) From 4053b9bdcb3592a798e8687cd5fa86ce1008f917 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:36:03 -0700 Subject: [PATCH 19/62] reformat body parameter --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index abc2903..8ce328f 100644 --- a/README.md +++ b/README.md @@ -440,7 +440,7 @@ Converts an issue to an Epic, along with any issues that should be part of it. |Name|Type|Comments ------------ | ------ | ------- -|`issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` #### Example Request Body From 2946064c99591ea0185699d89f54f1d1e8c58b2a Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Fri, 20 Oct 2017 10:37:10 -0700 Subject: [PATCH 20/62] Fix capitalization --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8ce328f..5dcdb06 100644 --- a/README.md +++ b/README.md @@ -749,7 +749,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -### Get Release Reports for a repository +### Get Release Reports for a Repository #### Endpoint From 6cb67b9ac3c06ac4911e91dcea08902096d85a03 Mon Sep 17 00:00:00 2001 From: Anna Zhao Date: Fri, 20 Oct 2017 17:47:27 -0700 Subject: [PATCH 21/62] minor fixes - capitalization for consistency, fixing mistakes, etc --- README.md | 51 +++++++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 3673467..2b211c0 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ All requests to the API need an API token. Generate a token in the [Settings](ht curl -H 'X-Authentication-Token: TOKEN' URL ``` -Alternatively, you can send the token in the URL using the `access_token` query string attribute. To do so, add `?access_token=TOKEN` to any URL. +Alternatively, you can choose to send the token in the URL using the `access_token` query string attribute. To do so, add `?access_token=TOKEN` to any URL. #### Notes @@ -60,7 +60,7 @@ Alternatively, you can send the token in the URL using the `access_token` query ## API Rate Limit -We allow a maximum of 100 requests per minute to our API. All requests responses include some headers related to this limitation. +We allow a maximum of 100 requests per minute to our API. All requests responses include the following headers related to this limitation. Header | Description ------ | ------- @@ -84,7 +84,7 @@ Status Code | Description #### Notes -- `repo_id` Is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). +- `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). ## Issues @@ -204,7 +204,7 @@ Get the events for an issue. ### Move an Issue Between Pipelines -Moves an issue between the pipelines in your repository. +Moves an issue between the Pipelines in your repository. #### Endpoint @@ -226,7 +226,7 @@ Moves an issue between the pipelines in your repository. #### Notes -- `pipeline_id` is the id for one of the pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this id, you can use the Get the ZenHub Board data for a repository endpoint. +- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the `Get the ZenHub Board data for a repository` endpoint. - `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. #### Example Request Body @@ -310,7 +310,8 @@ Get all Epics for a repository #### Notes -- The endpoint returns an array of the repository’s epics. For each Epic, issue number, repository ID, and the GitHub issue URL is provided. +- The endpoint returns an array of the repository’s Epics. The issue number, repository ID, +and GitHub issue URL is provided for each Epic. - If an issue is only an issue belonging to an Epic (and not a parent Epic), it is not considered an Epic and won’t be included in the return array. ### Get Epic Data @@ -330,7 +331,7 @@ Get the data for an Epic issue. #### Notes -- `epic_id` is the GitHub issue number. You may fetch the list of epics using Get Epics for a repository endpoint. +- `epic_id` is the GitHub issue number. You may fetch the list of Epics using `Get Epics for a repository` endpoint. #### Example Response ```json @@ -376,17 +377,18 @@ Get the data for an Epic issue. The endpoint returns: -- the total estimate Epic value (the sum of the Epic’s Estimate, plus all Estimates contained within it) +- the total Epic Estimate value (the sum of all the Estimates of Issues contained within + the Epic, as well as the Estimate of the Epic itself) - the Estimate of the Epic -- the Pipeline name the Epic is in +- the name of the Pipeline the Epic is in - issues belonging to the Epic For each issue belonging to the Epic: - issue number -- repo id +- repo ID - Estimate value -- Is epic flag (`true` or `false`) +- `is_epic` flag (`true` or `false`) - if the issue is from the same repository as the Epic, the ZenHub Board’s Pipeline name (from the repo the Epic is in) is attached. ### Convert an Epic to an Issue @@ -406,7 +408,7 @@ Converts an Epic back to a regular issue. #### Example Response -- `200` if the issue was converted to epic successfully +- `200` if the issue was converted to Epic successfully Does not return any body in the response. @@ -463,6 +465,11 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ------------ | ------ | ------- |`repo_id`|Number|Required |`issue_number`|Number|Required + +#### Body Parameters + +|Name|Type|Comments +------------ | ------ | ------- |`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` |`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` @@ -578,7 +585,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Notes -- The endpoint returns the Board’s pipelines, plus the issues contained within each Pipeline. It returns the issue number of each issue, their position in the Board, the is Epic flag (`true` or `false`), and its Estimate (if set). +- The endpoint returns the Board’s pipelines, plus the issues contained within each Pipeline. It returns the issue number of each issue, their position in the Board, the `is_epic` flag (`true` or `false`), and its Estimate (if set). - Even if the issues are returned in the right order, the position can’t be guessed from its index. Note that some issues won’t have position – this is because they have not been prioritized on your Board. - The Board returned by the endpoint doesn’t include closed issues. To get closed issues for a repository, you can use the GitHub API. Reopened issues might take up to one minute to appear in the correct Pipeline. @@ -595,7 +602,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -|`milestone_id`|Number|Required +|`milestone_number`|Number|Required #### Body Parameters @@ -626,7 +633,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|Number|Required -|`milestone_id`|Number|Required +|`milestone_number`|Number|Required #### Example Response @@ -692,7 +699,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Notes - The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a Board -- Additional repository ids can be passed in the body `repositories` parameter +- Additional repository IDs can be passed in the body `repositories` parameter - Any Boards not associated with the URL `repo_id` parameter, but associated with repositories in the request body `repositories` parameter will also be associated to the Release Report. - The user creating the release requires push permission to the repositories in the request. @@ -785,7 +792,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |`description`|String|Optional |`start_date`|ISO8601 date string|Optional |`desired_end_date`| ISO8601 date string| Optional -|`state`| String|Optional, 'open' or 'closed' +|`state`| String|Optional, `open` or `closed` #### Example Request Body @@ -834,7 +841,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repositories`|[Number]|Required, an array of repo ids +|`repositories`|[Number]|Required, an array of repo IDs #### Example Request Body @@ -877,7 +884,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repositories`|[Number]|Required, array of repository IDs +|`repositories`|[Number]|Required, array of repo IDs #### Example Request Body @@ -941,12 +948,12 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`add_issues`|[Number]|Required, an array of repo ids -|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`add_issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`remove_issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` #### Note -- Both the `add_issues` and `remove_issues` keys are required, but can be and empty array when not used +- Both the `add_issues` and `remove_issues` keys are required, but can be an empty array when not used #### Example Body Request From d222e67376768e9204f3bf23480638675d00381a Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Mon, 23 Oct 2017 08:24:47 -0700 Subject: [PATCH 22/62] Add the root endpoint section --- README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 58525c0..b2fad88 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ This describes the current version of the public ZenHub API. If you have any que [Overview](#overview) +- [Root Endpoint](#root-endpoint) - [Authentication](#authentication) - [API Rate Limit](#api-rate-limit) - [Errors](#errors) @@ -43,6 +44,10 @@ This describes the current version of the public ZenHub API. If you have any que [Contact Us](#contact-us) +## Root Endpoint + +The root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Enterprise, refer to the instructions in `https:///setup/howto/api`. + ## Authentication All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: @@ -99,7 +104,7 @@ Get the data for a specific issue. #### Endpoint -`GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number` +`GET /p1/repositories/:repo_id/issues/:issue_number` #### URL Parameters @@ -138,7 +143,7 @@ Get the events for an issue. #### Endpoint -`GET https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/events` +`GET /p1/repositories/:repo_id/issues/:issue_number/events` #### URL Parameters @@ -213,7 +218,7 @@ Moves an issue between the Pipelines in your repository. #### Endpoint -`POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/moves` +`POST /p1/repositories/:repo_id/issues/:issue_number/moves` #### URL Parameters @@ -251,7 +256,7 @@ Status `200` for a successful move. No response body. #### Endpoint -`PUT https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/estimate` +`PUT /p1/repositories/:repo_id/issues/:issue_number/estimate` #### URL Parameters @@ -292,7 +297,7 @@ Get all Epics for a repository #### Endpoint -`GET https://api.zenhub.io/p1/repositories/:repo_id/epics` +`GET /p1/repositories/:repo_id/epics` #### URL Parameters @@ -331,7 +336,7 @@ Get the data for an Epic issue. #### Endpoint -`GET https://api.zenhub.io/p1/repositories/:repo_id/epics/:epic_id` +`GET /p1/repositories/:repo_id/epics/:epic_id` #### URL Parameters @@ -408,7 +413,7 @@ Converts an Epic back to a regular issue. #### Endpoint -`POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/convert_to_issue` +`POST /p1/repositories/:repo_id/epics/:issue_number/convert_to_issue` #### URL Parameters @@ -429,7 +434,7 @@ Converts an issue to an Epic, along with any issues that should be part of it. #### Endpoint -`POST https://api.zenhub.io/p1/repositories/:repo_id/issues/:issue_number/convert_to_epic` +`POST /p1/repositories/:repo_id/issues/:issue_number/convert_to_epic` #### URL Parameters @@ -468,7 +473,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Endpoint -`POST https://api.zenhub.io/p1/repositories/:repo_id/epics/:issue_number/update_issues` +`POST /p1/repositories/:repo_id/epics/:issue_number/update_issues` #### URL Parameters From bb620e212a821452428a935b2507be95640ec62a Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Mon, 23 Oct 2017 08:35:03 -0700 Subject: [PATCH 23/62] Better formatting for tables --- README.md | 94 +++++++++++++++++++++++++++---------------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index b2fad88..4148250 100644 --- a/README.md +++ b/README.md @@ -110,8 +110,8 @@ Get the data for a specific issue. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required #### Example Response @@ -149,8 +149,8 @@ Get the events for an issue. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required #### Example Response @@ -224,19 +224,19 @@ Moves an issue between the Pipelines in your repository. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`pipeline_id`|String|Required -|`position`|String/Number| Required +|`pipeline_id`|`String`|Required +|`position`|`String` or `Number`| Required #### Notes -- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the `Get the ZenHub Board data for a repository` endpoint. +- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get Board Data for a Repository_](#get-the-zenhub-board-data-for-a-repository)` endpoint. - `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. #### Example Request Body @@ -262,14 +262,14 @@ Status `200` for a successful move. No response body. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`estimate`|Number|Required, number representing estimate value +|`estimate`|`Number`|Required, number representing estimate value #### Example Request @@ -303,7 +303,7 @@ Get all Epics for a repository |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required +|`repo_id`|`Number`|Required #### Example Response @@ -342,8 +342,8 @@ Get the data for an Epic issue. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`epic_id`|Number|Required, Github issue number +|`repo_id`|`Number`|Required +|`epic_id`|`Number`|Required, Github issue number #### Notes @@ -419,8 +419,8 @@ Converts an Epic back to a regular issue. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required, the number of the issue to be converted +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required, the number of the issue to be converted #### Example Response @@ -440,14 +440,14 @@ Converts an issue to an Epic, along with any issues that should be part of it. |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` #### Example Request Body @@ -479,15 +479,15 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`issue_number`|Number|Required +|`repo_id`|`Number`|Required +|`issue_number`|`Number|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`remove_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` -|`add_issues`|[{repo_id: Number, issue_number: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`remove_issues`|[`{repo_id: Number, issue_number: Number}`]|Required, array of Objects with `repo_id` and `issue_number` +|`add_issues`|[`{repo_id: Number, issue_number: Number}`]|Required, array of Objects with `repo_id` and `issue_number` #### Example Request Body @@ -542,7 +542,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required +|`repo_id`|`Number`|Required #### Example Response @@ -622,8 +622,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`milestone_number`|Number|Required +|`repo_id`|`Number`|Required +|`milestone_number`|`Number`|Required #### Body Parameters @@ -653,8 +653,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required -|`milestone_number`|Number|Required +|`repo_id`|`Number`|Required +|`milestone_number`|`Number`|Required #### Example Response @@ -681,17 +681,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required +|`repo_id`|`Number`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`title`|String|Required -|`description`| String| Optional +|`title`|`String`|Required +|`description`| `String`| Optional |`start_date`| ISO8601 date string|Optional |`desired_end_date`| ISO8601 date string| Optional -|`repositories`| [Number]| Optional +|`repositories`| `[Number]`| Optional #### Example Request Body ```json @@ -741,7 +741,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Example Response @@ -771,7 +771,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`repo_id`|Number|Required +|`repo_id`|`Number`|Required #### Example Response @@ -810,17 +810,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`title`|String|Required -|`description`|String|Optional +|`title`|`String`|Required +|`description`|`String`|Optional |`start_date`|ISO8601 date string|Optional |`desired_end_date`| ISO8601 date string| Optional -|`state`| String|Optional, `open` or `closed` +|`state`| `String`|Optional, `open` or `closed` #### Example Request Body @@ -863,13 +863,13 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`repositories`|[Number]|Required, an array of repo IDs +|`repositories`|`[Number]`|Required, an array of repo IDs #### Example Request Body @@ -906,13 +906,13 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`repositories`|[Number]|Required, array of repo IDs +|`repositories`|`[Number]`|Required, array of repo IDs #### Example Request Body @@ -952,7 +952,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Example Response @@ -973,14 +973,14 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`release_id`|String|Required +|`release_id`|`String`|Required #### Body Parameters |Name|Type|Comments ------------ | ------ | ------- -|`add_issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` -|`remove_issues`|[{`repo_id`: Number, `issue_number`: Number}]|Required, array of Objects with `repo_id` and `issue_number` +|`add_issues`|`[{repo_id`: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` +|`remove_issues`|`[{repo_id`: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` #### Note From a3a25cb55e8f20d9f814eb2a0af5348e0f99587d Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Mon, 23 Oct 2017 08:36:03 -0700 Subject: [PATCH 24/62] Fix code block --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4148250..f876df6 100644 --- a/README.md +++ b/README.md @@ -979,8 +979,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- -|`add_issues`|`[{repo_id`: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` -|`remove_issues`|`[{repo_id`: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` +|`add_issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` +|`remove_issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` #### Note From 8082f33b38ff5471d52f0e6eadbfb75bd78955bd Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Mon, 23 Oct 2017 08:37:14 -0700 Subject: [PATCH 25/62] Remove root endpoint --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f876df6..b0c0b07 100644 --- a/README.md +++ b/README.md @@ -536,7 +536,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Endpoint -`GET https://api.zenhub.io/p1/repositories/:repo_id/board` +`GET /p1/repositories/:repo_id/board` #### URL Parameters From 8dd5306dd8053d6aa2cbac5ffa141eb661b22022 Mon Sep 17 00:00:00 2001 From: Leo Zhang Date: Mon, 23 Oct 2017 14:02:13 -0700 Subject: [PATCH 26/62] Minor formatting --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b0c0b07..6685c3d 100644 --- a/README.md +++ b/README.md @@ -480,7 +480,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o |Name|Type|Comments ------------ | ------ | ------- |`repo_id`|`Number`|Required -|`issue_number`|`Number|Required +|`issue_number`|`Number`|Required #### Body Parameters From 9c8d02979ae673b595252a724b8d7866b2bcb495 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Tue, 12 Dec 2017 10:55:00 -0800 Subject: [PATCH 27/62] Fix the documentation of the Board endpoint --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 6685c3d..0f9c78b 100644 --- a/README.md +++ b/README.md @@ -550,6 +550,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o { "pipelines": [ { + "id": "595d430add03f01d32460080", "name": "New Issues", "issues": [ { @@ -565,6 +566,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ] }, { + "id": "595d430add03f01d32460081", "name": "Backlog", "issues": [ { @@ -576,6 +578,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ] }, { + "id": "595d430add03f01d32460082" "name": "To Do", "issues": [ { From 0625b0df64baa16241ad3c0a0493d248bcfb7e6b Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Tue, 12 Dec 2017 10:56:42 -0800 Subject: [PATCH 28/62] Fix malformed JSON in docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0f9c78b..19064d0 100644 --- a/README.md +++ b/README.md @@ -578,7 +578,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ] }, { - "id": "595d430add03f01d32460082" + "id": "595d430add03f01d32460082", "name": "To Do", "issues": [ { From 7be9ef7194d992b8f2c060779bad46d118fbf65e Mon Sep 17 00:00:00 2001 From: Anna Zhao Date: Tue, 27 Feb 2018 11:22:13 -0800 Subject: [PATCH 29/62] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 19064d0..6bed7a3 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Ent ## Authentication -All requests to the API need an API token. Generate a token in the [Settings](https://dashboard.zenhub.io/#/settings) section of your ZenHub Dashboard. The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens section** of your ZenHub [Dashboard](https://app.zenhub.com/app/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL @@ -1019,7 +1019,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o You can use our webhooks to fetch or store your ZenHub data, in real time, across services like Slack, Gitter, Spark, HipChat, or something custom! -To set up an integration, head on over to our [Dashboard](https://dashboard.zenhub.com/), navigate to your organization, and select the **Integrations** tab. From there, you may choose one of the 5 services (Slack, HipChat, Gitter, Spark, or Custom). +To set up an integration, head on over to our [Dashboard](https://app.zenhub.com/app/dashboard), navigate to your organization, and select the **Slack & Integrations** tab. From there, you may choose one of the 5 services (Slack, HipChat, Gitter, Spark, or Custom). For instructions, you'll notice the `How to create a webhook` link changes dynamically based on the service you select. Simply choose a repository with which to connect, add an optional description, paste your webhook, and click "Add" to save your new integration. From fcc51e0fb6f1c4394569c5fbf0397fd4b142c3e0 Mon Sep 17 00:00:00 2001 From: Anna Zhao Date: Tue, 27 Feb 2018 11:22:48 -0800 Subject: [PATCH 30/62] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6bed7a3..fd64c21 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Ent ## Authentication -All requests to the API need an API token. Generate a token in the **API Tokens section** of your ZenHub [Dashboard](https://app.zenhub.com/app/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/app/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL From d5ee0d3d417a49e4845dbd537d865f75fca3f9c9 Mon Sep 17 00:00:00 2001 From: Anna Zhao Date: Tue, 27 Feb 2018 15:31:09 -0800 Subject: [PATCH 31/62] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fd64c21..d27ade8 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Ent ## Authentication -All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/app/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL @@ -1019,7 +1019,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o You can use our webhooks to fetch or store your ZenHub data, in real time, across services like Slack, Gitter, Spark, HipChat, or something custom! -To set up an integration, head on over to our [Dashboard](https://app.zenhub.com/app/dashboard), navigate to your organization, and select the **Slack & Integrations** tab. From there, you may choose one of the 5 services (Slack, HipChat, Gitter, Spark, or Custom). +To set up an integration, head on over to our [Dashboard](https://app.zenhub.com/dashboard), navigate to your organization, and select the **Slack & Integrations** tab. From there, you may choose one of the 5 services (Slack, HipChat, Gitter, Spark, or Custom). For instructions, you'll notice the `How to create a webhook` link changes dynamically based on the service you select. Simply choose a repository with which to connect, add an optional description, paste your webhook, and click "Add" to save your new integration. From 6ffb797a4813061c0899209e48b3627ab36c595e Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Sat, 9 Jun 2018 21:59:21 -0700 Subject: [PATCH 32/62] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d27ade8..2c849a9 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ Moves an issue between the Pipelines in your repository. #### Notes -- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get Board Data for a Repository_](#get-the-zenhub-board-data-for-a-repository)` endpoint. +- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get Board Data for a Repository_](#get-the-zenhub-board-data-for-a-repository) endpoint. - `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. #### Example Request Body From 93ed6b1e0cd2dce084e205df3c567fdb869dae76 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Sat, 9 Jun 2018 22:02:19 -0700 Subject: [PATCH 33/62] Update README.md --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2c849a9..89b19bf 100644 --- a/README.md +++ b/README.md @@ -1094,22 +1094,22 @@ Our custom webhook sends a POST request to your webhook for multiple events that As an example, here's a simple Node/Express app that would be able receive the webhooks (using ngrok): ```javascript -var express = require('express'); -var http = require('http'); +var express = require('express'); +var http = require('http'); var bodyParser = require('body-parser'); -var app = express(); +var app = express(); http.createServer(app).listen('6000', function() { - console.log('Listening on 6000'); + console.log('Listening on 6000'); }); app.use(bodyParser()); app.post('*', function(req, res) { - console.dir(req.body); + console.dir(req.body); }); ``` # Contact us -We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support](https://github.com/ZenHubIO/support/issues#boards) repo or find us on [Twitter](http://www.twitter.com/zenhubio). +We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support repo](https://github.com/ZenHubIO/support/issues#boards) or find us on [Twitter](http://www.twitter.com/ZenHubHQ). From 0b3faffba573de8922490dae2be608c6af8aa264 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Sat, 9 Jun 2018 22:04:08 -0700 Subject: [PATCH 34/62] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 89b19bf..f662c76 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). -[Overview](#overview) +### [Overview](#overview) - [Root Endpoint](#root-endpoint) - [Authentication](#authentication) - [API Rate Limit](#api-rate-limit) - [Errors](#errors) -[Endpoint Reference](#endpoint-reference) +### [Endpoint Reference](#endpoint-reference) - [Issues](#issues) - [Get Issue Data](#get-issue-data) @@ -38,11 +38,11 @@ This describes the current version of the public ZenHub API. If you have any que - [Get all the Issues in a Release Report](#get-all-the-issues-for-a-release-report) - [Add or Remove Issues from a Release Report](#add-or-remove-issues-to-or-from-a-release-report) -[Webhooks](#webhooks) +### [Webhooks](#webhooks) - [Custom Webhooks](#custom-webhooks) -[Contact Us](#contact-us) +### [Contact Us](#contact-us) ## Root Endpoint From 215c75a5dfe48fcbda25e9713450d7f51934dff4 Mon Sep 17 00:00:00 2001 From: Pablo Navarro Date: Sat, 9 Jun 2018 22:06:41 -0700 Subject: [PATCH 35/62] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f662c76..89b19bf 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). -### [Overview](#overview) +[Overview](#overview) - [Root Endpoint](#root-endpoint) - [Authentication](#authentication) - [API Rate Limit](#api-rate-limit) - [Errors](#errors) -### [Endpoint Reference](#endpoint-reference) +[Endpoint Reference](#endpoint-reference) - [Issues](#issues) - [Get Issue Data](#get-issue-data) @@ -38,11 +38,11 @@ This describes the current version of the public ZenHub API. If you have any que - [Get all the Issues in a Release Report](#get-all-the-issues-for-a-release-report) - [Add or Remove Issues from a Release Report](#add-or-remove-issues-to-or-from-a-release-report) -### [Webhooks](#webhooks) +[Webhooks](#webhooks) - [Custom Webhooks](#custom-webhooks) -### [Contact Us](#contact-us) +[Contact Us](#contact-us) ## Root Endpoint From 94d94248a9c2abb9920590b9b2a5ef5e16be02ff Mon Sep 17 00:00:00 2001 From: nbcraft <4719911+nbcraft@users.noreply.github.com> Date: Fri, 22 Jun 2018 13:45:24 -0700 Subject: [PATCH 36/62] Add endpoint GET dependencies by repository #11208 --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/README.md b/README.md index 89b19bf..a6e648c 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ This describes the current version of the public ZenHub API. If you have any que - [Milestones](#milestones) - [Set the Milestone Start Date](#set-milestone-start-date) - [Get the Milestone Start Date](#get-milestone-start-date) +- [Dependencies](#dependencies) + - [Get Dependencies for a Repository](#get-dependencies-for-a-repository) - [Release Reports](#release-reports) - [Create a Release Report](#create-a-release-report) - [Get a Release Report](#get-a-release-report) @@ -665,6 +667,58 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o { "start_date": "2010-11-13T01:38:56.842Z" } ``` +## Dependencies + +- [Get Dependencies for a Repository](#get-dependencies-for-a-repository) + +### Get Dependencies for a Repository + +#### Endpoint + +`GET /p1/repositories/:repo_id/dependencies` + +#### URL Parameters + +|Name|Type|Comments +------------ | ------ | ------- +|`repo_id`|`Number`|Required + +#### Example Response + +```json +{ + "dependencies": [ + { + "blocking": { + "issue_number": 3953, + "repo_id": 1234567 + }, + "blocked": { + "issue_number": 1342, + "repo_id": 1234567 + } + }, + { + "blocking": { + "issue_number": 5, + "repo_id": 987 + }, + "blocked": { + "issue_number": 1342, + "repo_id": 1234567 + } + }, + ] +} +``` + +#### Notes + +- This endpoint fetches all dependencies associated to the given repository that the user has read permission to +- The endpoint takes a `repo_id` param in the URL. +- Only dependencies where the user has read permissions to both sides will be returned + + ## Release Reports - [Create a Release Report](#create-a-release-report) From d2d2307d6a0094a0627fe9f741cf311598ddc1ec Mon Sep 17 00:00:00 2001 From: nbcraft <4719911+nbcraft@users.noreply.github.com> Date: Mon, 9 Jul 2018 18:32:33 -0700 Subject: [PATCH 37/62] Add endpoint Create dependency #11210 --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/README.md b/README.md index a6e648c..a93facd 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ This describes the current version of the public ZenHub API. If you have any que - [Get the Milestone Start Date](#get-milestone-start-date) - [Dependencies](#dependencies) - [Get Dependencies for a Repository](#get-dependencies-for-a-repository) + - [Create a Dependency](#create-a-dependency) - [Release Reports](#release-reports) - [Create a Release Report](#create-a-release-report) - [Get a Release Report](#get-a-release-report) @@ -670,6 +671,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ## Dependencies - [Get Dependencies for a Repository](#get-dependencies-for-a-repository) +- [Create a Dependency](#create-a-dependency) ### Get Dependencies for a Repository @@ -718,6 +720,58 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - The endpoint takes a `repo_id` param in the URL. - Only dependencies where the user has read permissions to both sides will be returned +## Create a Dependency + +#### Endpoint + +`POST /p1/dependencies` + +#### Body Parameters + +|Name|Type|Comments +------------ | ------ | ------- +|`blocking`|`Object`| Required +|`blocking.repo_id`| `Number`| Required +|`blocking.issue_number`| `Number`| Required +|`blocked`|`Object`| Required +|`blocked.repo_id`| `Number`| Required +|`blocked.issue_number`| `Number`| Required + +#### Example Request Body +```json +{ + "blocking": { + "repo_id": 92563409, + "issue_number": 14 + }, + "blocked": { + "repo_id": 92563409, + "issue_number": 13 + } +} +``` + +#### Example Response Body +```json +{ + "blocking": { + "repo_id": 92563409, + "issue_number": 14 + }, + "blocked": { + "repo_id": 92563409, + "issue_number": 13 + } +} +``` + +#### Notes + +- This endpoint creates one dependency +- The endpoint takes a `dependency` in the Body (see description above). +- User needs write permission on both repositories +- Cannot create dependency that will cause cycle, or between repositories not in the same workspace +- On success: returns HTTP 200 and returns the created object ## Release Reports From c3512cbb765558dd36e4a76c71441468a5bfac61 Mon Sep 17 00:00:00 2001 From: nbcraft <4719911+nbcraft@users.noreply.github.com> Date: Wed, 11 Jul 2018 12:02:45 -0700 Subject: [PATCH 38/62] Add endpoint Remove dependency #11211 --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index a93facd..7743b3e 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ This describes the current version of the public ZenHub API. If you have any que - [Dependencies](#dependencies) - [Get Dependencies for a Repository](#get-dependencies-for-a-repository) - [Create a Dependency](#create-a-dependency) + - [Remove a Dependency](#remove-a-dependency) - [Release Reports](#release-reports) - [Create a Release Report](#create-a-release-report) - [Get a Release Report](#get-a-release-report) @@ -672,6 +673,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - [Get Dependencies for a Repository](#get-dependencies-for-a-repository) - [Create a Dependency](#create-a-dependency) +- [Remove a Dependency](#remove-a-dependency) ### Get Dependencies for a Repository @@ -773,6 +775,44 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - Cannot create dependency that will cause cycle, or between repositories not in the same workspace - On success: returns HTTP 200 and returns the created object +## Remove a Dependency + +#### Endpoint + +`DELETE /p1/dependencies` + +#### Body Parameters + +|Name|Type|Comments +------------ | ------ | ------- +|`blocking`|`Object`| Required +|`blocking.repo_id`| `Number`| Required +|`blocking.issue_number`| `Number`| Required +|`blocked`|`Object`| Required +|`blocked.repo_id`| `Number`| Required +|`blocked.issue_number`| `Number`| Required + +#### Example Request Body +```json +{ + "blocking": { + "repo_id": 92563409, + "issue_number": 14 + }, + "blocked": { + "repo_id": 92563409, + "issue_number": 13 + } +} +``` + +#### Notes + +- This endpoint removes one dependency +- The endpoint takes a `dependency` in the Body (see description above). +- User needs write permission on both repositories +- On success: returns HTTP 204 No Content and empty body + ## Release Reports - [Create a Release Report](#create-a-release-report) From b131481acda037dd706bd2b03f1c9c94f27caab7 Mon Sep 17 00:00:00 2001 From: nbcraft <4719911+nbcraft@users.noreply.github.com> Date: Mon, 30 Jul 2018 17:55:50 -0700 Subject: [PATCH 39/62] Get Issue Data: plus_ones.user_id was removed from response --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7743b3e..2097405 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,6 @@ Get the data for a specific issue. }, "plus_ones": [ { - "user_id": 16717, "created_at": "2015-12-11T18:43:22.296Z" } ], @@ -139,6 +138,7 @@ Get the data for a specific issue. #### Notes +- `plus_ones[].user_id` was removed from the response. - Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. ### Get Issue Events From 7a0b574790fbfbaef4263eb80698f43f805a298a Mon Sep 17 00:00:00 2001 From: Devin McInnis Date: Tue, 11 Dec 2018 12:11:01 -0800 Subject: [PATCH 40/62] Update API endpoints on README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2097405..c58b817 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,8 @@ This describes the current version of the public ZenHub API. If you have any que ## Root Endpoint -The root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Enterprise, refer to the instructions in `https:///setup/howto/api`. +On Cloud, the root endpoint for the public API is `https://api.zenhub.io/`. +For ZenHub Enterprise, the root endpoint is `https:///`. ## Authentication From 9c12796a89b577c42966dfeff3889ff34fd66072 Mon Sep 17 00:00:00 2001 From: Devin McInnis Date: Wed, 12 Dec 2018 12:02:55 -0800 Subject: [PATCH 41/62] Update links to API token pages --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c58b817..e3a0bf9 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ For ZenHub Enterprise, the root endpoint is `https:///`. ## Authentication -All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard/tokens) (or `https:///app/dashboard/tokens` for ZenHub Enterprise). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL From fef0a0b8c7efd6e27193d3f9a9c6c550bb4665ae Mon Sep 17 00:00:00 2001 From: Oleg Zdornyy Date: Thu, 20 Dec 2018 14:48:26 -0800 Subject: [PATCH 42/62] Add deprecation notices for Release Report: Add/remove Workspaces Deprecation notices and replacement endpoints to be rolled out in February 2019. --- README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e3a0bf9..1b7decd 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ This describes the current version of the public ZenHub API. If you have any que ## Root Endpoint -On Cloud, the root endpoint for the public API is `https://api.zenhub.io/`. +On Cloud, the root endpoint for the public API is `https://api.zenhub.io/`. For ZenHub Enterprise, the root endpoint is `https:///`. ## Authentication @@ -878,8 +878,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Notes -- The endpoint takes a `repo_id` param in the URL. This is the minimum requirement for associating a release with a Board -- Additional repository IDs can be passed in the body `repositories` parameter +- **CHANGE NOTICE:** Only the repositories provided in the param and the body will be added to the Release Report - change in effect mid February 2019. +- The endpoint takes a `repo_id` param in the URL. +- Additional repository IDs can be passed in the body `repositories` parameter - Any Boards not associated with the URL `repo_id` parameter, but associated with repositories in the request body `repositories` parameter will also be associated to the Release Report. - The user creating the release requires push permission to the repositories in the request. @@ -1007,6 +1008,10 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Add Workspaces to a Release Report +#### Deprecation notice +Endpoint to be replaced with `POST /p1/reports/release/:release_id/repositories/:repo_id` mid February 2019. +Documentation will be updated prior to release. + #### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/add` @@ -1050,6 +1055,10 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ### Remove Workspaces from Release Report +#### Deprecation notice +Endpoint to be replaced with `DELETE /p1/reports/release/:release_id/repositories/:repo_id` mid February 2019. +Documentation will be updated prior to release. + #### Endpoint `PATCH /p1/reports/release/:release_id/workspaces/remove` From 4b37b6a2295d822cb5d7c19285e7f7c2e5108eaa Mon Sep 17 00:00:00 2001 From: Oleg Zdornyy Date: Tue, 26 Feb 2019 16:34:42 -0800 Subject: [PATCH 43/62] Add endpoints for adding/removing Repositories to a Release Deprecate existing Add/Remove workspace from Release Report Add new endpoints for adding/removing Repositories to a Release Report --- README.md | 97 ++++++++++++++----------------------------------------- 1 file changed, 25 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 1b7decd..2b42144 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,8 @@ This describes the current version of the public ZenHub API. If you have any que - [Get a Release Report](#get-a-release-report) - [Get Release Reports for a Repository](#get-release-reports-for-a-repository) - [Edit a Release Report](#edit-a-release-report) - - [Add Workspaces to a Release Report](#add-workspaces-to-a-release-report) - - [Remove Workspaces from a Release Report](#remove-workspaces-from-release-report) + - [Add a Repository to a Release Report](#add-a-repository-to-a-release-report) + - [Remove a Repository from a Release Report](#remove-a-repository-from-a-release-report) - [Release Report Issues](#release-report-issues) - [Get all the Issues in a Release Report](#get-all-the-issues-for-a-release-report) - [Add or Remove Issues from a Release Report](#add-or-remove-issues-to-or-from-a-release-report) @@ -820,8 +820,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - [Get a Release Report](#get-a-release-report) - [Get Release Reports for a Repository](#get-release-reports-for-a-repository) - [Edit a Release Report](#edit-a-release-report) -- [Add Workspaces to a Release Report](#add-workspaces-to-a-release-report) -- [Remove Workspaces from a Release Report](#remove-workspaces-from-release-report) +- [Add a Repository to a Release Report](#add-a-repository-to-a-release-report) +- [Remove a Repository from a Release Report](#remove-a-repository-from-a-release-report) ### Create a Release Report @@ -841,8 +841,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ------------ | ------ | ------- |`title`|`String`|Required |`description`| `String`| Optional -|`start_date`| ISO8601 date string|Optional -|`desired_end_date`| ISO8601 date string| Optional +|`start_date`| ISO8601 date string| Required +|`desired_end_date`| ISO8601 date string| Required |`repositories`| `[Number]`| Optional #### Example Request Body @@ -1006,97 +1006,50 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o } ``` -### Add Workspaces to a Release Report - -#### Deprecation notice -Endpoint to be replaced with `POST /p1/reports/release/:release_id/repositories/:repo_id` mid February 2019. -Documentation will be updated prior to release. - +### Add a Repository to a Release Report #### Endpoint -`PATCH /p1/reports/release/:release_id/workspaces/add` +`POST /p1/reports/release/:release_id/repository/:repo_id` #### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|`String`|Required +|`repo_id`|`Number`|Required -#### Body Parameters - -|Name|Type|Comments ------------- | ------ | ------- -|`repositories`|`[Number]`|Required, an array of repo IDs - -#### Example Request Body - -```json -{ "repositories": [ 103707262 ] } -``` - -#### Example Response - -```json -{ - "release_id": "59d3cd520a430a6344fd3bdb", - "title": "Test release", - "description": "", - "start_date": "2017-10-01T19:00:00.000Z", - "desired_end_date": "2017-10-03T19:00:00.000Z", - "created_at": "2017-10-03T17:48:02.701Z", - "closed_at": null, - "state": "open", - "repositories": [ - 103707262, - 105683718 - ] -} -``` -### Remove Workspaces from Release Report +#### Notes +- On success, returns HTTP 200 OK and empty body -#### Deprecation notice -Endpoint to be replaced with `DELETE /p1/reports/release/:release_id/repositories/:repo_id` mid February 2019. -Documentation will be updated prior to release. +### Remove a Repository from a Release Report #### Endpoint -`PATCH /p1/reports/release/:release_id/workspaces/remove` +`DELETE /p1/reports/release/:release_id/repository/:repo_id` #### URL Parameters |Name|Type|Comments ------------ | ------ | ------- |`release_id`|`String`|Required +|`repo_id`|`Number`|Required -#### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repositories`|`[Number]`|Required, array of repo IDs +#### Notes +- On success, returns HTTP 204 OK and empty body -#### Example Request Body -```json -{ "repositories": [ 103707262 ] } -``` +### Add Workspaces to a Release Report +#### **DEPRECATED** +#### Endpoint +`PATCH /p1/reports/release/:release_id/workspaces/add` -#### Example Response -```json -{ - "release_id": "59d3cd520a430a6344fd3bdb", - "title": "Test release", - "description": "", - "start_date": "2017-10-01T19:00:00.000Z", - "desired_end_date": "2017-10-03T19:00:00.000Z", - "created_at": "2017-10-03T17:48:02.701Z", - "closed_at": null, - "state": "open", - "repositories": [ - 105683718 - ] -} -``` + +### Remove Workspaces from Release Report +#### **DEPRECATED** +#### Endpoint +`PATCH /p1/reports/release/:release_id/workspaces/remove` ## Release Report Issues From 151a8cb43127d388a39385571d6a9d104e089210 Mon Sep 17 00:00:00 2001 From: Kendra Moroz Date: Thu, 28 Feb 2019 14:17:45 -0800 Subject: [PATCH 44/62] Update README.md --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2b42144..cb22a11 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ # Overview -This describes the current version of the public ZenHub API. If you have any questions or feedback, please contact [support](mailto:support@zenhub.com). +The documentation below covers how to leverage the ZenHub API. + +## Getting support +If you have any questions or feedback, contact [support](mailto:support@zenhub.com) for support. You can also submit a feature request [here](https://portal.productboard.com/zenhub). + +--- [Overview](#overview) From 77b1aa50a6d1e550be171422c90d16ea7691ac52 Mon Sep 17 00:00:00 2001 From: Kendra Moroz Date: Thu, 28 Feb 2019 14:18:11 -0800 Subject: [PATCH 45/62] Update README.md --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cb22a11..85d563b 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,7 @@ -# Overview - -The documentation below covers how to leverage the ZenHub API. - -## Getting support +# Getting support If you have any questions or feedback, contact [support](mailto:support@zenhub.com) for support. You can also submit a feature request [here](https://portal.productboard.com/zenhub). ---- +# Overview [Overview](#overview) From 6ec7998a496d81afc745f92b4f135a7eaccca781 Mon Sep 17 00:00:00 2001 From: Kendra Moroz Date: Thu, 28 Feb 2019 14:19:26 -0800 Subject: [PATCH 46/62] Update README.md --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 85d563b..43841e5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Getting support -If you have any questions or feedback, contact [support](mailto:support@zenhub.com) for support. You can also submit a feature request [here](https://portal.productboard.com/zenhub). +If you have any questions or feedback, **contact [support](mailto:support@zenhub.com) for support**. The ZenHub Board for this repo has been sunset - all support inquiries should be submitted directly through the email above. + +You can also submit a feature request [here](https://portal.productboard.com/zenhub). # Overview From 5005a362accecd66640142b9737b2d5febe7ee42 Mon Sep 17 00:00:00 2001 From: Nathan Bardoux <4719911+nbcraft@users.noreply.github.com> Date: Wed, 22 May 2019 12:23:33 -0700 Subject: [PATCH 47/62] Add content-type JSON header section --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 43841e5..a2658de 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen - [Root Endpoint](#root-endpoint) - [Authentication](#authentication) +- [Content-Type: JSON](#content-type-json) - [API Rate Limit](#api-rate-limit) - [Errors](#errors) @@ -71,6 +72,15 @@ Alternatively, you can choose to send the token in the URL using the `access_tok - Each user may only have one token, so generating a new token will invalidate previously created tokens. - For ZenHub Enterprise users, please follow the instructions in `https:///setup/howto/api` +## Content-Type: JSON + +Our REST API only supports JSON content for requests with a body and for responses. +For each request containing a body with JSON, you will need to attach the header `'Content-Type: application/json'` with your request. For example, using `curl` it’d be: + +```sh +curl -H 'Content-Type: application/json' URL +``` + ## API Rate Limit We allow a maximum of 100 requests per minute to our API. All requests responses include the following headers related to this limitation. From 5c93acbd3ebed8a788c061ff0ac025ee0aee0010 Mon Sep 17 00:00:00 2001 From: Oleg Zdornyy Date: Wed, 19 Jun 2019 15:38:50 -0700 Subject: [PATCH 48/62] Add Workspaces routes Add documentation for 3 new routes: 1. GET /p2/repositories/:repo_id/workspaces Get all Workspaces containing :repo_id 2. POST /p2/workspaces/:workspace_id/repositories/:repo_id/issues/:issue_number/moves Move an issue in a Workspace specified by :workspace_id & :repo_id/:issue_number 3. GET /p2/workspaces/:workspace_id/repositories/:repo_id/board Get a Repository's Board data for a specific Workspace specified by :workspace_id & :repo_id All routes containing `pipeline` property now include a `pipelines` which will show all pipelines in all workspaces that issue is in. --- README.md | 610 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 397 insertions(+), 213 deletions(-) diff --git a/README.md b/README.md index a2658de..f6b66d5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Getting support + If you have any questions or feedback, **contact [support](mailto:support@zenhub.com) for support**. The ZenHub Board for this repo has been sunset - all support inquiries should be submitted directly through the email above. You can also submit a feature request [here](https://portal.productboard.com/zenhub). @@ -19,6 +20,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen - [Get Issue Data](#get-issue-data) - [Get Issue Events](#get-issue-events) - [Move an Issue Between Pipelines](#move-an-issue-between-pipelines) + - [Move an Issue Between Pipelines in the oldest Workspace](#move-an-issue-between-pipelines-in-the-oldest-workspace) - [Set Issue Estimate](#set-issue-estimate) - [Epics](#epics) - [Get Epics for a Repository](#get-epics-for-a-repository) @@ -26,8 +28,10 @@ You can also submit a feature request [here](https://portal.productboard.com/zen - [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) - [Convert an Issue to Epic](#convert-issue-to-epic) - [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) -- [Board](#board) - - [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) +- [Workspaces](#workspaces) + - [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) + - [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) + - [Get the oldest ZenHub Board for a repository](#get-the-oldest-zenhub-board-for-a-repository) - [Milestones](#milestones) - [Set the Milestone Start Date](#set-milestone-start-date) - [Get the Milestone Start Date](#get-milestone-start-date) @@ -85,23 +89,23 @@ curl -H 'Content-Type: application/json' URL We allow a maximum of 100 requests per minute to our API. All requests responses include the following headers related to this limitation. -Header | Description ------- | ------- -`X-RateLimit-Limit` | Total number of requests allowed before the reset time -`X-RateLimit-Used` | Number of requests sent in the current cycle. Will be set to 0 at the reset time. -`X-RateLimit-Reset` | Time in UTC epoch seconds when the usage gets reset. +| Header | Description | +| ------------------- | --------------------------------------------------------------------------------- | +| `X-RateLimit-Limit` | Total number of requests allowed before the reset time | +| `X-RateLimit-Used` | Number of requests sent in the current cycle. Will be set to 0 at the reset time. | +| `X-RateLimit-Reset` | Time in UTC epoch seconds when the usage gets reset. | To avoid time differences between your computer and our servers, we suggest to use the `Date` header in the response to know exactly when the limit is reset. -## Errors +# Errors The ZenHub API can return the following errors: -Status Code | Description ------------ | ------- -`401` | The token is not valid. See [Authentication](#authentication). -`403` | Reached request limit to the API. See [API Limits](#api-rate-limits). -`404` | Not found. +| Status Code | Description | +| ----------- | --------------------------------------------------------------------- | +| `401` | The token is not valid. See [Authentication](#authentication). | +| `403` | Reached request limit to the API. See [API Limits](#api-rate-limits). | +| `404` | Not found. | # Endpoint Reference @@ -113,7 +117,8 @@ Status Code | Description - [Get Issue Data](#get-issue-data) - [Get Issue Events](#get-issue-events) -- [Move an Issue Between Pipelines](#move-an-issue-between-pipelines) +- [Move an Issue Between Pipeline](#move-an-issue-between-pipelines) +- [Move an Issue Between Pipelines in the oldest Workspace](#move-an-issue-between-pipelines-in-the-oldest-workspace) - [Set Issue Estimate](#set-issue-estimate) ### Get Issue Data @@ -126,10 +131,10 @@ Get the data for a specific issue. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Example Response @@ -144,8 +149,22 @@ Get the data for a specific issue. } ], "pipeline": { - "name": "In Progress" + "name": "QA", + "pipeline_id": "5d0a7a9741fd098f6b7f58a7", + "workspace_id": "5d0a7a9741fd098f6b7f58ac" }, + "pipelines": [ + { + "name": "QA", + "pipeline_id": "5d0a7a9741fd098f6b7f58a7", + "workspace_id": "5d0a7a9741fd098f6b7f58ac" + }, + { + "name": "Done", + "pipeline_id": "5d0a7cea41fd098f6b7f58b7", + "workspace_id": "5d0a7cea41fd098f6b7f58b8" + } + ], "is_epic": true } ``` @@ -153,6 +172,8 @@ Get the data for a specific issue. #### Notes - `plus_ones[].user_id` was removed from the response. +- `pipeline` object references the oldest Workspace pipeline this issue is in. +- `pipelines` contains all pipelines in all Workspaces this issue is in. - Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. ### Get Issue Events @@ -165,11 +186,10 @@ Get the events for an issue. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required - +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Example Response @@ -211,7 +231,8 @@ Get the events for an issue. }, "to_pipeline": { "name": "In progress" - } + }, + "workspace_id": "5d0a7a9741fd098f6b7f58ac" }, { "user_id": 16717, @@ -229,10 +250,53 @@ Get the events for an issue. - Returns issue events, sorted by creation time, most recent first. - Each event contains the _User ID_ of the user who performed the change, the _Creation Date_ of the event, and the event _Type_. - Type can be either `estimateIssue` or `transferIssue`. The values before and after the event are included in the event data. +- `transferIssue` events include a `workspace_id` indicating in which Workspace the transfer occurred. ### Move an Issue Between Pipelines -Moves an issue between the Pipelines in your repository. +Moves an issue between Pipelines in a Workspace + +#### Endpoint + +`POST /p2/workspaces/:workspace_id/repositories/:repo_id/issues/:issue_number/moves` + +#### URL Parameters + +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `workspace_id` | `String` | Required | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | + +#### Body Parameters + +| Name | Type | Comments | +| ------------- | -------------------- | -------- | +| `pipeline_id` | `String` | Required | +| `position` | `String` or `Number` | Required | + +#### Notes + +- `workspace_id` is the ID of the Workspace you're transferring the issue in. To get a list of Workspaces for `repo_id`, you can use the [_Get ZenHub Workspaces for a repository_](#get-zenhub-workspaces-for-a-repository) endpoint. +- `pipeline_id` is the ID for one of the Pipelines in the Workspace specified by `workspace_id` (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get a ZenHub Board for a repository_](#get-a-zenhub-board-for-a-repository) endpoint. +- `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. + +#### Example Request Body + +```json +{ + "pipeline_id": "58bf13aba426771426665e60", + "position": "top" +} +``` + +#### Example Response + +Status `200` for a successful move. No response body. + +### Move an Issue Between Pipelines in the oldest Workspace + +Moves an issue between Pipelines for a repository in your oldest Workspace #### Endpoint @@ -240,21 +304,21 @@ Moves an issue between the Pipelines in your repository. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`pipeline_id`|`String`|Required -|`position`|`String` or `Number`| Required +| Name | Type | Comments | +| ------------- | -------------------- | -------- | +| `pipeline_id` | `String` | Required | +| `position` | `String` or `Number` | Required | #### Notes -- `pipeline_id` is the ID for one of the Pipelines in your repository (i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get Board Data for a Repository_](#get-the-zenhub-board-data-for-a-repository) endpoint. +- `pipeline_id` is the ID for one of the Pipelines in your oldest Workspace(i.e: In Progress, Done, QA). In order to obtain this ID, you can use the [_Get the oldest ZenHub Board for a repository_](#get-the-oldest-zenhub-board-for-a-repository) endpoint. - `position` can be specified as `top` or `bottom`, or a `0`-based position in the Pipeline such as `1`, which would be the second position in the Pipeline. #### Example Request Body @@ -278,16 +342,16 @@ Status `200` for a successful move. No response body. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`estimate`|`Number`|Required, number representing estimate value +| Name | Type | Comments | +| ---------- | -------- | -------------------------------------------- | +| `estimate` | `Number` | Required, number representing estimate value | #### Example Request @@ -319,9 +383,9 @@ Get all Epics for a repository #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | #### Example Response @@ -337,7 +401,7 @@ Get all Epics for a repository "issue_number": 1342, "repo_id": 1234567, "issue_url": "https://github.com/RepoOwner/RepoName/issues/1342" - }, + } ] } ``` @@ -345,7 +409,7 @@ Get all Epics for a repository #### Notes - The endpoint returns an array of the repository’s Epics. The issue number, repository ID, -and GitHub issue URL is provided for each Epic. + and GitHub issue URL is provided for each Epic. - If an issue is only an issue belonging to an Epic (and not a parent Epic), it is not considered an Epic and won’t be included in the return array. ### Get Epic Data @@ -358,50 +422,85 @@ Get the data for an Epic issue. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`epic_id`|`Number`|Required, Github issue number +| Name | Type | Comments | +| --------- | -------- | ----------------------------- | +| `repo_id` | `Number` | Required | +| `epic_id` | `Number` | Required, Github issue number | #### Notes - `epic_id` is the GitHub issue number. You may fetch the list of Epics using `Get Epics for a repository` endpoint. +- The Epic and the Epic's issues contain `pipeline` (the oldest Workspace's pipeline) and `pipelines` (all Workspace Pipelines that issue is in). #### Example Response + ```json { "total_epic_estimates": { "value": 60 }, "estimate": { "value": 10 }, - "pipeline": { "name": "Backlog" }, + "pipeline": { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + }, + "pipelines": [ + { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + }, + { + "workspace_id": "5d0a7cea41fd098f6b7f58b8", + "name": "In Progress", + "pipeline_id": "5d0a7cea41fd098f6b7f58b5" + } + ], "issues": [ { "issue_number": 3161, "is_epic": true, "repo_id": 1099029, "estimate": { "value": 40 }, - "pipeline": { "name": "New Issues" } + "pipelines": [ + { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + }, + { + "workspace_id": "5d0a7cea41fd098f6b7f58b8", + "name": "In Progress", + "pipeline_id": "5d0a7cea41fd098f6b7f58b5" + } + ], + "pipeline": { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + } }, { "issue_number": 2, "is_epic": false, "repo_id": 1234567, "estimate": { "value": 10 }, - "pipeline": { "name": "New Issues" } - }, - { - "issue_number": 1, - "is_epic": false, - "repo_id": 1234567 - }, - { - "issue_number": 6, - "is_epic": false, - "repo_id": 1234567 - }, - { - "issue_number": 7, - "is_epic": true, - "repo_id": 9876543 + "pipelines": [ + { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + }, + { + "workspace_id": "5d0a7cea41fd098f6b7f58b8", + "name": "In Progress", + "pipeline_id": "5d0a7cea41fd098f6b7f58b5" + } + ], + "pipeline": { + "workspace_id": "5d0a7a9741fd098f6b7f58ac", + "name": "Backlog", + "pipeline_id": "5d0a7a9741fd098f6b7f58a8" + } } ] } @@ -423,7 +522,6 @@ For each issue belonging to the Epic: - repo ID - Estimate value - `is_epic` flag (`true` or `false`) -- if the issue is from the same repository as the Epic, the ZenHub Board’s Pipeline name (from the repo the Epic is in) is attached. ### Convert an Epic to an Issue @@ -435,10 +533,10 @@ Converts an Epic back to a regular issue. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required, the number of the issue to be converted +| Name | Type | Comments | +| -------------- | -------- | ------------------------------------------------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required, the number of the issue to be converted | #### Example Response @@ -456,16 +554,16 @@ Converts an issue to an Epic, along with any issues that should be part of it. #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` +| Name | Type | Comments | +| -------- | ------------------------------------------- | ------------------------------------------------------------ | +| `issues` | `[{repo_id: Number, issue_number: Number}]` | Required, array of Objects with `repo_id` and `issue_number` | #### Example Request Body @@ -495,25 +593,23 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`issue_number`|`Number`|Required +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `issue_number` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`remove_issues`|[`{repo_id: Number, issue_number: Number}`]|Required, array of Objects with `repo_id` and `issue_number` -|`add_issues`|[`{repo_id: Number, issue_number: Number}`]|Required, array of Objects with `repo_id` and `issue_number` +| Name | Type | Comments | +| --------------- | ------------------------------------------- | ------------------------------------------------------------ | +| `remove_issues` | [`{repo_id: Number, issue_number: Number}`] | Required, array of Objects with `repo_id` and `issue_number` | +| `add_issues` | [`{repo_id: Number, issue_number: Number}`] | Required, array of Objects with `repo_id` and `issue_number` | #### Example Request Body ```json { - "remove_issues": [ - { "repo_id": 13550592, "issue_number": 3 } - ], + "remove_issues": [{ "repo_id": 13550592, "issue_number": 3 }], "add_issues": [ { "repo_id": 13550592, "issue_number": 2 }, { "repo_id": 13550592, "issue_number": 1 } @@ -530,10 +626,8 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ```json { - "removed_issues":[ - { "repo_id": 3887883, "issue_number": 3 } - ], - "added_issues":[ + "removed_issues": [{ "repo_id": 3887883, "issue_number": 3 }], + "added_issues": [ { "repo_id": 3887883, "issue_number": 2 }, { "repo_id": 3887883, "issue_number": 1 } ] @@ -546,11 +640,121 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - `add_issues` shows which issues were added in this operation. - Returns a `404` if the Epic doesn’t exist -## Board +## Workspaces + +- [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) +- [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) +- [Get the oldest ZenHub Board for a repository](#get-the-oldest-zenhub-board-for-a-repository) -- [Get Board Data for a Repository](#get-the-zenhub-board-data-for-a-repository) +### Get ZenHub Workspaces for a repository -### Get the ZenHub Board data for a repository +Gets all Workspaces containing `repo_id` + +#### Endpoint + +`GET /p2/repositories/:repo_id/workspaces` + +#### URL Parameters + +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | + +#### Example Response + +```json +[ + { + "name": "Design and UX", + "description": null, + "id": "5d0a7a9741fd098f6b7f58ac", + "repositories": [12345678, 912345] + }, + { + "name": "Roadmap", + "description": "Feature planning and enhancements", + "id": "5d0a7cea41fd098f6b7f58b8", + "repositories": [12345678] + } +] +``` + +### Get a ZenHub Board for a repository + +Get ZenHub Board data for a repository (`repo_id`) within the Workspace (`workspace_id`) + +#### Endpoint + +`GET /p2/workspaces/:workspace_id/repositories/:repo_id/board` + +#### URL Parameters + +| Name | Type | Comments | +| -------------- | -------- | -------- | +| `repo_id` | `Number` | Required | +| `workspace_id` | `String` | Required | + +#### Example Response + +```json +{ + "pipelines": [ + { + "id": "595d430add03f01d32460080", + "name": "New Issues", + "issues": [ + { + "issue_number": 279, + "estimate": { "value": 40 }, + "position": 0, + "is_epic": true + }, + { + "issue_number": 142, + "is_epic": false + } + ] + }, + { + "id": "595d430add03f01d32460081", + "name": "Backlog", + "issues": [ + { + "issue_number": 303, + "estimate": { "value": 40 }, + "position": 3, + "is_epic": false + } + ] + }, + { + "id": "595d430add03f01d32460082", + "name": "To Do", + "issues": [ + { + "issue_number": 380, + "estimate": { "value": 1 }, + "position": 0, + "is_epic": true + }, + { + "issue_number": 284, + "position": 2, + "is_epic": false + }, + { + "issue_number": 329, + "estimate": { "value": 8 }, + "position": 7, + "is_epic": false + } + ] + } + ] +} +``` + +### Get the oldest ZenHub board for a repository #### Endpoint @@ -558,9 +762,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | #### Example Response @@ -641,16 +845,16 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`milestone_number`|`Number`|Required +| Name | Type | Comments | +| ------------------ | -------- | -------- | +| `repo_id` | `Number` | Required | +| `milestone_number` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`start_date`| ISO8601 date string|Required +| Name | Type | Comments | +| ------------ | ------------------- | -------- | +| `start_date` | ISO8601 date string | Required | #### Example Request Body @@ -672,10 +876,10 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required -|`milestone_number`|`Number`|Required +| Name | Type | Comments | +| ------------------ | -------- | -------- | +| `repo_id` | `Number` | Required | +| `milestone_number` | `Number` | Required | #### Example Response @@ -697,9 +901,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | #### Example Response @@ -719,13 +923,13 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o { "blocking": { "issue_number": 5, - "repo_id": 987 + "repo_id": 987 }, "blocked": { "issue_number": 1342, "repo_id": 1234567 } - }, + } ] } ``` @@ -744,16 +948,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`blocking`|`Object`| Required -|`blocking.repo_id`| `Number`| Required -|`blocking.issue_number`| `Number`| Required -|`blocked`|`Object`| Required -|`blocked.repo_id`| `Number`| Required -|`blocked.issue_number`| `Number`| Required +| Name | Type | Comments | +| ----------------------- | -------- | -------- | +| `blocking` | `Object` | Required | +| `blocking.repo_id` | `Number` | Required | +| `blocking.issue_number` | `Number` | Required | +| `blocked` | `Object` | Required | +| `blocked.repo_id` | `Number` | Required | +| `blocked.issue_number` | `Number` | Required | #### Example Request Body + ```json { "blocking": { @@ -768,6 +973,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ``` #### Example Response Body + ```json { "blocking": { @@ -797,16 +1003,17 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`blocking`|`Object`| Required -|`blocking.repo_id`| `Number`| Required -|`blocking.issue_number`| `Number`| Required -|`blocked`|`Object`| Required -|`blocked.repo_id`| `Number`| Required -|`blocked.issue_number`| `Number`| Required +| Name | Type | Comments | +| ----------------------- | -------- | -------- | +| `blocking` | `Object` | Required | +| `blocking.repo_id` | `Number` | Required | +| `blocking.issue_number` | `Number` | Required | +| `blocked` | `Object` | Required | +| `blocked.repo_id` | `Number` | Required | +| `blocked.issue_number` | `Number` | Required | #### Example Request Body + ```json { "blocking": { @@ -844,30 +1051,29 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`title`|`String`|Required -|`description`| `String`| Optional -|`start_date`| ISO8601 date string| Required -|`desired_end_date`| ISO8601 date string| Required -|`repositories`| `[Number]`| Optional +| Name | Type | Comments | +| ------------------ | ------------------- | -------- | +| `title` | `String` | Required | +| `description` | `String` | Optional | +| `start_date` | ISO8601 date string | Required | +| `desired_end_date` | ISO8601 date string | Required | +| `repositories` | `[Number]` | Optional | #### Example Request Body + ```json { "title": "Great title", "description": "Amazing description", "start_date": "2007-01-01T00:00:00Z", "desired_end_date": "2007-01-01T00:00:00Z", - "repositories": [ - 103707262 - ] + "repositories": [103707262] } ``` @@ -883,9 +1089,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o "created_at": "2017-10-12T23:04:21.795Z", "closed_at": null, "state": "open", - "repositories": [ - 103707262 - ] + "repositories": [103707262] } ``` @@ -905,9 +1109,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | #### Example Response @@ -921,9 +1125,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o "created_at": "2017-10-03T17:48:02.701Z", "closed_at": null, "state": "open", - "repositories": [ - 105683718 - ] + "repositories": [105683718] } ``` @@ -935,9 +1137,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`repo_id`|`Number`|Required +| Name | Type | Comments | +| --------- | -------- | -------- | +| `repo_id` | `Number` | Required | #### Example Response @@ -974,19 +1176,19 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`title`|`String`|Required -|`description`|`String`|Optional -|`start_date`|ISO8601 date string|Optional -|`desired_end_date`| ISO8601 date string| Optional -|`state`| `String`|Optional, `open` or `closed` +| Name | Type | Comments | +| ------------------ | ------------------- | ---------------------------- | +| `title` | `String` | Required | +| `description` | `String` | Optional | +| `start_date` | ISO8601 date string | Optional | +| `desired_end_date` | ISO8601 date string | Optional | +| `state` | `String` | Optional, `open` or `closed` | #### Example Request Body @@ -1012,57 +1214,43 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o "created_at": "2017-10-03T18:26:11.700Z", "closed_at": "2017-10-03T18:26:11.700Z", "state": "closed", - "repositories": [ - 105683567, - 105683718 - ] + "repositories": [105683567, 105683718] } ``` ### Add a Repository to a Release Report + #### Endpoint `POST /p1/reports/release/:release_id/repository/:repo_id` #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required -|`repo_id`|`Number`|Required - +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | +| `repo_id` | `Number` | Required | #### Notes -- On success, returns HTTP 200 OK and empty body +- On success, returns HTTP 200 OK and empty body ### Remove a Repository from a Release Report + #### Endpoint `DELETE /p1/reports/release/:release_id/repository/:repo_id` #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required -|`repo_id`|`Number`|Required - +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | +| `repo_id` | `Number` | Required | #### Notes -- On success, returns HTTP 204 OK and empty body - - -### Add Workspaces to a Release Report -#### **DEPRECATED** -#### Endpoint -`PATCH /p1/reports/release/:release_id/workspaces/add` - -### Remove Workspaces from Release Report -#### **DEPRECATED** -#### Endpoint -`PATCH /p1/reports/release/:release_id/workspaces/remove` +- On success, returns HTTP 204 OK and empty body ## Release Report Issues @@ -1077,9 +1265,9 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | #### Example Response @@ -1098,16 +1286,16 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o #### URL Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`release_id`|`String`|Required +| Name | Type | Comments | +| ------------ | -------- | -------- | +| `release_id` | `String` | Required | #### Body Parameters -|Name|Type|Comments ------------- | ------ | ------- -|`add_issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` -|`remove_issues`|`[{repo_id: Number, issue_number: Number}]`|Required, array of Objects with `repo_id` and `issue_number` +| Name | Type | Comments | +| --------------- | ------------------------------------------- | ------------------------------------------------------------ | +| `add_issues` | `[{repo_id: Number, issue_number: Number}]` | Required, array of Objects with `repo_id` and `issue_number` | +| `remove_issues` | `[{repo_id: Number, issue_number: Number}]` | Required, array of Objects with `repo_id` and `issue_number` | #### Note @@ -1117,9 +1305,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ```json { - "add_issues": [ - { "repo_id": 103707262, "issue_number": 3 } - ], + "add_issues": [{ "repo_id": 103707262, "issue_number": 3 }], "remove_issues": [] } ``` @@ -1128,9 +1314,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o ```json { - "added": [ - { "repo_id": 103707262, "issue_number": 3 } - ], + "added": [{ "repo_id": 103707262, "issue_number": 3 }], "removed": [] } ``` @@ -1194,7 +1378,7 @@ Our custom webhook sends a POST request to your webhook for multiple events that "repo": "support", "user_name": "ZenHubIO", "issue_number": "618", - "issue_title": "ZenHub Change Log", + "issue_title": "ZenHub Change Log" } ``` From a09a74158a3d27b7886f13a506a9b2034553966b Mon Sep 17 00:00:00 2001 From: Devin McInnis <1831398+devinmcinnis@users.noreply.github.com> Date: Fri, 23 Aug 2019 12:01:15 -0700 Subject: [PATCH 49/62] Update #workspaces to #workspace #workspaces open the ZenHub app --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f6b66d5..04502ad 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen - [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) - [Convert an Issue to Epic](#convert-issue-to-epic) - [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) -- [Workspaces](#workspaces) +- [Workspaces](#workspace) - [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) - [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) - [Get the oldest ZenHub Board for a repository](#get-the-oldest-zenhub-board-for-a-repository) @@ -640,7 +640,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - `add_issues` shows which issues were added in this operation. - Returns a `404` if the Epic doesn’t exist -## Workspaces +## Workspace - [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) - [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) From 6848fdc598621d6968f911adf75fce3db42f3135 Mon Sep 17 00:00:00 2001 From: Laura Cowin <38923510+lauracowin@users.noreply.github.com> Date: Tue, 3 Sep 2019 13:46:40 -0700 Subject: [PATCH 50/62] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 04502ad..7349b4d 100644 --- a/README.md +++ b/README.md @@ -1420,4 +1420,4 @@ app.post('*', function(req, res) { # Contact us -We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support repo](https://github.com/ZenHubIO/support/issues#boards) or find us on [Twitter](http://www.twitter.com/ZenHubHQ). +We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, please reach us at [support@zenhub.com](mailto:support@zenhub.com) or find us on [Twitter](https://twitter.com/zenhubstatus). From d26ba1afb1f804e8793be3a173cdcc5949f1a711 Mon Sep 17 00:00:00 2001 From: Devin McInnis <1831398+devinmcinnis@users.noreply.github.com> Date: Tue, 7 Jan 2020 15:16:41 -0800 Subject: [PATCH 51/62] Update endpoint from .io -> .com --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7349b4d..6b89045 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen ## Root Endpoint -On Cloud, the root endpoint for the public API is `https://api.zenhub.io/`. +On Cloud, the root endpoint for the public API is `https://api.zenhub.com/`. For ZenHub Enterprise, the root endpoint is `https:///`. ## Authentication From de8f19cee24f9d1a157b5864932947a324fca9c3 Mon Sep 17 00:00:00 2001 From: Ev Haus Date: Mon, 22 Jun 2020 15:34:37 -0700 Subject: [PATCH 52/62] Update docs re: closed pipeline Addresses https://github.com/zenhubhq/freshdesk-tickets/issues/75 --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6b89045..dc5198c 100644 --- a/README.md +++ b/README.md @@ -173,8 +173,9 @@ Get the data for a specific issue. - `plus_ones[].user_id` was removed from the response. - `pipeline` object references the oldest Workspace pipeline this issue is in. + - **NOTE:** If an issue's status is closed, the `pipeline` value will describe the Pipeline that the issue was in prior to the issue being closed. The ZenHub API does not consider the "Closed" Pipeline to be a distinct Pipeline at this time and you should **not** use the Pipeline value to determine whether or not an issue is closed or open (use `status` instead). + - **NOTE:** Reopened issues might take up to one minute to show up in the correct Pipeline. - `pipelines` contains all pipelines in all Workspaces this issue is in. -- Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. ### Get Issue Events From 123718029d99d1a17e42a3c2855a822823f8332c Mon Sep 17 00:00:00 2001 From: George Champlin-Scharff Date: Thu, 18 Feb 2021 16:02:25 -0500 Subject: [PATCH 53/62] Update README.md Add info about the workspace_id to the Notes section, a user booked a support session to find this info out. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index dc5198c..958e6b2 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,7 @@ The ZenHub API can return the following errors: #### Notes - `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). +- `workspace_id` is the ID of the ZenHub Workspace. This is found in the URL for the Workspace after the name of the workspace. For example, the `workspace_id` for `https://app.zenhub.com/workspaces/workflows---product--design-workspace-5f6b5c9ab4fd7d76a3e5b7d8/board?` is `5f6b5c9ab4fd7d76a3e5b7d8`. ## Issues From 58cc06510bdf99cf881f3572a6f093330eda1230 Mon Sep 17 00:00:00 2001 From: Cameron Warje Date: Mon, 12 Apr 2021 16:56:27 -0400 Subject: [PATCH 54/62] Adding instructions for ZHE3 --- README.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 958e6b2..0d22169 100644 --- a/README.md +++ b/README.md @@ -58,12 +58,24 @@ You can also submit a feature request [here](https://portal.productboard.com/zen ## Root Endpoint -On Cloud, the root endpoint for the public API is `https://api.zenhub.com/`. -For ZenHub Enterprise, the root endpoint is `https:///`. +The ZenHub API root endpoint for Cloud is different than that of Enterprise and has also changed across Enterprise versions. Please refer to the table below for the appropriate endpoint. + +ZenHub Version | API Root Endpoint +--- | --- +Cloud | `https://api.zenhub.com/` +Enterprise 2 | `https:///` +Enterprise 3 | `https:///api/` ## Authentication -All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard/tokens) (or `https:///app/dashboard/tokens` for ZenHub Enterprise). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard/tokens) (for ZenHub Enterprise, refer to the table below for the proper link). + +ZenHub Enterprise Version | Auth Token Generation Page +--- | --- +Enterprise 2 | `https:///app/dashboard/tokens` +Enterprise 3 | `https:///dashboard/tokens` + +The token is sent in the `X-Authentication-Token` header. For example, using `curl` it would be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL From e5cabdbaca42345643be7447b5ee9fed44efdb6c Mon Sep 17 00:00:00 2001 From: Cameron Warje Date: Mon, 12 Apr 2021 16:58:25 -0400 Subject: [PATCH 55/62] Removing reference to deprecated instruction page --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 0d22169..611debc 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,6 @@ Alternatively, you can choose to send the token in the URL using the `access_tok #### Notes - Each user may only have one token, so generating a new token will invalidate previously created tokens. -- For ZenHub Enterprise users, please follow the instructions in `https:///setup/howto/api` ## Content-Type: JSON From 50f290b527758229c4f60c6015a731df40548b91 Mon Sep 17 00:00:00 2001 From: Cameron Warje Date: Mon, 12 Apr 2021 17:26:43 -0400 Subject: [PATCH 56/62] Update README.md Clarifying wording. Co-authored-by: Ev Haus --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 611debc..17363d9 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen ## Root Endpoint -The ZenHub API root endpoint for Cloud is different than that of Enterprise and has also changed across Enterprise versions. Please refer to the table below for the appropriate endpoint. +The ZenHub API root endpoint for Cloud is different than that of ZenHub On-Premise Enterprise instances and has also changed across Enterprise versions. Please refer to the table below for the appropriate endpoint. ZenHub Version | API Root Endpoint --- | --- From 42c771c1f63fc1c536d528001f06dcb0582a4afb Mon Sep 17 00:00:00 2001 From: Cameron Warje Date: Wed, 9 Jun 2021 16:14:17 -0400 Subject: [PATCH 57/62] Update API Documentation README --- README.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 17363d9..d6b6bb1 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen [Webhooks](#webhooks) - [Custom Webhooks](#custom-webhooks) + - [Content Type: urlencoded](#content-type-urlencoded) [Contact Us](#contact-us) @@ -1348,7 +1349,14 @@ For instructions, you'll notice the `How to create a webhook` link changes dynam ### Custom webhooks -Our custom webhook sends a POST request to your webhook for multiple events that occur on your ZenHub board: +Our custom webhook sends a POST request to your webhook for multiple events that occur on your ZenHub board. See below for examples of the events and data that they will contain. Please note that the content type in the examples has been written in JSON, however the actual data is sent in **x-www-form-urlencoded** format. + +#### Content Type: urlencoded + +The POST request is sent in the **x-www-form-urlencoded** format. + +Example: +```field1=value1&field2=value2``` #### Issue transfer @@ -1362,6 +1370,8 @@ Our custom webhook sends a POST request to your webhook for multiple events that "issue_number": "618", "issue_title": "ZenHub Change Log", "to_pipeline_name": "New Issues", + "workspace_id": "603fc3e575de63001cc163f9", + "workspace_name" "My Workspace", "from_pipeline_name": "Discussion" } ``` @@ -1408,7 +1418,9 @@ Our custom webhook sends a POST request to your webhook for multiple events that "issue_title": "ZenHub Change Log", "to_pipeline_name": "Backlog", "from_position": "4", - "to_position": "0" + "to_position": "0", + "workspace_id": "603fc3e575de63001cc163f9", + "workspace_name" "My Workspace" } ``` From 9751fb71631ece463cd1601ef54b39e4ba234687 Mon Sep 17 00:00:00 2001 From: Cameron Warje Date: Wed, 9 Jun 2021 16:25:27 -0400 Subject: [PATCH 58/62] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d6b6bb1..a84bac0 100644 --- a/README.md +++ b/README.md @@ -1371,7 +1371,7 @@ Example: "issue_title": "ZenHub Change Log", "to_pipeline_name": "New Issues", "workspace_id": "603fc3e575de63001cc163f9", - "workspace_name" "My Workspace", + "workspace_name": "My Workspace", "from_pipeline_name": "Discussion" } ``` From cce1e8f3532b437739a7413c2a48197ca7a74cc8 Mon Sep 17 00:00:00 2001 From: Joseph Totera Date: Wed, 15 Jun 2022 09:36:49 -0400 Subject: [PATCH 59/62] - Update readme - Added maintenance and support section to readme informing users this api is no longer maintained --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index a84bac0..1b488f8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +# ⚠️ Maintenance +This API is no longer actively maintained and has a limited feature set. Please take a look at our updated API and documentation available at https://developers.zenhub.com + + # Getting support If you have any questions or feedback, **contact [support](mailto:support@zenhub.com) for support**. The ZenHub Board for this repo has been sunset - all support inquiries should be submitted directly through the email above. From 2c820ede48f8bea7766e718fb76607163081f2ab Mon Sep 17 00:00:00 2001 From: Ev Haus Date: Thu, 15 Feb 2024 08:21:37 -0800 Subject: [PATCH 60/62] Update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1b488f8..b102caa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ -# ⚠️ Maintenance -This API is no longer actively maintained and has a limited feature set. Please take a look at our updated API and documentation available at https://developers.zenhub.com +# ⚠️ Deprecation Notice +> [!WARNING] +> This API has not been updated since 2021 is scheduled for deprecation. Please use our new GraphQL API at https://developers.zenhub.com # Getting support From b751859e151ceba383151fe5f8c288bc949c488e Mon Sep 17 00:00:00 2001 From: Ev Haus Date: Thu, 15 Feb 2024 08:24:52 -0800 Subject: [PATCH 61/62] Update README.md --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index b102caa..18666b8 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,7 @@ # Getting support -If you have any questions or feedback, **contact [support](mailto:support@zenhub.com) for support**. The ZenHub Board for this repo has been sunset - all support inquiries should be submitted directly through the email above. - -You can also submit a feature request [here](https://portal.productboard.com/zenhub). +If you have any questions or feedback, **contact [support](mailto:support@zenhub.com)**. You can submit feature requests [here](https://portal.productboard.com/zenhub). # Overview From d48e46813953bccaf6b6ff3a97f6697835fbeff7 Mon Sep 17 00:00:00 2001 From: Ev Haus Date: Wed, 28 May 2025 16:30:35 -0700 Subject: [PATCH 62/62] Update README.md --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index 18666b8..f8e5466 100644 --- a/README.md +++ b/README.md @@ -159,11 +159,6 @@ Get the data for a specific issue. "estimate": { "value": 8 }, - "plus_ones": [ - { - "created_at": "2015-12-11T18:43:22.296Z" - } - ], "pipeline": { "name": "QA", "pipeline_id": "5d0a7a9741fd098f6b7f58a7", @@ -187,7 +182,6 @@ Get the data for a specific issue. #### Notes -- `plus_ones[].user_id` was removed from the response. - `pipeline` object references the oldest Workspace pipeline this issue is in. - **NOTE:** If an issue's status is closed, the `pipeline` value will describe the Pipeline that the issue was in prior to the issue being closed. The ZenHub API does not consider the "Closed" Pipeline to be a distinct Pipeline at this time and you should **not** use the Pipeline value to determine whether or not an issue is closed or open (use `status` instead). - **NOTE:** Reopened issues might take up to one minute to show up in the correct Pipeline.