From 116745f3bcabb685e772c369310975283b121f8d Mon Sep 17 00:00:00 2001 From: mailson Date: Thu, 1 May 2025 22:53:19 +0100 Subject: [PATCH] added docs to internal articles api --- descriptions/2.13/api.intercom.io.yaml | 559 +++++++++++++++++++++++++ 1 file changed, 559 insertions(+) diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index 2a8a829..87cdee1 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -1915,6 +1915,389 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/internal_articles": + get: + summary: List all articles + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Internal Articles + operationId: listInternalArticles + description: "You can fetch a list of all internal articles by making a GET request to + `https://api.intercom.io/internal_articles`." + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + pages: + type: pages + page: 1 + per_page: 25 + total_pages: 1 + total_count: 1 + data: + - id: '39' + title: Thanks for everything + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + schema: + "$ref": "#/components/schemas/internal_article_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 2e760b85-9020-471b-89dc-f579ec8a0104 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + post: + summary: Create an internal article + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Internal Articles + operationId: createInternalArticle + description: You can create a new internal article by making a POST request to `https://api.intercom.io/internal_articles`. + responses: + '200': + description: internal article created + content: + application/json: + examples: + internal article created: + value: + id: '42' + title: Thanks for everything + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + schema: + "$ref": "#/components/schemas/internal_article" + '400': + description: Bad Request + content: + application/json: + examples: + Bad Request: + value: + type: error.list + request_id: e522ca8a-cd15-404e-84b3-7f7536003d4a + errors: + - code: parameter_not_found + message: author_id must be in the main body or default locale + translated_content object + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 85e91429-72df-4e69-8a12-b55793dff59f + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/create_internal_article_request" + examples: + internal_article_created: + summary: internal article created + value: + title: Thanks for everything + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + bad_request: + summary: Bad Request + value: + title: Thanks for everything + body: Body of the Internal Article + "/internal_articles/{id}": + get: + summary: Retrieve an internal article + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Internal Articles + operationId: retrieveInternalArticle + description: You can fetch the details of a single internal article by making a GET request + to `https://api.intercom.io/internal_articles/`. + responses: + '200': + description: Internal article found + content: + application/json: + examples: + Internal article found: + value: + id: '45' + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + schema: + "$ref": "#/components/schemas/internal_article" + '404': + description: Internal article not found + content: + application/json: + examples: + Internal article not found: + value: + type: error.list + request_id: 79abd27a-1bfb-42ec-a404-5728c76ba773 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 2eab07fb-5092-49a4-ba74-44094f31f264 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + put: + summary: Update an internal article + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the internal article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Internal Articles + operationId: updateInternalArticle + description: You can update the details of a single internal article by making a PUT + request to `https://api.intercom.io/internal_articles/`. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + id: '48' + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + schema: + "$ref": "#/components/schemas/internal_article" + '404': + description: Internal article not found + content: + application/json: + examples: + Internal article not found: + value: + type: error.list + request_id: f9adccb2-9fca-4b87-bbb7-65f2af5e1d78 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: d1ea223d-bb62-42e3-8bcf-30fdcf7dbd99 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_internal_article_request" + examples: + successful: + summary: successful + value: + title: Christmas is here! + body: "

New gifts in store for the jolly season

" + internal_article_not_found: + summary: Internal article not found + value: + title: Christmas is here! + body: "

New gifts in store for the jolly season

" + delete: + summary: Delete an internal article + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the internal article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Internal Articles + operationId: deleteInternalArticle + description: You can delete a single internal article by making a DELETE request to `https://api.intercom.io/internal_articles/`. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + id: '51' + object: internal_article + deleted: true + schema: + "$ref": "#/components/schemas/deleted_internal_article_object" + '404': + description: Internal article not found + content: + application/json: + examples: + Internal article not found: + value: + type: error.list + request_id: afe37506-cc48-4727-8068-ae7ff0e7b0e3 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c6e86ce8-9402-4196-89c5-f1b2912b4bac + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/internal_articles/search": + get: + summary: Search for internal articles + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: folder_id + in: query + required: false + description: The ID of the folder to search in. + example: 123 + schema: + type: string + tags: + - Internal Articles + operationId: searchInternalArticles + description: You can search for internal articles by making a GET request to `https://api.intercom.io/internal_articles/search`. + responses: + '200': + description: Search successful + content: + application/json: + examples: + Search successful: + value: + type: list + total_count: 1 + data: + internal_articles: + - id: '55' + body: Body of the Article + owner_id: 991266252 + author_id: 991266252 + locale: en + pages: + type: pages + page: 1 + total_pages: 1 + per_page: 10 + schema: + "$ref": "#/components/schemas/internal_article_search_response" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: c70746a8-a5b2-4772-afba-1a4b487ea75d + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/companies": post: summary: Create or Update a company @@ -13328,6 +13711,85 @@ components: "$ref": "#/components/schemas/article_translated_content" tags: "$ref": "#/components/schemas/tags" + internal_article: + title: Internal Article + type: object + x-tags: + - Articles + description: The Internal Articles API is a central place to gather all information and + take actions on your internal articles. + allOf: + - "$ref": "#/components/schemas/internal_article_list_item" + internal_article_list: + title: Internal Articles + type: object + description: This will return a list of internal articles for the App. + properties: + type: + type: string + description: The type of the object - `list`. + enum: + - list + example: list + pages: + "$ref": "#/components/schemas/cursor_pages" + total_count: + type: integer + description: A count of the total number of internal articles. + example: 1 + data: + type: array + description: An array of Internal Article objects + items: + "$ref": "#/components/schemas/internal_article_list_item" + internal_article_list_item: + title: Internal Articles + type: object + x-tags: + - Internal Articles + description: The data returned about your internal articles when you list them. + properties: + type: + type: string + description: The type of object - `internal_article`. + enum: + - internal_article + default: internal_article + example: internal_article + id: + type: string + description: The unique identifier for the article which is given by Intercom. + example: '6871119' + title: + type: string + description: The title of the article. + body: + type: string + nullable: true + description: The body of the article in HTML. + example: Default language body in html + owner_id: + type: integer + description: The id of the owner of the article. + example: '5017691' + author_id: + type: integer + description: The id of the author of the article. + example: '5017691' + created_at: + type: integer + format: date-time + description: The time when the article was created. + example: 1672928359 + updated_at: + type: integer + format: date-time + description: The time when the article was last updated. + example: 1672928610 + locale: + type: string + description: The default locale of the article. + example: en article_search_highlights: title: Article Search Highlights type: object @@ -19225,6 +19687,101 @@ components: example: collection translated_content: "$ref": "#/components/schemas/article_translated_content" + update_internal_article_request: + description: You can Update an Internal Article + type: object + title: Update Internal Article Request Payload + nullable: true + properties: + title: + type: string + description: The title of the article. + example: Thanks for everything + body: + type: string + description: The content of the article. + author_id: + type: integer + description: The id of the author of the article. + example: 1295 + owner_id: + type: integer + description: The id of the author of the article. + example: 1295 + deleted_internal_article_object: + title: Deleted Internal Article Object + type: object + description: Response returned when an object is deleted + properties: + id: + type: string + description: The unique identifier for the internal article which you provided in + the URL. + example: '6890762' + object: + type: string + description: The type of object which was deleted. - internal_article + enum: + - internal_article + example: internal_article + deleted: + type: boolean + description: Whether the internal article was deleted successfully or not. + example: true + create_internal_article_request: + description: You can create an Internal Article + type: object + title: Create Internal Article Request Payload + nullable: true + properties: + title: + type: string + description: The title of the article. + example: Thanks for everything + body: + type: string + description: The content of the article. + example: "

This is the body in html

" + author_id: + type: integer + description: The id of the author of the article. + example: 1295 + owner_id: + type: integer + description: The id of the owner of the article. + example: 1295 + required: + - title + - owner_id + - author_id + internal_article_search_response: + title: Internal Article Search Response + type: object + x-tags: + - Internal Articles + description: The results of an Internal Article search + properties: + type: + type: string + description: The type of the object - `list`. + enum: + - list + example: list + total_count: + type: integer + description: The total number of Internal Articles matching the search query + example: 5 + data: + type: object + description: An object containing the results of the search. + properties: + internal_articles: + type: array + description: An array of Internal Article objects + items: + "$ref": "#/components/schemas/internal_article" + pages: + "$ref": "#/components/schemas/cursor_pages" update_collection_request: description: You can update a collection type: object @@ -19949,6 +20506,8 @@ tags: You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an *external_id* parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.", - name: Articles description: Everything about your Articles +- name: Internal Articles + description: Everything about your Internal Articles - name: Companies description: Everything about your Companies - name: Contacts