2 files changed, 25 insertions, 22 deletions
diff --git a/doc/api/garage-admin-v2.yml b/doc/api/garage-admin-v2.yml
index 5cca7dd1..0b948135 100644
--- a/doc/api/garage-admin-v2.yml
+++ b/doc/api/garage-admin-v2.yml
@@ -950,7 +950,7 @@ paths:
     post:
       tags:
         - Bucket aliases
-      operationId: "AddlBucketAlias"
+      operationId: "AddBucketAlias"
       summary: "Add an alias to a bucket"
       description: |
         Add an alias for the target bucket.
@@ -962,17 +962,19 @@ paths:
           application/json:
             schema:
               type: object
-              required: [bucketId, alias]
+              required: [bucketId]
               properties:
                 bucketId:
                   type: string
                   example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
-                accessKeyId:
+                globalAlias:
                   type: string
-                  example: GK31c2f218a2e44f485b94239e
-                alias:
+                localAlias:
                   type: string
                   example: my_documents
+                accessKeyId:
+                  type: string
+                  example: GK31c2f218a2e44f485b94239e
       responses:
         '500': 
           description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
@@ -1003,17 +1005,18 @@ paths:
           application/json:
             schema:
               type: object
-              required: [bucketId, alias]
+              required: [bucketId]
               properties:
                 bucketId:
                   type: string
                   example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
-                accessKeyId:
+                globalAlias:
                   type: string
-                  example: GK31c2f218a2e44f485b94239e
-                alias:
+                  example: the_bucket
+                localAlias:
+                  type: string
+                accessKeyId:
                   type: string
-                  example: my_documents
       responses:
         '500': 
           description: "The server can not handle your request. Check your connectivity with the rest of the cluster."
diff --git a/doc/drafts/admin-api.md b/doc/drafts/admin-api.md
index 6d24a1b6..ca60ead1 100644
--- a/doc/drafts/admin-api.md
+++ b/doc/drafts/admin-api.md
@@ -753,32 +753,32 @@ Other flags will remain unchanged.
 #### AddBucketAlias `POST /v2/AddBucketAlias`
 
 Creates an alias for a bucket in the namespace of a specific access key.
-If `accessKeyId` is specified, an alias is created in the local namespace
-of the key. Otherwise, a global alias is created.
+To create a global alias, specify the `globalAlias` field.
+To create a local alias, specify the `localAlias` and `accessKeyId` fields.
 
 Request body format:
 
 ```json
 {
     "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
-    "accessKeyId": "GK31c2f218a2e44f485b94239e",
-    "alias": "my-bucket"
+    "globalAlias": "my-bucket"
 }
 ```
 
-#### RemoveBucketAlias `POST /v2/RemoveBucketAlias`
-
-Removes an alias for a bucket in the namespace of a specific access key.
-If `accessKeyId` is specified, the alias is removed from the local namespace
-of the key. Otherwise, the alias is removed from the global namespace.
-
-Request body format:
+or:
 
 ```json
 {
     "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
     "accessKeyId": "GK31c2f218a2e44f485b94239e",
-    "alias": "my-bucket"
+    "localAlias": "my-bucket"
 }
 ```
 
+#### RemoveBucketAlias `POST /v2/RemoveBucketAlias`
+
+Removes an alias for a bucket in the namespace of a specific access key.
+To remove a global alias, specify the `globalAlias` field.
+To remove a local alias, specify the `localAlias` and `accessKeyId` fields.
+
+Request body format: same as AddBucketAlias.