diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md
index 95d0666c2b..f319f625a2 100644
--- a/pages/apis/rest_api/packages/packages.md
+++ b/pages/apis/rest_api/packages/packages.md
@@ -66,6 +66,54 @@ Required scope: `write_packages`
 
 Success response: `200 OK`
 
+## List all packages
+
+Returns a [paginated list](<%= paginated_resource_docs_url %>) of all packages in a registry.
+Packages are listed in the order they were created (newest first).
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages"
+```
+
+```json
+{
+  "items": [
+    {
+      "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
+      "url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
+      "web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
+      "name": "banana",
+      "created_at": "2024-08-22T06:24:53Z",
+      "version": "1.0"
+    },
+    {
+      "id": "019178c2-6b08-7d66-a1db-b79b8ba83151",
+      "url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/packages/019178c2-6b08-7d66-a1db-b79b8ba83151",
+      "web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry/packages/019178c2-6b08-7d66-a1db-b79b8ba83151",
+      "name": "grapes",
+      "created_at": "2024-08-21T06:24:53Z",
+      "version": "2.8.3"
+    }
+  ],
+  "links": {
+    "self": "https://api.buildkite.localhost/v2/packages/organizations/my_great_org/registries/my-registry/packages",
+  }
+}
+```
+
+Optional [query string parameters](/docs/api#query-string-parameters):
+
+<table class="responsive-table">
+  <tbody>
+    <tr><th><code>name</code></th><td>Filters the results by the package name.<br><em>Example:</em> <code>?name=banana</code>.</td></tr>
+  </tbody>
+</table>
+
+Required scope: `read_packages`
+
+Success response: `200 OK`
+
 ## Get a package
 
 Returns the details for a single package.