Issue fields REST API

Note

These endpoints are in private preview and are subject to change

List issue fields for an organization

get/orgs/{org}/issue-fields

Lists all issue fields for an organization. OAuth app tokens and personal access tokens (classic) need the read:org scope to use this endpoint.

Fine-grained access tokens for "List issue fields for an organization"

This endpoint works with the following fine-grained token types:

GitHub App user access tokens. See Generating a user access token for a GitHub App.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

The fine-grained token must have the following permission set:

"Issue Fields" organization permissions (read)

Parameters for "List issue fields for an organization"

Headers

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

Path parameters

Name	Type	Required	Description
`org`	string	Yes	The organization name. The name is not case sensitive.

HTTP response status codes for "List issue fields for an organization"

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

Code samples

cURL

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/issue-fields

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('GET /orgs/{org}/issue-fields', {
  org: 'ORG',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /orgs/ORG/issue-fields

Example response

[
  {
    "id": 1,
    "node_id": "IFT_kwDNAd3NAZo",
    "name": "Text field",
    "description": "DRI",
    "data_type": "text",
    "created_at": "2024-12-11T14:39:09Z",
    "updated_at": "2024-12-11T14:39:09Z"
  },
  {
    "id": 2,
    "node_id": "IFSS_kwDNAd3NAZs",
    "name": "Priority",
    "description": "Level of importance",
    "data_type": "single_select",
    "options": [
      {
        "id": 1,
        "name": "High",
        "color": "red"
      },
      {
        "id": 2,
        "name": "Medium",
        "color": "yellow"
      },
      {
        "id": 3,
        "name": "Low",
        "color": "green"
      }
    ],
    "created_at": "2024-12-11T14:39:09Z",
    "updated_at": "2024-12-11T14:39:09Z"
  }
]

Example schema

{
  "type": "array",
  "items": {
    "title": "Issue Field",
    "description": "A custom attribute defined at the organization level for attaching structured data to issues.",
    "type": "object",
    "nullable": true,
    "properties": {
      "id": {
        "type": "integer",
        "description": "The unique identifier of the issue field."
      },
      "node_id": {
        "type": "string",
        "description": "The node identifier of the issue field."
      },
      "name": {
        "type": "string",
        "description": "The name of the issue field."
      },
      "description": {
        "type": "string",
        "description": "The description of the issue field.",
        "nullable": true
      },
      "data_type": {
        "type": "string",
        "description": "The data type of the issue field.",
        "enum": [
          "text",
          "date",
          "single_select",
          "number"
        ]
      },
      "options": {
        "description": "Available options for single select fields.",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "description": "The unique identifier of the option."
            },
            "name": {
              "type": "string",
              "description": "The name of the option."
            },
            "description": {
              "type": "string",
              "description": "The description of the option.",
              "nullable": true
            },
            "color": {
              "type": "string",
              "description": "The color of the option.",
              "enum": [
                "gray",
                "blue",
                "green",
                "yellow",
                "orange",
                "red",
                "pink",
                "purple"
              ],
              "nullable": true
            },
            "priority": {
              "type": "integer",
              "description": "The priority of the option for ordering.",
              "nullable": true
            },
            "created_at": {
              "type": "string",
              "description": "The time the option was created.",
              "format": "date-time"
            },
            "updated_at": {
              "type": "string",
              "description": "The time the option was last updated.",
              "format": "date-time"
            }
          },
          "required": [
            "id",
            "name"
          ]
        },
        "nullable": true
      },
      "created_at": {
        "type": "string",
        "description": "The time the issue field was created.",
        "format": "date-time"
      },
      "updated_at": {
        "type": "string",
        "description": "The time the issue field was last updated.",
        "format": "date-time"
      }
    },
    "required": [
      "id",
      "node_id",
      "name",
      "data_type"
    ]
  }
}

Create an issue field for an organization

post/orgs/{org}/issue-fields

Creates a new issue field for an organization.

To use this endpoint, the authenticated user must be an administrator for the organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

Fine-grained access tokens for "Create an issue field"

This endpoint works with the following fine-grained token types:

GitHub App user access tokens. See Generating a user access token for a GitHub App.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

The fine-grained token must have the following permission set:

"Issue Fields" organization permissions (write)

Parameters for "Create an issue field"

Headers

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

Path parameters

Name	Type	Required	Description
`org`	string	Yes	The organization name. The name is not case sensitive.

Body parameters

Name	Type	Required	Description
`name`	string	Yes	The name of the issue field.
`description`	string	No	The description of the issue field.
`data_type`	string	Yes	The data type of the issue field. Can be one of: `text`, `date`, `single_select`, `number`.
`options`	array	No	Array of options for single select fields. Required when `data_type` is `single_select`.

Properties of `options`

Name	Type	Required	Description
`name`	string	Yes	The name of the option.
`description`	string	No	The description of the option.
`color`	string	No	The color of the option. Can be one of: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`.
`priority`	integer	No	The priority of the option for ordering.

HTTP response status codes for "Create an issue field"

Status Code	Description
`200`	Response
`404`	Resource not found
`422`	Validation failed

Code samples

cURL

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/issue-fields \
  -d '{"name":"Priority","description":"Level of importance for the issue","data_type":"single_select","options":[{"name":"High","description":"High priority","color":"red"},{"name":"Medium","description":"Medium priority","color":"yellow"},{"name":"Low","description":"Low priority","color":"green"}]}'

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: "YOUR-TOKEN",
});

await octokit.request("POST /orgs/{org}/issue-fields", {
  org: "ORG",
  name: "Priority",
  description: "Level of importance for the issue",
  data_type: "single_select",
  options: [
    {
      name: "High",
      description: "High priority",
      color: "red",
    },
    {
      name: "Medium",
      description: "Medium priority",
      color: "yellow",
    },
    {
      name: "Low",
      description: "Low priority",
      color: "green",
    },
  ],
  headers: {
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /orgs/ORG/issue-fields \
  -f name='Priority' \
  -f description='Level of importance for the issue' \
  -f data_type='single_select' \
  -f options[0][name]='High' \
  -f options[0][description]='High priority' \
  -f options[0][color]='red' \
  -f options[1][name]='Medium' \
  -f options[1][description]='Medium priority' \
  -f options[1][color]='yellow' \
  -f options[2][name]='Low' \
  -f options[2][description]='Low priority' \
  -f options[2][color]='green'

Example response

{
  "id": 3,
  "node_id": "IFSS_kwDNAd3NAZ0",
  "name": "Priority",
  "description": "Level of importance for the issue",
  "data_type": "single_select",
  "options": [
    {
      "id": 4,
      "name": "High",
      "description": "High priority",
      "color": "red",
      "priority": 1,
      "created_at": "2024-12-11T14:45:12Z",
      "updated_at": "2024-12-11T14:45:12Z"
    },
    {
      "id": 5,
      "name": "Medium",
      "description": "Medium priority",
      "color": "yellow",
      "priority": 2,
      "created_at": "2024-12-11T14:45:12Z",
      "updated_at": "2024-12-11T14:45:12Z"
    },
    {
      "id": 6,
      "name": "Low",
      "description": "Low priority",
      "color": "green",
      "priority": 3,
      "created_at": "2024-12-11T14:45:12Z",
      "updated_at": "2024-12-11T14:45:12Z"
    }
  ],
  "created_at": "2024-12-11T14:45:12Z",
  "updated_at": "2024-12-11T14:45:12Z"
}

Update an issue field for an organization

patch/orgs/{org}/issue-fields/{issue_field_id}

Updates an issue field for an organization.

To use this endpoint, the authenticated user must be an administrator for the organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

Fine-grained access tokens for "Update an issue field"

This endpoint works with the following fine-grained token types:

GitHub App user access tokens. See Generating a user access token for a GitHub App.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

The fine-grained token must have the following permission set:

"Issue Fields" organization permissions (write)

Parameters for "Update an issue field"

Headers

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

Path parameters

Name	Type	Required	Description
`org`	string	Yes	The organization name. The name is not case sensitive.
`issue_field_id`	integer	Yes	The unique identifier of the issue field.

Body parameters

Name	Type	Required	Description
`name`	string	No	The name of the issue field.
`description`	string	No	The description of the issue field.
`options`	array	No	Array of options for single select fields. Only applicable for `single_select` fields.

Properties of `options`

Name	Type	Required	Description
`name`	string	Yes	The name of the option.
`description`	string	No	The description of the option.
`color`	string	No	The color of the option. Can be one of: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`.
`priority`	integer	No	The priority of the option for ordering.

HTTP response status codes for "Update an issue field"

Status Code	Description
`200`	Response
`404`	Resource not found
`422`	Validation failed

Code samples

cURL

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/issue-fields/ISSUE_FIELD_ID \
  -d '{"name":"Priority","description":"Level of importance for the issue"}'

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('PATCH /orgs/{org}/issue-fields/{issue_field_id}', {
  org: 'ORG',
  issue_field_id: 'ISSUE_FIELD_ID',
  name: 'Priority',
  description: 'Level of importance for the issue',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /orgs/ORG/issue-fields/ISSUE_FIELD_ID \
   -f 'name=Priority' -f 'description=Level of importance for the issue'

Example response

{
  "id": 512,
  "node_id": "IF_kwDNAd3NAZr",
  "name": "Priority",
  "description": "Level of importance for the issue",
  "data_type": "single_select",
  "options": [
    {
      "id": 1,
      "name": "High",
      "description": "High priority",
      "color": "red",
      "priority": 1,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    },
    {
      "id": 2,
      "name": "Medium",
      "description": "Medium priority",
      "color": "yellow",
      "priority": 2,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    },
    {
      "id": 3,
      "name": "Low",
      "description": "Low priority",
      "color": "green",
      "priority": 3,
      "created_at": "2025-01-15T10:30:15Z",
      "updated_at": "2025-01-15T10:30:15Z"
    }
  ],
  "created_at": "2025-01-15T10:30:15Z",
  "updated_at": "2025-01-15T10:30:15Z"
}

Response schema

{
  "title": "Issue Field",
  "description": "A custom attribute defined at the organization level for attaching structured data to issues.",
  "type": "object",
  "nullable": true,
  "properties": {
    "id": {
      "type": "integer",
      "description": "The unique identifier of the issue field."
    },
    "node_id": {
      "type": "string",
      "description": "The node identifier of the issue field."
    },
    "name": {
      "type": "string",
      "description": "The name of the issue field."
    },
    "description": {
      "type": "string",
      "description": "The description of the issue field.",
      "nullable": true
    },
    "data_type": {
      "type": "string",
      "description": "The data type of the issue field.",
      "enum": [
        "text",
        "date",
        "single_select",
        "number"
      ]
    },
    "options": {
      "description": "Available options for single select fields.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique identifier of the option."
          },
          "name": {
            "type": "string",
            "description": "The name of the option."
          },
          "description": {
            "type": "string",
            "description": "The description of the option.",
            "nullable": true
          },
          "color": {
            "type": "string",
            "description": "The color of the option.",
            "enum": [
              "gray",
              "blue",
              "green",
              "yellow",
              "orange",
              "red",
              "pink",
              "purple"
            ],
            "nullable": true
          },
          "priority": {
            "type": "integer",
            "description": "The priority of the option for ordering.",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "description": "The time the option was created.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "The time the option was last updated.",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "nullable": true
    },
    "created_at": {
      "type": "string",
      "description": "The time the issue field was created.",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "description": "The time the issue field was last updated.",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "node_id",
    "name",
    "data_type"
  ]
}

Delete an issue field for an organization

delete/orgs/{org}/issue-fields/{issue_field_id}

Deletes an issue field for an organization.

To use this endpoint, the authenticated user must be an administrator for the organization. OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

Fine-grained access tokens for "Delete an issue field"

This endpoint works with the following fine-grained token types:

GitHub App user access tokens. See Generating a user access token for a GitHub App.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

The fine-grained token must have the following permission set:

"Issue Fields" organization permissions (write)

Parameters for "Delete an issue field"

Headers

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

Path parameters

Name	Type	Required	Description
`org`	string	Yes	The organization name. The name is not case sensitive.
`issue_field_id`	integer	Yes	The unique identifier of the issue field.

HTTP response status codes for "Delete an issue field"

Status Code	Description
`204`	No Content
`404`	Resource not found
`422`	Validation failed

Code samples

cURL

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/issue-fields/ISSUE_FIELD_ID

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('DELETE /orgs/{org}/issue-fields/{issue_field_id}', {
  org: 'ORG',
  issue_field_id: 'ISSUE_FIELD_ID',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /orgs/ORG/issue-fields/ISSUE_FIELD_ID

Example response

Status: 204 No Content

In this article