Skip to content

Open-source live-chat, email support, omni-channel desk. An alternative to Intercom, Zendesk, Salesforce Service Cloud etc. 🔥💬

docs: use portal slug in help center API paths (#16318)

Sivin Varghesefb2a9f4b97b1
diff --git a/swagger/parameters/index.yml b/swagger/parameters/index.yml
index d9cb6872c88..feaa6242cba 100644
--- a/swagger/parameters/index.yml
+++ b/swagger/parameters/index.yml
@@ -52,5 +52,5 @@ public_inbox_identifier:
public_contact_identifier:
$ref: ./public/contact_identifier.yml
-portal_id:
- $ref: ./portal_id.yml
\ No newline at end of file
+portal_slug:
+ $ref: ./portal_slug.yml
\ No newline at end of file
diff --git a/swagger/parameters/portal_id.yml b/swagger/parameters/portal_id.yml
deleted file mode 100644
index dcd1f8b328d..00000000000
--- a/swagger/parameters/portal_id.yml
+++ /dev/null
@@ -1,6 +0,0 @@
-in: path
-name: id
-schema:
- type: string
-required: true
-description: The slug identifier of the portal
diff --git a/swagger/parameters/portal_slug.yml b/swagger/parameters/portal_slug.yml
new file mode 100644
index 00000000000..5d70718b5a8
--- /dev/null
+++ b/swagger/parameters/portal_slug.yml
@@ -0,0 +1,7 @@
+in: path
+name: portal_slug
+schema:
+ type: string
+required: true
+description: The slug of the portal. The numeric portal ID is not accepted.
+example: handbook
diff --git a/swagger/paths/application/portal/show.yml b/swagger/paths/application/portal/show.yml
index 69d8a95811f..acd403e67b2 100644
--- a/swagger/paths/application/portal/show.yml
+++ b/swagger/paths/application/portal/show.yml
@@ -8,7 +8,7 @@ security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- - $ref: '#/components/parameters/portal_id'
+ - $ref: '#/components/parameters/portal_slug'
responses:
'200':
description: Success
@@ -72,7 +72,7 @@ responses:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
- description: The given portal ID does not exist in the account
+ description: The given portal slug does not exist in the account
content:
application/json:
schema:
diff --git a/swagger/paths/application/portal/update.yml b/swagger/paths/application/portal/update.yml
index ba3f47ada3b..9169f0935c0 100644
--- a/swagger/paths/application/portal/update.yml
+++ b/swagger/paths/application/portal/update.yml
@@ -8,7 +8,7 @@ security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- - $ref: '#/components/parameters/portal_id'
+ - $ref: '#/components/parameters/portal_slug'
requestBody:
required: true
content:
diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml
index a72ddf9d385..59290a1b09c 100644
--- a/swagger/paths/index.yml
+++ b/swagger/paths/index.yml
@@ -319,28 +319,28 @@
$ref: ./application/portal/create.yml
get:
$ref: ./application/portal/index.yml
-/api/v1/accounts/{account_id}/portals/{id}:
+/api/v1/accounts/{account_id}/portals/{portal_slug}:
parameters:
- $ref: '#/components/parameters/account_id'
- - $ref: '#/components/parameters/portal_id'
+ - $ref: '#/components/parameters/portal_slug'
get:
$ref: ./application/portal/show.yml
patch:
$ref: ./application/portal/update.yml
# Help Center category
-/api/v1/accounts/{account_id}/portals/{id}/categories:
+/api/v1/accounts/{account_id}/portals/{portal_slug}/categories:
parameters:
- $ref: '#/components/parameters/account_id'
- - $ref: '#/components/parameters/portal_id'
+ - $ref: '#/components/parameters/portal_slug'
post:
$ref: ./application/category/create.yml
# Help Center article
-/api/v1/accounts/{account_id}/portals/{id}/articles:
+/api/v1/accounts/{account_id}/portals/{portal_slug}/articles:
parameters:
- $ref: '#/components/parameters/account_id'
- - $ref: '#/components/parameters/portal_id'
+ - $ref: '#/components/parameters/portal_slug'
post:
$ref: ./application/article/create.yml
diff --git a/swagger/swagger.json b/swagger/swagger.json
index b0b3ca6332f..71fcfbd37ee 100644
--- a/swagger/swagger.json
+++ b/swagger/swagger.json
@@ -4286,13 +4286,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"get": {
@@ -4315,7 +4315,7 @@
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"responses": {
@@ -4397,7 +4397,7 @@
}
},
"404": {
- "description": "The given portal ID does not exist in the account",
+ "description": "The given portal slug does not exist in the account",
"content": {
"application/json": {
"schema": {
@@ -4428,7 +4428,7 @@
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"requestBody": {
@@ -4534,13 +4534,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}/categories": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}/categories": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"post": {
@@ -4592,13 +4592,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}/articles": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}/articles": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"post": {
@@ -17894,14 +17894,15 @@
"required": true,
"description": "The source id of contact obtained on contact create"
},
- "portal_id": {
+ "portal_slug": {
"in": "path",
- "name": "id",
+ "name": "portal_slug",
"schema": {
"type": "string"
},
"required": true,
- "description": "The slug identifier of the portal"
+ "description": "The slug of the portal. The numeric portal ID is not accepted.",
+ "example": "handbook"
}
},
"securitySchemes": {
diff --git a/swagger/tag_groups/application_swagger.json b/swagger/tag_groups/application_swagger.json
index faf814e1280..5cf26d86f0b 100644
--- a/swagger/tag_groups/application_swagger.json
+++ b/swagger/tag_groups/application_swagger.json
@@ -2694,13 +2694,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"get": {
@@ -2723,7 +2723,7 @@
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"responses": {
@@ -2805,7 +2805,7 @@
}
},
"404": {
- "description": "The given portal ID does not exist in the account",
+ "description": "The given portal slug does not exist in the account",
"content": {
"application/json": {
"schema": {
@@ -2836,7 +2836,7 @@
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"requestBody": {
@@ -2942,13 +2942,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}/categories": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}/categories": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"post": {
@@ -3000,13 +3000,13 @@
}
}
},
- "/api/v1/accounts/{account_id}/portals/{id}/articles": {
+ "/api/v1/accounts/{account_id}/portals/{portal_slug}/articles": {
"parameters": [
{
"$ref": "#/components/parameters/account_id"
},
{
- "$ref": "#/components/parameters/portal_id"
+ "$ref": "#/components/parameters/portal_slug"
}
],
"post": {
@@ -16261,14 +16261,15 @@
"required": true,
"description": "The source id of contact obtained on contact create"
},
- "portal_id": {
+ "portal_slug": {
"in": "path",
- "name": "id",
+ "name": "portal_slug",
"schema": {
"type": "string"
},
"required": true,
- "description": "The slug identifier of the portal"
+ "description": "The slug of the portal. The numeric portal ID is not accepted.",
+ "example": "handbook"
}
},
"securitySchemes": {
diff --git a/swagger/tag_groups/client_swagger.json b/swagger/tag_groups/client_swagger.json
index 29dd4249640..30ca85dc8fb 100644
--- a/swagger/tag_groups/client_swagger.json
+++ b/swagger/tag_groups/client_swagger.json
@@ -7837,14 +7837,15 @@
"required": true,
"description": "The source id of contact obtained on contact create"
},
- "portal_id": {
+ "portal_slug": {
"in": "path",
- "name": "id",
+ "name": "portal_slug",
"schema": {
"type": "string"
},
"required": true,
- "description": "The slug identifier of the portal"
+ "description": "The slug of the portal. The numeric portal ID is not accepted.",
+ "example": "handbook"
}
},
"securitySchemes": {
diff --git a/swagger/tag_groups/other_swagger.json b/swagger/tag_groups/other_swagger.json
index 080c58ca429..357408fa812 100644
--- a/swagger/tag_groups/other_swagger.json
+++ b/swagger/tag_groups/other_swagger.json
@@ -7252,14 +7252,15 @@
"required": true,
"description": "The source id of contact obtained on contact create"
},
- "portal_id": {
+ "portal_slug": {
"in": "path",
- "name": "id",
+ "name": "portal_slug",
"schema": {
"type": "string"
},
"required": true,
- "description": "The slug identifier of the portal"
+ "description": "The slug of the portal. The numeric portal ID is not accepted.",
+ "example": "handbook"
}
},
"securitySchemes": {
diff --git a/swagger/tag_groups/platform_swagger.json b/swagger/tag_groups/platform_swagger.json
index a40fb3e2ebf..8ef6701aba7 100644
--- a/swagger/tag_groups/platform_swagger.json
+++ b/swagger/tag_groups/platform_swagger.json
@@ -8143,14 +8143,15 @@
"required": true,
"description": "The source id of contact obtained on contact create"
},
- "portal_id": {
+ "portal_slug": {
"in": "path",
- "name": "id",
+ "name": "portal_slug",
"schema": {
"type": "string"
},
"required": true,
- "description": "The slug identifier of the portal"
+ "description": "The slug of the portal. The numeric portal ID is not accepted.",
+ "example": "handbook"
}
},
"securitySchemes": {