From a07b68894c86cdd30145a9de01da94a4e54cfebf Mon Sep 17 00:00:00 2001
From: MHSanaei <ho3ein.sanaei@gmail.com>
Date: Thu, 28 May 2026 02:47:48 +0200
Subject: [PATCH] docs(api): document clients bulkAttach endpoint

---
 frontend/public/openapi.json             | 63 ++++++++++++++++++++++++
 frontend/src/pages/api-docs/endpoints.ts | 11 +++++
 2 files changed, 74 insertions(+)

diff --git a/frontend/public/openapi.json b/frontend/public/openapi.json
index aaf746a4..02c736e9 100644
--- a/frontend/public/openapi.json
+++ b/frontend/public/openapi.json
@@ -2905,6 +2905,69 @@
         }
       }
     },
+    "/panel/api/clients/bulkAttach": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Attach many existing clients to many inbounds in one call. Each client keeps its identity (email/UUID/password/subId) and a shared traffic row; all clients are added to a target inbound in a single AddInboundClient call. Clients already present on a target are reported under skipped. Returns per-email attached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.",
+        "operationId": "post_panel_api_clients_bulkAttach",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "emails": [
+                  "alice",
+                  "bob"
+                ],
+                "inboundIds": [
+                  7,
+                  9
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "attached": [
+                      "alice",
+                      "bob"
+                    ],
+                    "skipped": [
+                      "bob"
+                    ],
+                    "errors": []
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/panel/api/clients/bulkResetTraffic": {
       "post": {
         "tags": [
diff --git a/frontend/src/pages/api-docs/endpoints.ts b/frontend/src/pages/api-docs/endpoints.ts
index 1773da9c..f6a31a71 100644
--- a/frontend/src/pages/api-docs/endpoints.ts
+++ b/frontend/src/pages/api-docs/endpoints.ts
@@ -551,6 +551,17 @@ export const sections: readonly Section[] = [
         body: '{\n  "emails": ["alice", "bob"],\n  "group": "customer-a"\n}',
         response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
       },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/bulkAttach',
+        summary: 'Attach many existing clients to many inbounds in one call. Each client keeps its identity (email/UUID/password/subId) and a shared traffic row; all clients are added to a target inbound in a single AddInboundClient call. Clients already present on a target are reported under skipped. Returns per-email attached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.',
+        params: [
+          { name: 'emails', in: 'body (json)', type: 'array', desc: 'Emails of existing clients to attach.' },
+          { name: 'inboundIds', in: 'body (json)', type: 'integer[]', desc: 'Target inbound IDs to attach every client to.' },
+        ],
+        body: '{\n  "emails": ["alice", "bob"],\n  "inboundIds": [7, 9]\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "attached": ["alice", "bob"],\n    "skipped": ["bob"],\n    "errors": []\n  }\n}',
+      },
       {
         method: 'POST',
         path: '/panel/api/clients/bulkResetTraffic',