API Reference¶

This page summarizes the HTTP API surfaces identified during source-code inspection of WhiteLotusAI. It is intended as an engineering orientation page, not as a complete OpenAPI contract.

Detailed integration behaviour belongs in the corresponding integration pages. Request and response schemas, authentication requirements, status codes, and side effects must be verified against the relevant implementation before being documented as guaranteed behaviour.

API architecture¶

WhiteLotusAI uses a REST API gateway alongside supporting services. The gateway's API root is configurable through API_ROOT, which defaults to /api in the inspected source.

flowchart TB
    Client["Client or frontend"]
    Gateway["REST API gateway<br/>FastAPI"]

    subgraph GatewayRoutes["Gateway route surface"]
        direction TB
        Auth["Authentication"]
        Profile["Profile management"]
        Sessions["Sessions"]
        Admin["Administration"]
        RAG["RAG endpoints"]
        Proxy["Chat and proxy routing"]
    end

    subgraph Supporting["Supporting service surfaces"]
        direction TB
        Chat["Chat service<br/>Streaming and chat processing"]
        Integrations["Integrations service<br/>Provider operations, OAuth, webhooks, MCP"]
        User["User service"]
        SessionService["Session service"]
        RAGService["RAG service"]
    end

    Client --> Gateway
    Gateway --> Auth
    Gateway --> Profile
    Gateway --> Sessions
    Gateway --> Admin
    Gateway --> RAG
    Gateway --> Proxy

    Proxy -.->|"Effective route depends on configuration"| Chat
    Gateway -.->|"Configured service routing"| Integrations
    Gateway -.->|"Supporting service surface; verify runtime path"| User
    Gateway -.->|"Supporting service surface; verify runtime path"| SessionService
    Gateway -.->|"Supporting service surface; verify runtime path"| RAGService

    %% Theme-adaptive fills and text; colored outlines identify categories.
    classDef client stroke:#2563eb,stroke-width:2px
    classDef gateway stroke:#7c3aed,stroke-width:2.5px
    classDef route stroke:#7c3aed,stroke-width:1.5px
    classDef service stroke:#059669,stroke-width:2px

    class Client client
    class Gateway gateway
    class Auth,Profile,Sessions,Admin,RAG,Proxy route
    class Chat,Integrations,User,SessionService,RAGService service

    %% Transparent backgrounds preserve the active documentation theme.
    style GatewayRoutes fill:transparent,stroke:#7c3aed,stroke-width:1.5px
    style Supporting fill:transparent,stroke:#059669,stroke-width:1.5px

The diagram is a logical orientation map, not a deployment topology or confirmation that every path is exposed. Verify the actual route mapping and service communication for the target environment.

Gateway endpoint inventory¶

The paths below were identified in the gateway route definitions. Unless overridden by configuration, the gateway API prefix is /api.

Authentication¶

Source: rest_api/package/app/api/auth.py

Profile management¶

Source: rest_api/package/app/api/profile.py

The profile router declares a JWTBearer dependency. Verify the precise authentication and authorization behaviour against the implementation and tests before relying on it.

Sessions¶

Source: rest_api/package/app/api/session.py

Session operations may access or modify user-associated data. Verify ownership checks, input validation, and side effects at the route level.

Administration¶

Source: rest_api/package/app/api/admin.py

The administration router declares a JWTBearer dependency. That dependency alone does not establish that role-based authorization is correctly enforced for every operation.

Retrieval-augmented generation (RAG)¶

Source: rest_api/package/app/api/rag.py

Ingestion, deletion, and publication are state-changing operations. Verify request validation, authorization, storage effects, and error behaviour in the implementation.

Chat and gateway proxying¶

The gateway contains a chat router and registers a catch-all proxy router after the other routers. The existence of a chat router does not prove that it directly implements every chat endpoint.

The separate chat service registers its router under /api/chat-svc, including a streaming route at /stream.

Relevant source locations:

• rest_api/package/app/api/chat.py
• rest_api/package/app/api/proxy.py
• rest_api/package/app/main.py
• chat/package/app/handlers/chat_handlers.py
• chat/package/app/main.py

The final externally used chat URL depends on gateway proxy routing and deployment configuration. Confirm the effective route before publishing a client-facing example.

Integrations API surface¶

The integrations service registers integration and webhook routers under /api/integrations-svc. OAuth and MCP routers are registered separately.

The following endpoint families were identified in integrations/package/app/handlers/integration_handlers.py. These entries describe the inventory found in source; they are not a complete request/response specification.

Consult the relevant integration documentation for details. Verify exact paths, parameters, payloads, and response schemas against the handlers and provider clients. Do not infer the full external URL for a route family from this table alone.

Webhooks¶

The source contains webhook routes for Jira, Slack, and Microsoft Teams:

• POST /api/integrations-svc/webhooks/jira
• POST /api/integrations-svc/webhooks/slack
• POST /api/integrations-svc/webhooks/teams

Source: integrations/package/app/handlers/webhook_handlers.py

Webhook signature verification, request authenticity, replay protection, and event handling must be reviewed and tested independently.

OAuth and MCP endpoints¶

The integrations service defines OAuth- and MCP-related routes, including:

These routes are registered separately from the /api/integrations-svc integration and webhook routers. Their actual accessibility depends on service exposure and deployment routing.

Relevant source locations:

• integrations/package/app/mcp/oauth.py
• integrations/package/app/mcp/server.py
• integrations/package/app/main.py

Authentication and authorization¶

Authentication and authorization requirements must be documented per route; they should not be inferred from the service name or HTTP method.

The inspected gateway source includes a JWTBearer dependency on the logout, profile, session, administration, and RAG routers. Registration, login, and refresh serve different authentication purposes.

Integration handlers also use user-identifying headers, internal-service credentials, OAuth state, and provider tokens in different flows. The presence of a header or token lookup is not, on its own, evidence that user identity and resource ownership are securely enforced.

For each endpoint, verify and document:

• Whether authentication is required.
• The accepted credential or token type.
• How the authenticated user is identified.
• Whether resource-level authorization is checked.
• Whether internal-service authentication is required.
• Whether provider credentials are resolved for the correct user.
• How expired, revoked, or invalid credentials are handled.

Read-only operating requirement¶

WhiteLotusAI's current documentation work treats read-only integration behaviour as a requirement that must be verified against the application.

The source inventory contains state-changing route families, including message sending, issue creation, calendar event creation and deletion, file modification, permission changes, email mutations, and document management operations. Their presence in source is an audit finding; it does not prove that every operation is exposed to every user or has been exercised successfully.

Read the Read-Only Integration Policy

Interactive API documentation¶

The gateway configures Swagger UI at /api/docs when DEVELOP is enabled. The inspected source disables the gateway Swagger UI URL otherwise. The chat and integrations services similarly condition their /docs routes on development configuration.

Availability depends on the running service, configuration, and network exposure. Do not assume development API documentation is available or should be exposed publicly in production.

Use a generated schema as a verification aid, not as a substitute for reviewing authentication, authorization, side effects, and observed runtime behaviour.

Errors and validation¶

The gateway registers exception handlers for HTTP exceptions, request-validation errors, custom HTTP exceptions, and unexpected exceptions. Its application configuration also declares response documentation for HTTP 404 and validation 422 responses.

This does not establish that every service returns the same error format or that all error responses are safe and consistent.

For each endpoint, record:

• Expected success status codes and response bodies.
• Validation failures and their status codes.
• Authentication and authorization failures.
• Not-found and conflict behaviour, where applicable.
• Provider API errors and timeouts.
• Whether internal exception details or sensitive values could be exposed.

Read API Error Handling

Compatibility and versioning¶

The inspected source snapshot does not establish a single, consistent versioning contract for all gateway and integration routes. Do not assume every endpoint is versioned or that backward compatibility is guaranteed.

When an API change is introduced, document the affected routes, request and response changes, compatibility impact, migration requirements, and any deprecation period that is actually implemented.

Open documentation and verification findings¶

The following findings remain open until supported by source review, tests, or runtime evidence.

These are documentation and audit findings, not application changes performed by this page.

Source locations¶

The primary source locations used for this overview are listed below.

Gateway¶

• rest_api/package/app/main.py
• rest_api/package/app/settings.py
• rest_api/package/app/api/auth.py
• rest_api/package/app/api/profile.py
• rest_api/package/app/api/session.py
• rest_api/package/app/api/admin.py
• rest_api/package/app/api/rag.py
• rest_api/package/app/api/chat.py
• rest_api/package/app/api/proxy.py

Integrations¶

• integrations/package/app/main.py
• integrations/package/app/handlers/integration_handlers.py
• integrations/package/app/handlers/webhook_handlers.py
• integrations/package/app/mcp/oauth.py
• integrations/package/app/mcp/server.py

Chat¶

• chat/package/app/main.py
• chat/package/app/handlers/chat_handlers.py

Verification status¶

This page is a source-derived API overview. It is not a complete OpenAPI contract, a successful runtime test report, or a security certification.

Update this reference as endpoint implementations, route exposure, authentication requirements, and tests are verified. Keep unverified claims explicitly labelled until supporting evidence is available.