Article

Get Article by ID

GET
/knowledge/portalmgr/v4/portals/{portalID}/articles/{articleID}

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.

Authorization

accessToken
AuthorizationBearer <token>

JWT Bearer Token authentication for API access

In: header

Path Parameters

portalID*string

The ID of the portal being accessed.A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.

Match^[a-zA-Z0-9]{2,4}-\d{4,15}$
Length7 <= length <= 20
articleID*string

The ID of the Article.An Article ID is composed of a 2-4 letter prefix followed by a dash and 4-15 digits.

Match^[a-zA-Z0-9]{2,4}-\d{4,15}$
Length7 <= length <= 20

Query Parameters

$lang?string

The language that describes the details of a resource. Resources available in different languages may differ from each other.If lang is not passed, then the portal's default language is used.

Value in

  • "en-US"
  • "fr-FR"
  • "en-GB"
  • "es-ES"
  • "it-IT"
  • "nl-NL"
  • "da-DA"
  • "sv-SE"
  • "pt-PT"
  • "fi-FI"
  • "no-NB"
  • "no-NN"
  • "ja-JA"
  • "de-DE"
  • "pt-BR"
  • "zh-CN"
  • "zh-TW"
  • "ko-KO"
  • "ru-RU"
  • "el-EL"
  • "tr-TR"
  • "pl-PL"
  • "cs-CS"
  • "sk-SK"
  • "hu-HU"
  • "sr-SR"
  • "ar-SA"
  • "hr-HR"
  • "ro-RO"
  • "th-TH"
  • "de-AT"
  • "vi-VN"
  • "id-ID"
  • "ms-MY"
  • "fil-PH"
  • "fr-CA"
  • "hi-IN"
  • "uk-UA"
  • "bg-BG"
  • "sl-SI"
  • "xx-XX"
articleAdditionalAttributes?array<>

The attributes of an Article to be returned in addition to the default list of attributes, listed below. Multiple additional attributes can be specified using a comma-separated list. Passing 'all' will return all attributes.

Default Attributes

These Article attributes are always returned:

NameDescription
idThe ID of the Article.
nameThe name of the Article.
additionalInfoAdditional information provided as Article metadata.
articleTypeThe Article type and its attributes.
articleKeywordsA comma-separated list of keywords associated with this Article.
articleStateThe current state of the Article. States include A (Authoring), S (Staging), and P (Published).
articleSummaryA brief summary of the Article, provided as metadata.
createdByThe ID, first name, middle name and last name of the user that created the Article.
createdDateThe date that the Article was created.
departmentIdID of the department for which this Article belongs to.
descriptionThe Article's description.
expirationDateThe date that the Article is set to expire.
attachmentsThe Article's attachments
imageURLThe URL of the image that is present in the Article version. It is used as the thumbnail image for the Article.
includeInGenAIIndicates whether this Article is used for eGain's generative AI features.
isSubscribedIndicates whether the Article is subscribed for notifications.
languageCodeThe language code of the Article language.
linkThe link object, used to retrieve the details of the Article.
modifiedByThe ID, first name, middle name and last name of the user that last modified the Article.
modifiedDateThe date that the Article was last modified on.
topicBreadcrumbContains a list of topics from the top-level topic to this Article. There may be multiple paths.
versionIdThe ID of the Article version that is returned.
$customAdditionalAttributes?string

One or more comma-separated names for custom attributes defined by the user to be returned.

Match^([a-zA-Z0-9_-]+)(?:,[a-zA-Z0-9_-]+)*$
Length1 <= length <= 4000
accessSource?string

Provides information about the method in which the Article is accessed and is used for self-service analytics. Refer to the eGain User Guide regarding "Article View Contexts".

NameDescription
article_viewView an Article directly using its ID.
article_view_more_related_ArticleView related articles of an Article using its ID.
article_view_basic_searchView an Article via a basic search.
article_view_adv_searchView an Article via an advanced search.
article_view_guided_helpView an Article via a Guided Help solution.
article_view_browse_topicView an Article via browsing a topic.
article_view_browse_treeView an Article via browsing a topic tree.
article_view_popular_articlesView an Article using the Popular Items list in the Self-Service portal.
article_view_useful_itemsView Article using the Useful Items list in the Self-Service portal.
article_view_widgetView an Article via a widget.
article_view_announcementView an Article from the announcement section in the Self-Service portal.
article_view_bookmarkedView a bookmarked Article.
article_view_subscription_notificationView an Article from a subscription notification.
article_view_guided_help_additional_infoView an Article via additional information from a Guided Help search.
view_articles_pending_complianceView an Article via Read & Sign in the Self-Service portal.
type_ahead_SuggestionView an Article from a type-ahead Suggestion in the Self-Service portal.
semantic_SuggestionView an Article from a semantic Suggestion in the Self-Service portal.
instant_answerView an Article via an Instant Answers solution.
instant_answer_referenceView an Article that is used as a reference for an Instant Answers solution.
Default"article_view"

Value in

  • "article_view"
  • "article_view_more_related_Article"
  • "article_view_basic_search"
  • "article_view_adv_search"
  • "article_view_guided_help"
  • "article_view_browse_topic"
  • "article_view_browse_tree"
  • "article_view_popular_articles"
  • "article_view_useful_items"
  • "article_view_widget"
  • "article_view_announcement"
  • "article_view_bookmarked"
  • "article_view_subscription_notification"
  • "article_view_guided_help_additional_info"
  • "view_articles_pending_compliance"
  • "type_ahead_Suggestion"
  • "semantic_Suggestion"
  • "instant_answer"
  • "instant_answer_reference"
publishViewId?string

The ID of a publish view for an Article. A publish view is a set of tags used to generate multiple editions of the same Article for display on the self-service portal. Publish views are used in conjunction with single sourcing to tailor the content of an Article to a specific audience by granting access to an Article's version to users that possess the same tags.A publish view ID is composed of a 4-letter prefix, followed by a dash and 4-15 digits.

Match^[a-zA-Z0-9]{2,4}-\d{4,15}$
Length7 <= length <= 20
workflowMilestone?string

For agents with the View Author Portal or View Staging Portal actions, this determines which version of the Article is returned.'Authoring' returns the most recent version of an Article checked-in by an author.'Staging' returns the updated version currently being processed in a workflow.'Publish' returns the most recently published version.

Value in

  • "authoring"
  • "staging"
  • "publish"

Header Parameters

x-egain-activity-id?string

A unique numeric interaction identifier from eGain.

Match^[0-9]{4,9}$
Length4 <= length <= 9
x-ext-integration-id?string

The unique numeric identifier for a tenant, used in self-service functionality as well as third-party integrations.Note: The x-ext-integration-id and x-ext-interaction-id headers must always be provided together and cannot be supplied independently.The x-egain-activity-id may be provided on its own, or it may be provided along with both x-ext-integration-id and x-ext-interaction-id.

Match^[\w\W]+$
Lengthlength <= 40
x-ext-interaction-id?string

A unique interaction identifier from other CRM applications.Note: The x-ext-integration-id and x-ext-interaction-id headers must always be provided together and cannot be supplied independently.The x-egain-activity-id may be provided on its own, or it may be provided along with both x-ext-integration-id and x-ext-interaction-id.

Match^[\w\W]+$
Lengthlength <= 40
Accept-Language*string

The Language locale accepted by the client (used for locale specific fields in resource representation and in error responses).

Value in

  • "en-US"
  • "es-ES"
  • "fr-FR"
  • "it-IT"
  • "de-DE"
  • "nl-NL"
  • "pt-BR"
  • "pt-PT"
  • "da-DK"
  • "ru-RU"
  • "fr-CA"
  • "zh-CN"
  • "ja-JP"
  • "ko-KR"
  • "sv-SE"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/knowledge/portalmgr/v4/portals/PROD-1000/articles/PROD-2996?articleAdditionalAttributes=averageRating&%24customAdditionalAttributes=country_name&accessSource=article_view&publishViewId=PROD-3203" \  -H "x-egain-activity-id: 59237" \  -H "x-ext-integration-id: 3155180e-0c13-43e9-9c38-e9045bcbf176" \  -H "x-ext-interaction-id: 3155180e-0c13-43e9-9c38-e9045bcbf176" \  -H "Accept-Language: en-US"

{  "id": "PROD-2996",  "name": "Fair Lending FAQs",  "additionalInfo": "Can be shared to public.",  "articleType": {    "articleCategoryId": 0,    "typeName": "General",    "useStructuredAuthoring": false,    "articleTypeId": "999900000002020"  },  "articleKeywords": "Fair lending, Fair Housing Act, Discrimination protection, Residential mortgage loans, Equal opportunity housing",  "articleState": "P",  "articleSummary": "Fair lending ensures that lenders do not discriminate based on race, color,national origin, religion, sex, familial status, or disability when applying forresidential mortgage loans. The federal Fair Housing Act protects individuals'fair lending rights, enforced by the Office of Fair Housing and Equal Opportunity,along with state and local agencies. This law applies to U.S. citizens, greencard holders, and undocumented residents, ensuring equal opportunities in homesales, rentals, and financing.",  "attachments": [    {      "name": "eightbank.png",      "type": "INTERNAL",      "size": 45152,      "link": {        "rel": "self",        "href": "/knowledge/portalmgr/v4/portals/PROD-1000/articles/attachments/PROD-1000?q=fair%2Blending&%articleAdditionalAttributes=allonalArticleResult&workflowMilestone=publish&%24lang=en-US"      },      "id": "PROD-1000"    }  ],  "createdBy": {    "id": "1013",    "firstName": "John",    "middleName": "",    "lastName": "Doe"  },  "createdDate": "2022-06-30T14:54:55Z",  "departmentID": "1001",  "description": "Common questions and answers regarding Fair Lending.",  "expirationDate": "2031-01-02T10:56:00Z",  "imageURL": "https://hd.egain.com/images/km-for-dummies-24.jpg",  "includeInGenAI": true,  "isSubscribed": true,  "languageCode": "en-US",  "modifiedBy": {    "id": "1013",    "firstName": "John",    "middleName": "",    "lastName": "Doe"  },  "modifiedDate": "2025-01-28T19:53:58Z",  "link": {    "rel": "self",    "href": "/knowledge/portalmgr/v4/portals/PROD-1000/articles/PROD-2996?%&workflowMilestone=publish&accessSource=article_view&publishViewId=PROD-3203&%24lang=en-US"  },  "topicBreadcrumb": [    {      "topicSummary": [        {          "name": "Banking Regulations",          "link": {            "rel": "self",            "href": "/knowledge/portalmgr/v4/portals/PROD-1000/topics/PROD-1080"          }        }      ]    }  ],  "versionId": "PROD-2884"}

Cancel Job POST

# Cancel Import or Validation Job ## Overview This API allows users to cancel import or validation operations that are currently in progress or scheduled for future execution. Cancellation is immediate for scheduled jobs and graceful for running jobs. ## Cancellation Behavior - **Scheduled Jobs**: Immediate cancellation, no processing occurs - **In Progress Jobs**: Graceful shutdown, current item completes, no new items start - **Completed Jobs**: Cannot be cancelled (returns error) - **Failed Jobs**: Cannot be cancelled (already stopped) ## When to Cancel - **Content Issues**: Discover problems with source content - **Timing Changes**: Need to reschedule for different time - **Resource Constraints**: System resources are needed elsewhere - **User Request**: Manual cancellation by authorized users - **System Maintenance**: Planned maintenance windows ## Cancellation Process 1. **Request Received**: System receives cancellation request 2. **Status Check**: Verifies current job status 3. **Graceful Shutdown**: For running jobs, completes current item 4. **Resource Cleanup**: Releases allocated system resources 5. **Status Update**: Marks job as cancelled 6. **Notification**: Updates job status and logs ## Post-Cancellation - **Job Status**: Changes to "Cancelled" - **Partial Results**: Any completed items remain in system - **Logs**: Cancellation reason and timing recorded - **Resources**: System resources freed for other operations ## Best Practices - **Monitor Jobs**: Regularly check job status to identify candidates for cancellation - **Plan Cancellations**: Schedule cancellations during low-usage periods - **Resource Planning**: Consider resource impact before cancelling large jobs

Get Article By ID with Editions GET

## 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.