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", // 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

  • 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.
  • 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

# 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": {
            "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.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 →