REST API endpoints for issue fields

List issue fields

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

“List issue fields”的细粒度访问令牌

此端点支持以下精细令牌类型:

细粒度令牌必须具有以下权限集:

"Issue Fields" user permissions (read)

“List issue fields”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found

“List issue fields”的代码示例

如果你在 GHE.com 上访问 GitHub，请将 api.github.com 替换为企业的专用子域，位于 api.SUBDOMAIN.ghe.com。

请求示例

get/user/issue-fields

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/user/issue-fields

Response

Status: 200

[
  {
    "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"
  },
  {
    "id": 3,
    "node_id": "IFMS_kwDNAd3NAZt",
    "name": "Categories",
    "description": "Issue categories",
    "data_type": "multi_select",
    "options": [
      {
        "id": 4,
        "name": "Frontend",
        "color": "blue"
      },
      {
        "id": 5,
        "name": "Backend",
        "color": "green"
      },
      {
        "id": 6,
        "name": "Infrastructure",
        "color": "purple"
      }
    ],
    "created_at": "2024-12-11T14:39:09Z",
    "updated_at": "2024-12-11T14:39:09Z"
  }
]

Create an issue field

Creates a new issue field for the authenticated user's personal account.

OAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.

“Create an issue field”的细粒度访问令牌

此端点支持以下精细令牌类型:

细粒度令牌必须具有以下权限集:

"Issue Fields" user permissions (write)

“”Create an issue field 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

名称, 类型, 说明

name string 必须

Name of the issue field.

description string or null

Description of the issue field.

data_type string 必须

The data type of the issue field.

可以是以下选项之一: text, date, single_select, multi_select, number

visibility string

The visibility of the issue field. Can be restricted (visible only to the owner and to collaborators on the repository the field is read through) or all (visible to all users who can see issues). Defaults to restricted.

可以是以下选项之一: restricted, all

options array of objects or null

Options for select fields. Required when data_type is 'single_select' or 'multi_select'.

Properties of options

名称, 类型, 说明
`name` string 必须 Name of the option.
`description` string or null Description of the option.
`color` string 必须 Color for the option. 可以是以下选项之一: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`
`priority` integer 必须 Priority of the option for ordering.

“Create an issue field”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Create an issue field”的代码示例

如果你在 GHE.com 上访问 GitHub，请将 api.github.com 替换为企业的专用子域，位于 api.SUBDOMAIN.ghe.com。

请求示例

post/user/issue-fields

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

Response

Status: 200

{
  "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"
}

Update an issue field

Updates an issue field for the authenticated user.

The authenticated user must own the issue field. OAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.

“Update an issue field”的细粒度访问令牌

此端点支持以下精细令牌类型:

细粒度令牌必须具有以下权限集:

"Issue Fields" user permissions (write)

“”Update an issue field 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`issue_field_id` integer 必须 The unique identifier of the issue field.

名称, 类型, 说明

name string

Name of the issue field.

description string or null

Description of the issue field.

visibility string

The visibility of the issue field. Can be restricted (visible only to the owner and to collaborators on the repository the field is read through) or all (visible to all users who can see issues).

可以是以下选项之一: restricted, all

options array of objects

Options for select fields. Only applicable when updating single_select or multi_select fields. When provided, this array replaces the entire existing set of options rather than adding to or updating individual options. To retain or update an existing option, include it in the array with its id. Options sent without an id are treated as new options and may cause existing options to be deleted and recreated.

Properties of options

名称, 类型, 说明
`id` integer The id of an existing option to retain or update. Omit this when creating a new option.
`name` string 必须 Name of the option.
`description` string or null Description of the option.
`color` string 必须 Color for the option. 可以是以下选项之一: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`
`priority` integer 必须 Priority of the option for ordering.

“Update an issue field”的 HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Update an issue field”的代码示例

如果你在 GHE.com 上访问 GitHub，请将 api.github.com 替换为企业的专用子域，位于 api.SUBDOMAIN.ghe.com。

请求示例

patch/user/issue-fields/{issue_field_id}

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

Response

Status: 200

{
  "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"
}

Delete an issue field

Deletes an issue field for the authenticated user.

The authenticated user must own the issue field. OAuth app tokens and personal access tokens (classic) need the user scope to use this endpoint.

“Delete an issue field”的细粒度访问令牌

此端点支持以下精细令牌类型:

细粒度令牌必须具有以下权限集:

"Issue Fields" user permissions (write)

“”Delete an issue field 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`issue_field_id` integer 必须 The unique identifier of the issue field.

“Delete an issue field”的 HTTP 响应状态代码

状态代码	说明
`204`	A header with no content is returned.
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

“Delete an issue field”的代码示例

如果你在 GHE.com 上访问 GitHub，请将 api.github.com 替换为企业的专用子域，位于 api.SUBDOMAIN.ghe.com。

请求示例

delete/user/issue-fields/{issue_field_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/user/issue-fields/ISSUE_FIELD_ID

A header with no content is returned.

Status: 204

List issue fields

“List issue fields”的细粒度访问令牌

“List issue fields”的 HTTP 响应状态代码

“List issue fields”的代码示例

请求示例

Response

Create an issue field

“Create an issue field”的细粒度访问令牌

“”Create an issue field 的参数

“Create an issue field”的 HTTP 响应状态代码

“Create an issue field”的代码示例

请求示例

Response

Update an issue field

“Update an issue field”的细粒度访问令牌

“”Update an issue field 的参数

“Update an issue field”的 HTTP 响应状态代码

“Update an issue field”的代码示例

请求示例

Response

Delete an issue field

“Delete an issue field”的细粒度访问令牌

“”Delete an issue field 的参数

“Delete an issue field”的 HTTP 响应状态代码

“Delete an issue field”的代码示例

请求示例

A header with no content is returned.

此文档是否有帮助？

仍需帮助？