Utility API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
Utility API Endpoints in the OpenPoke project serve as a bridge between the Next.js frontend and the FastAPI backend. These endpoints primarily function as proxies, handling request transformation, authentication context, and communication with the core Python services. They manage essential tasks such as chat message delivery, conversation history management, timezone synchronization, and Gmail integration lifecycle (connection, status, and disconnection).
Chat and History Management
The chat utility endpoints facilitate the core interaction between the user and the AI assistant. The system uses a proxy pattern to forward messages from the React-based UI to the high-level interaction agent.
Chat Message Proxy
The /api/chat endpoint transforms UI message formats into OpenAI-compatible structures before forwarding them to the backend. It extracts text content from complex message "parts" used in the frontend and wraps them for the FastAPI chat service.
Sources: web/app/api/chat/route.ts:7-24, web/app/api/chat/route.ts:39-44
Conversation History
History endpoints support both retrieval (GET) and deletion (DELETE) of chat logs. The frontend utilizes these to populate the chat interface on load and provides a "Clear History" feature to reset the agent's memory.
Sources: web/app/api/chat/history/route.ts:4-28, web/app/page.tsx:47-56
Request Flow
The following diagram illustrates how a user message moves through the utility proxy to the backend.
The diagram shows the transformation of data from the frontend format to the backend requirement within the proxy layer.
Sources: web/app/api/chat/route.ts:26-61
Gmail Integration Utilities
These endpoints manage the OAuth and connection lifecycle for Gmail through the Composio service. They act as a specialized proxy for external integration management.
Connection and Status
The connection endpoints handle the initial handshake and ongoing status checks for the user's Gmail account. They require specific identifiers like authConfigId or connectionRequestId to interact with the backend services.
| Endpoint | Method | Required Body Parameters | Purpose |
|---|---|---|---|
/api/gmail/connect | POST | userId, authConfigId | Initiates Gmail OAuth flow via Composio |
/api/gmail/status | POST | userId, connectionRequestId | Checks the health/auth status of the link |
/api/gmail/disconnect | POST | userId, connectionId | Terminates the service integration |
Sources: web/app/api/gmail/connect/route.ts:4-24, web/app/api/gmail/status/route.ts:4-25, web/app/api/gmail/disconnect/route.ts:4-31
System Synchronization
Timezone Detection
A critical utility endpoint is used to synchronize the user's local timezone with the server. On initial load, the frontend detects the browser timezone using Intl.DateTimeFormat and sends it to the /api/timezone utility. This ensures that the agent's scheduling and email processing (e.g., RRULE generation) are contextually accurate for the user.
Sources: web/app/page.tsx:63-91
Configuration Handling
The utility endpoints utilize environment variables to resolve the backend location and specific service paths.
const serverBase = process.env.PY_SERVER_URL || 'http://localhost:8001';
const serverPath = process.env.PY_CHAT_PATH || '/api/v1/chat/send';
Sources: web/app/api/chat/route.ts:35-37
Conclusion
The Utility API Endpoints form the operational backbone of the OpenPoke web architecture. By abstracting the complexities of backend communication, timezone synchronization, and third-party integration (Gmail/Composio) into standardized Next.js API routes, the system ensures a decoupled and maintainable bridge between the multi-agent backend and the user interface.