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.

Fine-grained access tokens for "List issue fields"

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

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

"Issue Fields" user permissions (read)

HTTP response status codes for "List issue fields"

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

Code samples for "List issue fields"

Request example

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.

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

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

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

"Issue Fields" user permissions (write)

Parameters for "Create an issue field"

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

Name, Type, Description

name string Required

Name of the issue field.

description string or null

Description of the issue field.

data_type string Required

The data type of the issue field.

Can be one of: 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.

Can be one of: 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, Type, Description
`name` string Required Name of the option.
`description` string or null Description of the option.
`color` string Required Color for the option. Can be one of: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`
`priority` integer Required Priority of the option for ordering.

HTTP response status codes for "Create an issue field"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create an issue field"

Request example

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.

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

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

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

"Issue Fields" user 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, Description
`issue_field_id` integer Required The unique identifier of the issue field.

Name, Type, Description

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).

Can be one of: 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

Name, Type, Description
`id` integer The id of an existing option to retain or update. Omit this when creating a new option.
`name` string Required Name of the option.
`description` string or null Description of the option.
`color` string Required Color for the option. Can be one of: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `pink`, `purple`
`priority` integer Required Priority of the option for ordering.

HTTP response status codes for "Update an issue field"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Update an issue field"

Request example

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.

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

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

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

"Issue Fields" user 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, Description
`issue_field_id` integer Required The unique identifier of the issue field.

HTTP response status codes for "Delete an issue field"

Status code	Description
`204`	A header with no content is returned.
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Delete an issue field"

Request example

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

REST API endpoints for issue fields

List issue fields

Fine-grained access tokens for "List issue fields"

HTTP response status codes for "List issue fields"

Code samples for "List issue fields"

Request example

Response

Create an issue field

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

Parameters for "Create an issue field"

HTTP response status codes for "Create an issue field"

Code samples for "Create an issue field"

Request example

Response

Update an issue field

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

Parameters for "Update an issue field"

HTTP response status codes for "Update an issue field"

Code samples for "Update an issue field"

Request example

Response

Delete an issue field

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

Parameters for "Delete an issue field"

HTTP response status codes for "Delete an issue field"

Code samples for "Delete an issue field"

Request example

A header with no content is returned.

Was this Doc helpful?

Help us make GitHub Docs great!

Still need help?