diff --git a/api/openapi/apis/users.yaml b/api/openapi/apis/users.yaml
index 3d3d3dc..10029dd 100644
--- a/api/openapi/apis/users.yaml
+++ b/api/openapi/apis/users.yaml
@@ -48,6 +48,10 @@ paths:
       description: |-
         Create and send user invitation to email.
 
+        We can create invitations for new users or for existing users.
+
+        We don't update existing users, only assign them to new organizations and projects.
+
         ### Authority
 
         - `ADMINISTRATOR`