Introduction

The purpose of the Knowledge API is to grant access to the contents stored in your Inbenta Knowledge instance. You can then use these contents in any user-generated application and track event data for usage analysis. You can find these reports in the instance's Dashboard.

This page describes how to set up the Knowledge API, and how to request and retrieve information.

Obtain Authentication and Authorization Keys

All requests to the Knowledge API endpoints must be authenticated and authorized.
To obtain your credentials, see Finding your API credentials in the Help Center.

• The API Key will grant you access to the APIs.
• The Secret allows the request to access your instance's data.
• The Domain Key allows the request to access your instance's data, but only for requests coming from the browser (front-end integrations) and from a limited set of domains.

Use the access token

You need a valid access token to use the Knowledge API. Follow the steps listed in the Authorization section to set up your page with your token and refresh it. Once you obtain the access token, you must append it to every request inside the Authorization header, with the format Bearer <your_access_token>.

Get the API URL

The base URLs of the Knowledge API are dependent on the instance, so that Inbenta can offer worldwide service and allow service auto-escalation. This base URL may change over time. Do not store or cache it persistently. Instead, get it every time you obtain a new valid access token.

To get the current API URL for your instance, get the apis parameter from the same response that gave you the access token. Extract the URL corresponding to the instance product:

{
    "accessToken": "******************",
    "expiration": 1573563837,
    "expires_in": 1200,
    "apis": {
        ...
        "knowledge": "https://endpoint.inbenta.example/km",
        ...
    }
}

Specify the version

Once you have the appropriate API URL for your implementation, you must specify the version of the API.

You specify the version at the end of the URL with v + {version}.

Examples:

The URLs for the current latest version of each Knowledge API look like this:

• Knowledge: "https://endpoint.inbenta.example/prod/km/v1"

Use the API

Authorization

You need a valid access token to use the Knowledge API. Follow the steps listed in the Authorization section to set up your page with your token and refresh it.

Start Session

Once authorized, start the session to relate all events performed by a user during their interaction with your platform. To start the session, you will need a session token that can be generated using the POST /tracking/session endpoint.

Retrieve information

Now you can retrieve information from the Knowledge Base.

Example: Obtain results from a user question using the POST /search endpoint. This allows you to make a search in the content database. This endpoint requires:

1. The API Key,
2. An access token, and
3. A query that searches the database.

For more information about POST /search and other endpoints, see the API routes section.

Track events

• For more information on what data Inbenta tracks and how, see the Tracking Events section.
• Inbenta provides tracking codes for every content shown. For specific information about what each API endpoint tracks by default, see the API Routes section.
• To improve the accuracy of your analytics, Inbenta recommends tracking as many event types as possible. To see these recommendations per endpoint, see the Knowledge Tracking Guidelines section.