Pagination & Response Customization

The Search API provides options for controlling the number of results returned (pagination) and what additional attributes are included in the response. These parameters allow clients to efficiently fetch results in batches and enrich responses with custom metadata when needed.

Pagination Parameters

Pagination ensures that large result sets can be retrieved in smaller, more manageable pages. Use the following query parameters together to navigate results:

1. Page Number ($pagenum)

  • Indicates the page number of results to fetch.
  • Default: 1
  • Minimum: 1
  • Maximum: 999

2. Page Size ($pagesize)

  • Specifies the number of results per page.
  • Default: 10
  • Minimum: 1
  • Maximum: 30
  • Example: Retrieve page 2 of results with 20 results per page:
    Copy
    Copied
    curl -X GET "https://<API_DOMAIN>/knowledge/portalmgr/v4/PROD-1000/search?q=mortgage%20rates&$pagenum=2&$pagesize=20" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json"

Response Customization

Custom Attributes (articleCustomAdditionalAttributes)

  • Allows clients to request one or more custom attributes defined for articles.
  • Pass as a comma-separated list of attribute names in the query.
  • Useful for enriching responses with metadata beyond the default schema.
  • Default: none (custom attributes are not returned unless explicitly requested).
  • Example: Request region and complianceLevel as additional attributes:
    Copy
    Copied
    curl -X GET "https://<API_DOMAIN>/knowledge/portalmgr/v4/PROD-1000/search?q=mortgage%20rates&articleCustomAdditionalAttributes=region,complianceLevel" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: application/json"

    A successful response includes the custom attributes in the customAttributes field:

    Copy
    Copied
    {
"searchResults": {
"article": [
  {
    "id": "PROD-2001",
    "name": "Current Mortgage Rates",
    "snippet": "Today's mortgage rates are...",
    "customAttributes": [
      {
        "name": "region",
        "value": ["US-West"],
        "type": "STRING"
      },
      {
        "name": "complianceLevel",
        "value": ["SOX"],
        "type": "STRING"
      }
    ]
  }
]
},
"paginationInfo": {
"count": 50,
"pagenum": 2,
"pagesize": 20
}
}