Knowledge Bases (RAG)

​

List Knowledge Bases

​

GET /knowledge-bases

​

Query Parameters

curl "https://api-staging.internal-aui.io/knowledge-base-manager/v1/knowledge-bases?network_id=net-id&account_id=acc-id&seed_id=seed-id&include_hierarchy=true" \
  -H "x-api-key: your-kbm-api-key"

[
  {
    "id": "string",
    "name": "string",
    "scope_id": "string",
    "scope": {
      "type": "string",
      "network_id": "string",
      "account_id": "string",
      "seed_id": "string",
      "network_category_id": "string"
    }
  }
]

​

Best Practices

• Use include_hierarchy=true for full visibility — This returns knowledge bases inherited from parent scopes (account, organization), not just network-level ones. Essential for understanding what data the agent has access to.
• Filter by scope to avoid confusion — Always pass network_id and account_id to scope the results. Without filters, you may see knowledge bases from other agents.

​

Upload Files (Bulk)

​

POST /bulk/files

{
  "knowledge_base_id": "string",
  "knowledge_base_name": "string",
  "knowledge_base_created": true,
  "results": [
    { "resource_id": "string", "resource_name": "string", "status": "string" }
  ],
  "total_files": 3,
  "files_accepted": 3,
  "files_failed": 0
}

​

Best Practices

• Supported formats — Upload PDF, DOCX, CSV, TXT, and other document formats. Check files_failed in the response to catch unsupported or corrupted files.
• Use descriptive knowledge_base_name — Name knowledge bases by content domain (e.g., product-catalog-2026, return-policy). This makes it easier to manage and audit.
• Upload to an existing KB when possible — Pass knowledge_base_id to add files to an existing knowledge base rather than creating a new one for every upload. This keeps related content together.
• Batch uploads — Send multiple files in a single request rather than one file per request. This reduces overhead and ensures atomicity.

​

Upload Websites (Bulk Scrape)

​

POST /bulk/websites

{
  "urls": [
    { "url": "https://example.com", "resource_name": "string", "description": "string" }
  ],
  "scope": {
    "type": "string",
    "network_id": "string",
    "account_id": "string",
    "seed_id": "string"
  },
  "created_by": "string",
  "knowledge_base_id": "string",
  "knowledge_base_name": "string",
  "knowledge_base_description": "string"
}

{
  "knowledge_base_id": "string",
  "knowledge_base_name": "string",
  "knowledge_base_created": true,
  "results": [],
  "total_urls": 2,
  "urls_accepted": 2,
  "urls_failed": 0
}

​

Best Practices

• Provide meaningful resource_name — Name each URL resource clearly (e.g., FAQ Page, Pricing) rather than using the URL as the name. This improves RAG retrieval quality.
• Scrape sparingly — Website scraping is resource-intensive. Avoid scraping entire sites — target specific pages with high-quality content relevant to the agent’s domain.
• Check urls_failed in the response — Pages behind authentication, CAPTCHAs, or JavaScript-heavy SPAs may fail to scrape. Verify each URL is accessible before submitting.

​

Export Knowledge Bases

​

POST /bulk/export

{
  "scope": {
    "type": "string",
    "network_id": "string",
    "account_id": "string",
    "seed_id": "string",
    "network_category_id": "string"
  }
}

{
  "scope_levels": [
    {
      "scope_level": "string",
      "scope": {},
      "knowledge_bases": [
        {
          "name": "string",
          "description": "string",
          "resources": [
            {
              "file_name": "string",
              "resource_type": "string",
              "vectors": [
                {
                  "title": "string",
                  "content": "string",
                  "category": "string",
                  "sub_category": "string",
                  "tags": [],
                  "source_url": "string"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

​

Best Practices

• Export before destructive changes — Always export knowledge bases before deleting resources, migrating agents, or making bulk vector changes. The export includes all vectors and can be re-imported.
• Use exports for environment promotion — Export from staging and import into production to ensure the same knowledge base content is available in both environments.
• Store exports in version control — Save export JSON files alongside your .aui.json agent configs. This gives you a full backup and change history of your agent’s knowledge.

​

Import Knowledge Bases

​

POST /bulk/import

{
  "scope_levels": [],
  "created_by": "string"
}

{
  "results": [
    {
      "scope_level": "string",
      "knowledge_bases_created": 1,
      "knowledge_bases_found": 0,
      "resources_created": 3,
      "resources_updated": 0,
      "vectors_created": 15,
      "vectors_updated": 0,
      "vectors_deleted": 0,
      "vectors_unchanged": 0
    }
  ]
}

​

Best Practices

• Review the results summary — Check vectors_created, vectors_updated, and vectors_deleted to understand exactly what changed. Unexpected deletes may indicate a scope mismatch.
• Import is idempotent — Re-importing the same data will update existing vectors rather than creating duplicates. Use this for safe re-syncs.
• Match scope carefully — The import uses scope levels from the export. Ensure the target environment has matching network, account, and organization IDs, or remap them before importing.