This document outlines the setup and usage of ZenHub's public API: a RESTful API with JSON responses.
All requests to the API need an API token. Generate a token in the 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.
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.
Issue number is the same as displayed in your GitHub Issues page. For example, to fetch the Zenhub Public API 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, as well as any +1s.
NOTE: Closed issues might take up to 1 minute to show up in the Closed pipeline. Similarly reopened issues might take up to 1 minute to show in the right pipeline.
Here is an example of returned JSON data:
{
"estimate": {
"value": 8
},
"plus_ones": [
{
"user_id": 16717,
"created_at": "2015-12-11T18:43:22.296Z"
}
],
"pipeline": {
"name": "In Progress"
}
}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.
Issue number is the same as displayed in your GitHub Issues page. For example, to fetch the Zenhub Public API 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.
Here is an example of returned JSON data:
[
{
"user_id": 16717,
"type": "estimateIssue",
"created_at": "2015-12-11T19:43:22.296Z",
"from_estimate": {
"value": 8
}
},
{
"user_id": 16717,
"type": "estimateIssue",
"created_at": "2015-12-11T18:43:22.296Z",
"from_estimate": {
"value": 4
},
"to_estimate": {
"value": 8
}
},
{
"user_id": 16717,
"type": "estimateIssue",
"created_at": "2015-12-11T13:43:22.296Z",
"to_estimate": {
"value": 4
}
},
{
"user_id": 16717,
"type": "transferIssue",
"created_at": "2015-12-11T12:43:22.296Z",
"from_pipeline": {
"name": "Backlog"
},
"to_pipeline": {
"name": "In progress"
}
},
{
"user_id": 16717,
"type": "transferIssue",
"created_at": "2015-12-11T11:43:22.296Z",
"to_pipeline": {
"name": "Backlog"
}
}
]GET https://api.zenhub.io/p1/repositories/:repo_id/board
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 to find out your repository's ID.
For example, the URL to fetch the ZenHubIO/support would be https://api.zenhub.io/p1/repositories/13550592/board.
The endpoint returns the Board's pipelines, plus the issues contained within each pipeline. For each issue it returns the issue number, its position in the board, 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 in the Board.
Note: Closed issues might take up to 1 minute to show up in the Closed pipeline. Similarly reopened issues might take up to 1 minute to show in the right pipeline.
This is an example of returned JSON data:
{
"pipelines": [
{
"name": "New Issues",
"issues": [
{
"issue_number": 279,
"estimate": {
"value": 40
},
"position": 0
},
{
"issue_number": 142
}
]
},
{
"name": "Backlog",
"issues": [
{
"issue_number": 303,
"estimate": {
"value": 40
},
"position": 3
}
]
},
{
"name": "To Do",
"issues": [
{
"issue_number": 380,
"estimate": {
"value": 1
},
"position": 0
},
{
"issue_number": 284,
"position": 2
},
{
"issue_number": 329,
"estimate": {
"value": 8
},
"position": 7
}
]
}
]
}We allow 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. |
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.
The ZenHub API can return the following errors:
| Status Code | Meaning |
|---|---|
| 401 | The token is not valid. See Authentication. |
| 403 | Reached request limit to the API. See API Limits. |
| 404 | Not found. |
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 or find us on Twitter.