Get Articles in Topic

Request

Overview

The Get Articles in Topic API allows a user to retrieve the browsable articles in a topic.

Only articles directly associated with the specified topic are returned. This API does not support hierarchical traversal across child topics (for example, T1 → T2 → T3); articles associated with child topics are not returned.

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.

Security

oAuthUser(Required scopes: ) or oAuthOnBehalfOfUser(Required scopes: ) or oAuthCustomer(Required scopes: ) or oAuthOnBehalfOfCustomer(Required scopes: ) or oAuthAnonymousCustomer(Required scopes: ) or oAuthClient(Required scopes: )

Path

portalIDstring, [ 7 .. 20 ] characters^[a-zA-Z0-9]{2,4}-\d{4,15}$required

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.

Example:PROD-1000

Query

searchProfileIdstring, [ 1 .. 15 ] characters

Search Profile ID

Example:searchProfileId=959500000204621

$filter[topicId]string, [ 7 .. 20 ] characters^[a-zA-Z0-9]{2,4}-\d{4,15}$required

The ID of the topic. It is used to restrict to a specific topic. Only articles directly associated with this topic are returned; hierarchical traversal across child topics is not supported.

Example:$filter[topicId]=PROD-1065

articleResultAdditionalAttributesArray of strings

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:

Name	Description
id	The ID of the Article.
name	The name of the Article.
articleType	The Article Type and its attributes.
createdBy	The ID, first name, middle name and last name of the user that created the Article.
createdDate	The date that the Article was created.
hasAttachments	True: The Article has one or more attachments. False: The Article does not have any attachments.
languageCode	The language code of the Article language.
modifiedBy	The ID, first name, middle name and last name of the user that last modified the Article.
modifiedDate	The date that the Article was last modified on.
link	The link object, used to retrieve the details of the Article.
versionId	The ID of the Article version that is returned.

Items Enum:"averageRating""customAttributes""description""articleSummary""imageURL""isSubscribed""timesRated""topicBreadcrumb""ownedBy""ownedBy.userName"

Examples:

Single

An additional attribute to be returned.

articleResultAdditionalAttributes=["averageRating"]

Multiple

Additional attributes to be returned.

articleResultAdditionalAttributes=["ownedBy","ownedBy.userName"]

All

All additional attributes to be returned.

articleResultAdditionalAttributes=["all"]

articleResultExtendedAttributesArray of strings

Specifies extended attributes of an Article Result to be returned in the response. This parameter is used for specific metadata fields that are not included in the default response or the standard additional attributes list.

Note: The list of supported values for this parameter may be expanded in the future as more fields are added to the article result schema.

Name	Description
availabilityDate	The date and time when the article becomes available for viewing.

Items Value:"availabilityDate"

Examples:

Single

Returns the availability date for the article result.

articleResultExtendedAttributes=["availabilityDate"]

$filter[tags]string, [ 7 .. 2048 ] characters^([a-zA-Z0-9]{2,4}-\d{4,15})(,([a-zA-Z0-9]{2,...

A comma separated list of Tag / Tag Group IDs. The query results will be filtered by the tags that are specified.

Tag IDs and Tag Group IDs can be mixed together.

Example:$filter[tags]=PROD-5381

workflowMilestonestring

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.

Enum:"authoring""staging""publish"

Example:workflowMilestone=publish

$langstring(languageCode)

The language used for 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.

Enum:"en-US""fr-FR""en-GB""es-ES""it-IT""nl-NL""da-DA""sv-SE""pt-PT""fi-FI"

Example:$lang=en-US

$pagenuminteger, (int64), [ 1 .. 999 ]

Pagination parameter that specifies the page number of results to be returned. Used in conjunction with $pagesize.

Default:1

$pagesizeinteger, (int64), [ 1 .. 75 ]

Pagination parameter that specifies the number of results per page. Used in conjunction with $pagenum.

Default:10

$sortstring

Articles to be sorted on.

Enum:"availabilityDate""popularity""name"

Example:$sort=name

$orderstring

Sort order of articles.

Enum:"asc""desc"

Example:$order=asc

Headers

x-egain-activity-idstring, [ 4 .. 9 ] characters^[0-9]{4,9}$

A unique numeric interaction identifier from eGain.

Example:59237

x-ext-integration-idstring, <= 40 characters^[\w\W]+$

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.

Examples:

uuid

3155180e-0c13-43e9-9c38-e9045bcbf176

hex

00Dbn00000IxGnx

x-ext-interaction-idstring, <= 40 characters^[\w\W]+$

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.

Examples:

uuid

3155180e-0c13-43e9-9c38-e9045bcbf176

hex

00Dbn00000IxGnx

Accept-Languagestringrequired

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

Enum:"en-US""es-ES""fr-FR""it-IT""de-DE""nl-NL""pt-BR""pt-PT""da-DK""ru-RU"

Example:en-US

curl -i -X GET \
  'https://api.egain.cloud/knowledge/portalmgr/v4/portals/PROD-1000/articles?searchProfileId=959500000204621&%24filter%5BtopicId%5D=PROD-1065&articleResultAdditionalAttributes=averageRating&articleResultExtendedAttributes=availabilityDate&%24filter%5Btags%5D=PROD-5381&workflowMilestone=publish&%24lang=en-US&%24pagenum=1&%24pagesize=10&%24sort=name&%24order=asc' \
  -H 'Accept-Language: en-US' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -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'

Responses

Success

Bodyapplication/json

articlesArray of objects(ArticleResult)

Article details

paginationInfoobject(PaginationInfo)

Response

{
  "articles": [
    { … }
  ],
  "paginationInfo": {
    "count": 1,
    "pagenum": 1,
    "pagesize": 10
  }
}