API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The monGARS project exposes a comprehensive RESTful API built with FastAPI. This API serves as the primary interface for interacting with the system's core functionalities, including conversational AI, user authentication, conversation history management, and model provisioning. It is designed to be robust, secure, and easy to use, leveraging Pydantic for strict data validation and providing a standard OpenAPI specification for client generation and documentation.
The API surface is governed by a set of standards that enforce asynchronous routes, typed Pydantic responses, and specific security measures like rate limiting and WebSocket ticket verification. The entire system is modular, with the FastAPI layer (monGARS.api) handling authentication, REST/WebSocket endpoints, and dependency injection, while delegating complex logic to the core cognition engine.
Sources: README.md, monGARS/api/AGENTS.md
Architecture Overview
The API is built around the FastAPI framework, which provides automatic OpenAPI documentation, data validation, and dependency injection. The main application is defined in monGARS/api/web_api.py. It includes routers for different functionalities, such as conversation, authentication, and model management.
Key architectural principles include:
- Asynchronous Routes: All endpoints are designed as
asyncfunctions to handle I/O-bound operations efficiently. - Typed Schemas: Pydantic models defined in
monGARS/api/schemas.pyare used for request and response validation, ensuring data integrity. - Dependency Injection: FastAPI's dependency system is used to manage shared resources like security managers and rate limiters.
- Standardized Security: Authentication is handled via an OAuth2 password flow, and chat endpoints are protected by an in-memory rate limiter.
- OpenAPI Specification: A static
openapi.jsonfile is generated, which serves as the single source of truth for the API contract. This file is used by SDKs and for documentation.
Sources: monGARS/api/web_api.py, monGARS/api/AGENTS.md, scripts/export_openapi.py
API Request Flow
The following diagram illustrates the general flow of a request through the FastAPI application.
This diagram shows a typical request lifecycle, from client submission to response, including authentication, validation, and processing by core services.
Sources: monGARS/api/web_api.py, monGARS/api/schemas.py
OpenAPI Specification Generation
The openapi.json file is not generated dynamically by FastAPI at runtime. Instead, it is created and exported by the scripts/export_openapi.py script. This script imports the FastAPI app instance and uses app.openapi() to generate the schema, which is then written to the openapi.json file in the repository root. This approach ensures a stable and version-controlled API definition.
Sources: scripts/export_openapi.py:12-21
Authentication
The API uses OAuth2 with the Password Flow for authentication. Clients must first obtain a JWT bearer token by sending a POST request with a username and password to the /token endpoint. This token must then be included in the Authorization header for all protected endpoints.
Sources: monGARS/api/web_api.py:41-52, openapi.json
Token Acquisition Sequence
This diagram shows the sequence of events for a client to authenticate and receive a JWT access token.
Sources: monGARS/api/web_api.py:41-52, monGARS/api/AGENTS.md
Endpoints
The API is organized into several logical groups of endpoints, each prefixed and tagged for clarity in the OpenAPI documentation.
Sources: monGARS/api/web_api.py, openapi.json
Conversation Endpoints
These endpoints handle the core chat functionality.
| Method | Path | Summary |
|---|---|---|
POST | /api/v1/conversation/chat | Handles a user chat message |
GET | /api/v1/conversation/history | Retrieves conversation history |
Sources: monGARS/api/web_api.py:65-87, openapi.json
Chat Request Sequence
This diagram illustrates the flow for a chat message, including processing by core services and broadcasting the response via WebSockets.
Sources: monGARS/api/web_api.py:65-75
Model Management Endpoints
These endpoints are used to inspect and manage the LLM models used by the system. Access is restricted to admin users.
| Method | Path | Summary |
|---|---|---|
GET | /api/v1/models | Get available model configurations |
POST | /api/v1/models/provision | Trigger provisioning of LLM models |
Sources: monGARS/api/web_api.py:90-117, openapi.json
WebSocket Endpoint
The API provides a WebSocket endpoint for real-time communication.
| Path | Description |
|---|---|
/api/v1/ws | Establishes a WebSocket connection after verifying a ticket. Used for streaming events and chat updates. |
Connection to this endpoint requires a valid ticket obtained via a separate mechanism, as described in monGARS/api/AGENTS.md. The ws_manager handles message broadcasting and connection lifecycle.
Sources: monGARS/api/web_api.py:120-132, monGARS/api/AGENTS.md
Data Schemas
Pydantic models are used to define the data structures for API requests and responses. These models ensure that all data exchanged with the API is well-formed and validated.
Sources: monGARS/api/schemas.py, monGARS/api/AGENTS.md
Schema Class Diagram
This diagram shows the inheritance from Pydantic's BaseModel and the composition relationship between HistoryResponse and ChatMessage.
Sources: monGARS/api/schemas.py:10-75
Key Schemas
ChatRequest
This model represents the payload for a chat message sent to the /api/v1/conversation/chat endpoint.
| Field | Type | Description |
|---|---|---|
message | str | The user's text message. |
conversation_id | str (opt) | The ID of the existing conversation. |
parent_id | str (opt) | The ID of the parent message in the thread. |
file_paths | list[str] (opt) | Optional list of file paths for context. |
Sources: monGARS/api/schemas.py:11-17
ChatResponse
This model represents the response from the chat endpoint.
| Field | Type | Description |
|---|---|---|
response | str | The AI's response message. |
conversation_id | str | The ID of the conversation. |
parent_id | str | The ID of the user's message. |
message_id | str | The ID of the AI's response message. |
sources | list[str] | A list of sources used to generate the response. |
Sources: monGARS/api/schemas.py:20-27
HistoryResponse
This model represents the payload returned from the /api/v1/conversation/history endpoint.
| Field | Type | Description |
|---|---|---|
messages | list[ChatMessage] | A list of chat messages in the conversation. |
has_more | bool | Indicates if more messages are available for pagination. |
Sources: monGARS/api/schemas.py:65-68
API Clients and SDKs
The project provides official SDKs in Python and TypeScript to facilitate interaction with the API. These SDKs are built using the openapi.json specification and provide typed, asynchronous clients that cover the main endpoints, including authentication, chat, and model management.