# Article

Article APIs

## Get Article by ID

 - [GET /portals/{portalID}/articles/{articleID}](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticlebyid.md): ## Overview
  * The Get Article by ID API allows a user or client application to retrieve an Article using its ID.
    * It requires a Portal ID, which a user or client application can retrieve through the Administrative Console or by calling Get All Portals API.
    * Additional Article attributes and contextual views can be specified in the query parameters.

  * This API returns structured authoring attributes of Issue, Environment, Cause and Confidence Level when the following conditions are met:
    * The "Allow Structured Authoring" setting is enabled at the partition/department level through the Administrative Console.
    * The "Use Structured Authoring" flag is set on the article type.

## Prerequisites
  * Agents without a user profile and customers in a portal without a default user profile only have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
  * Agents with a user profile and customers in a portal with a default user profile have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
    * Contain access tags that are also in the assigned user profiles.
    * Contain publish views with associated tags that are also in the assigned user profiles.
  * Agents with the following assigned actions can view updates to articles currently being processed in workflows:
    * View Author Portal – Allows agents to view updates to articles at any stage in a workflow.
    * View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow.

## Get Article By ID with Editions

 - [GET /articles/{articleID}/witheditions](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticlebyidwitheditions.md): ## Overview
  * This API allows a user to retrieve an article with all its editions.
  * If there are no editions for the article, the response will contain the base content of the article.

## Get Article Edition Details

 - [GET /articles/{articleID}/editions/{publishViewId}](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticleeditiondetails.md): ## Overview
  * This API retrieves the details of an article edition.

## Get All Article Types in a Department

 - [GET /articletypes](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getallarticletypes.md): ## Overview
The Get All Article Types in a Department API retrieves a list of all Article Types configured for a specific department.

## Add Article to Reply

 - [PUT /portals/{portalID}/articles/{articleID}/addtoreply](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/addtoreply.md): ## Overview
The Add Article to Reply API captures events for articles used in a reply for a digital channel activity.

Note:  Either the x-ext-activity-id orx-ext-integration-id and x-ext-interaction-id header must be provided.

## Permissions
  * Only Agents can invoke this API.

## Add as Reference

 - [PUT /portals/{portalID}/articles/{articleID}/addasreference](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/addasreference.md): ## Overview
The Add as Reference API captures events for articles that are referenced by agents replying inside of a digital channel activity.

Note: Either the x-ext-activity-id orx-ext-integration-id and x-ext-interaction-id header must be provided.

## Permissions
  * Only Agents can invoke this API.

## Get Articles in Topic

 - [GET /portals/{portalID}/articles](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticlesintopic.md): ## Overview
The Get Articles in Topic API allows a user to retrieve the browsable articles in a topic.

## Prerequisites
  * Set the Article type’s parameter “Include in browse on portals” to "Yes" for an article to be returned by this API.
  * Agents without a user profile and customers in a portal without a default user profile only have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain published views without any associated tags.
  * Agents with a user profile and customers in a portal with a default user profile have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
    * Contain access tags that are also in the assigned user profiles.
    * Contain publish views with associated tags that are also in the assigned user profiles.
  
## Permissions  
  * Agents with the following assigned actions can view updates to articles currently being processed in workflows:
    * View Author Portal – Allows agents to view updates to articles at any stage in a workflow.
    * View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow.

## Get Article Attachment By ID

 - [GET /articles/attachments/{attachmentID}](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticleattachmentbyid.md): ## Overview
  This API allows one article attachment identified by an attachment ID to be retrieved.

## Get Article Attachment in Portal

 - [GET /portals/{portalID}/articles/attachments/{attachmentID}](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getattachmentbyidinportal.md): ## Overview
The Get Article Attachment API retrieves an attachment associated to an article by calling the attachment ID for a specified portal ID.

## Get Related Articles

 - [GET /portals/{portalID}/articles/{articleID}/related](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getrelatedarticles.md): ## Overview
The Get Related Articles API retrieves all related articles associated to a given article.

## Prerequisites
  * Set the Article type’s parameter “Include in browse on portals” to "Yes" for an article to be returned by this API.
  * Agents without a user profile and customers in a portal without a default user profile only have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
  * Agents with a user profile and customers in a portal with a default user profile have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
    * Contain access tags that are also in the assigned user profiles.
    * Contain publish views with associated tags that are also in the assigned user profiles.

## Permissions 
  * Agents with the following assigned actions can view updates to articles currently being processed in workflows:
    * View Author Portal – Allows agents to view updates to articles at any stage in a workflow.
    * View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow.

## Get Announcement Articles

 - [GET /portals/{portalID}/articles/announcements](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getannouncementarticles.md): ## Overview
The Get Announcement Articles API returns a portal's announcement articles. Only displayable announcement articles in the portal are returned. 

## Prerequisites
  * For an article to display or be returned, set the Article type’s parameter, “Include in browse on portals,” to "Yes".
  * Agents without a user profile and customers in a portal without a default user profile only have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
  * Agents with a user profile and customers in a portal with a default user profile have access to articles that:
    * Do not contain any access tags.
    * Do not contain any publish views.
    * Contain publish views without any associated tags.
    * Contain access tags that are also in the assigned user profiles.
    * Contain publish views with associated tags that are also in the assigned user profiles.

## Permissions 
  * Agents with the following assigned actions can view updates to articles currently being processed in workflows:
    * View Author Portal – Allows agents to view updates to articles at any stage in a workflow.
    * View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow.

## Get Article Ratings

 - [GET /portals/{portalID}/articles/{articleID}/ratings](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticleratings.md): ## Overview
The Get Article Ratings API returns ratings set for an Article. These ratings help you to assess the quality, helpfulness, or relevance of an article.

## Rate an Article

 - [PUT /portals/{portalID}/articles/{articleID}/ratings](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/ratearticle.md): ## Overview
The Rate an Article API allows a user to set a rating for an article. These ratings allow you to assess the quality, helpfulness, or relevance of an article.

## Get Pending Article Compliances

 - [GET /portals/{portalID}/articles/compliance/pending](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getpendingcompliancearticles.md): ## Overview
The Get Pending Article Compliances API retrieves all compliance-enabled articles in a portal that need to be read by the current user. Results are sorted in ascending order of the compliance due date.

## Prerequisites
* The Article compliances that are returned must be:
    * Available for the current user profile.
    * Displayable. An article is displayable when the "Include in browse on portals" property is enabled for the article.

## Get Acknowledged Article Compliances

 - [GET /portals/{portalID}/articles/compliance/acknowledged](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getacknowledgedcompliancearticles.md): ## Overview
The Get Acknowledged Article Compliances API retrieves all compliance-enabled articles in a portal that have been read by the current user in the last 60 days. Results are sorted in descending order of the acknowledgement date.

## Prerequisites
* The Article compliances that are returned must be:
    * Available for the current user profile.
    * Displayable. An article is displayable when the "Include in browse on portals" property is enabled for the article.
    * Acknowledged within the last 60 days.
    * Only the latest version of a republished compliance article will be shown.
    * Results will be sorted in descending order of acknowledgment date.

## Comply With an Article

 - [PUT /portals/{portalID}/articles/{articleID}/comply](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/complyarticle.md): ## Overview
The Comply with an Article API allows the user to comply with an article by passing the Article's ID, which marks it as read by the user.            

## Prerequisites
  * The user must be an agent and:
    * Be available in the portal.
    * Be available for the current user profile.
    * Have the Article's compliance policy enabled.
  * If the Article has Access Tags, then it must be available for the agent's current user profile.
  * If the Article has Publish Views, then at least one edition of the Article must be available for the agent's current user profile.

## My Subscription

 - [GET /portals/{portalID}/articles/subscribed](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getmysubscription.md): ## Overview
The My Subscription API allows authenticated users and agents to retrieve the list of articles to which they are subscribed.

## Subscribe to an Article

 - [PUT /portals/{portalID}/articles/{articleID}/subscribe](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/subscribearticle.md): ## Overview
The Subscribe to an Article API allows eGain users, authenticated customers and agents to subscribe and receive notifications about changes to an Article.

## Prerequisites
  * Notifications are sent only if the following conditions are met:
    * The Article content has been modified since the last published version.
    * The attachment list has been modified since the last published version.
    * The author has checked the "Include Article in new and modified Article list" option while publishing the Article.
  * For the Subscribe to an Article API to execute successfully:
    * The Article must be in the portal.
    * The user must have provided an email address.

## Permissions
  * Agent Permissions: The following permissions are required if the user is an agent:
    * If the Article has Access Tags:
      * The Article must be available for the agent's current user profile.
    * If the Article has Publish Views:
      * At least one edition of the Article must be available for the agent's current user profile.
    * If the Article has filters and the "tags query parameter" is provided:
      * The Article filters must match the provided tags or tag groups.
  * Customer Permissions: The following permissions are required if the user is a customer:
    * If the Article has Access Tags:
      * The portal must have a default user profile
      * The Article must be available for the portal's default user profile.
    * If the Article has Publish Views:
      * The portal must have a default user profile
      * At least one edition must be available for the portal's default user profile.
    * If the Article has filters and the "tags query parameter" is provided, then the Article filters must match the provided tags or tag groups.

## Unsubscribe to an Article

 - [PUT /portals/{portalID}/articles/{articleID}/unsubscribe](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/unsubscribearticle.md): ## Overview
The Unsubscribe to an Article API allows authenticated users and agents to unsubscribe to an Article for which they were earlier subscribed to receive change notifications.

## Get Article Permissions By ID

 - [GET /portals/{portalID}/articles/{articleID}/permissions](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticlepermissionsbyid.md): ## Overview
  * The Get Article Permission by ID permits a user to retrieve permissions associated to an article.

## Get Article Personalization Details

 - [GET /portals/{portalID}/articles/{articleID}/personalization](https://apidev.egain.com/apis/v4/knowledge/portalmgr/api-bundled/article/getarticlepersonalization.md): ## Overview
  The Get Article Personalization Details API allows agents to retrieve the personalization tag details of an Article.