Update OpenAPI 3.1 Descriptions

descriptions-next/api.github.com/api.github.com.2022-11-28.yaml

@@ -1767,6 +1767,9 @@ paths:
     get:
       summary: Get Copilot metrics for an enterprise team
       description: |-
+        > [!NOTE]
+        > This endpoint is only applicable to dedicated enterprise accounts for Copilot Business. See "[About enterprise accounts for Copilot Business](https://docs.github.com/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business)."
+
         Use this endpoint to see a breakdown of aggregated metrics for various GitHub Copilot features. See the response schema tab for detailed metrics definitions.
 
         The response contains metrics for up to 28 days prior. Metrics are processed once per day for the previous day,
@@ -1843,7 +1846,7 @@ paths:
       summary: Get a summary of Copilot usage for an enterprise team
       description: |-
         > [!NOTE]
-        > This endpoint is in public preview and is subject to change.
+        > This endpoint is in public preview and is subject to change. This endpoint is only applicable to dedicated enterprise accounts for Copilot Business. See "[About enterprise accounts for Copilot Business](https://docs.github.com/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business)."
 
         You can use this endpoint to see a daily breakdown of aggregated usage metrics for Copilot completions and Copilot Chat in the IDE
         for users within an enterprise team, with a further breakdown of suggestions, acceptances, and number of active users by editor and language for each day.
@@ -8496,13 +8499,11 @@ paths:
         Purchases a GitHub Copilot seat for all users within each specified team.
         The organization will be billed for each seat based on the organization's Copilot plan. For more information about Copilot pricing, see "[About billing for GitHub Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization)."
 
-        Only organization owners can add Copilot seats for their organization members.
-
-        In order for an admin to use this endpoint, the organization must have a Copilot Business or Enterprise subscription and a configured suggestion matching policy.
+        Only organization owners can purchase Copilot seats for their organization members. The organization must have a Copilot Business or Copilot Enterprise subscription and a configured suggestion matching policy.
         For more information about setting up a Copilot subscription, see "[Subscribing to Copilot for your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization)."
         For more information about setting a suggestion matching policy, see "[Managing policies for Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#policies-for-suggestion-matching)."
 
-        The response will contain the total number of new seats that were created and existing seats that were refreshed.
+        The response contains the total number of new seats that were created and existing seats that were refreshed.
 
         OAuth app tokens and personal access tokens (classic) need either the `manage_billing:copilot` or `admin:org` scopes to use this endpoint.
       tags:
@@ -8580,14 +8581,11 @@ paths:
 
         Sets seats for all members of each team specified to "pending cancellation".
         This will cause the members of the specified team(s) to lose access to GitHub Copilot at the end of the current billing cycle unless they retain access through another team.
-
-        For more information about Copilot pricing, see "[About billing for GitHub Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization)."
-
-        For more information about disabling access to Copilot Business or Enterprise, see "[Revoking access to Copilot for members of your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization)."
+        For more information about disabling access to Copilot, see "[Revoking access to Copilot for members of your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization)."
 
         Only organization owners can cancel Copilot seats for their organization members.
 
-        The response will contain the total number of seats set to "pending cancellation".
+        The response contains the total number of seats set to "pending cancellation".
 
         OAuth app tokens and personal access tokens (classic) need either the `manage_billing:copilot` or `admin:org` scopes to use this endpoint.
       tags:
@@ -8667,13 +8665,11 @@ paths:
         Purchases a GitHub Copilot seat for each user specified.
         The organization will be billed for each seat based on the organization's Copilot plan. For more information about Copilot pricing, see "[About billing for GitHub Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization)."
 
-        Only organization owners can add Copilot seats for their organization members.
-
-        In order for an admin to use this endpoint, the organization must have a Copilot Business or Enterprise subscription and a configured suggestion matching policy.
+        Only organization owners can purchase Copilot seats for their organization members. The organization must have a Copilot Business or Copilot Enterprise subscription and a configured suggestion matching policy.
         For more information about setting up a Copilot subscription, see "[Subscribing to Copilot for your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization)."
         For more information about setting a suggestion matching policy, see "[Managing policies for Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#policies-for-suggestion-matching)."
 
-        The response will contain the total number of new seats that were created and existing seats that were refreshed.
+        The response contains the total number of new seats that were created and existing seats that were refreshed.
 
         OAuth app tokens and personal access tokens (classic) need either the `manage_billing:copilot` or `admin:org` scopes to use this endpoint.
       tags:
@@ -8750,14 +8746,11 @@ paths:
 
         Sets seats for all users specified to "pending cancellation".
         This will cause the specified users to lose access to GitHub Copilot at the end of the current billing cycle unless they retain access through team membership.
-
-        For more information about Copilot pricing, see "[About billing for GitHub Copilot in your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization)."
-
-        For more information about disabling access to Copilot Business or Enterprise, see "[Revoking access to Copilot for members of your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization)."
+        For more information about disabling access to Copilot, see "[Revoking access to Copilot for members of your organization](https://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization)."
 
         Only organization owners can cancel Copilot seats for their organization members.
 
-        The response will contain the total number of seats set to "pending cancellation".
+        The response contains the total number of seats set to "pending cancellation".
 
         OAuth app tokens and personal access tokens (classic) need either the `manage_billing:copilot` or `admin:org` scopes to use this endpoint.
       tags:
@@ -89634,18 +89627,20 @@ components:
           description: The type of scan
         status:
           type: string
-          description: The state of the scan. Either "completed" or "running"
+          description: The state of the scan. Either "completed", "running", or "pending"
         completed_at:
           type:
           - string
           - 'null'
           format: date-time
           description: The time that the scan was completed. Empty if the scan is
-            active
+            running
         started_at:
-          type: string
+          type:
+          - string
+          - 'null'
           format: date-time
-          description: The time that the scan was started
+          description: The time that the scan was started. Empty if the scan is pending
     secret-scanning-scan-history:
       type: object
       properties: