From 22fe409b05bb4c01cd3671fb20cd07f05f6d1063 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Thu, 26 Feb 2026 08:36:26 +0000 Subject: [PATCH 1/7] Add Internal Articles Folders API to Unstable version - Add folder_id field to internal_article schema (nullable) - Add folder_id parameter to create internal article request - Add folder_id query parameter to search endpoint (already present) - Add new endpoints: * GET /internal_articles/folders - List all folders * POST /internal_articles/folders - Create a folder * GET /internal_articles/folders/{id} - Get folder details * PUT /internal_articles/folders/{id} - Update a folder * DELETE /internal_articles/folders/{id} - Delete empty folder * POST /internal_articles/move_to_folder - Bulk move articles - Add schemas: * internal_article_folder * internal_article_folder_list * create_internal_article_folder_request * update_internal_article_folder_request This enables folder management for internal articles through the API, allowing customers to organize their internal documentation. Relates to: intercom/intercom#472943 --- descriptions/0/api.intercom.io.yaml | 438 ++++++++++++++++++++++++++++ 1 file changed, 438 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 7002a97..5851853 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2637,6 +2637,308 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/internal_articles/folders": + get: + summary: List all folders + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + description: The page number + schema: + type: integer + example: 1 + - name: per_page + in: query + description: Number of results per page + schema: + type: integer + example: 50 + maximum: 150 + tags: + - Internal Articles + operationId: listInternalArticleFolders + description: "You can fetch a list of all folders for internal articles by making a GET request to `https://api.intercom.io/internal_articles/folders`." + responses: + '200': + description: successful + content: + application/json: + example: + type: list + data: + - id: 6 + name: Product Documentation + description: Internal product docs + emoji: "📚" + parent_folder_id: null + article_count: 5 + created_at: 1672928359 + updated_at: 1672928610 + total_count: 1 + pages: + type: pages + page: 1 + per_page: 50 + total_pages: 1 + schema: + "$ref": "#/components/schemas/internal_article_folder_list" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + post: + summary: Create a folder + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Internal Articles + operationId: createInternalArticleFolder + description: "You can create a new folder for internal articles by making a POST request to `https://api.intercom.io/internal_articles/folders`." + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/create_internal_article_folder_request" + example: + folder: + name: Product Documentation + description: Internal product docs + emoji: "📚" + responses: + '200': + description: folder created + content: + application/json: + example: + id: 6 + name: Product Documentation + description: Internal product docs + emoji: "📚" + parent_folder_id: null + article_count: 0 + created_at: 1672928359 + updated_at: 1672928359 + schema: + "$ref": "#/components/schemas/internal_article_folder" + '422': + description: Validation error + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + "/internal_articles/folders/{id}": + get: + summary: Retrieve a folder + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the folder + schema: + type: integer + example: 6 + tags: + - Internal Articles + operationId: retrieveInternalArticleFolder + description: "You can fetch the details of a single folder by making a GET request to `https://api.intercom.io/internal_articles/folders/`." + responses: + '200': + description: folder found + content: + application/json: + example: + id: 6 + name: Product Documentation + description: Internal product docs + emoji: "📚" + parent_folder_id: null + article_count: 5 + created_at: 1672928359 + updated_at: 1672928610 + schema: + "$ref": "#/components/schemas/internal_article_folder" + '404': + description: Folder not found + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + put: + summary: Update a folder + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the folder + schema: + type: integer + example: 6 + tags: + - Internal Articles + operationId: updateInternalArticleFolder + description: "You can update a folder by making a PUT request to `https://api.intercom.io/internal_articles/folders/`." + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_internal_article_folder_request" + example: + folder: + name: Updated Product Documentation + emoji: "📖" + responses: + '200': + description: folder updated + content: + application/json: + example: + id: 6 + name: Updated Product Documentation + description: Internal product docs + emoji: "📖" + parent_folder_id: null + article_count: 5 + created_at: 1672928359 + updated_at: 1672928900 + schema: + "$ref": "#/components/schemas/internal_article_folder" + '404': + description: Folder not found + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + delete: + summary: Delete a folder + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the folder + schema: + type: integer + example: 6 + tags: + - Internal Articles + operationId: deleteInternalArticleFolder + description: "You can delete a folder (if it contains no articles) by making a DELETE request to `https://api.intercom.io/internal_articles/folders/`." + responses: + '200': + description: folder deleted + content: + application/json: + example: + id: 6 + object: folder + deleted: true + '404': + description: Folder not found + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '422': + description: Folder contains articles + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + "/internal_articles/move_to_folder": + post: + summary: Bulk move articles to folder + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Internal Articles + operationId: moveInternalArticlesToFolder + description: "You can move multiple articles to a folder (or remove them from folders) by making a POST request to `https://api.intercom.io/internal_articles/move_to_folder`." + requestBody: + content: + application/json: + schema: + type: object + required: + - article_ids + - destination_folder_id + properties: + article_ids: + type: array + items: + type: integer + description: Array of article IDs to move + example: [123, 124, 125] + destination_folder_id: + oneOf: + - type: integer + - type: string + enum: ["root"] + description: Target folder ID, or "root" to remove from folders + example: 6 + examples: + move_to_folder: + summary: Move articles to folder + value: + article_ids: [123, 124] + destination_folder_id: 6 + move_to_root: + summary: Move articles to root + value: + article_ids: [123, 124] + destination_folder_id: "root" + responses: + '200': + description: articles moved + content: + application/json: + example: + moved_count: 2 + destination_folder_id: 6 + schema: + type: object + properties: + moved_count: + type: integer + description: Number of articles successfully moved + destination_folder_id: + type: integer + nullable: true + description: Target folder ID, or null if moved to root + '404': + description: Folder not found + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '422': + description: Validation error + content: + application/json: + schema: + "$ref": "#/components/schemas/error" "/companies": post: summary: Create or Update a company @@ -16706,6 +17008,132 @@ components: description: An array of Internal Article objects items: "$ref": "#/components/schemas/internal_article_list_item" + internal_article_folder: + title: Internal Article Folder + type: object + x-tags: + - Internal Articles + description: A folder for organizing internal articles + properties: + id: + type: integer + description: The unique identifier for the folder + example: 6 + name: + type: string + description: The name of the folder + example: Product Documentation + description: + type: string + nullable: true + description: The description of the folder + example: Internal product documentation + emoji: + type: string + nullable: true + description: An emoji associated with the folder + example: "📚" + parent_folder_id: + type: integer + nullable: true + description: The ID of the parent folder, or null if this is a root folder + example: null + article_count: + type: integer + description: The number of articles in this folder + example: 5 + created_at: + type: integer + format: date-time + description: The time when the folder was created (seconds) + example: 1672928359 + updated_at: + type: integer + format: date-time + description: The time when the folder was last updated (seconds) + example: 1672928610 + internal_article_folder_list: + title: Internal Article Folder List + type: object + x-tags: + - Internal Articles + description: A list of folders for internal articles + properties: + type: + type: string + enum: + - list + example: list + data: + type: array + items: + "$ref": "#/components/schemas/internal_article_folder" + total_count: + type: integer + description: Total number of folders + example: 2 + pages: + "$ref": "#/components/schemas/cursor_pages" + create_internal_article_folder_request: + title: Create Internal Article Folder Request + type: object + x-tags: + - Internal Articles + description: Request payload for creating a folder + required: + - folder + properties: + folder: + type: object + required: + - name + properties: + name: + type: string + description: The name of the folder + example: Product Documentation + description: + type: string + description: The description of the folder + example: Internal product documentation + emoji: + type: string + description: An emoji for the folder + example: "📚" + parent_folder_id: + type: integer + nullable: true + description: The ID of the parent folder + example: null + update_internal_article_folder_request: + title: Update Internal Article Folder Request + type: object + x-tags: + - Internal Articles + description: Request payload for updating a folder + required: + - folder + properties: + folder: + type: object + properties: + name: + type: string + description: The name of the folder + example: Updated Product Documentation + description: + type: string + description: The description of the folder + example: Updated internal product documentation + emoji: + type: string + description: An emoji for the folder + example: "📖" + parent_folder_id: + type: integer + nullable: true + description: The ID of the parent folder + example: null article_list: title: Articles type: object @@ -16880,6 +17308,11 @@ components: type: string description: The default locale of the article. example: en + folder_id: + type: integer + nullable: true + description: The ID of the folder this article belongs to, or null if not in a folder. + example: 6 article_search_highlights: title: Article Search Highlights type: object @@ -19310,6 +19743,11 @@ components: type: integer description: The id of the owner of the article. example: 1295 + folder_id: + type: integer + nullable: true + description: The ID of the folder to place this article in, or null to leave it without a folder. + example: 6 required: - title - owner_id From 41c613e16260cdc7f4652bc06bde847b967fa6f1 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Thu, 26 Feb 2026 12:19:10 +0000 Subject: [PATCH 2/7] docs: Refactor folder endpoints to top-level /folders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update OpenAPI specification to reflect folder endpoints moving from /internal_articles/folders to top-level /folders resource. Changes: - Update paths: /internal_articles/folders → /folders - Update operation IDs: Remove "InternalArticle" prefix - Change tags: "Internal Articles" → "Folders" - Update descriptions: Remove "for internal articles" references - Remove bulk move endpoint /internal_articles/move_to_folder This makes folders a first-class organizational structure that can be used across multiple content types, not just internal articles. Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 109 +++++----------------------- 1 file changed, 17 insertions(+), 92 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5851853..aaaf597 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2637,7 +2637,7 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" - "/internal_articles/folders": + "/folders": get: summary: List all folders parameters: @@ -2659,9 +2659,9 @@ paths: example: 50 maximum: 150 tags: - - Internal Articles - operationId: listInternalArticleFolders - description: "You can fetch a list of all folders for internal articles by making a GET request to `https://api.intercom.io/internal_articles/folders`." + - Folders + operationId: listFolders + description: "You can fetch a list of all folders for organizing content by making a GET request to `https://api.intercom.io/folders`." responses: '200': description: successful @@ -2700,9 +2700,9 @@ paths: schema: "$ref": "#/components/schemas/intercom_version" tags: - - Internal Articles - operationId: createInternalArticleFolder - description: "You can create a new folder for internal articles by making a POST request to `https://api.intercom.io/internal_articles/folders`." + - Folders + operationId: createFolder + description: "You can create a new folder for organizing content by making a POST request to `https://api.intercom.io/folders`." requestBody: content: application/json: @@ -2735,7 +2735,7 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" - "/internal_articles/folders/{id}": + "/folders/{id}": get: summary: Retrieve a folder parameters: @@ -2751,9 +2751,9 @@ paths: type: integer example: 6 tags: - - Internal Articles - operationId: retrieveInternalArticleFolder - description: "You can fetch the details of a single folder by making a GET request to `https://api.intercom.io/internal_articles/folders/`." + - Folders + operationId: retrieveFolder + description: "You can fetch the details of a single folder by making a GET request to `https://api.intercom.io/folders/`." responses: '200': description: folder found @@ -2791,9 +2791,9 @@ paths: type: integer example: 6 tags: - - Internal Articles - operationId: updateInternalArticleFolder - description: "You can update a folder by making a PUT request to `https://api.intercom.io/internal_articles/folders/`." + - Folders + operationId: updateFolder + description: "You can update a folder by making a PUT request to `https://api.intercom.io/folders/`." requestBody: content: application/json: @@ -2840,9 +2840,9 @@ paths: type: integer example: 6 tags: - - Internal Articles - operationId: deleteInternalArticleFolder - description: "You can delete a folder (if it contains no articles) by making a DELETE request to `https://api.intercom.io/internal_articles/folders/`." + - Folders + operationId: deleteFolder + description: "You can delete a folder (if it contains no articles) by making a DELETE request to `https://api.intercom.io/folders/`." responses: '200': description: folder deleted @@ -2864,81 +2864,6 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" - "/internal_articles/move_to_folder": - post: - summary: Bulk move articles to folder - parameters: - - name: Intercom-Version - in: header - schema: - "$ref": "#/components/schemas/intercom_version" - tags: - - Internal Articles - operationId: moveInternalArticlesToFolder - description: "You can move multiple articles to a folder (or remove them from folders) by making a POST request to `https://api.intercom.io/internal_articles/move_to_folder`." - requestBody: - content: - application/json: - schema: - type: object - required: - - article_ids - - destination_folder_id - properties: - article_ids: - type: array - items: - type: integer - description: Array of article IDs to move - example: [123, 124, 125] - destination_folder_id: - oneOf: - - type: integer - - type: string - enum: ["root"] - description: Target folder ID, or "root" to remove from folders - example: 6 - examples: - move_to_folder: - summary: Move articles to folder - value: - article_ids: [123, 124] - destination_folder_id: 6 - move_to_root: - summary: Move articles to root - value: - article_ids: [123, 124] - destination_folder_id: "root" - responses: - '200': - description: articles moved - content: - application/json: - example: - moved_count: 2 - destination_folder_id: 6 - schema: - type: object - properties: - moved_count: - type: integer - description: Number of articles successfully moved - destination_folder_id: - type: integer - nullable: true - description: Target folder ID, or null if moved to root - '404': - description: Folder not found - content: - application/json: - schema: - "$ref": "#/components/schemas/error" - '422': - description: Validation error - content: - application/json: - schema: - "$ref": "#/components/schemas/error" "/companies": post: summary: Create or Update a company From ab102b2b625f158918d5a8d58cb7841fdcf82527 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Tue, 10 Mar 2026 15:36:10 +0000 Subject: [PATCH 3/7] docs: Update Folders API and add folder_id to article schemas - Add parent_folder_id query param to GET /folders for hierarchy filtering - Rename article_count to content_count to match monolith presenter - Add folder_id to article_list_item, create/update article requests - Add folder_id to update_internal_article_request - Add phrase query param and fix folder_id type on internal articles search - Add deleted_folder_object schema for delete response - Fix owner_id description in update_internal_article_request Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 77 +++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 10 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index aaaf597..1a3ec61 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2591,8 +2591,15 @@ paths: - name: folder_id in: query required: false - description: The ID of the folder to search in. + description: The ID of the folder to search in. Results will include articles from this folder and all its descendant folders. example: 123 + schema: + type: integer + - name: phrase + in: query + required: false + description: The search phrase to filter internal articles by. + example: getting started schema: type: string tags: @@ -2612,10 +2619,12 @@ paths: data: internal_articles: - id: '55' + title: Getting Started Guide body: Body of the Article owner_id: 991266252 author_id: 991266252 locale: en + folder_id: 123 pages: type: pages page: 1 @@ -2658,6 +2667,13 @@ paths: type: integer example: 50 maximum: 150 + - name: parent_folder_id + in: query + required: false + description: Filter folders by parent folder ID. Use this to list only direct children of a specific folder. + schema: + type: integer + example: 1 tags: - Folders operationId: listFolders @@ -2675,7 +2691,7 @@ paths: description: Internal product docs emoji: "📚" parent_folder_id: null - article_count: 5 + content_count: 5 created_at: 1672928359 updated_at: 1672928610 total_count: 1 @@ -2724,7 +2740,7 @@ paths: description: Internal product docs emoji: "📚" parent_folder_id: null - article_count: 0 + content_count: 0 created_at: 1672928359 updated_at: 1672928359 schema: @@ -2765,7 +2781,7 @@ paths: description: Internal product docs emoji: "📚" parent_folder_id: null - article_count: 5 + content_count: 5 created_at: 1672928359 updated_at: 1672928610 schema: @@ -2814,7 +2830,7 @@ paths: description: Internal product docs emoji: "📖" parent_folder_id: null - article_count: 5 + content_count: 5 created_at: 1672928359 updated_at: 1672928900 schema: @@ -2842,7 +2858,7 @@ paths: tags: - Folders operationId: deleteFolder - description: "You can delete a folder (if it contains no articles) by making a DELETE request to `https://api.intercom.io/folders/`." + description: "You can delete a folder (if it contains no content) by making a DELETE request to `https://api.intercom.io/folders/`." responses: '200': description: folder deleted @@ -2852,6 +2868,8 @@ paths: id: 6 object: folder deleted: true + schema: + "$ref": "#/components/schemas/deleted_folder_object" '404': description: Folder not found content: @@ -2859,7 +2877,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: Folder contains articles + description: Folder contains content content: application/json: schema: @@ -16963,9 +16981,9 @@ components: nullable: true description: The ID of the parent folder, or null if this is a root folder example: null - article_count: + content_count: type: integer - description: The number of articles in this folder + description: The number of content items in this folder example: 5 created_at: type: integer @@ -17030,6 +17048,25 @@ components: nullable: true description: The ID of the parent folder example: null + deleted_folder_object: + title: Deleted Folder Object + type: object + description: Response returned when a folder is deleted + properties: + id: + type: integer + description: The unique identifier for the deleted folder + example: 6 + object: + type: string + description: The type of object - `folder`. + enum: + - folder + example: folder + deleted: + type: boolean + description: Whether the folder was successfully deleted. + example: true update_internal_article_folder_request: title: Update Internal Article Folder Request type: object @@ -17185,6 +17222,11 @@ components: "$ref": "#/components/schemas/article_translated_content" tags: "$ref": "#/components/schemas/tags" + folder_id: + type: integer + nullable: true + description: The ID of the folder this article belongs to, or null if not in a folder. + example: 6 internal_article_list_item: title: Internal Articles type: object @@ -19643,6 +19685,11 @@ components: example: collection translated_content: "$ref": "#/components/schemas/article_translated_content" + folder_id: + type: integer + nullable: true + description: The ID of the folder to place this article in, or null to leave it without a folder. + example: 6 required: - title - author_id @@ -24704,6 +24751,11 @@ components: example: collection translated_content: "$ref": "#/components/schemas/article_translated_content" + folder_id: + type: integer + nullable: true + description: The ID of the folder to place this article in, or null to remove it from its folder. + example: 6 update_internal_article_request: description: You can Update an Internal Article type: object @@ -24723,8 +24775,13 @@ components: example: 1295 owner_id: type: integer - description: The id of the author of the article. + description: The id of the owner of the article. example: 1295 + folder_id: + type: integer + nullable: true + description: The ID of the folder to place this article in, or null to remove it from its folder. + example: 6 update_collection_request: description: You can update a collection type: object From abbb8aecda5c4d67fd2864c8dc445ba6bc17dff0 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Wed, 11 Mar 2026 15:08:49 +0000 Subject: [PATCH 4/7] docs: Rename folder schemas to first-class resource naming Folders are a top-level resource that can hold both articles and internal articles. Rename internal_article_folder* schemas to folder* to reflect this. Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 42 ++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1a3ec61..1c85f9c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2701,7 +2701,7 @@ paths: per_page: 50 total_pages: 1 schema: - "$ref": "#/components/schemas/internal_article_folder_list" + "$ref": "#/components/schemas/folder_list" '401': description: Unauthorized content: @@ -2723,7 +2723,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/create_internal_article_folder_request" + "$ref": "#/components/schemas/create_folder_request" example: folder: name: Product Documentation @@ -2744,7 +2744,7 @@ paths: created_at: 1672928359 updated_at: 1672928359 schema: - "$ref": "#/components/schemas/internal_article_folder" + "$ref": "#/components/schemas/folder" '422': description: Validation error content: @@ -2785,7 +2785,7 @@ paths: created_at: 1672928359 updated_at: 1672928610 schema: - "$ref": "#/components/schemas/internal_article_folder" + "$ref": "#/components/schemas/folder" '404': description: Folder not found content: @@ -2814,7 +2814,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_internal_article_folder_request" + "$ref": "#/components/schemas/update_folder_request" example: folder: name: Updated Product Documentation @@ -2834,7 +2834,7 @@ paths: created_at: 1672928359 updated_at: 1672928900 schema: - "$ref": "#/components/schemas/internal_article_folder" + "$ref": "#/components/schemas/folder" '404': description: Folder not found content: @@ -16951,12 +16951,12 @@ components: description: An array of Internal Article objects items: "$ref": "#/components/schemas/internal_article_list_item" - internal_article_folder: - title: Internal Article Folder + folder: + title: Folder type: object x-tags: - - Internal Articles - description: A folder for organizing internal articles + - Folders + description: A folder for organizing content properties: id: type: integer @@ -16995,12 +16995,12 @@ components: format: date-time description: The time when the folder was last updated (seconds) example: 1672928610 - internal_article_folder_list: - title: Internal Article Folder List + folder_list: + title: Folder List type: object x-tags: - - Internal Articles - description: A list of folders for internal articles + - Folders + description: A paginated list of folders properties: type: type: string @@ -17010,18 +17010,18 @@ components: data: type: array items: - "$ref": "#/components/schemas/internal_article_folder" + "$ref": "#/components/schemas/folder" total_count: type: integer description: Total number of folders example: 2 pages: "$ref": "#/components/schemas/cursor_pages" - create_internal_article_folder_request: - title: Create Internal Article Folder Request + create_folder_request: + title: Create Folder Request type: object x-tags: - - Internal Articles + - Folders description: Request payload for creating a folder required: - folder @@ -17067,11 +17067,11 @@ components: type: boolean description: Whether the folder was successfully deleted. example: true - update_internal_article_folder_request: - title: Update Internal Article Folder Request + update_folder_request: + title: Update Folder Request type: object x-tags: - - Internal Articles + - Folders description: Request payload for updating a folder required: - folder From e00a5978171e7e7288f7c306af3e3a4d73d09cfc Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Wed, 11 Mar 2026 15:33:08 +0000 Subject: [PATCH 5/7] docs: Remove phrase param, inline folder request/list schemas - Remove phrase query param from internal articles search (not implemented) - Inline folder_list, create_folder_request, update_folder_request schemas directly into endpoint definitions instead of separate schema refs - Remove standalone schema definitions for the above - Keep folder and deleted_folder_object as reusable schemas Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 160 ++++++++++++---------------- 1 file changed, 67 insertions(+), 93 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1c85f9c..4be809b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2595,13 +2595,6 @@ paths: example: 123 schema: type: integer - - name: phrase - in: query - required: false - description: The search phrase to filter internal articles by. - example: getting started - schema: - type: string tags: - Internal Articles operationId: searchInternalArticles @@ -2619,7 +2612,6 @@ paths: data: internal_articles: - id: '55' - title: Getting Started Guide body: Body of the Article owner_id: 991266252 author_id: 991266252 @@ -2701,7 +2693,23 @@ paths: per_page: 50 total_pages: 1 schema: - "$ref": "#/components/schemas/folder_list" + type: object + properties: + type: + type: string + enum: + - list + example: list + data: + type: array + items: + "$ref": "#/components/schemas/folder" + total_count: + type: integer + description: Total number of folders + example: 2 + pages: + "$ref": "#/components/schemas/cursor_pages" '401': description: Unauthorized content: @@ -2723,7 +2731,32 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/create_folder_request" + type: object + required: + - folder + properties: + folder: + type: object + required: + - name + properties: + name: + type: string + description: The name of the folder + example: Product Documentation + description: + type: string + description: The description of the folder + example: Internal product documentation + emoji: + type: string + description: An emoji for the folder + example: "📚" + parent_folder_id: + type: integer + nullable: true + description: The ID of the parent folder + example: null example: folder: name: Product Documentation @@ -2814,7 +2847,30 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/update_folder_request" + type: object + required: + - folder + properties: + folder: + type: object + properties: + name: + type: string + description: The name of the folder + example: Updated Product Documentation + description: + type: string + description: The description of the folder + example: Updated internal product documentation + emoji: + type: string + description: An emoji for the folder + example: "📖" + parent_folder_id: + type: integer + nullable: true + description: The ID of the parent folder + example: null example: folder: name: Updated Product Documentation @@ -16995,59 +17051,6 @@ components: format: date-time description: The time when the folder was last updated (seconds) example: 1672928610 - folder_list: - title: Folder List - type: object - x-tags: - - Folders - description: A paginated list of folders - properties: - type: - type: string - enum: - - list - example: list - data: - type: array - items: - "$ref": "#/components/schemas/folder" - total_count: - type: integer - description: Total number of folders - example: 2 - pages: - "$ref": "#/components/schemas/cursor_pages" - create_folder_request: - title: Create Folder Request - type: object - x-tags: - - Folders - description: Request payload for creating a folder - required: - - folder - properties: - folder: - type: object - required: - - name - properties: - name: - type: string - description: The name of the folder - example: Product Documentation - description: - type: string - description: The description of the folder - example: Internal product documentation - emoji: - type: string - description: An emoji for the folder - example: "📚" - parent_folder_id: - type: integer - nullable: true - description: The ID of the parent folder - example: null deleted_folder_object: title: Deleted Folder Object type: object @@ -17067,35 +17070,6 @@ components: type: boolean description: Whether the folder was successfully deleted. example: true - update_folder_request: - title: Update Folder Request - type: object - x-tags: - - Folders - description: Request payload for updating a folder - required: - - folder - properties: - folder: - type: object - properties: - name: - type: string - description: The name of the folder - example: Updated Product Documentation - description: - type: string - description: The description of the folder - example: Updated internal product documentation - emoji: - type: string - description: An emoji for the folder - example: "📖" - parent_folder_id: - type: integer - nullable: true - description: The ID of the parent folder - example: null article_list: title: Articles type: object From 8528fa4cb1f095ef03a9f0c02792270ec04284df Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Thu, 12 Mar 2026 17:33:07 +0000 Subject: [PATCH 6/7] docs: Add missing error responses (401, 422) to folder endpoints Add 401 Unauthorized to Create, Retrieve, Update, Delete folder endpoints. Add 422 Validation error to Update folder endpoint. Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4be809b..8e3dcee 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2778,6 +2778,12 @@ paths: updated_at: 1672928359 schema: "$ref": "#/components/schemas/folder" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" '422': description: Validation error content: @@ -2819,6 +2825,12 @@ paths: updated_at: 1672928610 schema: "$ref": "#/components/schemas/folder" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" '404': description: Folder not found content: @@ -2891,12 +2903,24 @@ paths: updated_at: 1672928900 schema: "$ref": "#/components/schemas/folder" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" '404': description: Folder not found content: application/json: schema: "$ref": "#/components/schemas/error" + '422': + description: Validation error + content: + application/json: + schema: + "$ref": "#/components/schemas/error" delete: summary: Delete a folder parameters: @@ -2926,6 +2950,12 @@ paths: deleted: true schema: "$ref": "#/components/schemas/deleted_folder_object" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" '404': description: Folder not found content: From e2631b848e5dc888d3f23ab570e1cb1361a5b701 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Thu, 12 Mar 2026 18:37:12 +0000 Subject: [PATCH 7/7] docs: Use 400 for validation errors, reserve 422 for delete conflict Create and Update folder endpoints now return 400 Bad Request for validation errors. 422 is reserved for Delete when folder has content. Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8e3dcee..06686d2 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2784,8 +2784,8 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" - '422': - description: Validation error + '400': + description: Bad request content: application/json: schema: @@ -2915,8 +2915,8 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" - '422': - description: Validation error + '400': + description: Bad request content: application/json: schema: