API Endpoint Inventory¶

Document status: Source-derived inventory · Runtime verification pending

This document provides a consolidated inventory of HTTP endpoints identified in the WhiteLotusAI source repository. It records route paths, HTTP methods, service ownership, and operational considerations to support API discovery, engineering work, and security reviews.

At a glance¶

1. How to read this inventory¶

Route conventions¶

• API_ROOT defaults to /api for gateway routers. If this setting changes, gateway route paths may change accordingly.
• The integrations service registers integration and webhook routers under /api/integrations-svc.
• The chat service registers its router under /api/chat-svc.
• OAuth metadata, OAuth flow, and MCP routes are registered separately from the integrations prefix.
• {parameter} denotes a path parameter.
• Query parameters and required headers are not exhaustively listed.
• GET is generally retrieval-oriented. Other methods may change application state.
• A route's presence in source code does not prove that it is enabled, reachable, or publicly exposed in a deployed environment.

Endpoint method guide¶

2. Service and routing overview¶

The diagram illustrates the documented service boundaries. It does not assert that every downstream endpoint is publicly reachable through the gateway.

flowchart TB
    CLIENT["Client Application"]
    GATEWAY["REST API Gateway<br/>FastAPI · API_ROOT"]

    subgraph GW["Gateway Route Groups"]
        direction LR
        AUTH["Authentication<br/>Profiles · Sessions"]
        ADMIN["Administration"]
        RAG["RAG and Documents"]
        PROXY["Chat and Proxy"]
    end

    subgraph SERVICES["Downstream Services"]
        direction LR
        CHAT["Chat Service<br/>/api/chat-svc"]
        INT["Integrations Service<br/>/api/integrations-svc"]
    end

    subgraph EXT["Integration and Protocol Routes"]
        direction LR
        WEBHOOK["Webhooks"]
        OAUTH["OAuth Endpoints"]
        MCP["MCP Endpoint"]
    end

    CLIENT --> GATEWAY
    GATEWAY --> AUTH
    GATEWAY --> ADMIN
    GATEWAY --> RAG
    GATEWAY --> PROXY
    PROXY -. "Configured routing" .-> CHAT
    PROXY -. "Configured routing" .-> INT
    INT --> WEBHOOK
    INT --> OAUTH
    INT --> MCP

    classDef client fill:#E8EAF6,stroke:#5C6BC0,color:#1A237E,stroke-width:1.5px
    classDef gateway fill:#EDE7F6,stroke:#7E57C2,color:#311B92,stroke-width:2px
    classDef route fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1,stroke-width:1px
    classDef service fill:#E0F2F1,stroke:#26A69A,color:#004D40,stroke-width:1.5px
    classDef protocol fill:#FFF3E0,stroke:#FB8C00,color:#7F3100,stroke-width:1px

    class CLIENT client
    class GATEWAY gateway
    class AUTH,ADMIN,RAG,PROXY route
    class CHAT,INT service
    class WEBHOOK,OAUTH,MCP protocol

    style GW fill:transparent,stroke:#9FA8DA,stroke-width:1.5px
    style SERVICES fill:transparent,stroke:#80CBC4,stroke-width:1.5px
    style EXT fill:transparent,stroke:#FFCC80,stroke-width:1.5px

3. REST API gateway¶

Source root: rest_api/package/app/

3.1 Health and root¶

Confirm the effective health and root URLs in the running deployment, including any configured route prefix.

3.2 Authentication¶

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

3.3 Profile¶

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

3.4 Sessions¶

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

3.5 Administration¶

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

3.6 Retrieval-augmented generation (RAG)¶

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

Ingestion, deletion, and publication may change application state. Verify document ownership, ingestion validation, publication semantics, and applicable permissions in the handlers.

3.7 Chat and proxy routing¶

Sources:

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

The gateway defines a chat router with a /chat prefix and a catch-all proxy route accepting GET, POST, DELETE, PUT, and PATCH requests under the gateway API prefix.

The proxy is registered after the other routers. The effective downstream destination depends on its routing logic and configuration.

4. Chat service¶

Sources:

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

The service router is registered under /api/chat-svc.

5. Integrations service¶

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

The integration router is registered under /api/integrations-svc.

The following tabs group the documented integration routes by provider. They are navigation aids; each table remains a source-derived inventory.

6. Webhook endpoints¶

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

The webhook router is registered under /api/integrations-svc.

The source declares signature-related headers for some webhook handlers. Header declarations alone do not prove that signatures are validated.

7. OAuth and MCP endpoints¶

Sources:

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

These routers are registered separately from the /api/integrations-svc prefix.

These paths belong to the integrations service. Their public reachability depends on service exposure and deployment routing.

8. Read-only audit classification¶

This classification is a preliminary assessment based on route names and HTTP methods. It is not a complete handler-level security review.

9. Open findings and verification plan¶

Recommended verification sequence¶

1. Inventory source registrations: Confirm routers, prefixes, HTTP methods, and route registration order.
2. Inspect authorization: Trace authentication middleware, dependencies, role checks, and service-to-service credentials.
3. Audit mutations: Identify all state-changing handlers, including indirect effects and alternate tool-dispatch paths.
4. Validate schemas: Record required parameters, request bodies, response models, status codes, and error responses.
5. Test deployed routes: Verify expected success and failure behaviour in a controlled environment.
6. Record evidence: Update the findings table only when source inspection or reproducible tests support a conclusion.

10. Source locations¶

The following paths are the primary source locations referenced by this inventory.

11. Maintenance¶

Update this inventory when routes are added, removed, renamed, or moved between services. Recheck route prefixes and deployment routing when API_ROOT, gateway proxy configuration, service ports, or reverse-proxy rules change.

For a complete API contract, complement this document with generated OpenAPI specifications and endpoint-level documentation covering request and response schemas, authentication requirements, error codes, and examples.

Document classification: Engineering reference · Source-derived · Runtime verification pending