diff --git a/content/rest/apps/apps.md b/content/rest/apps/apps.md
index 7f7fa4b74f27..429e024550cf 100644
--- a/content/rest/apps/apps.md
+++ b/content/rest/apps/apps.md
@@ -1,6 +1,7 @@
---
-title: Apps
-intro: 'The GitHub Apps API enables you to retrieve the information about the installation as well as specific information about GitHub Apps.'
+title: GitHub Apps
+allowTitleToDifferFromFilename: true
+intro: 'The {% data variables.product.prodname_github_apps %} API enables you to retrieve information about {% data variables.product.prodname_github_apps %}.'
topics:
- API
miniTocMaxHeadingLevel: 3
@@ -11,12 +12,14 @@ versions:
ghec: '*'
---
+## About the {% data variables.product.prodname_github_apps %} API
+
{% data reusables.apps.general-apps-restrictions %}
This page lists endpoints that you can access while authenticated as a GitHub App. See "[Authenticating as a GitHub App](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app)" to learn more.
When authenticated as a GitHub App, the GitHub Apps API enables you to get high-level information about a GitHub App as well as specific information about installations of an app.
-You can access REST API v3 endpoints while authenticated as a GitHub App. These endpoints have a "Notes" section that contains a bullet point that says "Works with GitHub Apps." You can also access these endpoints while authenticated as a user.
+You can access REST API v3 endpoints while authenticated as a GitHub App. These endpoints have text that says "Works with GitHub Apps." You can also access these endpoints while authenticated as a user.
A subset of REST API v3 endpoints requires authenticating as a GitHub App installation. See [Installations](/rest/reference/apps#installations) for a list of these endpoints.
diff --git a/content/rest/apps/installations.md b/content/rest/apps/installations.md
index 8e858caed43f..52384aab04ca 100644
--- a/content/rest/apps/installations.md
+++ b/content/rest/apps/installations.md
@@ -1,6 +1,8 @@
---
-title: Installations
-intro: 'The Installations API enables you to get information about installations of your GitHub App and perform actions within those installations.'
+title: GitHub App installations
+allowTitleToDifferFromFilename: true
+shortTitle: Installations
+intro: 'The {% data variables.product.prodname_github_app %} installations API enables you to get information about installations of your {% data variables.product.prodname_github_app %} and perform actions within those installations.'
topics:
- API
miniTocMaxHeadingLevel: 3
@@ -11,6 +13,8 @@ versions:
ghec: '*'
---
+## About the {% data variables.product.prodname_github_app %} installations API
+
An _installation_ refers to any user or organization account that has installed the app. For information on how to authenticate as an installation and limit access to specific repositories, see "[Authenticating as an installation](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation)."
To list all GitHub App installations for an organization, see "[List app installations for an organization](/rest/reference/orgs#list-app-installations-for-an-organization)."
diff --git a/content/rest/apps/marketplace.md b/content/rest/apps/marketplace.md
index d49e3bed46db..da34e0cda01f 100644
--- a/content/rest/apps/marketplace.md
+++ b/content/rest/apps/marketplace.md
@@ -1,5 +1,7 @@
---
-title: Marketplace
+title: GitHub Marketplace
+allowTitleToDifferFromFilename: true
+shortTitle: Marketplace
intro: ''
topics:
- API
@@ -9,6 +11,8 @@ versions:
ghec: '*'
---
+## About the {% data variables.product.prodname_marketplace %} API
+
For more information about {% data variables.product.prodname_marketplace %}, see "[GitHub Marketplace](/marketplace/)."
The {% data variables.product.prodname_marketplace %} API allows you to see which customers are using a pricing plan, see a customer's purchases, and see if an account has an active subscription.
diff --git a/content/rest/apps/oauth-applications.md b/content/rest/apps/oauth-applications.md
index 037850e51c81..406e67d4ce90 100644
--- a/content/rest/apps/oauth-applications.md
+++ b/content/rest/apps/oauth-applications.md
@@ -1,5 +1,6 @@
---
-title: OAuth Applications
+title: OAuth Apps
+allowTitleToDifferFromFilename: true
intro: ''
topics:
- API
@@ -11,4 +12,6 @@ versions:
ghec: '*'
---
-You can use this API to manage the OAuth tokens an OAuth application uses to access people's accounts on {% ifversion ghae %}{% data variables.product.product_name %}{% else %}{% data variables.product.product_location %}{% endif %}.
+## About the {% data variables.product.prodname_oauth_app %} API
+
+You can use this API to manage the OAuth tokens an {% data variables.product.prodname_oauth_app %} uses to access people's accounts on {% ifversion ghae %}{% data variables.product.product_name %}{% else %}{% data variables.product.product_location %}{% endif %}.
diff --git a/content/rest/apps/webhooks.md b/content/rest/apps/webhooks.md
index c3cf61466f2c..2b2bc9dc7a03 100644
--- a/content/rest/apps/webhooks.md
+++ b/content/rest/apps/webhooks.md
@@ -1,5 +1,7 @@
---
-title: Webhooks
+title: GitHub App webhooks
+allowTitleToDifferFromFilename: true
+shortTitle: Webhooks
intro: ''
topics:
- API
@@ -11,4 +13,6 @@ versions:
ghec: '*'
---
+## About the {% data variables.product.prodname_github_app %} webhooks API
+
A {% data variables.product.prodname_github_app %}'s webhook allows you to receive HTTP `POST` payloads whenever certain events happen for an app. {% data reusables.webhooks.webhooks-rest-api-links %}
diff --git a/content/rest/codespaces/codespaces.md b/content/rest/codespaces/codespaces.md
index 11d920b1c286..3064bf6b263f 100644
--- a/content/rest/codespaces/codespaces.md
+++ b/content/rest/codespaces/codespaces.md
@@ -11,4 +11,6 @@ miniTocMaxHeadingLevel: 3
{% data reusables.codespaces.codespaces-api-beta-note %}
+## About the Codespaces API
+
The {% data variables.product.prodname_codespaces %} API enables you to manage {% data variables.product.prodname_codespaces %} using the REST API. This API is available for authenticated users and OAuth Apps, but not GitHub Apps. For more information, see "[{% data variables.product.prodname_codespaces %}](/codespaces)."
diff --git a/content/rest/codespaces/machines.md b/content/rest/codespaces/machines.md
index b39416253ff0..c15e0c01366a 100644
--- a/content/rest/codespaces/machines.md
+++ b/content/rest/codespaces/machines.md
@@ -1,6 +1,8 @@
---
-title: Machines
-intro: 'The Machines API allows a user to determine which machine types are available to create a codespace, either on a given repository or as an authenticated user.'
+title: Codespaces machines
+allowTitleToDifferFromFilename: true
+shortTitle: Machines
+intro: 'The Codespaces machines API allows a user to determine which machine types are available to create a codespace, either on a given repository or as an authenticated user.'
versions:
fpt: '*'
ghec: '*'
@@ -9,6 +11,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
-For more information, see "[About machine types](/codespaces/developing-in-codespaces/changing-the-machine-type-for-your-codespace#about-machine-types)."
+## About the Codespaces machines API
+
+The Codespaces machines API allows a user to determine which machine types are available to create a codespace, either on a given repository or as an authenticated user. For more information, see "[About machine types](/codespaces/developing-in-codespaces/changing-the-machine-type-for-your-codespace#about-machine-types)."
You can also use this information when changing the machine of an existing codespace by updating its `machine` property. The machine update will take place the next time the codespace is restarted. For more information, see "[Changing the machine type for your codespace](/codespaces/developing-in-codespaces/changing-the-machine-type-for-your-codespace)."
\ No newline at end of file
diff --git a/content/rest/codespaces/repository-secrets.md b/content/rest/codespaces/repository-secrets.md
index ccab41f36eab..ef08bc4cb07f 100644
--- a/content/rest/codespaces/repository-secrets.md
+++ b/content/rest/codespaces/repository-secrets.md
@@ -1,6 +1,8 @@
---
-title: Repository Secrets
-intro: 'The Repository Secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) for repositories that the user has access to.'
+title: Codespaces repository secrets
+allowTitleToDifferFromFilename: true
+shortTitle: Repository secrets
+intro: 'The Codespaces repository secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) for repositories that the user has access to in a codespace.'
versions:
fpt: '*'
ghec: '*'
@@ -10,6 +12,6 @@ topics:
miniTocMaxHeadingLevel: 3
---
-## Repository Secrets
+## About the Codespaces repository secrets API
-The Repository Secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) for repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see "[Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
\ No newline at end of file
+The Codespaces repository secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) for repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see "[Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
\ No newline at end of file
diff --git a/content/rest/codespaces/secrets.md b/content/rest/codespaces/secrets.md
index fb315dc8ce54..6ea9cb901b50 100644
--- a/content/rest/codespaces/secrets.md
+++ b/content/rest/codespaces/secrets.md
@@ -1,15 +1,16 @@
---
-title: User Secrets
-intro: 'The User Secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) as well as assign secrets to repositories that the user has access to.'
+title: Codespaces user secrets
+allowTitleToDifferFromFilename: true
+shortTitle: User secrets
+intro: 'The Codespaces user secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) as well as assign secrets to repositories that the user has access to in a codespace.'
versions:
fpt: '*'
ghec: '*'
topics:
- API
miniTocMaxHeadingLevel: 3
-allowTitleToDifferFromFilename: true
---
-## User Secrets
+## About the Codespaces user secrets API
-The User Secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) as well as assign secrets to repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see "[Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
\ No newline at end of file
+The Codespaces user secrets API allows a user to create, list, and delete secrets (such as access tokens for cloud services) as well as assign secrets to repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see "[Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."
\ No newline at end of file
diff --git a/content/rest/deployments/deployments.md b/content/rest/deployments/deployments.md
index 84f4f9eea371..56e392feadc6 100644
--- a/content/rest/deployments/deployments.md
+++ b/content/rest/deployments/deployments.md
@@ -11,6 +11,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
+## About the deployments API
+
Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a [`deployment` event](/developers/webhooks-and-events/webhook-events-and-payloads#deployment) that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native).
Deployment statuses allow external services to mark deployments with an `error`, `failure`, `pending`, `in_progress`, `queued`, or `success` state that systems listening to [`deployment_status` events](/developers/webhooks-and-events/webhook-events-and-payloads#deployment_status) can consume.
diff --git a/content/rest/deployments/environments.md b/content/rest/deployments/environments.md
index 1d90c1aa6b55..3e5548afb8a9 100644
--- a/content/rest/deployments/environments.md
+++ b/content/rest/deployments/environments.md
@@ -1,6 +1,8 @@
---
-title: Environments
-intro: 'The Environments API allows you to create, configure, and delete environments.'
+title: Deployment environments
+allowTitleToDifferFromFilename: true
+shortTitle: Environments
+intro: 'The Deployment environments API allows you to create, configure, and delete deployment environments.'
versions:
fpt: '*'
ghes: '>=3.2'
@@ -11,6 +13,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
+## About the Deployment environments API
+
For more information about environments, see "[Using environments for deployment](/actions/deployment/using-environments-for-deployment)." To manage environment secrets, see "[Secrets](/rest/reference/actions#secrets)."
{% data reusables.gated-features.environments %}
\ No newline at end of file
diff --git a/content/rest/orgs/members.md b/content/rest/orgs/members.md
index 40c46bda07cb..0e2b4676c16e 100644
--- a/content/rest/orgs/members.md
+++ b/content/rest/orgs/members.md
@@ -1,5 +1,7 @@
---
-title: Members
+title: Organization members
+allowTitleToDifferFromFilename: true
+shortTitle: Members
intro: ''
versions:
fpt: '*'
diff --git a/content/rest/orgs/webhooks.md b/content/rest/orgs/webhooks.md
index 97ae08ff1c07..7a968e651692 100644
--- a/content/rest/orgs/webhooks.md
+++ b/content/rest/orgs/webhooks.md
@@ -1,5 +1,7 @@
---
-title: Webhooks
+title: Organization webhooks
+allowTitleToDifferFromFilename: true
+shortTitle: Webhooks
intro: ''
versions:
fpt: '*'
@@ -11,11 +13,13 @@ topics:
miniTocMaxHeadingLevel: 3
---
+## About the Organization webhooks API
+
Organization webhooks allow you to receive HTTP `POST` payloads whenever certain events happen in an organization. {% data reusables.webhooks.webhooks-rest-api-links %}
For more information on actions you can subscribe to, see "[{% data variables.product.prodname_dotcom %} event types](/developers/webhooks-and-events/github-event-types)."
-### Scopes & Restrictions
+### Scopes and restrictions
All actions against organization webhooks require the authenticated user to be an admin of the organization being managed. Additionally, OAuth tokens require the `admin:org_hook` scope. For more information, see "[Scopes for OAuth Apps](/developers/apps/scopes-for-oauth-apps)."
diff --git a/content/rest/projects/cards.md b/content/rest/projects/cards.md
index f92c71993516..b90949b575f5 100644
--- a/content/rest/projects/cards.md
+++ b/content/rest/projects/cards.md
@@ -1,6 +1,8 @@
---
-title: Cards
-intro: ''
+title: Project board cards
+shortTitle: Cards
+allowTitleToDifferFromFilename: true
+intro: 'The Project board cards API lets you create and manage cards on a project board.'
versions:
fpt: '*'
ghes: '*'
@@ -10,3 +12,5 @@ topics:
- API
miniTocMaxHeadingLevel: 3
---
+
+{% data reusables.projects.projects-api %}
diff --git a/content/rest/projects/collaborators.md b/content/rest/projects/collaborators.md
index a68e1809bc52..9338e150ca4d 100644
--- a/content/rest/projects/collaborators.md
+++ b/content/rest/projects/collaborators.md
@@ -1,6 +1,8 @@
---
-title: Collaborators
-intro: "This API allows you to interact with an organization's projects."
+title: Project board collaborators
+shortTitle: Collaborators
+allowTitleToDifferFromFilename: true
+intro: 'The Project board collaborators API lets you manage collaborators on a project board.'
versions:
fpt: '*'
ghes: '*'
@@ -11,3 +13,4 @@ topics:
miniTocMaxHeadingLevel: 3
---
+{% data reusables.projects.projects-api %}
diff --git a/content/rest/projects/columns.md b/content/rest/projects/columns.md
index e3c098557471..fc8cc4578295 100644
--- a/content/rest/projects/columns.md
+++ b/content/rest/projects/columns.md
@@ -1,6 +1,8 @@
---
-title: Columns
-intro: ''
+title: Project board columns
+shortTitle: Columns
+allowTitleToDifferFromFilename: true
+intro: 'The Project board columns API lets you create and manage columns on a project board.'
versions:
fpt: '*'
ghes: '*'
@@ -10,3 +12,5 @@ topics:
- API
miniTocMaxHeadingLevel: 3
---
+
+{% data reusables.projects.projects-api %}
diff --git a/content/rest/projects/projects.md b/content/rest/projects/projects.md
index ff8566819831..72c0ddc6995b 100644
--- a/content/rest/projects/projects.md
+++ b/content/rest/projects/projects.md
@@ -1,6 +1,8 @@
---
-title: Projects
-intro: 'The Projects API lets you create, list, update, delete and customize projects in a repository.'
+title: Project boards
+shortTitle: Boards
+allowTitleToDifferFromFilename: true
+intro: 'The Project boards API lets you create and manage projects in a repository.'
versions:
fpt: '*'
ghes: '*'
@@ -9,4 +11,6 @@ versions:
topics:
- API
miniTocMaxHeadingLevel: 3
----
\ No newline at end of file
+---
+
+{% data reusables.projects.projects-api %}
diff --git a/content/rest/teams/discussion-comments.md b/content/rest/teams/discussion-comments.md
index 0dde5647e033..0ff93bb0f666 100644
--- a/content/rest/teams/discussion-comments.md
+++ b/content/rest/teams/discussion-comments.md
@@ -1,5 +1,7 @@
---
-title: Discussion Comments
+title: Team discussion comments
+allowTitleToDifferFromFilename: true
+shortTitle: Discussion comments
intro: 'The team discussion comments API allows you to get, create, edit, and delete discussion comments on a [team discussion](/rest/reference/teams#discussions) post.'
versions:
fpt: '*'
@@ -11,4 +13,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
-Any member of the team's [organization](/rest/reference/orgs) can create and read comments on a public discussion. For more details, see "[About team discussions](/organizations/collaborating-with-your-team/about-team-discussions/)." This API is only available to authenticated members of the team's organization.
\ No newline at end of file
+## About the Team discussion comments API
+
+Any member of the team's [organization](/rest/reference/orgs) can create and read comments on a public discussion. For more details, see "[About team discussions](/organizations/collaborating-with-your-team/about-team-discussions/)."
+
+{% data reusables.organizations.team-api %}
diff --git a/content/rest/teams/discussions.md b/content/rest/teams/discussions.md
index 1a6cc51805f0..6faf1327812a 100644
--- a/content/rest/teams/discussions.md
+++ b/content/rest/teams/discussions.md
@@ -1,6 +1,8 @@
---
-title: Discussions
-intro: "The Team Discussions API allows you to get, create, edit, and delete discussion posts on a team's page."
+title: Team discussions
+allowTitleToDifferFromFilename: true
+shortTitle: Discussions
+intro: "The Team discussions API allows you to get, create, edit, and delete discussion posts on a team's page."
versions:
fpt: '*'
ghes: '*'
@@ -11,4 +13,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
-You can use team discussions to have conversations that are not specific to a repository or project. Any member of the team's [organization](/rest/reference/orgs) can create and read public discussion posts. For more details, see "[About team discussions](//organizations/collaborating-with-your-team/about-team-discussions/)." To learn more about commenting on a discussion post, see the [team discussion comments API](/rest/reference/teams#discussion-comments). This API is only available to authenticated members of the team's organization.
\ No newline at end of file
+## About the Team discussions API
+
+You can use team discussions to have conversations that are not specific to a repository or project. Any member of the team's [organization](/rest/reference/orgs) can create and read public discussion posts. For more details, see "[About team discussions](//organizations/collaborating-with-your-team/about-team-discussions/)." To learn more about commenting on a discussion post, see the [team discussion comments API](/rest/reference/teams#discussion-comments).
+
+{% data reusables.organizations.team-api %}
diff --git a/content/rest/teams/external-groups.md b/content/rest/teams/external-groups.md
index ab172bd08435..d989a5db03a5 100644
--- a/content/rest/teams/external-groups.md
+++ b/content/rest/teams/external-groups.md
@@ -1,6 +1,6 @@
---
-title: External Groups
-intro: 'The external groups API allows you to view the external identity provider groups that are available to your organization and manage the connection between external groups and teams in your organization.'
+title: External groups
+intro: 'The External groups API allows you to view the external identity provider groups that are available to your organization and manage the connection between external groups and teams in your organization.'
versions:
fpt: '*'
ghae: '*'
@@ -10,6 +10,8 @@ topics:
miniTocMaxHeadingLevel: 3
---
+## About the External groups API
+
To use this API, the authenticated user must be a team maintainer or an owner of the organization associated with the team.
{% ifversion ghec %}
diff --git a/content/rest/teams/members.md b/content/rest/teams/members.md
index fdcee0660114..dba2bcbf0d6f 100644
--- a/content/rest/teams/members.md
+++ b/content/rest/teams/members.md
@@ -1,5 +1,7 @@
---
-title: Members
+title: Team members
+allowTitleToDifferFromFilename: true
+shortTitle: Members
intro: ''
versions:
fpt: '*'
@@ -11,7 +13,9 @@ topics:
miniTocMaxHeadingLevel: 3
---
-This API is only available to authenticated members of the team's organization. OAuth access tokens require the `read:org` [scope](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
+## About the Team members API
+
+{% data reusables.organizations.team-api %}
{% ifversion fpt or ghes or ghec %}
{% note %}
diff --git a/content/rest/teams/team-sync.md b/content/rest/teams/team-sync.md
index 3b6dfa15dd99..74ce72e46ef6 100644
--- a/content/rest/teams/team-sync.md
+++ b/content/rest/teams/team-sync.md
@@ -1,6 +1,6 @@
---
-title: Team Synchronization
-intro: 'The Team Synchronization API allows you to manage connections between {% data variables.product.product_name %} teams and external identity provider (IdP) groups.'
+title: Team synchronization
+intro: 'The Team synchronization API allows you to manage connections between {% data variables.product.product_name %} teams and external identity provider (IdP) groups.'
versions:
fpt: '*'
ghec: '*'
@@ -10,6 +10,8 @@ miniTocMaxHeadingLevel: 3
allowTitleToDifferFromFilename: true
---
+## About the Team synchronization API
+
To use this API, the authenticated user must be a team maintainer or an owner of the organization associated with the team. The token you use to authenticate will also need to be authorized for use with your IdP (SSO) provider. For more information, see "Authorizing a personal access token for use with a SAML single sign-on organization."
You can manage GitHub team members through your IdP with team synchronization. Team synchronization must be enabled to use the Team Synchronization API. For more information, see "Synchronizing teams between your identity provider and GitHub."
diff --git a/content/rest/teams/teams.md b/content/rest/teams/teams.md
index fa741a215ecb..41d3a923d88f 100644
--- a/content/rest/teams/teams.md
+++ b/content/rest/teams/teams.md
@@ -11,4 +11,6 @@ topics:
miniTocMaxHeadingLevel: 3
---
-This API is only available to authenticated members of the team's [organization](/rest/reference/orgs). OAuth access tokens require the `read:org` [scope](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). {% data variables.product.prodname_dotcom %} generates the team's `slug` from the team `name`.
+## About the Teams API
+
+{% data reusables.organizations.team-api %}
diff --git a/data/reusables/organizations/team-api.md b/data/reusables/organizations/team-api.md
new file mode 100644
index 000000000000..e9f3eaeb593b
--- /dev/null
+++ b/data/reusables/organizations/team-api.md
@@ -0,0 +1 @@
+This API is only available to authenticated members of the team's [organization](/rest/reference/orgs). OAuth access tokens require the `read:org` [scope](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). {% data variables.product.prodname_dotcom %} generates the team's `slug` from the team `name`.
diff --git a/data/reusables/projects/projects-api.md b/data/reusables/projects/projects-api.md
new file mode 100644
index 000000000000..cbda42276cff
--- /dev/null
+++ b/data/reusables/projects/projects-api.md
@@ -0,0 +1,7 @@
+{% ifversion fpt or ghec %}
+{% note %}
+
+**Note:** This API only applies to project boards. Projects (beta) can be managed with the GraphQL API. For more information, see "[Using the API to manage projects (beta)](/issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects)."
+
+{% endnote %}
+{% endif %}
\ No newline at end of file