Developers

Editor API Setup

Introduction

The purpose of the Knowledge Editor API is to give users access to create, edit and retrieve anything from the Knowledge Base of the Inbenta Knowledge instance.

This page describes how to set up the Knowledge Editor API.

Obtain API credentials

 
Important

Please read this page carefully and make sure that you have all your credentials and necessary assets available before you start. If you need help, contact Inbenta.

All requests to Knowledge Editor API endpoints will be authenticated and authorized. In order to access it you need several keys.

API key and secret

To obtain your Editor API key and secret, open your Inbenta Knowledge instance and go to the Administration tab. Look for the "Knowledge Editor API" section:

 
Note

If you do not see this tab, you do not have the necessary permissions to access it. Contact your administrator if you need access to this section.

The Knowledge Editor API section contains two subsections: Production and Development. Each section provides the keys and instructions to implement the API in the corresponding environment.

 
Note

The "Development" API credentials are intended for use only during development. They behave exactly the same as "Production" credentials but have considerably lower rate limits. Do not use these credentials in Production environments.

There you can get the API key and secret.

  • The API Key will grant you access to the APIs.
  • The Secret allows the request to access your instance's data.
 
Note

For a complete description of keys and authorization methods, see the Authorization section.

 
Caution

Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations. For more information, see the Authorization page.

User personal secret token

In addition to the API key and secret, you need to identify yourself in the API. To do so, you need a user personal secret token.

  • The Personal Secret identifies the user doing the action.

To obtain your User Personal Secret token, see Generating and managing personal API secrets (This links redirects you to the Help Center).

 
Note

For a complete description of User Personal Secret tokens and authorization methods, see Using UPS Tokens.

API setup

Obtain and use the access token

You need a valid access token to use the Knowledge Editor API. Follow the steps listed in the Authorization section to set up your page with your token. 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 Editor 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, for example:

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

Do not perform this request after each API call! You would quickly exceed your rate limits.

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}.

Example:

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

  • Knowledge Editor: "https://endpoint.inbenta.example/km-editor/v1"

Use the API

Authorization

 
Note

For a complete description of keys and authorization methods, see the Authorization section.

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

 
Caution

Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations.

Retrieve information

Now you can create or retrieve information from the Knowledge Base.

Example: How to create a content

To create a content use the POST /contents endpoint. This endpoint requires:

  1. the API Key,
  2. an access token, and
  3. the data for the content that you want to create.

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

 
Notes

• All payload request have a limit of 1MB.

• When the response to a request exceeds 10MB, the API returns a 413 error (entity too large). If this happens, paginate the requested collection to obtain smaller pieces of information per request.