Issue field values REST API

Note

These endpoints are in private preview and are subject to change

List issue field values for an issue

get/repos/{owner}/{repo}/issues/{issue_number}/issue-field-values

Lists all issue field values for a specific issue.

Fine-grained access tokens for "List issue field values for an issue"

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.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

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

"Issues" repository permissions (read)

Parameters for "List issue field values for an issue"

Headers

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

Path parameters

Name	Type	Required	Description
`owner`	string	Yes	The account owner of the repository. The name is not case sensitive.
`repo`	string	Yes	The name of the repository without the `.git` extension. The name is not case sensitive.
`issue_number`	integer	Yes	The number that identifies the issue.

Query parameters

Name	Type	Description
`per_page`	integer	The number of results per page (max 100). For more information, see Using pagination in the REST API.
`page`	integer	The page number of the results to fetch. For more information, see Using pagination in the REST API.

HTTP response status codes for "List issue field values for an issue"

Status Code	Description
`200`	OK
`301`	Moved permanently
`404`	Resource not found
`410`	Gone

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/repos/OWNER/REPO/issues/ISSUE_NUMBER/issue-field-values

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: "YOUR-TOKEN",
});

await octokit.request(
  "GET /repos/{owner}/{repo}/issues/{issue_number}/issue-field-values",
  {
    owner: "OWNER",
    repo: "REPO",
    issue_number: "ISSUE_NUMBER",
    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" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/issue-field-values

Example response

[
  {
    "issue_field_id": 1,
    "node_id": "IFT_GDKND",
    "data_type": "text",
    "value": "DRI"
  },
  {
    "issue_field_id": 2,
    "node_id": "IFSS_SADMS",
    "data_type": "single_select",
    "value": 1,
    "single_select_option": {
      "id": 1,
      "name": "High",
      "color": "red"
    }
  },
  {
    "issue_field_id": 3,
    "node_id": "IFN_POINTS",
    "data_type": "number",
    "value": 42
  },
  {
    "issue_field_id": 4,
    "node_id": "IFD_DUEDATE",
    "data_type": "date",
    "value": "2025-12-25"
  }
]

Add issue field values to an issue

post/repositories/{repository_id}/issues/{issue_number}/issue-field-values

Add custom field values to an issue. You can set values for organization-level issue fields that have been defined for the repository's organization.

This endpoint supports the following field data types:

text: String values for text fields
single_select: Option names for single-select fields (must match an existing option name)
number: Numeric values for number fields
date: ISO 8601 date strings for date fields

Only users with push access to the repository can add issue field values. If you don't have the proper permissions, you'll receive a 403 Forbidden response.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see "Rate limits for the API" and "Best practices for using the REST API."

Fine-grained access tokens for "Add issue field values to an issue"

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.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

The fine-grained token must have at least one of the following permission sets:

"Issues" repository permissions (write)
"Pull requests" repository permissions (write)

Parameters for "Add issue field values to an issue"

Headers

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

Path parameters

Name	Type	Required	Description
`repository_id`	integer	Yes	The unique identifier of the repository.
`issue_number`	integer	Yes	The number that identifies the issue.

Body parameters

Name	Type	Required	Description
`issue_field_values`	array	Yes	An array of issue field values to add to this issue. Each field value must include the field ID and the value to set.

Properties of `issue_field_values` objects

Name	Type	Required	Description
`field_id`	integer	Yes	The ID of the issue field to set
`value`	string or number	Yes	The value to set for the field. The type depends on the field's data type. For text fields, provide a `string` value. For single_select fields, provide the option name as a `string` (must match an existing option). For number fields, provide a `numeric` value. For date fields, provide an ISO 8601 date string.

HTTP response status codes for "Add issue field values to an issue"

Status Code	Description
`200`	OK
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.
`503`	Service unavailable

Code samples

cURL

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/repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values \
  -d '{"issue_field_values":[{"field_id":123,"value":"Critical"},{"field_id":456,"value":5},{"field_id":789,"value":"2024-12-31"}]}'

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('POST /repositories/{repository_id}/issues/{issue_number}/issue-field-values', {
  repository_id: 'REPOSITORY_ID',
  issue_number: 'ISSUE_NUMBER',
  issue_field_values: [
    {
      field_id: 123,
      value: 'Critical'
    },
    {
      field_id: 456,
      value: 5
    },
    {
      field_id: 789,
      value: '2024-12-31'
    }
  ],
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# 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" \
  /repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values \
  --input - <<< '{
  "issue_field_values": [
    {
      "field_id": 123,
      "value": "Critical"
    },
    {
      "field_id": 456,
      "value": 5
    },
    {
      "field_id": 789,
      "value": "2024-12-31"
    }
  ]
}'

Example response

[
  {
    "issue_field_id": 1,
    "node_id": "IFT_GDKND",
    "data_type": "text",
    "value": "DRI"
  },
  {
    "issue_field_id": 2,
    "node_id": "IFSS_SADMS",
    "data_type": "single_select",
    "value": 1,
    "single_select_option": {
      "id": 1,
      "name": "High",
      "color": "red"
    }
  },
  {
    "issue_field_id": 3,
    "node_id": "IFN_POINTS",
    "data_type": "number",
    "value": 42
  },
  {
    "issue_field_id": 4,
    "node_id": "IFD_DUEDATE",
    "data_type": "date",
    "value": "2025-12-25"
  }
]

Example schema

{
  "type": "array",
  "items": {
    "title": "Issue Field Value",
    "description": "A value assigned to an issue field",
    "type": "object",
    "properties": {
      "issue_field_id": {
        "description": "Unique identifier for the issue field.",
        "type": "integer",
        "format": "int64",
        "example": 1
      },
      "node_id": {
        "type": "string",
        "example": "IFT_GDKND"
      },
      "data_type": {
        "description": "The data type of the issue field",
        "type": "string",
        "enum": [
          "text",
          "single_select",
          "number",
          "date"
        ],
        "example": "text"
      },
      "value": {
        "description": "The value of the issue field",
        "anyOf": [
          {
            "type": "string",
            "example": "Sample text"
          },
          {
            "type": "number",
            "example": 42.5
          },
          {
            "type": "integer",
            "example": 1
          }
        ],
        "nullable": true
      },
      "single_select_option": {
        "description": "Details about the selected option (only present for single_select fields)",
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier for the option.",
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "name": {
            "description": "The name of the option",
            "type": "string",
            "example": "High"
          },
          "color": {
            "description": "The color of the option",
            "type": "string",
            "example": "red"
          }
        },
        "required": [
          "id",
          "name",
          "color"
        ],
        "nullable": true
      }
    },
    "required": [
      "issue_field_id",
      "node_id",
      "data_type",
      "value"
    ]
  }
}

Set issue field values for an issue

put/repositories/{repository_id}/issues/{issue_number}/issue-field-values

Set custom field values for an issue, replacing any existing values. You can set values for organization-level issue fields that have been defined for the repository's organization.

This endpoint supports the following field data types:

text: String values for text fields
single_select: Option names for single-select fields (must match an existing option name)
number: Numeric values for number fields
date: ISO 8601 date strings for date fields

This operation will replace all existing field values with the provided ones. If you want to add field values without replacing existing ones, use the POST endpoint instead.

Only users with push access to the repository can set issue field values. If you don't have the proper permissions, you'll receive a 403 Forbidden response.

Fine-grained access tokens for "Set issue field values for an issue"

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.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

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

"Issues" repository permissions (write)
"Pull requests" repository permissions (write)

Parameters for "Set issue field values for an issue"

Headers

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

Path parameters

Name	Type	Required	Description
`repository_id`	integer	Yes	The unique identifier of the repository.
`issue_number`	integer	Yes	The number that identifies the issue.

Body parameters

Name	Type	Required	Description
`issue_field_values`	array	Yes	An array of issue field values to add to this issue. Each field value must include the field ID and the value to set. All existing field values will be replaced.

Properties of `issue_field_values` objects

Name	Type	Required	Description
`field_id`	integer	Yes	The ID of the issue field to set
`value`	string or number	Yes	The value to set for the field. The type depends on the field's data type. For text fields, provide a `string` value. For single_select fields, provide the option name as a `string` (must match an existing option). For number fields, provide a `numeric` value. For date fields, provide an ISO 8601 date string.

HTTP response status codes for "Set issue field values for an issue"

Status Code	Description
`200`	OK
`400`	Bad request
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.
`503`	Service unavailable

Code samples

cURL

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values \
  -d '{"issue_field_values":[{"field_id":123,"value":"Critical"},{"field_id":456,"value":5},{"field_id":789,"value":"2024-12-31"}]}'

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('PUT /repositories/{repository_id}/issues/{issue_number}/issue-field-values', {
  repository_id: 'REPOSITORY_ID',
  issue_number: 'ISSUE_NUMBER',
  issue_field_values: [
    {
      field_id: 123,
      value: 'Critical'
    },
    {
      field_id: 456,
      value: 5
    },
    {
      field_id: 789,
      value: '2024-12-31'
    }
  ],
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values \
  --input - <<< '{
  "issue_field_values": [
    {
      "field_id": 123,
      "value": "Critical"
    },
    {
      "field_id": 456,
      "value": 5
    },
    {
      "field_id": 789,
      "value": "2024-12-31"
    }
  ]
}'

Example response

[
  {
    "issue_field_id": 1,
    "node_id": "IFT_GDKND",
    "data_type": "text",
    "value": "DRI"
  },
  {
    "issue_field_id": 2,
    "node_id": "IFSS_SADMS",
    "data_type": "single_select",
    "value": 1,
    "single_select_option": {
      "id": 1,
      "name": "High",
      "color": "red"
    }
  },
  {
    "issue_field_id": 3,
    "node_id": "IFN_POINTS",
    "data_type": "number",
    "value": 42
  },
  {
    "issue_field_id": 4,
    "node_id": "IFD_DUEDATE",
    "data_type": "date",
    "value": "2025-12-25"
  }
]

Delete an issue field value from an issue

delete/repositories/{repository_id}/issues/{issue_number}/issue-field-values/{issue_field_id}

Remove a specific custom field value from an issue.

Only users with push access to the repository can delete issue field values. If you don't have the proper permissions, you'll receive a 403 Forbidden response.

If the specified field does not have a value set on the issue, this operation will return a 404 error.

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

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.
GitHub App installation access tokens. See Generating an installation access token for a GitHub App.
Fine-grained personal access tokens. See Managing your personal access tokens.

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

"Issues" repository permissions (write)
"Pull requests" repository permissions (write)

Parameters for "Delete an issue field value from an issue"

Headers

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

Path parameters

Name	Type	Required	Description
`repository_id`	integer	Yes	The unique identifier of the repository.
`issue_number`	integer	Yes	The number that identifies the issue.
`issue_field_id`	integer	Yes	The unique identifier of the issue field.

HTTP response status codes for "Delete an issue field value from an issue"

Status Code	Description
`204`	Issue field value deleted successfully
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.
`503`	Service unavailable

Code samples

cURL

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/repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values/ISSUE_FIELD_ID

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: "YOUR-TOKEN",
});

await octokit.request(
  "DELETE /repositories/{repository_id}/issues/{issue_number}/issue-field-values/{issue_field_id}",
  {
    repository_id: "REPOSITORY_ID",
    issue_number: "ISSUE_NUMBER",
    issue_field_id: "ISSUE_FIELD_ID",
    headers: {
      "X-GitHub-Api-Version": "2022-11-28",
    },
  },
);

GitHub CLI

# 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" \
  /repositories/REPOSITORY_ID/issues/ISSUE_NUMBER/issue-field-values/ISSUE_FIELD_ID

Example response

Status: 204 No Content

Issue field values REST API

In this article