doc_version: "1.0.0" last_updated: "2026-06-18" status: "Active"

API Documentation¶

This directory contains documentation for all 13 API services in src/apis/.

Overview¶

The API services provide REST endpoints for the Bast AI platform, built on FastAPI. They handle chat processing, authentication, analytics, and various management functions.

API Services¶

API	Version	Description	Tests
base	0.1.10	Core FastAPI setup	-
cat	0.2.11	Chat processing, conversations	-
security	0.1.21	Authentication (WorkOS, Google, MS)	-
analytics	0.1.15	Metrics, dashboards	7
feedback	0.1.6	User feedback management	-
ontology	0.1.1	Knowledge graph access	-
parse	0.1.5	Document parsing	-
status	0.1.2	Health checks	-
user_management	0.1.1	User CRUD operations	-
agno	0.1.1	Agno agent configuration API	-
cat-runtime	0.1.5	CAT runtime execution, conversation logging	-
org-services	0.1.5	Organization services and tenant management	-
platform	0.2.3	Platform management, org lifecycle, cloud provisioning	-

Architecture¶

Dependency Hierarchy¶

bast-api-base (Foundation)
    │
    ├── bast-cat-api (Chat)
    ├── bast-security-api (Auth)
    ├── bast-analytics-api (Metrics)
    ├── bast-feedback-api (Feedback)
    ├── bast-ontology-api (Knowledge)
    ├── bast-parse-api (Parsing)
    ├── bast-status-api (Health)
    ├── bast-user-management-api (Users)
    ├── bast-agno-api (Agno Config)
    ├── bast-cat-runtime-api (CAT Runtime)
    ├── bast-org-services-api (Org Services)
    └── bast-platform-api (Platform)

Base API Components¶

The bast-api-base provides:

Component	Description
`BastApp`	Main FastAPI application class
`CAT`	Cat configuration object
`BAST_MODEL`	Traditional model instance
`BAST_AGNO_MODEL`	Agno agent model instance
`USER_DB`	User database connection

Key Endpoints¶

Chat API (CAT)¶

Endpoint	Method	Description
`/api/v1/cat/chat`	POST	Unified chat with dynamic routing
`/api/v1/cat/agno_chat`	POST	Direct Agno chat endpoint
`/api/v1/cat/legacy_chat`	POST	Direct legacy chat endpoint
`/api/v1/cat/conversations`	GET	List conversations
`/api/v1/cat/conversations/{id}`	GET	Get conversation history
`/api/v1/cat/conversations/{id}`	DELETE	Delete conversation
`/api/v1/cat/conversations/{id}/rename`	PUT	Rename conversation
`/api/v1/cat/config`	GET	Get configuration

Security API¶

Endpoint	Method	Description
`/api/v1/auth/workos`	POST	WorkOS authentication
`/api/v1/auth/google`	POST	Google OAuth
`/api/v1/auth/microsoft`	POST	Microsoft authentication
`/api/v1/auth/logout`	POST	User logout
`/api/v1/auth/memory`	GET/POST	User memory management

Analytics API¶

Endpoint	Method	Description
`/api/v1/analytics/metrics`	GET	User activity metrics
`/api/v1/analytics/topics`	GET	Topic analysis
`/api/v1/analytics/chat-logs`	GET	Chat log retrieval
`/api/v1/analytics/health`	GET	System health

Status API¶

Endpoint	Method	Description
`/api/v1/status/health`	GET	Health check
`/api/v1/status/ready`	GET	Readiness check
`/api/v1/status/version`	GET	Version information

Chat Mode Routing¶

The CAT API supports dynamic chat mode routing:

Mode	Handler	Description
`legacy`	`legacy_chat.py`	Traditional multi-model processing
`agno`	`agno_chat.py`	Agno-based agent processing
`custom`	Configurable	Custom routing logic

Configuration in YAML:

cat:
  chat_mode: agno  # or "legacy" or "custom"

Authentication Providers¶

Supported Providers¶

WorkOS — SSO, passwordless authentication
Google OAuth — Google account integration
Microsoft (MSAL) — Azure AD / Microsoft account integration

All providers are configured via environment variables and YAML configuration. JWT tokens are issued upon successful authentication with configurable expiration.

Common Patterns¶

API Router Structure¶

from fastapi import APIRouter, Depends
from bast_api_base import get_app_state

router = APIRouter(prefix="/api/v1/myapi", tags=["myapi"])

@router.get("/endpoint")
async def my_endpoint(state = Depends(get_app_state)):
    cat = state.CAT
    # ... implementation

Error Handling¶

from fastapi import HTTPException

@router.get("/resource/{id}")
async def get_resource(id: str):
    resource = db.find(id)
    if not resource:
        raise HTTPException(status_code=404, detail="Resource not found")
    return resource

Request Validation¶

from pydantic import BaseModel

class ChatRequest(BaseModel):
    message: str
    conversation_id: str | None = None
    context: dict | None = None

@router.post("/chat")
async def chat(request: ChatRequest):
    # ... implementation

Maintainers¶

Bast AI Team