From 86542d85533fe9ed7930c87345936618db7f896c Mon Sep 17 00:00:00 2001
From: Steven Webb <steve@buildkite.com>
Date: Wed, 18 Sep 2024 15:02:51 +0800
Subject: [PATCH] Documents package copy api

---
 pages/apis/rest_api/packages/packages.md | 46 +++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md
index f64a29cab2..8718cb2204 100644
--- a/pages/apis/rest_api/packages/packages.md
+++ b/pages/apis/rest_api/packages/packages.md
@@ -41,7 +41,7 @@ Required request form-field content:
 </tbody>
 </table>
 
-Required scope: `create_packages`
+Required scope: `write_packages`
 
 Success response: `200 OK`
 
@@ -80,6 +80,50 @@ Required scope: `read_packages`
 
 Success response: `200 OK`
 
+## Copy a package
+
+Copies a package from a source registry to a destination registry.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X POST "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries/#{source_registry.slug}/packages/#{package.id}/copy?to=#{destination_registry.slug}"
+  -H "Content-Type: application/json"
+```
+
+```json
+{
+  "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",
+  "organization": {
+    "id": "0190e784-eeb7-4ce4-9d2d-87f7aba85433",
+    "slug": "my_great_org",
+    "url": "https://api.buildkite.com/v2/organizations/my_great_org",
+    "web_url": "https://buildkite.com/my_great_org"
+  },
+  "registry": {
+    "id": "0191e238-e0a3-7b0b-bb34-beea0035a39d",
+    "graphql_id": "UmVnaXN0cnktLS0wMTkxZTIzOC1lMGEzLTdiMGItYmIzNC1iZWVhMDAzNWEzOWQ=",
+    "slug": "my-registry",
+    "url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry",
+    "web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry"
+  }
+}
+```
+
+Required [query string parameters](/docs/api#query-string-parameters):
+
+<table class="responsive-table">
+<tbody>
+  <tr><th><code>to</code></th><td>Destination registry slug.<br><em>Example:</em> <code>"to=my-registry"</code>.</td></tr>
+</tbody>
+</table>
+
+Required scopes: `read_packages, write_packages`
+
+Success response: `200 OK`
+
 ## Delete a package
 
 ```bash