# Issue fields REST API

Learn how to use the REST API to manage issue fields for your organization.

> \[!NOTE] These endpoints are in private preview and are subject to change

## List issue fields for an organization

<div class="pb-3 text-mono d-flex flex-row flex-items-start "><span class="IssueLabel IssueLabel--big color-bg-accent-emphasis color-fg-on-emphasis text-uppercase mr-2">get</span><code>/orgs/{org}/issue-fields</code></div>

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](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
* GitHub App installation access tokens. See [Generating an installation access token for a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).
* Fine-grained personal access tokens. See [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).

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

<div class="pb-3 text-mono d-flex flex-row flex-items-start "><span class="IssueLabel IssueLabel--big color-bg-accent-emphasis color-fg-on-emphasis text-uppercase mr-2">post</span><code>/orgs/{org}/issue-fields</code></div>

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](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
* GitHub App installation access tokens. See [Generating an installation access token for a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).
* Fine-grained personal access tokens. See [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).

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

```bash
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

```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

```bash
# 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

```json
{
  "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

<div class="pb-3 text-mono d-flex flex-row flex-items-start "><span class="IssueLabel IssueLabel--big color-bg-accent-emphasis color-fg-on-emphasis text-uppercase mr-2">patch</span><code>/orgs/{org}/issue-fields/{issue_field_id}</code></div>

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](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
* GitHub App installation access tokens. See [Generating an installation access token for a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).
* Fine-grained personal access tokens. See [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).

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

```bash
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

```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

```bash
# 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

```json
{
  "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

<div class="pb-3 text-mono d-flex flex-row flex-items-start "><span class="IssueLabel IssueLabel--big color-bg-accent-emphasis color-fg-on-emphasis text-uppercase mr-2">delete</span><code>/orgs/{org}/issue-fields/{issue_field_id}</code></div>

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](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
* GitHub App installation access tokens. See [Generating an installation access token for a GitHub App](/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app).
* Fine-grained personal access tokens. See [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).

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

```bash
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

```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

```bash
# 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
```