Using the API to manage projects (beta)

This article demonstrates how to use the GraphQL API to manage a project.

Authentication

my_org="octo-org"
my_num=5
gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  query($organization: String! $number: Int!){
    organization(login: $organization){
      projectNext(number: $number) {
        id
      }
    }
  }' -f organization=$my_org -F number=$my_num

Finding information about projects

Use queries to get data about projects. For more information, see "About queries."

Finding the node ID of a project

To update your project through the API, you will need to know the node ID of the project.

You can find the node ID of a project if you know the organization name and project number. Replace ORGANIZATION with the name of your organization. For example, octo-org. Replace NUMBER with your project number. To find the project number, look at the project URL. For example, https://github.com/orgs/octo-org/projects/5 has a project number of 5.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"query{organization(login: \"ORGANIZATION\") {projectNext(number: NUMBER){id}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  query{
    organization(login: "ORGANIZATION"){
      projectNext(number: NUMBER) {
        id
      }
    }
  }'

You can also find the node ID of all projects in your organization. The following example will return the node ID and title of the first 20 projects in an organization. Replace ORGANIZATION with the name of your organization. For example, octo-org.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"{organization(login: \"ORGANIZATION\") {projectsNext(first: 20) {nodes {id title}}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  query{
    organization(login: "ORGANIZATION") {
      projectsNext(first: 20) {
        nodes {
          id
          title
        }
      }
    }
  }'

Finding the node ID of a field

To update the value of a field, you will need to know the node ID of the field. Additionally, for single select fields, you will need to know the ID of the options.

The following example will return the ID, name, and settings for the first 20 fields in a project. Replace PROJECT_ID with the node ID of your project.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"query{node(id: \"PROJECT_ID\") {... on ProjectNext {fields(first: 20) {nodes {id name settings}}}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  query{
    node(id: "PROJECT_ID") {
      ... on ProjectNext {
        fields(first: 20) {
          nodes {
            id
            name
            settings
          }
        }
      }
    }
  }'

The response will look similar to the following example:

{
  "data": {
    "node": {
      "fields": {
        "nodes": [
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE1OQ==",
            "name": "Title",
            "settings": "null"
          },
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MA==",
            "name": "Assignees",
            "settings": "null"
          },
          {
            "id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MQ==",
            "name": "Status",
            "settings": "{\"options\":[{\"id\":\"f75ad846\",\"name\":\"Todo\",\"name_html\":\"Todo\"},{\"id\":\"47fc9ee4\",\"name\":\"In Progress\",\"name_html\":\"In Progress\"},{\"id\":\"98236657\",\"name\":\"Done\",\"name_html\":\"Done\"}]}"
          }
        ]
      }
    }
  }
}

Each field has an ID. Additionally, each option in a single select field has an ID.

Finding information about items in a project

You can query the API to find information about items in your project.

The following example will return the title and ID for the first 20 items in a project. For each item, it will also return the value and name for the first 8 fields in the project. If the item is an issue or pull request, it will return the login of the first 10 assignees. Replace PROJECT_ID with the node ID of your project.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"query{node(id: \"PROJECT_ID\") {... on ProjectNext {items(first: 20) {nodes{title id fieldValues(first: 8) {nodes{value projectField{name}}} content{...on Issue {assignees(first: 10) {nodes{login}}} ...on PullRequest {assignees(first: 10) {nodes{login}}}}}}}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  query{
    node(id: "PROJECT_ID") {
      ... on ProjectNext {
        items(first: 20) {
          nodes{
            title
            id
            fieldValues(first: 8) {
              nodes{
                value
                projectField{
                  name
                }
              }
            }
            content{
              ...on Issue {
                assignees(first: 10) {
                  nodes{
                    login
                  }
                }
              }
              ...on PullRequest {
                assignees(first: 10) {
                  nodes{
                    login
                  }
                }
              }
            }
          }
        }
      }
    }
  }'

A project may contain items that a user does not have permission to view. In this case, the response will include redacted item.

{
  "node": {
  "title": "You can't see this item",
  ...
  }
}

Updating projects

Use mutations to update projects. For more information, see "About mutations."

Adding an item to a project

The following example will add an issue or pull request to your project. Replace PROJECT_ID with the node ID of your project. Replace CONTENT_ID with the node ID of the issue or pull request that you want to add.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"mutation {addProjectNextItem(input: {projectId: \"PROJECT_ID\" contentId: \"CONTENT_ID\"}) {projectNextItem {id}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  mutation {
    addProjectNextItem(input: {projectId: "PROJECT_ID" contentId: "CONTENT_ID"}) {
      projectNextItem {
        id
      }
    }
  }'

The response will contain the node ID of the newly created item.

{
  "data": {
    "addProjectNextItem": {
      "projectNextItem": {
        "id": "MDE1OlByb2plY3ROZXh0SXRlbTM0MjEz"
      }
    }
  }
}

If you try add an item that already exists, the existing item ID is returned instead.

Updating a custom, non-single select field

The following example will update a date field. Replace PROJECT_ID with the node ID of your project. Replace ITEM_ID with the node ID of the item you want to update. Replace FIELD_ID with the ID of the field that you want to update.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"2021-5-11\"}) {projectNextItem {id}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  mutation {
    updateProjectNextItemField(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: "2021-5-11"
      }
    ) {
      projectNextItem {
        id
      }
    }
  }'

Updating a single-select field

The following example will update a date field.

• PROJECT_ID - Replace this with the node ID of your project.
• ITEM_ID - Replace this with the node ID of the item you want to update.
• FIELD_ID - Replace this with the ID of the field that you want to update.
• OPTION_ID - Replace this with the ID of the desired value.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"OPTION_ID\"}) {projectNextItem {id}}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  mutation {
    updateProjectNextItemField(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
        fieldId: "FIELD_ID"
        value: "OPTION_ID"
      }
    ) {
      projectNextItem {
        id
      }
    }
  }'

Deleting an item from a project

The following example will delete an item from a project. Replace PROJECT_ID with the node ID of your project. Replace ITEM_ID with the node ID of the item you want to delete.

curl --request POST \
  --url https://api.github.com/graphql \
  --header 'Authorization: token TOKEN' \
  --header 'GraphQL-Features: projects_next_graphql' \
  --data '{"query":"mutation {deleteProjectNextItem(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\"}) {deletedItemId}}"}'

gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
  mutation {
    deleteProjectNextItem(
      input: {
        projectId: "PROJECT_ID"
        itemId: "ITEM_ID"
      }
    ) {
      deletedItemId
    }
  }'

Reference

Objects

ProjectNext

• Closable
• Node
• Updatable

Fields

ProjectNextConnection

The connection type for ProjectNext.

ProjectNextEdge

ProjectNextField

A field inside a project.

ProjectNextFieldConnection

The connection type for ProjectNextField.

ProjectNextFieldEdge

ProjectNextItem

• Node

An item in a ProjectNext.

ProjectNextItemContent

Content associated with a ProjectNextItem.

Types:

• issue - Reference to an issue
• pull request - Reference to a pull request.

ProjectNextItemConnection

The connection type for ProjectNextItem.

ProjectNextItemEdge

ProjectNextItemFieldValue

• Node

A value of a field in an item in a ProjectNext.

ProjectNextItemFieldValueConnection

The connection type for ProjectNextItemFieldValue.

ProjectNextItemEdge

An edge in a connection.

Interfaces

ProjectNextOwner

Represents an owner of a project.

Implemented by

• Organization

Fields

Mutations

addProjectNextItem

Adds an existing item (Issue or PullRequest) to a project.

Input fields

• input(AddProjectNextItemInput!)

Return fields

updateProjectNextItemField

Updates a field of an item from a project.

Input fields

• input(UpdateProjectNextItemFieldInput!)

Return fields

deleteProjectNextItem

Deletes an item from a project.

Input fields

• input(DeleteProjectNextItemInput!)

Return fields

Input Objects

DeleteProjectNextItemInput

Autogenerated input type of AddProjectNextItem.

Input fields

UpdateProjectNextItemFieldInput

Autogenerated input type of UpdateProjectNextItemField.

Input fields

DeleteProjectNextItemInput

Autogenerated input type of DeleteProjectNextItem.

Input fields