# External Knowledge API

# Overview

This API provides endpoints for managing articles, allowing users to create, retrieve, update, and delete articles. The API supports various operations with built-in validation and authentication. The other types of knowledge like webpages or PDF documents are neither touched nor retrievable by the below described endpoints.

# Authentication

All endpoints require API key authentication, ask your Customer Success Manager or techical support at moinAI for the key.

Example `cURL' call:

curl -L -X DELETE 'https://api.moin.ai/api/v1/knowledge/67d9a6e63f12004d3b14f4da' -H 'x-api-key: YOUR_API_KEY'

Beware: If your company owns more than one chatbot from moinAI, then each of the bots has a single dedicated API key that identifies the bot where the knowledge should be added.

# Endpoints

# 1. Create a New Article

Method: POST
Endpoint: https://api.moin.ai/api/v1/knowledge
Description: Add a new article to the system
Rate-Limit 15000 chars per minute. Will throw 429 after that.

# Request Body

{
  "title": "Article Title",  // Required, min 3 characters
  "body": "Article Content as markdown", // Required, min 1 character
  "metadata": {              // Optional
    "category": "Technology",
    "author": "John Doe"
  },
  "activeOn": [              // Optional
    {
      "agent": "faq_some_agent",
      "channel": "customer_service"
    }
  ],
  "strict": false
}

Some further explanation

body The body should be a valid markdown document. Basic Markdown such as titles and headers, links and tables are supported, i.e. if the document contains such a structure the generated answers based on these documents can make use of them.
metadata The metadata field can be used freely to enrich the article information. The properties of the metadata need to have a flat structure, i.e. only numbers, strings or boolean values are allowed. Metadata can be used, for example, to store an ID or a version date for comparison with the original system. They can also be used to filter when retrieving the articles.
activeOn The activeOn field is used to control the agents where the article can be used for answer generation. The channel and the agent ids can be found in the hub.
strict The strict field controls whether the article can only be added to active agents and channels

Some examples for different useCases: A product brochure with product id

{
  "title": "The turbo broom 2000",  
  "body": "# The turbo broom 2000\n ##Installation instructions \n ...", 
  "metadata": {              
    "category": "Product brochures",
    "author": "John Doe",
    "productId": "tb2000"
  },
  "activeOn": [
    {
      "agent": "faq_produktinfo",
      "channel": "customer_service"
    }
  ],
  "strict": false
}

A taxonomy on the articles for better oranisation of the articles or to match some internal structure

{
  "title": "FAQ - Account Data - Reset",
  "body": "# FAQ - Account Data - Reset\n In order to reset your account data, you need to ...",
  "metadata": {              
    "category": "FAQ",
    "subCategory": "Account Data",
    "topic": "Reset",
    "author": "John Doe"
  },
  "activeOn": [              
    {
      "agent": "faq_faq",
      "channel": "customer_service"
    }
  ],
  "strict": false
}

# Response

Success (200):
- Returns article details including ID, creation timestamp
- Includes characterUsed metric

Example success response:

{
    "success": true,
    "message": "Content addition initiated.",
    "data": {
        "id": "67d9a6e63f12004d3b14f4da",
        "status": "uploading",
        "title": "Olivenöl ist lecker",
        "body": "# Olivenöl ist lecker\n Besonders frisches Olivenöl ist lecker. Und gesund.",
        "metadata": {
            "tag": "essen",
            "version": 1
        },
        "activeOn": [
            {
                "agent": "faq_ern_hrung",
                "channel": "null"
            },
            {
                "agent": "faq_oliven_l",
                "channel": "null"
            }
        ],
        "createdAt": "2025-03-18T17:01:26.035Z",
        "updatedAt": "2025-03-18T17:01:26.035Z",
        "characterCount": 74
    },
    "characterUsed": 4783727
}

Error (400): Invalid input

Example error response:

{
    "message": "Validation error!",
    "code": 1001,
    "status": 400,
    "data": {
        "result": [
            {
                "message": "Metadata key 'tags' must have one of following types: string, number, boolean.",
                "field": "metadata",
                "type": "metadataField"
            }
        ]
    }
}

Error (422): Unprocessable entity due to Maximum Characters Quota reached Each customer has a specific quota on the amount of characters that all the articles in their library contain in sum. If an article would be attempted to be added that would result in breached quota, an error with status code 422 will be issued.

Example error response:

{
    "success": false,
    "error": {
        "message": "Max Library Characters Quota reached. Details: Exceeding the limit on '2000' characters, current character used: '99000', total limit is: '100000'.",
        "code": 30001,
        "status": 422
    }
}

Error (429): Too many requests - character rate limit exceeded There is a rate limit on adding articles based on the amount of characters (in sum) added per minute. If the the limit is exceeded the following kind of response will be returned with status code 429:

Character rate limit exceeded. Please try again later.

# 2. Retrieve Articles

Method: GET
Endpoint: https://api.moin.ai/api/v1/knowledge
Description: Fetch articles with optional filtering

# Query Parameters

id: Filter by specific article ID
title: Filter by article title

# Response

Success (200):
- Returns array of matching articles
- Each article includes full details

Example response:

{
    "success": true,
    "data": [
        {
            "id": "67d9a6e63f12004d3b14f4da",
            "status": "active",
            "title": "Olivenöl ist lecker",
            "body": "# Olivenöl ist lecker\n Besonders frisches Olivenöl ist lecker. Und gesund.",
            "metadata": {
                "tags": "essen, trinken, slow-food",
                "version": 1
            },
            "activeOn": [
                {
                    "agent": "faq_test_rag_thema",
                    "channel": "null"
                },
                {
                    "agent": "faq_oliven_l",
                    "channel": "null"
                }
            ],
            "createdAt": "2025-03-18T17:01:26.035Z",
            "updatedAt": "2025-03-18T17:01:26.076Z",
            "characterCount": 74
        }
    ]
}

Error (400): Invalid query parameters

# 3. Update an Article

Method: PUT
Endpoint: https://api.moin.ai/api/v1/knowledge/:id
Description: Update an existing article by its ID

# Request Body

Similar to create article, but all fields are optional

Can update title, body, metadata, active channels

{
  "title": "Article Title",  // Optional, min 3 characters
  "body": "Article Content", // Optional, min 1 character
  "metadata": {              // Optional
    "category": "Technology",
    "author": "John Doe"
  },
  "activeOn": [              // Optional
    {
      "agent": "support_bot",
      "channel": "customer_service"
    }
  ]
}

# Response

Success (200):
- Returns updated article details
- Includes characterUsed metric
Error (400): Invalid input
Error (404): Article not found
Error (422): Unprocessable entity due to Maximum Characters Quota reached
Error (429): Too many requests - character rate limit exceeded Responses are similar to the 'Add Article' endpoint

# 4. Delete an Article

Method: DELETE
Endpoint: https://api.moin.ai/api/v1/knowledge/:id
Description: Remove an article from the system

# Response

Success (200):
- Confirmation message

Example response:

{
    "success": true,
    "message": "Article with ID '67d9a6e63f12004d3b14f4da' was successfully deleted."
}

Error (404): Article not found

← MoinAI API: REST based interaction with your chatbot and its Knowledge Base Knowledge Base Search API →