Knowledge Base (New)

Create Knowledge Base

POST /api/knowledge-bases/

Request Body

Parameters

Field	Type	Required	Description
embeddingModel	string (uuid)	Yes
rerankerModel	string (uuid)	Yes
name	string	Yes
description	string	No
numberOfRetrievedChunks	integer	No	Number of retrieved reference chunks, default is 12, minimum is 1
sentenceWindowSize	integer	No	RAG augmented sentence window size, default is 2, minimum is 0
enableHyde	boolean	No	Enable HyDE, default is False
similarityCutoff	number (double)	No	Similarity cutoff, default is 0.0, range is 0.0-1.0
enableRerank	boolean	No	Enable reranking, default is True
chatbots	array[IdName]	No
groups	array[IdName]	No

Request Structure Example

{
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG augmented sentence window size, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Whether to enable reranking, default is True (Optional)
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
}

Request Example Value

{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example Name",
  "description": "Example string",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Name",
    "description": "Example String",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG sentence window size for expansion, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Enable reranking, default is True (Optional)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Returns the number of ChatbotFiles under this knowledge base (excluding processed files)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "description": "Response string",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "filesCount": 456,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}

---

List all knowledge bases

GET /api/knowledge-bases/

Parameters

Parameter Name	Required	Type	Description
embeddingModel	❌	string
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string
rerankerModel	❌	string

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/?embeddingModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&rerankerModel=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "user"?: string (uuid) // Optional
      "organization"?: string (uuid) // Optional
      "embeddingModel": string (uuid)
      "rerankerModel": string (uuid)
      "name": string
      "description"?: string // Optional
      "numberOfRetrievedChunks"?: integer // The number of retrieved reference chunks, default is 12, minimum is 1 (Optional)
      "sentenceWindowSize"?: integer // RAG augmented sentence window size, default is 2, minimum is 0 (Optional)
      "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
      "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
      "enableRerank"?: boolean // Whether to enable reranking, default is True (Optional)
      "labels": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "chatbots"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "groups"?: [ // List of groups that can access the knowledge base (Optional)
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "filesCount": integer // Returns the number of ChatbotFiles under this knowledge base (excluding processed files)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user": "550e8400-e29b-41d4-a716-446655440000",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string",
      "description": "Response string",
      "numberOfRetrievedChunks": 456,
      "sentenceWindowSize": 456,
      "enableHyde": false,
      "similarityCutoff": 456,
      "enableRerank": false,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string"
        }
      ],
      "chatbots": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string"
        }
      ],
      "filesCount": 456,
      "createdAt": "Response string",
      "updatedAt": "Response string"
    }
  ]
}

---

Get Specific Knowledge Base Details

GET /api/knowledge-bases/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Knowledge Base.

Code Example

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG augmented sentence window size, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Enable rerank, default is True (Optional)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Returns the number of ChatbotFiles under this knowledge base (excluding processed files)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "description": "Response string",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "filesCount": 456,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}

---

Update Knowledge Base

PUT /api/knowledge-bases/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Knowledge Base.

Request Body

Request Parameters

Field	Type	Required	Description
user	string (uuid)	No
organization	string (uuid)	No
embeddingModel	string (uuid)	Yes
rerankerModel	string (uuid)	Yes
name	string	Yes
description	string	No
numberOfRetrievedChunks	integer	No	Number of retrieved reference chunks, default is 12, minimum is 1
sentenceWindowSize	integer	No	RAG augmented sentence window size, default is 2, minimum is 0
enableHyde	boolean	No	Enable HyDE, default is False
similarityCutoff	number (double)	No	Similarity cutoff, default is 0.0, range is 0.0-1.0
enableRerank	boolean	No	Whether to enable reranking, default is True
chatbots	array[IdName]	No
groups	array[IdName]	No	List of groups that can access the knowledge base

Request Structure Example

{
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG augmented sentence window size, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Whether to enable rerank, default is True (Optional)
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
    }
  ]
}

Request Example Value

{
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example Name",
  "description": "Example String",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Name",
    "description": "Example String",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG sentence window size, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Enable rerank, default is True (Optional)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Returns the number of ChatbotFiles under this knowledge base (excluding processed files)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "description": "Response string",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "filesCount": 456,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}

---

Partially Update a Knowledge Base

PATCH /api/knowledge-bases/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Knowledge Base.

Request Body

Request Parameters

Field	Type	Required	Description
user	string (uuid)	No
organization	string (uuid)	No
embeddingModel	string (uuid)	No
rerankerModel	string (uuid)	No
name	string	No
description	string	No
numberOfRetrievedChunks	integer	No	Number of retrieved reference chunks, default is 12, minimum is 1
sentenceWindowSize	integer	No	RAG augmented sentence window size, default is 2, minimum is 0
enableHyde	boolean	No	Enable HyDE, default is False
similarityCutoff	number (double)	No	Similarity cutoff threshold, default is 0.0, range is 0.0-1.0
enableRerank	boolean	No	Whether to enable reranking, default is True
chatbots	array[IdName]	No
groups	array[IdName]	No	List of groups that can access the knowledge base

Request Schema Example

{
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel"?: string (uuid) // Optional
  "rerankerModel"?: string (uuid) // Optional
  "name"?: string // Optional
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG augmented sentence window size, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Whether to enable reranking, default is True (Optional)
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
    }
  ]
}

Request Example Value

{
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example Name",
  "description": "Example string",
  "numberOfRetrievedChunks": 123,
  "sentenceWindowSize": 123,
  "enableHyde": true,
  "similarityCutoff": 123,
  "enableRerank": true,
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "550e8400-e29b-41d4-a716-446655440000",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Name",
    "description": "Example String",
    "numberOfRetrievedChunks": 123,
    "sentenceWindowSize": 123,
    "enableHyde": true,
    "similarityCutoff": 123,
    "enableRerank": true,
    "chatbots": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "user"?: string (uuid) // Optional
  "organization"?: string (uuid) // Optional
  "embeddingModel": string (uuid)
  "rerankerModel": string (uuid)
  "name": string
  "description"?: string // Optional
  "numberOfRetrievedChunks"?: integer // Number of retrieved chunks, default is 12, minimum is 1 (Optional)
  "sentenceWindowSize"?: integer // RAG sentence window size for expansion, default is 2, minimum is 0 (Optional)
  "enableHyde"?: boolean // Enable HyDE, default is False (Optional)
  "similarityCutoff"?: number (double) // Similarity cutoff, default is 0.0, range is 0.0-1.0 (Optional)
  "enableRerank"?: boolean // Enable rerank, default is True (Optional)
  "labels": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "chatbots"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "groups"?: [ // List of groups that can access the knowledge base (Optional)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "filesCount": integer // Returns the number of ChatbotFiles under this knowledge base (excluding processed files)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "description": "Response string",
  "numberOfRetrievedChunks": 456,
  "sentenceWindowSize": 456,
  "enableHyde": false,
  "similarityCutoff": 456,
  "enableRerank": false,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "filesCount": 456,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}

---

Delete Knowledge Base

DELETE /api/knowledge-bases/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Knowledge Base.

Code Examples

Shell/Bash

# Example API Call (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response

Status Code	Description
204	No response body

---

Create a New Label

POST /api/knowledge-bases/{knowledgeBasePk}/labels/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
name	string	Yes

Request Structure Example

{
  "name": string
}

Request Example Value

{
  "name": "Sample Name"
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name"
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "name"?: string // Optional
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response String"
}

---

List labels in a knowledge base

GET /api/knowledge-bases/{knowledgeBasePk}/labels/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/?page=1&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "name"?: string // Optional
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response String"
    }
  ]
}

---

Get Specific Label Details

GET /api/knowledge-bases/{knowledgeBasePk}/labels/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this knowledge base label.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "name"?: string // Optional
}

Example Response Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response String"
}

---

Update Label

PUT /api/knowledge-bases/{knowledgeBasePk}/labels/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this knowledge base label.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
name	string	Yes

Request Structure Example

{
  "name": string
}

Request Example Value

{
  "name": "Example Name"
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name"
  }'

# Please replace YOUR_API_KEY and check the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "name"?: string // Optional
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response String"
}

---

Partially Update Label

PATCH /api/knowledge-bases/{knowledgeBasePk}/labels/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this knowledge base label.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
name	string	No

Request Structure Example

{
  "name"?: string // Optional
}

Request Example Value

{
  "name": "Example Name"
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Name"
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "name"?: string // Optional
}

Example Response Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response String"
}

---

Delete Label

DELETE /api/knowledge-bases/{knowledgeBasePk}/labels/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this knowledge base label.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/labels/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response

Status Code	Description
204	No response body

---

Upload File to Knowledge Base

POST /api/knowledge-bases/{knowledgeBasePk}/files/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string
fileType	❌	string	Filter by file type, e.g., pdf, docx, txt, xlsx, etc.
knowledgeBase	❌	string	Knowledge Base ID
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string	Search keyword, can search by file name or file ID.
status	❌	string	Filter by file status. Possible values: `initial` (Initializing), `processing` (Processing), `done` (Done), `deleting` (Deleting), `deleted` (Deleted), `failed` (Failed). `initial`: Initial ; `processing`: Processing ; `done`: Done ; `deleting`: Deleting ; `deleted`: Deleted ; `faile...

Request Body

Request Parameters

Field	Type	Required	Description
files	array[ChatbotFileCreate]	Yes	Supports batch upload of multiple files, with a limit of 50 files per request

Request Structure Example

{
  "files": [ // Supports batch upload of multiple files, with a limit of 50 files per request
    {
      "filename": string // File name
      "file": string (uri) // The file to be uploaded
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
      }
      "parser"?: string (uuid) // Optional
      "labels"?: [ // Optional
        {
          "id": string (uuid)
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
    }
  ]
}

Request Example Value

{
  "files": [
    {
      "filename": "my-file.pdf",
      "file": "string",
      "knowledgeBase": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "my-knowledge-base"
      },
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "labels": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "my-label"
        }
      ],
      "rawUserDefineMetadata": "string"
    },
    {
      "filename": "you-can-upload-multiple-files.pdf",
      "file": "string",
      "knowledgeBase": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "my-file.pdf",
        "file": "string",
        "knowledgeBase": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "my-knowledge-base"
        },
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "labels": [
          {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "my-label"
          }
        ],
        "rawUserDefineMetadata": "string"
      },
      {
        "filename": "you-can-upload-multiple-files.pdf",
        "file": "string",
        "knowledgeBase": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        },
        "parser": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 201

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "filename": string // File name
      "file": string (uri) // File to upload
      "fileType": string
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // Optional
      }
      }
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "createdAt": string (timestamp)
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "Response String",
      "file": "https://example.com/file.jpg",
      "fileType": "Response String",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "provider": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response String"
        }
      ],
      "rawUserDefineMetadata": null,
      "createdAt": "Response String"
    }
  ]
}

---

Batch Delete Files

POST /api/knowledge-bases/{knowledgeBasePk}/files/batch-delete/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
ids	array[string]	Yes

Request Structure Example

{
  "ids": [
    string (uuid)
  ]
}

Request Example Value

{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code	Description
204	No response body

---

List Files in a Knowledge Base

GET /api/knowledge-bases/{knowledgeBasePk}/files/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string
fileType	❌	string	Filter by file type, e.g., pdf, docx, txt, xlsx, etc.
knowledgeBase	❌	string	Knowledge Base ID
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string	Search keyword, can search by file name or file ID
status	❌	string	Filter by file status. Available values: `initial`: Initial ; `processing`: Processing ; `done`: Done ; `deleting`: Deleting ; `deleted`: Deleted ; `faile...

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "filename": string // File name
      "file": string (uri) // File to upload
      "fileType": string
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // Optional
      }
      }
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "createdAt": string (timestamp)
    }
  ]
}

Example Response Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "Response String",
      "file": "https://example.com/file.jpg",
      "fileType": "Response String",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "provider": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response String"
        }
      ],
      "rawUserDefineMetadata": null,
      "createdAt": "Response String"
    }
  ]
}

---

Get Specific File Details

GET /api/knowledge-bases/{knowledgeBasePk}/files/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Chatbot File.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "filename": string // File name
  "file": string (uri) // File to upload
  "fileType": string
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
    "name": string
  }
  "size": integer
  "status": 
  {
  }
  "parser": {
  {
    "id": string (uuid)
    "name": string
    "provider": 
    {
    }
    "order"?: integer // Optional
  }
  }
  "labels"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
  "createdAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "Response string",
  "file": "https://example.com/file.jpg",
  "fileType": "Response string",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string"
  },
  "size": 456,
  "status": {},
  "parser": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "provider": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "rawUserDefineMetadata": null,
  "createdAt": "Response string"
}

---

Update File Information

PUT /api/knowledge-bases/{knowledgeBasePk}/files/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Chatbot File.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
filename	string	Yes	File name
file	string (uri)	Yes	The file to upload
knowledgeBase	object (contains 2 properties: id, name)	No
knowledgeBase.id	string (uuid)	Yes
parser	string (uuid)	No
labels	array[IdName]	No
rawUserDefineMetadata	object	No

Request Structure Example

{
  "filename": string // File name
  "file": string (uri) // The file to upload
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
  }
  "parser"?: string (uuid) // Optional
  "labels"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
}

Request Example Value

{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "filename": string // File name
  "file": string (uri) // File to upload
  "fileType": string
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
    "name": string
  }
  "size": integer
  "status": 
  {
  }
  "parser": {
  {
    "id": string (uuid)
    "name": string
    "provider": 
    {
    }
    "order"?: integer // Optional
  }
  }
  "labels"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
  "createdAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "Response String",
  "file": "https://example.com/file.jpg",
  "fileType": "Response String",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String"
  },
  "size": 456,
  "status": {},
  "parser": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "provider": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response String"
    }
  ],
  "rawUserDefineMetadata": null,
  "createdAt": "Response String"
}

---

Partially Update File

PATCH /api/knowledge-bases/{knowledgeBasePk}/files/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Chatbot File.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
filename	string	No	File name
file	string (uri)	No	The file to upload
knowledgeBase	object (contains 2 properties: id, name)	No
knowledgeBase.id	string (uuid)	Yes
parser	string (uuid)	No
labels	array[IdName]	No
rawUserDefineMetadata	object	No

Request Structure Example

{
  "filename"?: string // File name (Optional)
  "file"?: string (uri) // File to upload (Optional)
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
  }
  "parser"?: string (uuid) // Optional
  "labels"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
}

Request Example Value

{
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "parser": "550e8400-e29b-41d4-a716-446655440000",
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "parser": "550e8400-e29b-41d4-a716-446655440000",
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "filename": string // File name
  "file": string (uri) // File to upload
  "fileType": string
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
    "name": string
  }
  "size": integer
  "status": 
  {
  }
  "parser": {
  {
    "id": string (uuid)
    "name": string
    "provider": 
    {
    }
    "order"?: integer // Optional
  }
  }
  "labels"?: [ // Optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
  "createdAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "Response String",
  "file": "https://example.com/file.jpg",
  "fileType": "Response String",
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String"
  },
  "size": 456,
  "status": {},
  "parser": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "provider": {},
    "order": 456
  },
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response String"
    }
  ],
  "rawUserDefineMetadata": null,
  "createdAt": "Response String"
}

---

Partially Update Files

PATCH /api/knowledge-bases/{knowledgeBasePk}/files/batch-reparse/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string
fileType	❌	string	Filter by file type, e.g., pdf, docx, txt, xlsx, etc.
knowledgeBase	❌	string	Knowledge Base ID
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string	Search keyword, can search by file name or file ID
status	❌	string	Filter by file status, possible values: initial, processing, done, deleting, deleted, failed initial: Initial ; processing: Processing ; done: Done ; deleting: Deleting ; deleted: Deleted ; faile...

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/batch-reparse/?fileType=example&knowledgeBase=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&query=example&status=deleted" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "filename": string // File name
      "file": string (uri) // File to upload
      "fileType": string
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // Optional
      }
      }
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "createdAt": string (timestamp)
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "Response String",
      "file": "https://example.com/file.jpg",
      "fileType": "Response String",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "provider": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response String"
        }
      ],
      "rawUserDefineMetadata": null,
      "createdAt": "Response String"
    }
  ]
}

---

Delete File

DELETE /api/knowledge-bases/{knowledgeBasePk}/files/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Chatbot File.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# Example API Call (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response

Status Code	Description
204	No response body

---

Create New FAQ

POST /api/knowledge-bases/{knowledgeBasePk}/faqs/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
question	string	Yes
answer	string	Yes
answerMediaUrls	object	No	URLs for media files such as images and videos in the answer
labels	array[IdName]	No
rawUserDefineMetadata	object	No
knowledgeBase	object (with 2 properties: id, name)	No
knowledgeBase.id	string (uuid)	Yes

Request Structure Example

{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // Stores the URLs of media files such as images, videos, etc. in the answer (optional)
  "labels"?: [ // optional
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
  }
}

Request Example Value

{
  "question": "Example string",
  "answer": "Example string",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Code Example

Shell/Bash

# API Call Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Example string",
    "answer": "Example string",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // Stores the URLs of media files such as images, videos, etc. in the answer (optional)
  "hitsCount": integer
  "embeddingTokensCount": integer // The number of embedding tokens used when creating this FAQ
  "labels"?: [ // optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
    "name": string
  }
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Response string",
  "answer": "Response string",
  "answerMediaUrls": null,
  "hitsCount": 456,
  "embeddingTokensCount": 456,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string"
  }
}

---

Batch Delete FAQs

POST /api/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
ids	array[string]	No

Request Structure Example

{
  "ids"?: [ // Optional
    string (uuid)
  ]
}

Request Example Value

{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X POST "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/batch-delete/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code	Description
204	No response body

---

List all FAQs for a specific knowledge base

GET /api/knowledge-bases/{knowledgeBasePk}/faqs/

Parameters

Parameter Name	Required	Type	Description
knowledgeBasePk	✅	string
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
query	❌	string

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/?page=1&pageSize=1&query=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and check the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "question": string
      "answer": string
      "answerMediaUrls"?: object // URLs for media files like images, videos, etc., in the answer (Optional)
      "hitsCount": integer
      "embeddingTokensCount": integer // Number of embedding tokens used when creating this FAQ
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "question": "Response string",
      "answer": "Response string",
      "answerMediaUrls": null,
      "hitsCount": 456,
      "embeddingTokensCount": 456,
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string"
        }
      ],
      "rawUserDefineMetadata": null,
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response string"
      }
    }
  ]
}

---

Get Specific FAQ Details

GET /api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // URLs of media files such as images, videos, etc. in the answer (optional)
  "hitsCount": integer
  "embeddingTokensCount": integer // Number of embedding tokens used when creating this FAQ
  "labels"?: [ // optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
    "name": string
  }
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Response string",
  "answer": "Response string",
  "answerMediaUrls": null,
  "hitsCount": 456,
  "embeddingTokensCount": 456,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string"
  }
}

---

Update FAQ

PUT /api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
question	string	Yes
answer	string	Yes
answerMediaUrls	object	No	URLs for media files such as images and videos in the answer
labels	array[IdName]	No
rawUserDefineMetadata	object	No
knowledgeBase	object (contains 2 properties: id, name)	No
knowledgeBase.id	string (uuid)	Yes

Request Structure Example

{
  "question": string
  "answer": string
  "answerMediaUrls"?: object // Stores the URLs of media files such as images, videos, etc. in the answer (optional)
  "labels"?: [ // optional
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
  }
}

Request Example Value

{
  "question": "Example string",
  "answer": "Example string",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PUT "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Example string",
    "answer": "Example string",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // Stores the URLs of media files such as images, videos, etc. in the answer (optional)
  "hitsCount": integer
  "embeddingTokensCount": integer // The number of embedding tokens used when creating this FAQ
  "labels"?: [ // optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
    "name": string
  }
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Response string",
  "answer": "Response string",
  "answerMediaUrls": null,
  "hitsCount": 456,
  "embeddingTokensCount": 456,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string"
  }
}

---

Partially Update FAQ

PATCH /api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
question	string	No
answer	string	No
answerMediaUrls	object	No	URLs for media files such as images and videos in the answer
labels	array[IdName]	No
rawUserDefineMetadata	object	No
knowledgeBase	object (contains 2 properties: id, name)	No
knowledgeBase.id	string (uuid)	Yes

Request Schema Example

{
  "question"?: string // Optional
  "answer"?: string // Optional
  "answerMediaUrls"?: object // Stores URLs for media files like images, videos, etc., in the answer (Optional)
  "labels"?: [ // Optional
    {
      "id": string (uuid)
    }
  ]
  "rawUserDefineMetadata"?: object // Optional
  "knowledgeBase"?:  // Optional
  {
    "id": string (uuid)
  }
}

Request Example Value

{
  "question": "Example string",
  "answer": "Example string",
  "answerMediaUrls": null,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Example String",
    "answer": "Example String",
    "answerMediaUrls": null,
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "rawUserDefineMetadata": null,
    "knowledgeBase": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "question": string
  "answer": string
  "answerMediaUrls"?: object // URLs of media files such as images, videos, etc. in the answer (optional)
  "hitsCount": integer
  "embeddingTokensCount": integer // The number of embedding tokens used when creating this FAQ
  "labels"?: [ // optional
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "rawUserDefineMetadata"?: object // optional
  "knowledgeBase"?:  // optional
  {
    "id": string (uuid)
    "name": string
  }
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "question": "Response string",
  "answer": "Response string",
  "answerMediaUrls": null,
  "hitsCount": 456,
  "embeddingTokensCount": 456,
  "labels": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  ],
  "rawUserDefineMetadata": null,
  "knowledgeBase": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string"
  }
}

---

Delete FAQ

DELETE /api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this FAQ.
knowledgeBasePk	✅	string

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/faqs/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

Python

PHP

Response

Status Code	Description
204	No response body

---