Skip to content
forgit api docs

Update issue field for an organization

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

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.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

issue_field_id
required
integer

The unique identifier of the issue field.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
name

Name of the issue field.

string
description

Description of the issue field.

string
nullable
visibility

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.

string
Allowed values: organization_members_only all
options

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.

Array<object>
object
id

The id of an existing option to retain or update. Omit this when creating a new option.

integer
name
required

Name of the option.

string
description

Description of the option.

string
nullable
color
required

Color for the option.

string
Allowed values: gray blue green yellow orange red pink purple
priority
required

Priority of the option for ordering.

integer
Examples

Update name and description

Update the name and description of an issue field

{
  "name": "Priority",
  "description": "Level of importance for the issue"
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Issue Field

A custom attribute defined at the organization level for attaching structured data to issues.

object
id
required

The unique identifier of the issue field.

integer
node_id
required

The node identifier of the issue field.

string
name
required

The name of the issue field.

string
description

The description of the issue field.

string
nullable
data_type
required

The data type of the issue field.

string
Allowed values: text date single_select multi_select number
visibility

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

string
Allowed values: organization_members_only all
options

Available options for single select and multi select fields.

Array<object>
nullable
object
id
required

The unique identifier of the option.

integer
name
required

The name of the option.

string
description

The description of the option.

string
nullable
color

The color of the option.

string
nullable
Allowed values: gray blue green yellow orange red pink purple
priority

The priority of the option for ordering.

integer
nullable
created_at

The time the option was created.

string format: date-time
updated_at

The time the option was last updated.

string format: date-time
created_at

The time the issue field was created.

string format: date-time
updated_at

The time the issue field was last updated.

string format: date-time
Examples
Example default 
{
  "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"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error Simple

Validation Error Simple

object
message
required
string
documentation_url
required
string
errors
Array<string>
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    "example"
  ]
}