Ingestion APIs

Overview

Ingestion APIs enable external systems to push payloads of different types to your Aisera applications. The payloads for the following Entities vary by the endpoints that are registered to the external systems:

• Alerts

• Changes

• Incidents

• Knowledge Articles

• Problems

• Requests

• Request Items

• Conversations

Look up each of these Entities in the API Reference section of this chapter for examples of how to use each Entity call.

Prerequisites

Follow the steps in the Integrations and Data Sources section to setup connections for your Aisera application.

Setup

External System

Webhook (also known as callback) should be configured on external system to send data to the ingestion APIs. Follow the relevant system guides. The following should be included in the requests:

1. Endpoint URL: depending on the data being ingested, the corresponding endpoint should be used:

• https://<tenant>.api.aisera.cloud/alerts

• https://<tenant>.api.aisera.cloud/changes

• https://<tenant>.api.aisera.cloud/incidents

• https://<tenant>.api.aisera.cloud/knowledge-articles

• https://<tenant>.api.aisera.cloud/problems

• https://<tenant>.api.aisera.cloud/requests

• https://<tenant>.api.aisera.cloud/requestitems

• https://<tenant>.api.aisera.cloud/conversations

1. App Token (x-app-token) should be added to the header (see the Auth section)

2. Bearer access token (Authorization) should be added to the header the authorization header (see the Auth section)

Add the custom header parameters as query parameters if the former is unsupported by external systems. However, the following endpoints only support x-app-token as a query parameter:

• /incidents

• /requests

• /requestitems

Auth

App token and access (bearer) token are required to send data to the endpoints.

App token is available on the App details page:

1. Login to your Aisera management portal (<tenant>.login.aisera.cloud)

2. Navigate to Settings > AiseraGPT

3. Choose the app of interest to open its details page

4. Add a data source as the System of Record (SOR)

5. The App Token will then be available here

The bearer access token can be generated and added to the header:

1. Create a service account on your tenant with the necessary permissions:

   1. Navigate to Settings > User Accounts

   2. Click on + New User

   3. Create the new account with the Login Role of Service Account

2. POST a request to the following URL: https://<tenant>.api.aisera.cloud/tenant-users/oauth2/token

3. Include the following parameters in the body...

   1. "grant_type": "password"

   2. "client_id": App Token available on the details page of the channel

   3. "username": username of the service account

   4. "password": password of the service account

Use the Postman collection to generate your token using the above steps.

The bearer access token generated using the method above expires in an hour. External system support for OAuth2 is recommended.

Use

Depending on the data being ingested, the corresponding APIs should be used:

• https://<tenant>.api.aisera.cloud/alerts

• https://<tenant>.api.aisera.cloud/changes

• https://<tenant>.api.aisera.cloud/incidents

• https://<tenant>.api.aisera.cloud/knowledge-articles

• https://<tenant>.api.aisera.cloud/problems

• https://<tenant>.api.aisera.cloud/requests

• https://<tenant>.api.aisera.cloud/requestitems

• https://<tenant>.api.aisera.cloud/conversations

Examples of these APIs are available in the Postman collection.

Handling Errors

Aisera uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user.

Restrictions

• Rate Limits: Aisera does not enforce any hard rate limits on the endpoints. However, we recommend restricting to 5 calls, per endpoint, per minute.

• Payload Size: Aisera does not enforce any hard limits on the size of the payload. However, we recommend restricting the payload to a maximum of 50 records and 1 MB of content.

Postman Collection

16KB

Aisera Ingestion APIs.postman_collection.json

Open

Changelogs

Review the Product Release Notes.

The payloads vary by the endpoints that are registered to the external systems: