moinAI Technical Documentation

# 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

# 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"
            }
        ]
    }
}

# 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 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

← Knowledge Base Search API →