From 02e98f7fa2306c27726abcae27ed53d7a1055ba7 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Sun, 21 Apr 2024 13:13:08 +0200
Subject: [PATCH] api-docs: Tweak newly documented invites endpoints
 documentation.

Makes a few small tweaks on the newly documented invites endpoints
for current API documentation conventions that were missed in the
review process.
---
 api_docs/include/rest-endpoints.md |  2 +-
 zerver/openapi/zulip.yaml          | 12 +++++++++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md
index 943100c80c..07eef381dd 100644
--- a/api_docs/include/rest-endpoints.md
+++ b/api_docs/include/rest-endpoints.md
@@ -92,7 +92,7 @@
 
 * [Get all invitations](/api/get-invites)
 * [Send invitations](/api/send-invites)
-* [Create reusable invitation link](/api/create-invite-link)
+* [Create a reusable invitation link](/api/create-invite-link)
 * [Revoke an email invitation](/api/revoke-email-invite)
 
 #### Server & organizations
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 4f7cd62e3a..f5738a25cf 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -12060,7 +12060,7 @@ paths:
   /invites/multiuse:
     post:
       operationId: create-invite-link
-      summary: Create reusable invitation link
+      summary: Create a reusable invitation link
       tags: ["invites"]
       description: |
         Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
@@ -12207,7 +12207,7 @@ paths:
                             "code": "BAD_REQUEST",
                           }
                         description: |
-                          A typical failed JSON response for an invalid `invite_id`:
+                          A typical failed JSON response for an invalid email invitation ID:
   /register:
     post:
       operationId: register-queue
@@ -19836,7 +19836,13 @@ components:
         id:
           type: integer
           description: |
-            The unique ID of the invitation.
+            The ID of the invitation.
+
+            Note that email invitations and reusable invitation links are stored
+            in different database tables on the server, so each ID is guaranteed
+            to be unique in combination with the boolean value of `is_multiuse`,
+            e.g. there can only be one invitation with `id: 1` and `is_multiuse:
+            true`.
         invited_by_user_id:
           type: integer
           description: |