Merge pull request #4992 from github/openapi-update-5869cf6b8f3cbbd48741b5a987a9f281b633d1bcc2ea7cb3b23ddbf8d7da9395

Update OpenAPI 3.0 Descriptions

Author: dinonuggies1

descriptions/api.github.com/api.github.com.2022-11-28.json

@@ -69661,6 +69661,155 @@
         }
       }
     },
+    "/users/{username}/attestations/bulk-list": {
+      "post": {
+        "summary": "List attestations by bulk subject digests",
+        "description": "List a collection of artifact attestations associated with any entry in a list of subject digests owned by a user.\n\nThe collection of attestations returned by this endpoint is filtered according to the authenticated user's permissions; if the authenticated user cannot read a repository, the attestations associated with that repository will not be included in the response. In addition, when using a fine-grained access token the `attestations:read` permission is required.\n\n**Please note:** in order to offer meaningful security benefits, an attestation's signature and timestamps **must** be cryptographically verified, and the identity of the attestation signer **must** be validated. Attestations can be verified using the [GitHub CLI `attestation verify` command](https://cli.github.com/manual/gh_attestation_verify). For more information, see [our guide on how to use artifact attestations to establish a build's provenance](https://docs.github.com/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).",
+        "tags": [
+          "users"
+        ],
+        "operationId": "users/list-attestations-bulk",
+        "externalDocs": {
+          "description": "API method documentation",
+          "url": "https://docs.github.com/rest/users/attestations#list-attestations-by-bulk-subject-digests"
+        },
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/per-page"
+          },
+          {
+            "$ref": "#/components/parameters/pagination-before"
+          },
+          {
+            "$ref": "#/components/parameters/pagination-after"
+          },
+          {
+            "$ref": "#/components/parameters/username"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "subject_digests": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "List of subject digests to fetch attestations for.",
+                    "minItems": 1,
+                    "maxItems": 1024
+                  },
+                  "predicate_type": {
+                    "type": "string",
+                    "description": "Optional filter for fetching attestations with a given predicate type.\nThis option accepts `provenance`, `sbom`, or freeform text for custom predicate types."
+                  }
+                },
+                "required": [
+                  "subject_digests"
+                ]
+              },
+              "examples": {
+                "default": {
+                  "$ref": "#/components/examples/bulk-subject-digest-body"
+                },
+                "withPredicateType": {
+                  "$ref": "#/components/examples/bulk-subject-digest-body-with-predicate-type"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "attestations_subject_digests": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "nullable": true,
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "bundle": {
+                              "type": "object",
+                              "properties": {
+                                "mediaType": {
+                                  "type": "string"
+                                },
+                                "verificationMaterial": {
+                                  "type": "object",
+                                  "properties": {},
+                                  "additionalProperties": true
+                                },
+                                "dsseEnvelope": {
+                                  "type": "object",
+                                  "properties": {},
+                                  "additionalProperties": true
+                                }
+                              },
+                              "description": "The bundle of the attestation."
+                            },
+                            "repository_id": {
+                              "type": "integer"
+                            },
+                            "bundle_url": {
+                              "type": "string"
+                            }
+                          }
+                        }
+                      },
+                      "description": "Mapping of subject digest to bundles."
+                    },
+                    "page_info": {
+                      "type": "object",
+                      "properties": {
+                        "has_next": {
+                          "type": "boolean",
+                          "description": "Indicates whether there is a next page."
+                        },
+                        "has_previous": {
+                          "type": "boolean",
+                          "description": "Indicates whether there is a previous page."
+                        },
+                        "next": {
+                          "type": "string",
+                          "description": "The cursor to the next page."
+                        },
+                        "previous": {
+                          "type": "string",
+                          "description": "The cursor to the previous page."
+                        }
+                      },
+                      "description": "Information about the current page."
+                    }
+                  }
+                },
+                "examples": {
+                  "default": {
+                    "$ref": "#/components/examples/list-attestations-bulk"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "x-github": {
+          "githubCloudOnly": false,
+          "enabledForGitHubApps": true,
+          "category": "users",
+          "subcategory": "attestations"
+        }
+      }
+    },
     "/users/{username}/attestations/delete-request": {
       "post": {
         "summary": "Delete attestations in bulk",