diff --git a/apps/api/v2/swagger/documentation.json b/apps/api/v2/swagger/documentation.json
index af0e2fe361..31ec7fe8f9 100644
--- a/apps/api/v2/swagger/documentation.json
+++ b/apps/api/v2/swagger/documentation.json
@@ -9132,6 +9132,8 @@
           {
             "name": "credentialId",
             "in": "query",
+            "description": "The ID of the user's calendar credential used to access the calendar. Retrieve this from your connected calendar credentials via the `/v2/credentials` endpoint.",
+            "example": 135,
             "required": true,
             "schema": {
               "type": "number"
@@ -9140,6 +9142,8 @@
           {
             "name": "externalId",
             "in": "query",
+            "description": "The external calendar identifier from the calendar provider (e.g., email address for Google Calendar). This is returned when listing connected calendars.",
+            "example": "user@gmail.com",
             "required": true,
             "schema": {
               "type": "string"
diff --git a/docs/api-reference/v2/openapi.json b/docs/api-reference/v2/openapi.json
index 322e220fe9..5ec6fc073d 100644
--- a/docs/api-reference/v2/openapi.json
+++ b/docs/api-reference/v2/openapi.json
@@ -8746,6 +8746,8 @@
           {
             "name": "credentialId",
             "in": "query",
+            "description": "The ID of the user's calendar credential used to access the calendar. Retrieve this from your connected calendar credentials via the `/v2/credentials` endpoint.",
+            "example": 135,
             "required": true,
             "schema": {
               "type": "number"
@@ -8754,6 +8756,8 @@
           {
             "name": "externalId",
             "in": "query",
+            "description": "The external calendar identifier from the calendar provider (e.g., email address for Google Calendar). This is returned when listing connected calendars.",
+            "example": "user@gmail.com",
             "required": true,
             "schema": {
               "type": "string"