diff --git a/data/nav.yml b/data/nav.yml index 605e8cae2e..f3a7c62f58 100644 --- a/data/nav.yml +++ b/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" diff --git a/pages/apis/agent_api.md b/pages/apis/agent_api.md index 698a242a94..7595ef4f4d 100644 --- a/pages/apis/agent_api.md +++ b/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 diff --git a/pages/apis/agent_api/metrics.md b/pages/apis/agent_api/metrics.md index 4135bb484a..27a964f641 100644 --- a/pages/apis/agent_api/metrics.md +++ b/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 diff --git a/pages/apis/rest_api/access_token.md b/pages/apis/rest_api/access_token.md index e528b98c3a..8c8ed89b62 100644 --- a/pages/apis/rest_api/access_token.md +++ b/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 Authorization HTTP header. diff --git a/pages/apis/rest_api/agents.md b/pages/apis/rest_api/agents.md index d371ce8786..e1508d9dba 100644 --- a/pages/apis/rest_api/agents.md +++ b/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. diff --git a/pages/apis/rest_api/analytics/flaky_tests.md b/pages/apis/rest_api/analytics/flaky_tests.md index 99154ced6b..f5de36c0b7 100644 --- a/pages/apis/rest_api/analytics/flaky_tests.md +++ b/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 diff --git a/pages/apis/rest_api/clusters.md b/pages/apis/rest_api/clusters.md index 33bb0f3905..27cffb89f0 100644 --- a/pages/apis/rest_api/clusters.md +++ b/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 diff --git a/pages/apis/rest_api/meta.md b/pages/apis/rest_api/meta.md index 0db9a8ff15..492f72bfdc 100644 --- a/pages/apis/rest_api/meta.md +++ b/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. diff --git a/pages/apis/rest_api/organizations.md b/pages/apis/rest_api/organizations.md index e71dd7ef93..a74b16abfb 100644 --- a/pages/apis/rest_api/organizations.md +++ b/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 diff --git a/pages/apis/rest_api/organizations/members.md b/pages/apis/rest_api/organizations/members.md index 9e5dfae107..f05b73f6d3 100644 --- a/pages/apis/rest_api/organizations/members.md +++ b/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 diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md new file mode 100644 index 0000000000..85de10f1ba --- /dev/null +++ b/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` diff --git a/pages/apis/rest_api/pipeline_templates.md b/pages/apis/rest_api/pipeline_templates.md index 052b055367..abf2cf1b19 100644 --- a/pages/apis/rest_api/pipeline_templates.md +++ b/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 diff --git a/pages/apis/rest_api/pipelines.md b/pages/apis/rest_api/pipelines.md index 1a0c04024c..5bfa3f2303 100644 --- a/pages/apis/rest_api/pipelines.md +++ b/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) diff --git a/pages/apis/rest_api/rules.md b/pages/apis/rest_api/rules.md index c2eed2e7c3..1395469ff0 100644 --- a/pages/apis/rest_api/rules.md +++ b/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 diff --git a/pages/apis/rest_api/teams.md b/pages/apis/rest_api/teams.md index 647501f212..ee2e5c961d 100644 --- a/pages/apis/rest_api/teams.md +++ b/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 diff --git a/pages/apis/rest_api/teams/members.md b/pages/apis/rest_api/teams/members.md index 13cd1cda02..c1cc514c9f 100644 --- a/pages/apis/rest_api/teams/members.md +++ b/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 diff --git a/pages/apis/rest_api/teams/pipelines.md b/pages/apis/rest_api/teams/pipelines.md index 34634081c9..956cce4495 100644 --- a/pages/apis/rest_api/teams/pipelines.md +++ b/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 diff --git a/pages/apis/rest_api/teams/suites.md b/pages/apis/rest_api/teams/suites.md index 786d825ef4..f0e447cc23 100644 --- a/pages/apis/rest_api/teams/suites.md +++ b/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 diff --git a/pages/apis/rest_api/user.md b/pages/apis/rest_api/user.md index 9a34111aee..6c303e859c 100644 --- a/pages/apis/rest_api/user.md +++ b/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