RAG API

The RAG (Retrieval-Augmented Generation) API allows you to manage knowledge containers and documents for providing context-aware AI responses. The system retrieves relevant information from your approved document sources when users ask questions.

Note: At Advisors Asset Management, RAG containers are permission-based and can contain financial and regulatory documents that provide factual support for AI-generated responses.

RAG Containers

RAG containers are collections of documents that provide context for AI responses. Each container can be associated with specific permissions and user groups.

List RAG Containers

Get a list of all RAG containers that the authenticated user has access to.

GET /api/v1/rag/containers

Authentication: Required

Required Permissions: view_rag_containers

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Items per page (default: 20, max: 100)
category	string	No	Filter by container category
search	string	No	Search term to filter containers

Example Response

{
    "success": true,
    "data": {
        "containers": [
            {
                "id": 1,
                "name": "Financial Regulations",
                "description": "SEC and FINRA regulatory documents",
                "category": "regulatory",
                "document_count": 245,
                "last_updated": "2025-03-10T14:30:00Z",
                "permissions": {
                    "can_view": true,
                    "can_edit": false,
                    "can_delete": false
                },
                "created_at": "2024-12-01T10:00:00Z"
            },
            {
                "id": 2,
                "name": "Investment Strategies",
                "description": "Best practices and strategies for investment management",
                "category": "investment",
                "document_count": 89,
                "last_updated": "2025-03-08T16:45:00Z",
                "permissions": {
                    "can_view": true,
                    "can_edit": true,
                    "can_delete": false
                },
                "created_at": "2024-11-15T09:30:00Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 2,
            "total_pages": 1
        }
    },
    "message": "RAG containers retrieved successfully"
}

Create RAG Container

Create a new RAG container for organizing documents.

POST /api/v1/rag/containers

Authentication: Required

Required Permissions: create_rag_containers

Request Parameters

Parameter	Type	Required	Description
name	string	Yes	Container name (max 255 characters)
description	string	No	Container description
category	string	Yes	Container category (regulatory, investment, general, etc.)
is_public	boolean	No	Whether container is accessible to all users (default: false)
permissions	array	No	Array of permission keys required to access this container

Example Request

{
    "name": "Compliance Guidelines",
    "description": "Internal compliance guidelines and procedures",
    "category": "regulatory",
    "is_public": false,
    "permissions": ["view_compliance_docs"]
}

Example Response

{
    "success": true,
    "data": {
        "container": {
            "id": 3,
            "name": "Compliance Guidelines",
            "description": "Internal compliance guidelines and procedures",
            "category": "regulatory",
            "is_public": false,
            "document_count": 0,
            "permissions": ["view_compliance_docs"],
            "created_at": "2025-03-11T10:30:00Z",
            "updated_at": "2025-03-11T10:30:00Z"
        }
    },
    "message": "RAG container created successfully"
}

Get RAG Container

Get details of a specific RAG container including its documents.

GET /api/v1/rag/containers/{container_id}

Authentication: Required

Required Permissions: view_rag_containers

Path Parameters

Parameter	Type	Required	Description
container_id	integer	Yes	ID of the RAG container

Example Response

{
    "success": true,
    "data": {
        "container": {
            "id": 1,
            "name": "Financial Regulations",
            "description": "SEC and FINRA regulatory documents",
            "category": "regulatory",
            "is_public": false,
            "document_count": 245,
            "permissions": ["view_financial_regulations"],
            "documents": [
                {
                    "id": 101,
                    "filename": "SEC_Rule_10b-5.pdf",
                    "title": "SEC Rule 10b-5: Employment of Manipulative Devices",
                    "file_size": 1024576,
                    "mime_type": "application/pdf",
                    "upload_date": "2025-02-15T09:00:00Z",
                    "processed": true,
                    "chunk_count": 45
                },
                {
                    "id": 102,
                    "filename": "FINRA_Rule_2111.pdf",
                    "title": "FINRA Rule 2111: Suitability",
                    "file_size": 2048576,
                    "mime_type": "application/pdf",
                    "upload_date": "2025-02-10T14:30:00Z",
                    "processed": true,
                    "chunk_count": 78
                }
            ],
            "created_at": "2024-12-01T10:00:00Z",
            "updated_at": "2025-03-10T14:30:00Z"
        }
    },
    "message": "RAG container retrieved successfully"
}

RAG Documents

Documents are the individual files within RAG containers that provide context for AI responses.

Upload Document

Upload a document to a RAG container for processing and indexing.

POST /api/v1/rag/containers/{container_id}/documents

Authentication: Required

Required Permissions: upload_rag_documents

Path Parameters

Parameter	Type	Required	Description
container_id	integer	Yes	ID of the RAG container

Form Data Parameters

Parameter	Type	Required	Description
file	file	Yes	The document file to upload (PDF, DOCX, TXT, etc.)
title	string	No	Custom title for the document (auto-generated from filename if not provided)
description	string	No	Description of the document content
metadata	object	No	Additional metadata as JSON object

Example Response

{
    "success": true,
    "data": {
        "document": {
            "id": 103,
            "container_id": 1,
            "filename": "investment_policy.pdf",
            "title": "Investment Policy Statement",
            "description": "Corporate investment policy and guidelines",
            "file_size": 3145728,
            "mime_type": "application/pdf",
            "upload_date": "2025-03-11T10:45:00Z",
            "processed": false,
            "processing_status": "queued",
            "metadata": {
                "department": "Investment Management",
                "version": "2.1",
                "effective_date": "2025-01-01"
            }
        }
    },
    "message": "Document uploaded successfully and queued for processing"
}

Delete Document

Delete a document from a RAG container.

DELETE /api/v1/rag/documents/{document_id}

Authentication: Required

Required Permissions: delete_rag_documents

Path Parameters

Parameter	Type	Required	Description
document_id	integer	Yes	ID of the document to delete

Example Response

{
    "success": true,
    "data": null,
    "message": "Document deleted successfully"
}

Search and Retrieval

These endpoints allow you to search within RAG containers and retrieve relevant context.

Search Container

Search for relevant content within a specific RAG container.

POST /api/v1/rag/containers/{container_id}/search

Authentication: Required

Required Permissions: search_rag_containers

Path Parameters

Parameter	Type	Required	Description
container_id	integer	Yes	ID of the RAG container to search

Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query
limit	integer	No	Number of results to return (default: 10, max: 50)
threshold	float	No	Similarity threshold (0.0-1.0, default: 0.7)

Example Request

{
    "query": "suitability requirements for investment recommendations",
    "limit": 5,
    "threshold": 0.75
}

Example Response

{
    "success": true,
    "data": {
        "results": [
            {
                "document_id": 102,
                "document_title": "FINRA Rule 2111: Suitability",
                "chunk_id": "chunk_102_15",
                "content": "Before making any investment recommendation, a member must have a reasonable basis to believe that the recommendation is suitable for the customer based on the information obtained through reasonable diligence...",
                "similarity_score": 0.89,
                "metadata": {
                    "page_number": 3,
                    "section": "General Suitability Requirements"
                }
            },
            {
                "document_id": 101,
                "document_title": "SEC Rule 10b-5: Employment of Manipulative Devices",
                "chunk_id": "chunk_101_8",
                "content": "Investment advisers must ensure that their recommendations are in the best interest of their clients and based on thorough analysis of the client's financial situation...",
                "similarity_score": 0.82,
                "metadata": {
                    "page_number": 5,
                    "section": "Fiduciary Duty"
                }
            }
        ],
        "query": "suitability requirements for investment recommendations",
        "total_results": 2,
        "search_time_ms": 145
    },
    "message": "Search completed successfully"
}

API Tester

Test the RAG API endpoints directly from this documentation.