Quickstart for eGain API

Get up and running with eGain's AI Knowledge Hub APIs in just a few steps. This guide walks you through setting up your account, ingesting content, and building your first application with eGain's powerful knowledge management capabilities.

Step 1: Set Up Your eGain Account

New to eGain?

If you don't have an existing eGain account, you can get started with a free trial of eGain's AI Knowledge Hub:

👉 Start your free trial here

The free trial gives you access to:

Full AI Knowledge Hub capabilities
Content ingestion and management
Search and retrieval APIs
Portal customization tools

Existing Users

If you already have an eGain account, sign in with your current account to proceed to the next step.

Step 2: Ingest Your Content

The next step is to ingest your content into the eGain AI Knowledge Hub. There are two primary methods to accomplish this, each catering to different technical needs and data sources.

Prerequisites

A valid OAuth 2.0 access bearer token with the knowledge.contentmgr.manage scope from your eGain environment. You must first set up a client application and acquire an access token. Our API Authentication Guide provides detailed instructions on how to Step 1: Create a Client Application and Step 2: Find Your API Endpoints (Metadata). You will then use the Client Credentials Flow from Step 3 to obtain the necessary Bearer token for authentication.
Access credentials and connection details for your data source (for example, S3 path and credentials or SFTP server details).

cURL Command (Get Access Token)

Copy

Copied

curl -v --location 'https://<API_DOMAIN>/system/auth/<TENANT_ID>-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=app.knowledge.contentmgr.manage'

Method 1: Use our External Connector Ingestion API

This method uses a dedicated connector for data sources such as SharePoint, which serves as a specialized wrapper for our general Ingestion API (detailed in Method 2). It simplifies the process by pre-configuring the data source type and requiring only data source specific details for authentication and location without the need to format your data beforehand.

Currently we only support Sharepoint as a data source connector.

https://napsapps.egain.services/tenant/external/ingestion

Copy

Copied

{
    "languages": [{
        "default": true,
        "languageCode": "en-us"
    }],
    "dataSource": "Sharepoint",
    "sourceConfig": {
        "site": "<YOUR_SHAREPOINT_SITE>",
        "host": "<YOUR_SHAREPOINT_HOST>",
        "tenantId": "<YOUR_TENANT_ID>",
        "clientid": "<YOUR_CLIENT_ID>",
        "clientSecret": "<YOUR_CLIENT_SECRET>"
    }
}

cURL Command (SharePoint)

The following cURL command demonstrates how to start an ingestion job from a SharePoint source. Specifically this will use our publish SharePoint source where we will have sample content ready to be ingested into an eGain instance. Ensure you replace all placeholder values with your actual sharepoint instance information when ingesting your own SharePoint data.

Copy

Copied

curl -v --location 'https://napsapps.egain.services/tenant/external/ingestion' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--data '{
    "languages": [
        {
            "default": true,
            "languageCode": "en-us"
        }
    ],
    "dataSource": "Sharepoint",
    "sourceConfig": {
        "site": "EightBankKnowledgePortal",
        "host": "eightbank.sharepoint.com",
        "tenantId": "1442c167-8146-4361-b462-b6fb26a6cf75",
        "clientId": "ce05764b-bcec-4c17-b538-76f4db921dff",
        "clientSecret": "g5W8Q~DJVFpHDJdNn2-jFg6TjSvlACPYvk8MHaEH"
    }
}'

Method 2: Using the Ingestion API with Your Own Data Source

This method provides maximum flexibility and is ideal for automation and integration with your existing infrastructure. The Ingestion API allows you to pull content from a data source that you own and manage, such as an AWS S3 bucket or a secure SFTP server. To enable access to your content, you must provide the API with the correct path and any required credentials.

Sample Data

You may use our Sample Data Source, which is already formatted, or you may use your own content to be ingested. The sample is only available as a .zip file, which you must download and upload to your own data source location. The API does not accept a .zip file path; it requires the full extracted file structure.

Prerequisites

Before using the Ingestion API, ensure the following requirements are met:

Content is correctly formatted into the required file structure. For more details, see the Data Import Format Guide .

Important Note: It is highly recommended to validate your content before importing using the Validation API. This serves as a “dry run” that checks the entire content package for formatting issues, incorrect paths, and other potential errors without actually importing any data. Performing this step can save significant time and help prevent failed jobs.

To know more, see: Guide: Validating Content Before Import

API Endpoint

To start an ingestion job, make a POST request to the following endpoint:

https://${API_DOMAIN}/knowledge/contentmgr/v4/import/content

Example Request (AWS S3)

The request body must be a JSON object specifying your data source details, the operation, and an optional schedule.

Copy

Copied

{
  "dataSource": {
    "type": "AWS S3 bucket",
    "path": "s3://your-company-bucket/path/to/content",
    "region": "us-east-1",
    "credentials": {
      "accessKeyId": "YOUR_AWS_ACCESS_KEY_ID",
      "secretAccessKey": "YOUR_AWS_SECRET_ACCESS_KEY"
    }
  },
  "operation": "import",
  "scheduleTime": {
    "date": "2024-03-01T10:00:00.000Z"
  }
}

cURL Command (AWS S3)

Copy

Copied

curl -v --location --request POST 'https://<API_DOMAIN>/knowledge/contentmgr/v4/import/content' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "dataSource": {
        "type": "AWS S3 bucket",
        "path": "s3://your-bucket-name/your-folder/content",
        "region": "your-aws-region",
        "credentials": {
            "accessKeyId": "YOUR_AWS_ACCESS_KEY_ID",
            "secretAccessKey": "YOUR_AWS_SECRET_ACCESS_KEY"
        }
    },
    "operation": "import"
}'

(For details on using a Shared File Path, see our Shared Path Ingestion Guide.)

Successful Response (for API Methods 1 & 2)

A successful API request queues the job and returns a 202 Accepted status code. The Location header in the response contains the URL used to check the status of the import job.

Example Response Header: location: /knowledge/contentmgr/v4/import/content/7A84B875-6F75-4C7B-B137-0632B62DB0BD

After the import job has completed successfully, the content becomes available in eGain.

Step 3: View Your Imported Content in the Knowledge Console

Once your content import is complete, you can access and manage your imported content within the Knowledge Console.

Access Your Imported Content

Log in to your AI Knowledge Hub instance using your credentials.
In the Knowledge Console, navigate to Articles > Folders > Mirrored Content > SharePoint .
The folder structure is automatically imported and organized to match your SharePoint hierarchy.
Browse through the folders to view your articles.

Manage Your Imported Content

In the Knowledge Console, you can perform the following actions to manage your articles:

Manage : Edit, update, or organize your knowledge articles.
Search : Use the built-in global search functionality to find specific articles.
Browse : Access automatically generated topics created through Topics from Folders. All mirrored articles are organized under these topics and displayed in 'Portal Zero' by default. You can also create a new portal and include selected topics from folders to view your content in a customized way.
Preview : While editing an article, use the 'Preview in Portal' option to see how the content appears within a selected portal before publishing.

Customize Your Portal with Theme Studio

Personalize your knowledge portal to reflect your brand identity:

Log in to your eGain AI Knowledge Hub instance as a Knowledge Manager.
In the Knowledge Console, navigate to Publishing > Themes .
Under the Default Themes section, click the Customize button to create a new theme.
In the theme workspace, you can select the portal you want to modify and select the target audience.
Use the Global and Page settings to customize colors, fonts, page layouts, and upload your logo or other brand assets to align with your brand guidelines.
Preview your updates in real time as you make changes.
Once satisfied, publish the theme to apply it to your portal and make it live for your users.

Portal Features

The knowledge portal provides the following features to help you consume and manage your knowledge more efficiently:

Responsive Design: Optimized for both desktop and mobile devices.
Advanced Search: Powerful search capabilities to quickly find relevant content.
Content Organization: Supports categorization and tagging for easier navigation.
Multi-Language Support: Provides content in multiple languages to serve diverse user bases.

Step 4: Use Answers, Retrieve and Search APIs

Along with accessing your newly imported content in the Knowledge Console, you can now also integrate with our AIS and Portal Manager APIs to power intelligent search and retrieval experiences.

Answers API – Retrieves the most relevant content for a given user query and provides curated content chunks to the LLM to generate a natural language answer.
Retrieve API – Returns content chunks directly related to a given user query. Ideal for building custom LLM integrations where you want full control over how answers are generated.
Search API – Delivers ranked and relevant search results from your knowledge base, helping users quickly find the information they need.

Below are example CURL requests that demonstrate how to use these APIs in action:

Answers API CURL Command

Copy

Copied

curl -i -X POST  'https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/answers?q=How%20do%20credit%20cards%20work%3F&%24lang=<YOUR_LANGUAGE_CODE>' \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <YOUR_ACCESS_TOKEN>" \
   -d \
'' \

This request retrieves a generated answer for the query “How do credit cards work?”, using the Answers API, which combines retrieval and LLM generation to return a concise, contextually relevant response.

Retrieve API CURL Command

Copy

Copied

curl -i -X POST  'https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/retrieve?q=How%20do%20credit%20cards%20work%3F&%24lang=<YOUR_LANGUAGE_CODE>' \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <YOUR_ACCESS_TOKEN>" \
   -d \
'' \

This request retrieves the relevant content chunks for the query “How do credit cards work?”, allowing you to build your own LLM-based answer generation or content analysis workflow.

Search API Curl Command

Copy

Copied

curl -i -X POST  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search?q=How%20do%20credit%20cards%20work%3F&%24lang=<YOUR_LANGUAGE_CODE>' \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <YOUR_ACCESS_TOKEN>" \
   -d \
'' \

This request retrieves ranked search results from your knowledge base for the query “How do credit cards work?”, providing metadata and relevance scores.

Next steps

Now that your content is ingested and accessible, you are ready to build powerful applications leveraging eGain's Search, Retrieve, and Answer APIs. These APIs enable you to deliver intelligent search experiences and generate AI-powered answers for your users.

Review the Authentication Guide to learn how to securely connect to the eGain APIs using OAuth 2.0 and manage access tokens.
Explore the Guides , SDKs , APIs for detailed documentation.
Try out our Reference Implementations on GitHub.
Reach out to us and your felow developers on Developer Community