# Ingestion APIs

## Overview

Ingestion APIs let external systems push data into your Aisera applications via webhook. When a webhook fires, Aisera receives the payload, maps it to its internal schema using the field mappings configured on your data source, and makes it available for AI workflows and search.

The following endpoints are available:

* [Alerts](https://docs.aisera.com/apis/apis/ingestion-apis/alerts)
* [Changes](https://docs.aisera.com/apis/apis/ingestion-apis/changes)
* [Incidents](https://docs.aisera.com/apis/apis/ingestion-apis/incidents)
* [Knowledge Articles](https://docs.aisera.com/apis/apis/ingestion-apis/knowledge-articles)
* [Problems](https://docs.aisera.com/apis/apis/ingestion-apis/problems)
* [Requests](https://docs.aisera.com/apis/apis/ingestion-apis/requests)
* [Request Items](https://docs.aisera.com/apis/apis/ingestion-apis/request-items)
* [Conversations](https://docs.aisera.com/apis/apis/ingestion-apis/conversations)

## Setup

### Prerequisites

Before configuring a webhook, ensure the following are in place in your Aisera Admin UI:

* An Aisera application [has been created](https://app.gitbook.com/s/ksUDWGr9UTfOpa53PosP/how-to-set-up-an-aiseragpt-bot).
* A data source has been configured as the System of Record (SOR) for the app, with field mappings that match your external system's payload structure.
* A service account has been created on your tenant. See Bearer access token for steps.

### Configure your external system

Configure a webhook on your external system to send data to the Aisera endpoint for the type of data you are ingesting. See the relevant endpoint page for its URL. Every request must include an app token and a bearer access token. See [Authentication](#auth) for how to obtain both.

{% hint style="info" %}
If your external system does not support custom request headers, you can pass the tokens as query parameters instead. The supported query parameters differ by endpoint:

For `/alerts`, `/changes`, `/conversations`, and `/knowledge-articles`:

* `key`: bearer access token (URL-encoded)
* `apptoken`: app token (URL-encoded)

For `/incidents`, `/requests`, and `/requestitems`:

* `at`: app token (URL-encoded)

The bearer access token cannot be passed as a query parameter for `/incidents`, `/requests`, or `/requestitems`.
{% endhint %}

### Authentication

Every request to an Ingestion API endpoint requires two tokens.

#### App token

The app token identifies the Aisera app and data source receiving the data. To retrieve it:

1. Create a data source in your Aisera application.
2. Navigate to **Settings > AiseraGPT** and select your application.
3. On the **AiseraGPT Details** page, scroll to **Data Sources** and toggle the **System of Record** switch for your data source. If you have not added the data source yet, add it first, or select a pre-existing one.
4. The app token appears under **Integration Information**.

Pass the app token in the `x-app-token` request header.

#### Bearer access token

The bearer access token authenticates the request. To generate it:

1. Navigate to **Settings > User Accounts**
2. Click **+ New User**
3. Create the new account with the **Login Role** of **Service Account**
4. POST a request to `https://<tenant>.api.aisera.cloud/tenant-users/oauth2/token` with the following body parameters:<br>

   ```json
   {
     "grant_type": "password",
     "client_id": "<your app token>",
     "username": "<service account username>",
     "password": "<service account password>"
   }
   ```

The endpoint returns the following response:

```json
{
    "access_token": "",
    "refresh_token": "",
    "token_type": "bearer",
    "expires_in": 3600
}
```

Pass the bearer access token in the `Authorization` request header.

{% hint style="warning" %}
The bearer access token expires after one hour. External system support for OAuth2 is recommended.
{% endhint %}

## Handling Errors

Aisera uses standard HTTP response codes to indicate whether a method completed successfully. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a request error. Codes in the 5xx range indicate an internal system error that cannot be resolved by the user.

## Restrictions

Aisera does not enforce hard rate limits, but we recommend no more than 5 calls per endpoint per minute. Aisera also does not enforce hard payload size limits, but we recommend a maximum of 50 records and 1 MB per request.

## Postman Collection

See the Postman collection for examples of endpoint usage and token generation.

{% file src="<https://2703380601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk4yi9BewsGoT4eKpZoaG%2Fuploads%2FTa9aiEYf2waHy8qSD0H7%2FAisera%20Ingestion%20APIs.postman_collection.json?alt=media&token=2a5356d6-3bef-40ca-9b34-a9dbb3cb269d>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aisera.com/apis/apis/ingestion-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.