REST API endpoints for issue fields - GitHub Docs (original) (raw)

Use the REST API to create and manage issue fields for an organization.

List issue fields for an organization

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:

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

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, Description
org string RequiredThe 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 for "List issue fields for an organization"

Request example

get/orgs/{org}/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/orgs/ORG/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 issue field for an organization

Creates a new issue field for an organization.

You can find out more about issue fields in Managing issue fields in 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 issue field for an organization"

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

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

Parameters for "Create issue field for an organization"

Headers

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

Path parameters

Name, Type, Description
org string RequiredThe organization name. The name is not case sensitive.

Body parameters

Name, Type, Description
name string RequiredName of the issue field.
description string or null Description of the issue field.
data_type string RequiredThe 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 organization_members_only (visible only within the organization) or all (visible to all users who can see issues). Only used when the visibility settings feature is enabled. Defaults to organization_members_only.Can be one of: organization_members_only, all
options array of objects or null Options for select fields. Required when data_type is 'single_select' or 'multi_select'.
Properties of optionsName, Type, Descriptionname string RequiredName of the option.description string or null Description of the option.color string RequiredColor for the option.Can be one of: gray, blue, green, yellow, orange, red, pink, purple priority integer RequiredPriority of the option for ordering.

HTTP response status codes for "Create issue field for an organization"

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

Code samples for "Create issue field for an organization"

Request example

post/orgs/{org}/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/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"}]}'

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 issue field for an organization

Updates an issue field for an organization.

You can find out more about issue fields in Managing issue fields in 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 issue field for an organization"

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

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

Parameters for "Update issue field for an organization"

Headers

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

Path parameters

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

Body parameters

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 organization_members_only (visible only within the organization) or all (visible to all users who can see issues). Only used when the visibility settings feature is enabled.Can be one of: organization_members_only, 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 optionsName, Type, Descriptionid integer The id of an existing option to retain or update. Omit this when creating a new option.name string RequiredName of the option.description string or null Description of the option.color string RequiredColor for the option.Can be one of: gray, blue, green, yellow, orange, red, pink, purple priority integer RequiredPriority of the option for ordering.

HTTP response status codes for "Update issue field for an organization"

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

Code samples for "Update issue field for an organization"

Request example

patch/orgs/{org}/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/orgs/ORG/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 issue field for an organization

Deletes an issue field for an organization.

You can find out more about issue fields in Managing issue fields in 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 issue field for an organization"

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

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

Parameters for "Delete issue field for an organization"

Headers

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

Path parameters

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

HTTP response status codes for "Delete issue field for an organization"

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 issue field for an organization"

Request example

delete/orgs/{org}/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/orgs/ORG/issue-fields/ISSUE_FIELD_ID

A header with no content is returned.