Get Articles in Topic

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.
SecurityoAuthUser or oAuthCustomer or oAuthAnonymousCustomer
Request
path Parameters
portalID
required
string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

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 Parameters
$filter[topicId]
string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

The ID of the topic. It is used to restrict to a specific topic.

Example: $filter[topicId]=PROD-1065
articleResultAdditionalAttributes
Array 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" "workflow" "compliance" "personalization" "all" Examples:
An additional attribute to be returned.
articleResultAdditionalAttributes=averageRating
Additional attributes to be returned.
articleResultAdditionalAttributes=ownedBy,ownedBy.userName
All additional attributes to be returned.
articleResultAdditionalAttributes=all
$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
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.

    • Enum: "authoring" "staging" "publish"
    Example: workflowMilestone=publish
    $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.

    • Enum: "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" "xx-XX"
    Example: $lang=en-US
    $pagenum
    integer <int64> [ 1 .. 999 ]
    Default: 1

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

    $pagesize
    integer <int64> [ 1 .. 75 ]
    Default: 10

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

    $sort
    string

    Articles to be sorted on.

    Enum: "availabilityDate" "popularity" "name"
    Example: $sort=name
    $order
    string

    Sort order of articles.

    Enum: "asc" "desc"
    Example: $order=asc
    header Parameters
    x-egain-activity-id
    string [ 4 .. 9 ] characters ^[0-9]{4,9}$

    A unique numeric interaction identifier from eGain.

    Example: 59237
    x-ext-integration-id
    string <= 40 characters ^[\w\W]+$

    The unique numeric identifier for a tenant, used in self-service functionality as well as third-party integrations.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-interaction-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    x-ext-interaction-id
    string <= 40 characters ^[\w\W]+$

    A unique interaction identifier from other CRM applications.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-integration-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    Accept-Language
    required
    string

    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" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"
    Example: en-US
    Responses
    200

    Success

    204

    No Content

    400

    Bad Request

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    406

    Not acceptable

    500

    Internal server error

    get/portals/{portalID}/articles
    Request samples
    Response samples
    application/json
    {
    • "articles": [
      ],
    • "paginationInfo": {
      }
    }