Getting Started

Zenhub's GraphQL API gives you access to many of the same features we use to build Zenhub. Built using GraphQL, it allows you to structure your requests to fetch only the data that you want while also limiting the number of requests that you'll need to make. If you're unfamilliar with GraphQL, the official GraphQL documentation may be a good place to start.

Authentication

In order to use the GraphQL API, we need to be able to authenticate who is making the request. This is done via a Personal API Key that's associated with your Zenhub account.

To generate your Personal API Key, go to the API section of your Zenhub Dashboard. From here, you can create a new Personal API Key for the GraphQL API. You can have up to 5 Personal API Keys at a time.

Remember to copy the value of the key as it will only be shown to you once. Should you lose the key value, revoke that key and create a new one.

Once you have a Personal API Key, it should be passed along with all requests that are made to the GraphQL API as the value for the Authorization header in the format: "Authorization": "Bearer YOUR_PERSONAL_API_KEY".

Endpoint

To make a request to Zenhub's GraphQL API, send a POST request to https://api.zenhub.com/public/graphql The API only accepts POST requests. Other HTTP methods, such as GET or PUT, will fail.

Errors & Response Codes

As this is a GraphQL API, a response code of 200 does not guarantee that the request was successful. Responses in GraphQL are in JSON and this JSON may contain an "errors" field with a list of errors that occurred with your request. Most of the time, if there's an error or something goes wrong with the request you're trying to make, this error field in the response is where you can find information about it.

It's possible for a few other response codes to come from our API:

Status Code	Description
401	The token is not valid. See Authentication.

Queries & Mutations

note

To test these queries and mutations out, we recommend using our Explorer, an instance of GraphiQL we've included in this website to aid your development. Tools with support for working with GraphQL APIs such as Insomnia would work as well.

As a bit of a starting point, we've included documentation on a couple of common queries and mutations users of the API typically use. If you're looking for a complete list of what's available, head on over to our Explorer to check out the schema and start crafting your queries today.

Getting an Issue

One of the most basic and common things people do is fetch a single issue. This can be done by leveraging the QUERY issueByInfo. Given the issue's repository GitHub ID, issue number, and workspace ID, you can fetch everything about the issue from it's content, any connected issues, what sprints it belongs to, etc.

Sample query

# Sample variables:
# {
#   "workspaceId": "some_workspace_id"
#   "repositoryGhId": 1234,
#   "issueNumber": 1
# }

query getIssueInfo($repositoryGhId: Int!, $issueNumber: Int!, $workspaceId: ID!) {
  issueByInfo(repositoryGhId: $repositoryGhId, issueNumber: $issueNumber) {
    id
    repository {
      id
      ghId
    }
    number
    title
    body
    state
    estimate {
      value
    }
    sprints (first: 10) {
      nodes {
        id
        name
      }
    }
    labels (first: 10) {
      nodes {
        id
        name
        color
      }
    }
  }
}

Moving an Issue

Writing scripts to move issues is another common use of our API. This functionality can be performed via the GraphQL API through the MUTATION moveIssue. Given the ID of the issue you wish to move, along with the ID of the pipeline you'd like to move it to, and the position in that pipeline, you can use this mutation to move the issue as needed.

Sample mutation

# Sample variables:
# {
#   "WorkspaceId": "some_workspace_id",
#   "MoveIssueInput": {
#     "pipelineId": "some_pipeline_id",
#     "issueId": "some_issue_id",
#     "position": 0
#   }
# }

mutation moveIssue($MoveIssueInput: MoveIssueInput!, $WorkspaceId: ID!) {
  moveIssue(input: $MoveIssueInput) {
    issue {
      id
      pipelineIssue(workspaceId: $WorkspaceId) {
        priority {
          id
          name
          color
        }
        pipeline {
          id
        }
      }
    }
  }
}