Body of the Article
@@ -1549,22 +1589,19 @@ paths: state: published created_at: 1734537288 updated_at: 1734537288 - has_unpublished_changes: false - draft_updated_at: null url: http://help-center.test/myapp-68/en/articles/42-thanks-for-everything + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true created_by_id: 5017691 updated_by_id: 5017691 - exclude_from_article_suggestions: false - help_center_audience: everyone - scheduled_publish_at: null - scheduled_unpublish_at: null + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" '400': - description: Bad Request + description: Bad Request. A JSON request whose body is an empty object returns `400` with no response body. content: application/json: examples: @@ -1593,6 +1630,48 @@ paths: field: scheduled_unpublish_at message: Cannot set scheduled_publish_at and scheduled_unpublish_at in the same request + Missing title: + value: + type: error.list + request_id: b052ee5c-f602-5d9a-8356-94544cd9b12a + errors: + - code: parameter_not_found + message: Title is a required parameter + Unsupported locale: + value: + type: error.list + request_id: 00e07e24-9182-5d6a-8830-4a977fd902c9 + errors: + - code: data_invalid + message: Locale 'xx' isn't supported. + Collection not found: + value: + type: error.list + request_id: 4c9f130d-bfb7-5cab-9a98-7c9fa6650ea9 + errors: + - code: parameter_invalid + message: Collection not found + Publish time in the past: + value: + type: error.list + request_id: b0015de0-8628-523f-bca1-780ed3bdcc75 + errors: + - code: parameter_invalid + message: scheduled_publish_at must be in the future + schema: + "$ref": "#/components/schemas/error" + '404': + description: 'Not found: the author, an audience, the folder or a collection in `parent_ids` does not exist.' + content: + application/json: + examples: + Author not found: + value: + type: error.list + request_id: e1650d39-7d30-554f-aeb1-b4aa32837f1a + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -1607,6 +1686,34 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Author not authorised: + value: + type: error.list + request_id: 4be1f5b3-3590-5eb7-83df-6d852559f097 + errors: + - code: action_forbidden + message: author_id 991267497 is not authorised on this workspace + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Body and body_markdown both provided: + value: + type: error.list + request_id: a560a2a1-1b69-5178-8953-b3d8c982eb29 + errors: + - code: parameter_invalid + message: body and body_markdown are mutually exclusive - please provide only one + Invalid availability value: + value: + type: error.list + request_id: 3a0b96f7-6f76-5b2e-899a-776192cb6235 + errors: + - code: parameter_invalid + message: ai_chatbot_availability must be true or false schema: "$ref": "#/components/schemas/error" requestBody: @@ -1657,8 +1764,10 @@ paths: tags: - Articles operationId: retrieveArticle - description: You can fetch the details of a single article by making a GET request - to `https://api.intercom.io/articles/New gifts in store for the jolly season
@@ -1791,51 +1909,57 @@ paths: state: published created_at: 1734537297 updated_at: 1734537298 - has_unpublished_changes: false - draft_updated_at: null url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true created_by_id: 5017691 updated_by_id: 5017691 - exclude_from_article_suggestions: false - help_center_audience: everyone - scheduled_publish_at: null - scheduled_unpublish_at: null + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" '400': - description: Bad Request + description: Bad Request. A JSON request whose body is an empty object returns `400` with no response body. content: application/json: examples: - Scheduling conflict: + Publish and unpublish in the same request: value: type: error.list - request_id: 8d11c1f4-0a55-4f7f-8e2f-4f6c1f3b2c11 + request_id: 884b59c8-2bae-51de-b300-e9b78dfa793c errors: - code: parameter_invalid - field: scheduled_publish_at - message: Cannot schedule a publish while setting state to draft - Conflicting pending schedules: + message: Cannot schedule a publish and unpublish in the same request + Publish time in the past: value: type: error.list - request_id: 0a82a3a4-94f1-4f1a-bea1-aaf41a8d3c22 + request_id: 9936f252-ad05-5bf2-b681-c94d83904f71 errors: - code: parameter_invalid - field: scheduled_unpublish_at - message: Cannot set scheduled_publish_at and scheduled_unpublish_at - in the same request - Unpublish before publish: + message: scheduled_publish_at must be in the future + Unpublish on an article that is not published: value: type: error.list - request_id: 11aa22bb-33cc-44dd-55ee-66ff77889900 + request_id: 4d09d60a-6f62-5b5e-b71a-92c949fad184 errors: - code: parameter_invalid - field: scheduled_unpublish_at - message: Cannot schedule unpublish for an article that has never - been published + message: Cannot schedule an unpublish on an article that is not currently published + Unsupported locale: + value: + type: error.list + request_id: bf534ebb-919e-5f80-91d0-35de1deffc4a + errors: + - code: data_invalid + message: Locale 'xx' isn't supported. + Collection not found: + value: + type: error.list + request_id: f1c380ad-c52e-50ba-a678-70a258799efe + errors: + - code: parameter_invalid + message: Collection not found schema: "$ref": "#/components/schemas/error" '404': @@ -1850,6 +1974,13 @@ paths: errors: - code: not_found message: Resource Not Found + Author not found: + value: + type: error.list + request_id: da7836a0-95a1-5926-969c-6bc26f5a6633 + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -1864,6 +1995,34 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Author not authorised: + value: + type: error.list + request_id: f62b30e2-5b2e-561d-b1e8-01a84a380ee2 + errors: + - code: action_forbidden + message: author_id 991267508 is not authorised on this workspace + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Body and body_markdown both provided: + value: + type: error.list + request_id: 2ee5920d-5fd3-5adc-8a58-d3e0cf3723c1 + errors: + - code: parameter_invalid + message: body and body_markdown are mutually exclusive - please provide only one + Invalid availability value: + value: + type: error.list + request_id: f504af40-1675-56e1-8d06-28eae3412526 + errors: + - code: parameter_invalid + message: ai_chatbot_availability must be true or false schema: "$ref": "#/components/schemas/error" requestBody: @@ -1902,7 +2061,10 @@ paths: tags: - Articles operationId: deleteArticle - description: You can delete a single article by making a DELETE request to `https://api.intercom.io/articles/Unpublished changes staged as a draft
@@ -1991,12 +2194,15 @@ paths: state: published created_at: 1734537292 updated_at: 1734537292 - has_unpublished_changes: true - draft_updated_at: 1734537292 url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: true + draft_updated_at: 1734537292 schema: "$ref": "#/components/schemas/article" '404': @@ -2028,9 +2234,11 @@ paths: The article must already be published; staging a draft on an article that has never been published returns `422`. - Only versioned text content (such as `title` and `body`) is staged. - Non-versioned fields like AI availability are ignored, leaving the live - values untouched. + Only text content is staged: `title`, `description`, `body` or + `body_markdown`, and `author_id`, including per-locale values in + `translated_content`. Any other field in the request body, such as `state`, + `parent_id`, `folder_id`, `audience_ids`, the AI availability fields or the + scheduling fields, is still validated but not applied, so the live article is left untouched. Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. responses: @@ -2045,6 +2253,26 @@ paths: type: article workspace_id: this_is_an_id80_that_should_be_at_least_4 parent_ids: [] + folder_id: null + statistics: + type: article_statistics + views: 0 + conversations: 0 + reactions: 0 + happy_reaction_percentage: 0 + neutral_reaction_percentage: 0 + sad_reaction_percentage: 0 + fin_involvements: 0 + fin_resolutions: 0 + fin_resolution_rate: 0 + tags: + type: tag.list + tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '79' title: Christmas is here! description: '' body:New gifts in store for the jolly season
@@ -2053,18 +2281,21 @@ paths: state: published created_at: 1734537297 updated_at: 1734537298 - has_unpublished_changes: true - draft_updated_at: 1734537298 url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: true + draft_updated_at: 1734537298 schema: "$ref": "#/components/schemas/article" '404': "$ref": "#/components/responses/ObjectNotFound" '422': - description: Article must be published before a draft can be staged + description: Article is not published, or a requested locale is not published content: application/json: examples: @@ -2131,6 +2362,26 @@ paths: type: article workspace_id: this_is_an_id80_that_should_be_at_least_4 parent_ids: [] + folder_id: null + statistics: + type: article_statistics + views: 0 + conversations: 0 + reactions: 0 + happy_reaction_percentage: 0 + neutral_reaction_percentage: 0 + sad_reaction_percentage: 0 + fin_involvements: 0 + fin_resolutions: 0 + fin_resolution_rate: 0 + tags: + type: tag.list + tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '79' title: Christmas is here! description: '' body:New gifts in store for the jolly season
@@ -2139,12 +2390,15 @@ paths: state: published created_at: 1734537297 updated_at: 1734537299 - has_unpublished_changes: false - draft_updated_at: null url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" '404': @@ -2218,15 +2472,15 @@ paths: - name: per_page in: query required: false - description: The number of results to return per page. - example: 25 + description: The number of results to return per page. Defaults to 10. + example: 10 schema: type: integer - name: locale in: query required: false description: Filter versions to a specific locale. Use the locale identifier - (for example `en`, `fr`). If the locale is not configured for the workspace, + (for example `en`, `fr`). If the article has no content in that locale, a `400` is returned. example: en schema: @@ -2254,7 +2508,7 @@ paths: pages: type: pages page: 1 - per_page: 25 + per_page: 10 total_pages: 1 total_count: 2 data: @@ -2283,17 +2537,17 @@ paths: schema: "$ref": "#/components/schemas/article_version_list" '400': - description: Unknown locale + description: No content for the requested locale content: application/json: examples: - Unknown locale: + No content for locale: value: type: error.list request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f errors: - code: parameter_invalid - message: Unknown locale + message: No content found for locale 'fr' on article 123 schema: "$ref": "#/components/schemas/error" '404': @@ -2325,8 +2579,8 @@ paths: - name: locale in: query required: false - description: Return the version's content for a specific locale. If the locale - is not configured for the workspace, a `400` is returned. + description: Return the version's content for a specific locale. If the article + has no content in that locale, a `400` is returned. example: en schema: type: string @@ -2365,17 +2619,17 @@ paths: schema: "$ref": "#/components/schemas/article_version" '400': - description: Unknown locale + description: No content for the requested locale content: application/json: examples: - Unknown locale: + No content for locale: value: type: error.list request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f errors: - code: parameter_invalid - message: Unknown locale + message: No content found for locale 'fr' on article 123 schema: "$ref": "#/components/schemas/error" '404': @@ -2465,7 +2719,7 @@ paths: schema: "$ref": "#/components/schemas/error" '404': - description: Article or tag not found + description: Article, tag or teammate not found content: application/json: examples: @@ -2483,6 +2737,13 @@ paths: errors: - code: tag_not_found message: Tag not found + Admin not found: + value: + type: error.list + request_id: 7a34a204-9fae-5335-b818-1da0df3b5234 + errors: + - code: admin_not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -2584,18 +2845,24 @@ paths: - name: phrase in: query required: false - description: The phrase within your articles to search for. + description: The phrase within your articles to search for. Maximum length is 500 characters. example: Getting started schema: type: string + maxLength: 500 - name: state in: query required: false description: The state of the Articles returned. One of `published`, `draft` - or `all`. + or `all`. Defaults to `published`. example: published schema: type: string + enum: + - published + - draft + - all + default: published - name: help_center_id in: query required: false @@ -2611,10 +2878,29 @@ paths: example: false schema: type: boolean + - name: page + in: query + required: false + description: The page of results to fetch. Defaults to the first page. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 10. + example: 10 + schema: + type: integer tags: - Articles operationId: searchArticles - description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + description: | + You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + + If no articles match the search, `data` is an empty array rather than an object. + + Requires the `read_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. responses: '200': description: Search successful @@ -2631,9 +2917,15 @@ paths: type: article workspace_id: this_is_an_id92_that_should_be_at_least_4 parent_ids: [] + folder_id: null tags: type: tag.list tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '91' title: Title 1 description: '' body: '' @@ -2643,23 +2935,67 @@ paths: created_at: 1734537306 updated_at: 1734537306 url: + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true created_by_id: 5017691 updated_by_id: 5017691 - exclude_from_article_suggestions: false - help_center_audience: everyone - scheduled_publish_at: null - scheduled_unpublish_at: null + has_unpublished_changes: false + draft_updated_at: null highlights: [] pages: type: pages page: 1 total_pages: 1 per_page: 10 + No results: + value: + type: list + total_count: 0 + data: [] + pages: + type: pages + page: 1 + total_pages: 1 + per_page: 10 schema: "$ref": "#/components/schemas/article_search_response" + '400': + description: Bad Request + content: + application/json: + examples: + Phrase too long: + value: + type: error.list + request_id: 1bc9b60b-0786-5071-8f02-7a1774b9e60c + errors: + - code: parameter_invalid + message: Phrase is too long + Invalid state: + value: + type: error.list + request_id: 45ab1896-953a-51ff-ab2a-208ae54fd42c + errors: + - code: parameter_mismatch + message: Article state must be one of published, draft, all + Invalid help center: + value: + type: error.list + request_id: 4a19af49-61cb-5405-a03e-240ff7d4e685 + errors: + - code: invalid_help_center_id + message: Invalid Help Center ID + Invalid pagination: + value: + type: error.list + request_id: a88426cc-4cdd-5084-baf4-4db7b55bd4f9 + errors: + - code: data_invalid + message: Pagination data must be a number greater than 0 + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -3953,7 +4289,7 @@ paths: description: | You can fetch a list of all URL redirects for a help center by making a GET request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects`. - Redirects are returned in descending order on the `updated_at` attribute. + Redirects are returned in ascending alphabetical order of `from_url`. Requires the `read_help_center_redirects_scope` OAuth scope. Set `Intercom-Version: Preview`. responses: @@ -4307,13 +4643,35 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. Defaults to the first page. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 20. Maximum is 250. + example: 20 + schema: + type: integer + maximum: 250 + - name: help_center_id + in: query + required: false + description: Only return collections that belong to this Help Center. + example: 123 + schema: + type: integer tags: - Help Center operationId: listAllCollections description: | You can fetch a list of all collections by making a GET request to `https://api.intercom.io/help_center/collections`. - Collections will be returned in descending order on the `updated_at` attribute. This means if you need to iterate through results then we'll show the most recently updated collections first. + Requires the `read_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. responses: '200': description: Successful @@ -4325,9 +4683,10 @@ paths: type: list data: - id: '159' + type: collection workspace_id: this_is_an_id96_that_should_be_at_least_4 name: English collection title - url: http://help-center.test/myapp-96/collection-17 + url: http://help-center.test/myapp-96/en/collections/159-english-collection-title order: 17 created_at: 1734537309 updated_at: 1734537309 @@ -4336,9 +4695,10 @@ paths: parent_id: help_center_id: 79 - id: '160' + type: collection workspace_id: this_is_an_id96_that_should_be_at_least_4 name: English section title - url: http://help-center.test/myapp-96/section-1 + url: http://help-center.test/myapp-96/en/collections/160-english-section-title order: 1 created_at: 1734537309 updated_at: 1734537309 @@ -4354,6 +4714,27 @@ paths: total_pages: 1 schema: "$ref": "#/components/schemas/collection_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too large: + value: + type: error.list + request_id: a53bbddf-0c1f-5347-ad35-6e77920c9856 + errors: + - code: parameter_invalid + message: Per Page is too big + Invalid help center: + value: + type: error.list + request_id: 806bb340-2357-544e-8fc2-8500543d72bd + errors: + - code: invalid_help_center_id + message: Invalid help center id + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -4378,7 +4759,10 @@ paths: tags: - Help Center operationId: createCollection - description: You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections.` + description: | + You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections`. + + Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. responses: '200': description: collection created @@ -4388,9 +4772,10 @@ paths: collection created: value: id: '165' + type: collection workspace_id: this_is_an_id100_that_should_be_at_least_ name: Thanks for everything - url: http://help-center.test/myapp-100/ + url: http://help-center.test/myapp-100/en/collections/165-thanks-for-everything order: 1 created_at: 1734537312 updated_at: 1734537312 @@ -4412,6 +4797,20 @@ paths: errors: - code: parameter_not_found message: Name is a required parameter. + Invalid help center: + value: + type: error.list + request_id: 68bc842d-927f-5ac0-a16c-27cfa23c2f2f + errors: + - code: invalid_help_center_id + message: Invalid help center id + Parent collection not found: + value: + type: error.list + request_id: aefba0b8-1416-5186-9b13-2d2ea4c4eedd + errors: + - code: parameter_invalid + message: Parent collection doesn't exist schema: "$ref": "#/components/schemas/error" '401': @@ -4460,8 +4859,10 @@ paths: tags: - Help Center operationId: retrieveCollection - description: You can fetch the details of a single collection by making a GET - request to `https://api.intercom.io/help_center/collections/This is the body in html
" body_markdown: type: string - description: The content of the article in markdown. For multilingual articles, this - will be the body of the default language's content. An alternative to `body` — you - can provide content as markdown instead of HTML. Mutually exclusive with `body`. + description: The content of the draft in markdown. For multilingual articles, this + will be the body of the default language's content. Mutually exclusive with `body`. example: "## Updated heading\n\nNew content.\n" author_id: type: integer - description: The id of the author of the article. For multilingual articles, + description: The id of the author of the draft. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace. example: 1295 - state: - type: string - description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the publish state unchanged, so a draft stays - a draft and an edit to a published article goes live immediately unless - that article already has a pending draft or a scheduled publish time is - set in the same request. The `PUT /articles/{id}/draft` endpoint ignores - this field and always stages a draft. For multilingual articles, this - will be the state of the default language's content. - enum: - - published - - draft - example: draft - parent_id: - type: string - description: The id of the article's parent collection or section. An article - without this field stands alone. - example: '18' - parent_type: - type: string - description: The type of parent, which can either be a `collection` or `section`. - example: collection - parent_ids: - type: array - description: The ids of the parent collections to place this article in. - Send an empty array to remove the article from all collections. When - provided, this takes precedence over `parent_id` and `parent_type`. - items: - type: integer - example: - - 18 - - 19 translated_content: + description: Draft content for other locales, keyed by locale code. Each locale + must already be published on the article. "$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 - audience_ids: - type: array - nullable: true - description: >- - The list of audience IDs to assign to this article for Fin AI Agent targeting. - Sending a top-level `audience_ids` broadcasts the same set to every locale. - Sending `audience_ids: []` clears all audience memberships from every locale. - For per-locale targeting, use `translated_content.Body of the Article
+ body_markdown: "Body of the Article\n" author_id: 991267497 state: published created_at: 1734537288 updated_at: 1734537288 url: http://help-center.test/myapp-68/en/articles/42-thanks-for-everything + audience_ids: [] + ai_chatbot_availability: true + ai_copilot_availability: true + ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" '400': - description: Bad Request + description: Bad Request. A JSON request whose body is an empty object returns `400` with no response body. content: application/json: examples: @@ -2246,6 +2310,48 @@ paths: - code: parameter_not_found message: author_id must be in the main body or default locale translated_content object + Missing title: + value: + type: error.list + request_id: b052ee5c-f602-5d9a-8356-94544cd9b12a + errors: + - code: parameter_not_found + message: Title is a required parameter + Unsupported locale: + value: + type: error.list + request_id: 00e07e24-9182-5d6a-8830-4a977fd902c9 + errors: + - code: data_invalid + message: Locale 'xx' isn't supported. + Collection not found: + value: + type: error.list + request_id: 4c9f130d-bfb7-5cab-9a98-7c9fa6650ea9 + errors: + - code: parameter_invalid + message: Collection not found + Publish time in the past: + value: + type: error.list + request_id: b0015de0-8628-523f-bca1-780ed3bdcc75 + errors: + - code: parameter_invalid + message: scheduled_publish_at must be in the future + schema: + "$ref": "#/components/schemas/error" + '404': + description: 'Not found: the author, an audience, the folder or a collection in `parent_ids` does not exist.' + content: + application/json: + examples: + Author not found: + value: + type: error.list + request_id: e1650d39-7d30-554f-aeb1-b4aa32837f1a + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -2260,6 +2366,34 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Author not authorised: + value: + type: error.list + request_id: 4be1f5b3-3590-5eb7-83df-6d852559f097 + errors: + - code: action_forbidden + message: author_id 991267497 is not authorised on this workspace + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Body and body_markdown both provided: + value: + type: error.list + request_id: a560a2a1-1b69-5178-8953-b3d8c982eb29 + errors: + - code: parameter_invalid + message: body and body_markdown are mutually exclusive - please provide only one + Invalid availability value: + value: + type: error.list + request_id: 3a0b96f7-6f76-5b2e-899a-776192cb6235 + errors: + - code: parameter_invalid + message: ai_chatbot_availability must be true or false schema: "$ref": "#/components/schemas/error" requestBody: @@ -2277,7 +2411,6 @@ paths: author_id: 991267497 state: published parent_id: 145 - parent_type: collection translated_content: fr: title: Merci pour tout @@ -2310,8 +2443,10 @@ paths: tags: - Articles operationId: retrieveArticle - description: You can fetch the details of a single article by making a GET request - to `https://api.intercom.io/articles/New gifts in store for the jolly season
+ body_markdown: "New gifts in store for the jolly season\n" author_id: 991267508 state: published created_at: 1734537297 updated_at: 1734537298 url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] + ai_chatbot_availability: true + ai_copilot_availability: true + ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" + '400': + description: Bad Request. A JSON request whose body is an empty object returns `400` with no response body. + content: + application/json: + examples: + Publish and unpublish in the same request: + value: + type: error.list + request_id: 884b59c8-2bae-51de-b300-e9b78dfa793c + errors: + - code: parameter_invalid + message: Cannot schedule a publish and unpublish in the same request + Publish time in the past: + value: + type: error.list + request_id: 9936f252-ad05-5bf2-b681-c94d83904f71 + errors: + - code: parameter_invalid + message: scheduled_publish_at must be in the future + Unpublish on an article that is not published: + value: + type: error.list + request_id: 4d09d60a-6f62-5b5e-b71a-92c949fad184 + errors: + - code: parameter_invalid + message: Cannot schedule an unpublish on an article that is not currently published + Unsupported locale: + value: + type: error.list + request_id: bf534ebb-919e-5f80-91d0-35de1deffc4a + errors: + - code: data_invalid + message: Locale 'xx' isn't supported. + Collection not found: + value: + type: error.list + request_id: f1c380ad-c52e-50ba-a678-70a258799efe + errors: + - code: parameter_invalid + message: Collection not found + schema: + "$ref": "#/components/schemas/error" '404': description: Article Not Found content: @@ -2440,6 +2653,13 @@ paths: errors: - code: not_found message: Resource Not Found + Author not found: + value: + type: error.list + request_id: da7836a0-95a1-5926-969c-6bc26f5a6633 + errors: + - code: not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -2454,6 +2674,34 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Author not authorised: + value: + type: error.list + request_id: f62b30e2-5b2e-561d-b1e8-01a84a380ee2 + errors: + - code: action_forbidden + message: author_id 991267508 is not authorised on this workspace + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable Entity + content: + application/json: + examples: + Body and body_markdown both provided: + value: + type: error.list + request_id: 2ee5920d-5fd3-5adc-8a58-d3e0cf3723c1 + errors: + - code: parameter_invalid + message: body and body_markdown are mutually exclusive - please provide only one + Invalid availability value: + value: + type: error.list + request_id: f504af40-1675-56e1-8d06-28eae3412526 + errors: + - code: parameter_invalid + message: ai_chatbot_availability must be true or false schema: "$ref": "#/components/schemas/error" requestBody: @@ -2489,7 +2737,10 @@ paths: tags: - Articles operationId: deleteArticle - description: You can delete a single article by making a DELETE request to `https://api.intercom.io/articles/Unpublished changes staged as a draft
@@ -2578,12 +2870,15 @@ paths: state: published created_at: 1734537292 updated_at: 1734537292 - has_unpublished_changes: true - draft_updated_at: 1734537292 url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: true + draft_updated_at: 1734537292 schema: "$ref": "#/components/schemas/article" '404': @@ -2615,9 +2910,13 @@ paths: The article must already be published; staging a draft on an article that has never been published returns `422`. - Only versioned text content (such as `title` and `body`) is staged. - Non-versioned fields like AI availability are ignored, leaving the live - values untouched. + Only text content is staged: `title`, `description`, `body` or + `body_markdown`, and `author_id`, including per-locale values in + `translated_content`. Any other field in the request body, such as `state`, + `parent_id`, `folder_id`, `audience_ids`, the AI availability fields or the + scheduling fields, is still validated but not applied, so the live article is left untouched. The + scheduling, state and placement notes on the request schema's other fields + do not apply to this endpoint, because those fields are not applied. Requires the `read_write_articles_scope` OAuth scope. responses: @@ -2632,6 +2931,26 @@ paths: type: article workspace_id: this_is_an_id80_that_should_be_at_least_4 parent_ids: [] + folder_id: null + statistics: + type: article_statistics + views: 0 + conversations: 0 + reactions: 0 + happy_reaction_percentage: 0 + neutral_reaction_percentage: 0 + sad_reaction_percentage: 0 + fin_involvements: 0 + fin_resolutions: 0 + fin_resolution_rate: 0 + tags: + type: tag.list + tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '79' title: Christmas is here! description: '' body:New gifts in store for the jolly season
@@ -2640,18 +2959,21 @@ paths: state: published created_at: 1734537297 updated_at: 1734537298 - has_unpublished_changes: true - draft_updated_at: 1734537298 url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: true + draft_updated_at: 1734537298 schema: "$ref": "#/components/schemas/article" '404': "$ref": "#/components/responses/ObjectNotFound" '422': - description: Article must be published before a draft can be staged + description: Article is not published, or a requested locale is not published content: application/json: examples: @@ -2718,6 +3040,26 @@ paths: type: article workspace_id: this_is_an_id80_that_should_be_at_least_4 parent_ids: [] + folder_id: null + statistics: + type: article_statistics + views: 0 + conversations: 0 + reactions: 0 + happy_reaction_percentage: 0 + neutral_reaction_percentage: 0 + sad_reaction_percentage: 0 + fin_involvements: 0 + fin_resolutions: 0 + fin_resolution_rate: 0 + tags: + type: tag.list + tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '79' title: Christmas is here! description: '' body:New gifts in store for the jolly season
@@ -2726,12 +3068,15 @@ paths: state: published created_at: 1734537297 updated_at: 1734537299 - has_unpublished_changes: false - draft_updated_at: null url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here + audience_ids: [] ai_chatbot_availability: true ai_copilot_availability: true ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: false + draft_updated_at: null schema: "$ref": "#/components/schemas/article" '404': @@ -2862,7 +3207,7 @@ paths: schema: "$ref": "#/components/schemas/error" '404': - description: Article or tag not found + description: Article, tag or teammate not found content: application/json: examples: @@ -2880,6 +3225,13 @@ paths: errors: - code: tag_not_found message: Tag not found + Admin not found: + value: + type: error.list + request_id: 7a34a204-9fae-5335-b818-1da0df3b5234 + errors: + - code: admin_not_found + message: Admin not found schema: "$ref": "#/components/schemas/error" '401': @@ -2996,15 +3348,15 @@ paths: - name: per_page in: query required: false - description: The number of results to return per page. - example: 25 + description: The number of results to return per page. Defaults to 10. + example: 10 schema: type: integer - name: locale in: query required: false description: Filter versions to a specific locale. Use the locale identifier - (for example `en`, `fr`). If the locale is not configured for the workspace, + (for example `en`, `fr`). If the article has no content in that locale, a `400` is returned. example: en schema: @@ -3032,7 +3384,7 @@ paths: pages: type: pages page: 1 - per_page: 25 + per_page: 10 total_pages: 1 total_count: 2 data: @@ -3061,17 +3413,17 @@ paths: schema: "$ref": "#/components/schemas/article_version_list" '400': - description: Unknown locale + description: No content for the requested locale content: application/json: examples: - Unknown locale: + No content for locale: value: type: error.list request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f errors: - code: parameter_invalid - message: Unknown locale + message: No content found for locale 'fr' on article 123 schema: "$ref": "#/components/schemas/error" '404': @@ -3103,8 +3455,8 @@ paths: - name: locale in: query required: false - description: Return the version's content for a specific locale. If the locale - is not configured for the workspace, a `400` is returned. + description: Return the version's content for a specific locale. If the article + has no content in that locale, a `400` is returned. example: en schema: type: string @@ -3143,17 +3495,17 @@ paths: schema: "$ref": "#/components/schemas/article_version" '400': - description: Unknown locale + description: No content for the requested locale content: application/json: examples: - Unknown locale: + No content for locale: value: type: error.list request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f errors: - code: parameter_invalid - message: Unknown locale + message: No content found for locale 'fr' on article 123 schema: "$ref": "#/components/schemas/error" '404': @@ -3171,18 +3523,24 @@ paths: - name: phrase in: query required: false - description: The phrase within your articles to search for. + description: The phrase within your articles to search for. Maximum length is 500 characters. example: Getting started schema: type: string + maxLength: 500 - name: state in: query required: false description: The state of the Articles returned. One of `published`, `draft` - or `all`. + or `all`. Defaults to `published`. example: published schema: type: string + enum: + - published + - draft + - all + default: published - name: help_center_id in: query required: false @@ -3198,10 +3556,29 @@ paths: example: false schema: type: boolean + - name: page + in: query + required: false + description: The page of results to fetch. Defaults to the first page. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 10. + example: 10 + schema: + type: integer tags: - Articles operationId: searchArticles - description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + description: | + You can search for articles by making a GET request to `https://api.intercom.io/articles/search`. + + If no articles match the search, `data` is an empty array rather than an object. + + Requires the `read_articles_scope` OAuth scope. responses: '200': description: Search successful @@ -3218,25 +3595,85 @@ paths: type: article workspace_id: this_is_an_id92_that_should_be_at_least_4 parent_ids: [] + folder_id: null tags: type: tag.list tags: [] + exclude_from_article_suggestions: false + help_center_audience: everyone + scheduled_publish_at: null + scheduled_unpublish_at: null + content_id: '91' title: Title 1 description: '' body: '' + body_markdown: '' author_id: 991267521 state: draft created_at: 1734537306 updated_at: 1734537306 url: + audience_ids: [] + ai_chatbot_availability: true + ai_copilot_availability: true + ai_sales_agent_availability: true + created_by_id: 5017691 + updated_by_id: 5017691 + has_unpublished_changes: false + draft_updated_at: null highlights: [] pages: type: pages page: 1 total_pages: 1 per_page: 10 + No results: + value: + type: list + total_count: 0 + data: [] + pages: + type: pages + page: 1 + total_pages: 1 + per_page: 10 schema: "$ref": "#/components/schemas/article_search_response" + '400': + description: Bad Request + content: + application/json: + examples: + Phrase too long: + value: + type: error.list + request_id: 1bc9b60b-0786-5071-8f02-7a1774b9e60c + errors: + - code: parameter_invalid + message: Phrase is too long + Invalid state: + value: + type: error.list + request_id: 45ab1896-953a-51ff-ab2a-208ae54fd42c + errors: + - code: parameter_mismatch + message: Article state must be one of published, draft, all + Invalid help center: + value: + type: error.list + request_id: 4a19af49-61cb-5405-a03e-240ff7d4e685 + errors: + - code: invalid_help_center_id + message: Invalid Help Center ID + Invalid pagination: + value: + type: error.list + request_id: a88426cc-4cdd-5084-baf4-4db7b55bd4f9 + errors: + - code: data_invalid + message: Pagination data must be a number greater than 0 + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -5220,7 +5657,7 @@ paths: description: | You can fetch a list of all URL redirects for a help center by making a GET request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects`. - Redirects are returned in descending order on the `updated_at` attribute. + Redirects are returned in ascending alphabetical order of `from_url`. Requires the `read_help_center_redirects_scope` OAuth scope. responses: @@ -5561,13 +5998,35 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + required: false + description: The page of results to fetch. Defaults to the first page. + example: 1 + schema: + type: integer + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 20. Maximum is 250. + example: 20 + schema: + type: integer + maximum: 250 + - name: help_center_id + in: query + required: false + description: Only return collections that belong to this Help Center. + example: 123 + schema: + type: integer tags: - Help Center operationId: listAllCollections description: | You can fetch a list of all collections by making a GET request to `https://api.intercom.io/help_center/collections`. - Collections will be returned in descending order on the `updated_at` attribute. This means if you need to iterate through results then we'll show the most recently updated collections first. + Requires the `read_articles_scope` OAuth scope. responses: '200': description: Successful @@ -5579,9 +6038,10 @@ paths: type: list data: - id: '159' + type: collection workspace_id: this_is_an_id96_that_should_be_at_least_4 name: English collection title - url: http://help-center.test/myapp-96/collection-17 + url: http://help-center.test/myapp-96/en/collections/159-english-collection-title order: 17 created_at: 1734537309 updated_at: 1734537309 @@ -5590,9 +6050,10 @@ paths: parent_id: help_center_id: 79 - id: '160' + type: collection workspace_id: this_is_an_id96_that_should_be_at_least_4 name: English section title - url: http://help-center.test/myapp-96/section-1 + url: http://help-center.test/myapp-96/en/collections/160-english-section-title order: 1 created_at: 1734537309 updated_at: 1734537309 @@ -5608,6 +6069,27 @@ paths: total_pages: 1 schema: "$ref": "#/components/schemas/collection_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too large: + value: + type: error.list + request_id: a53bbddf-0c1f-5347-ad35-6e77920c9856 + errors: + - code: parameter_invalid + message: Per Page is too big + Invalid help center: + value: + type: error.list + request_id: 806bb340-2357-544e-8fc2-8500543d72bd + errors: + - code: invalid_help_center_id + message: Invalid help center id + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -5632,7 +6114,10 @@ paths: tags: - Help Center operationId: createCollection - description: You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections.` + description: | + You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections`. + + Requires the `read_write_articles_scope` OAuth scope. responses: '200': description: collection created @@ -5642,9 +6127,10 @@ paths: collection created: value: id: '165' + type: collection workspace_id: this_is_an_id100_that_should_be_at_least_ name: Thanks for everything - url: http://help-center.test/myapp-100/ + url: http://help-center.test/myapp-100/en/collections/165-thanks-for-everything order: 1 created_at: 1734537312 updated_at: 1734537312 @@ -5666,6 +6152,20 @@ paths: errors: - code: parameter_not_found message: Name is a required parameter. + Invalid help center: + value: + type: error.list + request_id: 68bc842d-927f-5ac0-a16c-27cfa23c2f2f + errors: + - code: invalid_help_center_id + message: Invalid help center id + Parent collection not found: + value: + type: error.list + request_id: aefba0b8-1416-5186-9b13-2d2ea4c4eedd + errors: + - code: parameter_invalid + message: Parent collection doesn't exist schema: "$ref": "#/components/schemas/error" '401': @@ -5714,8 +6214,10 @@ paths: tags: - Help Center operationId: retrieveCollection - description: You can fetch the details of a single collection by making a GET - request to `https://api.intercom.io/help_center/collections/