Integrating with Generative AI Tools via the Expert API
Overview
This guide is intended for customers who want to integrate NiCE CXone Expert with a Generative AI tool such as Claude, ChatGPT, or a custom LLM application. By connecting Expert's knowledge base to a GenAI tool, you can enable AI-powered experiences that draw on your organization's published content.
This document covers two topics:
• Authentication: How to generate and use a Server API Token or a Long-term JSON Web Token (JWT) to authenticate API requests securely.
• API Reference: The key API endpoints available for discovering and retrieving content from Expert.
CXone Expert does not currently support MCP (Model Context Protocol) servers. All integration with GenAI tools must be done via direct API calls as described in this guide.
Authentication
All Expert API requests must be associated with a specific user account. Expert is a permission-based platform, and API responses will reflect the content that the associated user is permitted to see. There are two recommended authentication approaches for GenAI integrations, depending on your use case.
Option 1: Standard Server API Token (User Specified at Request Time)
A standard Server API Token lets you include a user context with each individual API request. This is useful when the calling application can dynamically determine which user to impersonate at call time.
With this approach, the token itself is not scoped to a user. Instead, you specify the user when making each call. This gives you flexibility, but it also means the GenAI tool or integration layer must supply the correct user context with every request.
This approach is suitable when:
- Your integration layer should have the ability to make calls as any user, including an admin user
- You want a single token that can act on behalf of multiple different users
- You are building a tightly controlled integration where you manage the user context programmatically
You can follow this doc to generate a Server API Token.
Option 2: Long-term JSON Web Token (Recommended for GenAI Integrations)
When configuring a GenAI tool to access Expert content, you are typically setting up a durable connection rather than a per-request call. In many GenAI platforms, API credentials are provided once during setup and cannot be changed dynamically at runtime. This means you must decide upfront which user's permissions the integration should operate under.
A Long-term JSON Web Token (JWT), also referred to as an OAuth bearer token, solves this problem by binding the user context directly into the token at generation time. The resulting token will always operate with the permissions of the specified user, regardless of how or where it is used.
This is strongly recommended for GenAI integrations because:
- Permissions are locked to a specific user at token creation time, giving you predictable, auditable access control.
- The GenAI tool receives a single bearer token it can use directly, without needing to manage user identity logic.
- You can create a dedicated read-only service account user in Expert and scope the token to that user, ensuring the GenAI tool cannot access content beyond what that user is permitted to see.
- The token has a 10-year expiration, making it suitable for long-lived integrations.
You can follow this doc to generate a Long-term JSON Web Token.
User Permissions and Content Access
Because Expert is permission-based, the content returned by every API call is governed by the user associated with the token. Only pages that the specified user is permitted to view will be returned. This means:
- If the user only has access to public content, private or restricted pages will not appear in API responses.
- If you want the GenAI tool to see all content, use an Admin or high-privilege user as the token's associated user.
- If you want the GenAI tool to see only what end users see, use a standard member account.
It is a best practice to create a dedicated service account user in Expert for your GenAI integration. This makes it easy to audit API activity and adjust permissions independently of any real user's account.
API Reference
The following endpoints are the primary methods for retrieving content from Expert for use in a GenAI integration. The full list of available API endpoints can be found here
All endpoints require authentication via the Authorization header as described in the previous section. You can find specific code examples on how to do this in this doc.
Page Retreival
Expert does not have an endpoint that gets all site content at once, including page content data. Instead, you will need to first retreive the page ID's you plan on ingesting, then call a separate endpoint to retreive the page content/file data.
Pages Endpoint
This endpoint retreives all pages on your site and returns them in a hierarchal structure including Page ID's. Page ID's can be used in subsequent endpoints found below to retreive the relevant content.
Search Endpoint
This endpoint allows you to input a query to find matching articles. The important part is using parameters to find articles that match specific use cases on the site. The search endpoint also returns pages with their Page ID's to be used in subsequent endpoints.
- The "pathancestors" parameter can be used to find articles under a specific section of your site
- The "tags" parameter allows you to find articles with a specific tag/classification
Content Retreival
Once you have the list of articles that you need, you can use the following endpoints to get the content from those articles:
Pages Endpoint
GET /@api/deki/pages/{pageid}/contents
This endpoint returns the HTML contents of a single page given a Page ID
Files Endpoint
GET /@api/deki/pages/{pageid}/files
This endpoint returns any files that are attached to a page given a Page ID
Recommended Integration Workflow
The following workflow describes a typical approach for ingesting Expert content into a GenAI tool's knowledge base. Adjust it based on the specific requirements and capabilities of the GenAI platform you are integrating with.
- Create a service account
- Create a dedicated user in Expert to represent the GenAI integration. Set appropriate permissions to scope what content the tool can access.
- Generate a Long-term JWT
- Create a Server API token with a Long-term JWT scoped to the service account.
- Discover relevant pages
- Use GET /pages (for full sitemap) or GET /site/query (to filter by category or tag) to identify the pages you want to ingest.
- Retrieve page content
- For each relevant page ID, call GET /pages/{pageid}/contents to retrieve the HTML content.
- Retrieve page files
- Optionally call GET /pages/{pageid}/files for pages that may have important document attachments. Download and process file content as needed.
- Pass content to GenAI tool
- Provide the retrieved content to your GenAI platform's knowledge base, document store, or context window, per that platform's integration method.
- Refresh periodically
- Expert content changes over time. Implement a refresh schedule (we recommend a daily frequency) to re-fetch updated page content and keep the GenAI tool's knowledge current.