Skip to main content
Custom Knowledge Base Connectors let you integrate into any knowledge base using API Connections. By using API Connections, we can crawl any knowledge base that exposes an API, which most knowledge management systems (KMSs) do. To use a Custom KB Connector, you implement an API Connection that fetches articles from your knowledge base; ASAPP then crawls that connection on a schedule, ingesting the articles into the Knowledge Base for GenerativeAgent to use when answering user questions.
We provide example implementations for popular KB platforms such as Salesforce; reach out to your ASAPP team for access.

​
How it works

When the system crawls your Custom KB Connector, it runs your API Connection repeatedly until all articles are fetched:
  1. First call — The connection is invoked with empty or undefined paginationParams.
  2. Your response — You return a batch of articles and, if there are more, a nextParams object (e.g., page number, cursor, or offset).
  3. Next call — The system invokes your connection again, passing that nextParams as paginationParams.
  4. Repeat — Steps 2–3 continue until you return that there are no further pages.
  5. Ingestion — All articles from every call are collected and submitted into the Knowledge Base for review and deployment.
The shape of paginationParams and nextParams is up to you; the system passes them through so you can support any pagination style your KB API uses.
Articles from Custom KB Connectors go through the same review and deployment process as other imported content. You can enable auto-deploy on the connector if you want updates to go live without manual review.

​
Before you begin

  • Get your API Key and Secret, with access to GenerativeAgent and Knowledge Base as needed.
  • Your knowledge base must have a publically accessible API that supports listing/fetching articles in a way that can be adapted to pagination (e.g., by page, cursor, or offset).

​
Step 1: Create an API connection for the Knowledge Base

Create an API Connection that fetches articles from your knowledge base. The connection must implement the Knowledge Base Connector request/response interface so the system can crawl all articles and handle pagination.
1

Create or edit an API Connection

In API Integration Hub → API Connections, create a new connection or open an existing one to edit. You will implement the KB Connector interface in this connection.
2

Implement the connector interface

Implement the request/response contract below. Your logic (JSONata or code) should call your knowledge base API and map its data into the required response shape. The implementation must conform to this contract:
Request: The connection receives a single argument with this shape:
{
  "type": "object",
  "properties": {
    "paginationParams": {
      "type": "object",
      "description": "Pagination parameters passed on each request.",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
On the first execution, paginationParams is undefined or {}. On each subsequent call, it contains the nextParams you returned in the previous response.
Response: Return an object with this shape:
{
  "type": "object",
  "properties": {
    "articles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "The proposed title of the article. Required.",
            "minLength": 1,
            "maxLength": 256
          },
          "content": {
            "type": "string",
            "description": "The article content in plain text. Required.",
            "minLength": 1,
            "maxLength": 200000
          },
          "url": {
            "type": "string",
            "description": "Required. The canonical URL for the article. Used as the identifier during crawling so the system can update a previously uploaded article and avoid duplication."
          },
          "metadata": {
            "type": "array",
            "description": "Additional key-value pairs related to the article (optional).",
            "items": {
              "type": "object",
              "required": ["key", "value"],
              "properties": {
                "key": { "type": "string", "minLength": 1 },
                "value": { "type": "string", "minLength": 1 }
              }
            }
          },
          "queryExamples": {
            "type": "array",
            "description": "Examples of customer questions related to the article (optional).",
            "items": { "type": "string" }
          }
        },
        "required": ["title", "content", "url"],
        "additionalProperties": false
      }
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextParams": {
      "type": "object",
      "description": "Parameters to use as paginationParams on the next call (if hasMore true).",
      "additionalProperties": true
    }
  },
  "required": ["articles", "hasMore"],
  "additionalProperties": false
}
Each article must include a url. This URL is the identifier for that article during crawling: the system uses it to recognize when an article was already ingested, so it can update the existing one instead of creating a duplicate.When hasMore is true, you must provide nextParams with whatever your API needs for the next page (e.g., { page: 2 } or { cursor: "abc123" }). When hasMore is false, the crawl stops. Save and test the API Connection before moving to Step 2.The system submits these articles to the Knowledge Base; they will go through the normal review and approval flow unless the connector is set to auto-deploy.
The system executes your API Connection in a loop:
  1. First call: paginationParams is empty or undefined.
  2. Your connection returns articles, hasMore, and nextParams.
  3. If hasMore is true, the system calls again with paginationParams set to your nextParams, and repeats until hasMore is false.
  4. All collected articles are submitted to the Knowledge Base and follow the standard import and review process.
After the API Connection is created and implements the KB Connector interface, go to the Knowledge Bases page to add the Custom connector.

​
Step 2: Add the Custom connector

Configure the Custom Knowledge Base Connector so GenerativeAgent knows which API Connection to use and how often to crawl it.
1

Open Add Source on the Knowledge Bases page

  1. Navigate to GenerativeAgent → Knowledge in the ASAPP dashboard.
  2. Click Add content (or the equivalent control to add a source).
  3. From the Add Source dropdown, select Custom Knowledge Base Connector.
2

Fill in the connector form

In the Custom Knowledge Base Connector form, provide:
  • Name (required): A name for this connector (e.g., “Internal Wiki KB”).
  • Description (optional): Short description of the source.
  • API Connection (required): Select the API Connection you created in Step 1. Only connections that implement the KB Connector interface are eligible. The form validates that the selected connection conforms to the required interface.
  • Crawling settings: Use the same crawling and deployment options as other Knowledge Base sources (e.g., sync frequency, whether updates require review or auto-deploy).
3

Save the connector

Save the Custom Knowledge Base Connector. It will appear as a content source on the Knowledge Bases page. The system will use your crawling settings to determine when to run the next sync.

​
Step 3: Crawl and use the connector

Once the Custom connector is saved, the system crawls it according to your crawling settings. All articles are fetched and appear in the Knowledge Base like any other content source—you can view, review, and manage them as described in Connecting your Knowledge Base. After articles are published and deployed, GenerativeAgent uses the new content when answering questions, the same way it uses other Knowledge Base sources.

​
Viewing and managing articles

Articles imported from a Custom Knowledge Base Connector are shown in the Knowledge Base UI with the connector indicated as the content source. You get the same article-level controls as for other sources: edit metadata, set refresh frequency, search, and filter. Content source and deployment status are visible so you can confirm which articles came from your custom connector.

​
Debugging your connector

All executions of your API Connection for the Knowledge Base are recorded in the API log. In the log view. You can inspect request/response data, execution time, and errors. Use this to troubleshoot pagination, authentication, or response shape issues.

​
Next steps

Connecting your Knowledge Base

Overview of importing, syncing, and deploying your Knowledge Base

Connect Your APIs

Create and manage API Connections

Add via API

Submit individual articles via the Knowledge Base API

Knowledge Base API Reference

Submission API and article format reference