From 22fe409b05bb4c01cd3671fb20cd07f05f6d1063 Mon Sep 17 00:00:00 2001 From: Samet Ozcan Date: Thu, 26 Feb 2026 08:36:26 +0000 Subject: [PATCH 1/3] 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/3] 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/3] 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