Merge pull request #2966 from buildkite/ev-packages-api-registry-index

[PKG-7402] API docs for registries index

data/nav.yml

@@ -557,7 +557,15 @@
             - name: "Members"
               path: "apis/rest-api/organizations/members"
               pill: "beta"
+        - name: "Packages "
+          # Keep space at end to prevent "Packages" in global nav bar being
+          # highlighted when any child page of "API > REST > Packages" is selected.
+          children:
+            - name: "Registries"
+              path: "apis/rest-api/packages/registries"
         - name: "Pipelines "
+          # Keep space at end to prevent "Pipelines" in global nav bar being
+          # highlighted when any child page of "API > REST > Pipelines" is selected.
           children:
             - name: "Overview"
               path: "apis/rest-api/pipelines"

pages/apis/agent_api.md

@@ -1,12 +1,12 @@
 # Agent REST API overview
 
-The Agent REST API is used for agent registration, agent deregistration, starting jobs on agents, finishing jobs on agents, and agent metrics.
+The agent REST API endpoint is used for agent registration, agent deregistration, starting jobs on agents, finishing jobs on agents, and agent metrics.
 
 The only publicly available endpoint is `/metrics`. The [Buildkite metrics agent](https://github.com/buildkite/buildkite-agent-metrics) uses the data returned by the metrics endpoint for agent autoscaling.
 
-All other endpoints in the Agent API are intended only for use by the Buildkite Agent, therefore stability and backwards compatibility are not guaranteed, and changes won't be announced.
+All other endpoints in the agent API are intended only for use by the Buildkite Agent, therefore stability and backwards compatibility are not guaranteed, and changes won't be announced.
 
-The current version of the Agent API is v3.
+The current version of the agent API is v3.
 
 ## Schema
 
@@ -24,9 +24,9 @@ curl https://agent.buildkite.com
 
 ## Authentication
 
-Unlike the [Buildkite REST API](/docs/apis/rest-api), which uses an [API access token](/docs/apis/rest-api#authentication), the Agent REST API uses an [Agent registration token](/docs/agent/v3/tokens) for authentication.
+Unlike the [Buildkite REST API](/docs/apis/rest-api), which uses an [API access token](/docs/apis/rest-api#authentication), the agent REST API uses an [agent token](/docs/agent/v3/tokens) for authentication.
 
-To authenticate using an Agent registration token, set the `Authorization` HTTP header to the word `Token`, followed by a space, followed by the access token. For example:
+To authenticate using an agent token, set the `Authorization` HTTP header to the word `Token`, followed by a space, followed by the agent token. For example:
 
 ```bash
 curl -H "Authorization: Token $TOKEN" https://agent.buildkite.com/v3/metrics

pages/apis/agent_api/metrics.md

@@ -4,7 +4,7 @@ toc: false
 
 # Metrics API
 
-The Metrics API endpoint provides information on idle and busy agents, jobs, and queues for the [Agent registration token](/docs/agent/v3/tokens) supplied in the request `Authorization` header.
+The metrics API endpoint provides information on idle and busy agents, jobs, and queues for the [Agent registration token](/docs/agent/v3/tokens) supplied in the request `Authorization` header.
 
 ## Get metrics
 

pages/apis/rest_api/access_token.md

@@ -1,8 +1,8 @@
 # Access token API
 
-The Access token API allows you to inspect and revoke an API access token. This can be useful if you find a token, can't identify its owner, and you want to revoke it.
+The access token API endpoint allows you to inspect and revoke an API access token. This can be useful if you find a token, can't identify its owner, and you want to revoke it.
 
->📘
+> 📘
 > All the endpoints expect the token to be provided using the <a href="/docs/apis/rest-api#authentication">Authorization HTTP header</a>.
 
 

pages/apis/rest_api/agents.md

@@ -1,6 +1,5 @@
 # Agents API
 
-
 ## List agents
 
 Returns a [paginated list](<%= paginated_resource_docs_url %>) of an organization's agents. The list only includes connected agents - agents in a disconnected state are not returned.

pages/apis/rest_api/analytics/flaky_tests.md

@@ -1,6 +1,6 @@
 # Flaky tests API
 
-The Flaky test API endpoint provides information about tests detected as flaky in a test suite.
+The flaky test API endpoint provides information about tests detected as flaky in a test suite.
 
 ## List all flaky tests
 

pages/apis/rest_api/clusters.md

@@ -1,6 +1,6 @@
 # Clusters API
 
-The clusters API lets you create and manage clusters in your organization.
+The clusters API endpoint lets you create and manage clusters in your organization.
 
 ## Clusters
 

pages/apis/rest_api/meta.md

@@ -1,6 +1,6 @@
 # Meta API
 
-The Meta API provides information about Buildkite, including a list of Buildkite's IP addresses.
+The meta API endpoint provides information about Buildkite, including a list of Buildkite's IP addresses.
 
 It does not require authentication.
 

pages/apis/rest_api/organizations.md

@@ -1,6 +1,6 @@
 # Organizations API
 
-The organizations API:
+The organizations API endpoint:
 
 - allows you to list organizations and retrieve information about an organization
 

pages/apis/rest_api/organizations/members.md

@@ -1,6 +1,6 @@
 # Organization members API
 
-The organization members API allows users to view all members of an organization.
+The organization members API endpoint allows users to view all members of an organization.
 
 ## Organization member data model
 

pages/apis/rest_api/packages/registries.md

@@ -0,0 +1,35 @@
+# Registries API
+
+The registries API endpoint lets you [create and manage registries](/docs/packages/manage-registries) in your organization.
+
+## List all registries
+
+Returns a list of an organization's registries.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries"
+```
+
+```json
+[
+  {
+    "id": "0191df84-85e4-77aa-83ba-6579084728eb",
+    "graphql_id": "UmVnaXN0cnktLS0wMTkxZGY4NC04NWU0LTc3YWEtODNiYS02NTc5MDg0NzI4ZWI=",
+    "slug": "my-registry",
+    "url": "https://api.buildkite.com/v2/packages/organizations/my-org/registries/my-registry",
+    "web_url": "https://buildkite.com/organizations/my-org/packages/registries/my-registry",
+    "name": "my registry",
+    "ecosystem": "ruby",
+    "description": "registry containing ruby gems",
+    "emoji": null,
+    "color": null,
+    "public": false,
+    "oidc_policy": null
+  }
+]
+```
+
+Required scope: `read_registries`
+
+Success response: `200 OK`

pages/apis/rest_api/pipeline_templates.md

@@ -3,7 +3,7 @@
 > 📘 Enterprise feature
 > [Pipeline templates](https://buildkite.com/docs/pipelines/templates) are only available on an [Enterprise](https://buildkite.com/pricing) plan.
 
-The pipeline templates API allows admins to create and manage pipeline templates for an organization.
+The pipeline templates API endpoint allows admins to create and manage pipeline templates for an organization.
 Non-admins can only read or assign pipeline templates marked as `available` by organization admins.
 
 ## Pipeline template data model

pages/apis/rest_api/pipelines.md

@@ -1,6 +1,6 @@
 # Pipelines API
 
-The pipelines API consists of several endpoints that allow you to manage:
+The pipelines API endpoint consists of several endpoints that allow you to manage:
 
 - pipelines, along with their [builds](/docs/apis/rest-api/builds)
 - a build's [annotations](/docs/apis/rest-api/annotations), [artifacts](/docs/apis/rest-api/artifacts), and [jobs](/docs/apis/rest-api/jobs)

pages/apis/rest_api/rules.md

@@ -1,6 +1,6 @@
 # Rules API
 
-The rules API lets you create and manage rules in your organization.
+The rules API endpoint lets you create and manage rules in your organization.
 
 ## Rules
 

pages/apis/rest_api/teams.md

@@ -1,6 +1,6 @@
 # Teams API
 
-The teams API allows you to view and manage teams within an organization.
+The teams API endpoint allows you to view and manage teams within an organization.
 
 ## Team data model
 

pages/apis/rest_api/teams/members.md

@@ -1,6 +1,6 @@
 # Team members API
 
-The team members API allows users to review, create, update, and delete members associated with a team in your organization.
+The team members API endpoint allows users to review, create, update, and delete members associated with a team in your organization.
 
 ## Team member data model
 

pages/apis/rest_api/teams/pipelines.md

@@ -1,6 +1,6 @@
 # Team pipelines API
 
-The team pipelines API allows users to review, create, update, and delete pipelines associated with a team in your organization.
+The team pipelines API endpoint allows users to review, create, update, and delete pipelines associated with a team in your organization.
 
 ## Team pipeline data model
 

pages/apis/rest_api/teams/suites.md

@@ -1,6 +1,6 @@
 # Team suites API
 
-The team suites API allows users to review, create, update, and delete test suites associated with a team in your organization.
+The team suites API endpoint allows users to review, create, update, and delete test suites associated with a team in your organization.
 
 ## Team suite data model
 

pages/apis/rest_api/user.md

@@ -1,6 +1,6 @@
 # User API
 
-The User API endpoint allows you to inspect details about the user account that owns the API token that is currently being used.
+The user API endpoint allows you to inspect details about the user account that owns the API token that is currently being used.
 
 
 ## Get the current user