Skip to content
khanhthanhdev edited this page Jun 2, 2026 · 1 revision

API

AI Knowledge Cloud exposes four API route groups under app/api/. All endpoints are protected by same-origin validation and rate limiting.

Endpoints

Route Method Purpose
/api/chat POST Streaming AI chat with tool context and semantic caching
/api/rag POST RAG retrieval for tool context
/api/inngest POST Inngest webhook for background job events
/api/auth/[...nextauth] GET/POST NextAuth.js authentication handlers

Chat API (/api/chat)

The primary user-facing API. Accepts a conversation history and returns a streamed AI response powered by Google Gemini.

Request body:

{
  "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "..." }] }],
  "toolSlug": "optional-tool-slug",
  "locale": "en"
}

Constraints:

  • Max 40 messages per request
  • Max 8,000 characters per message text
  • Max 50 parts per message
  • Locale: en or vi

Rate limits:

  • 10 requests per minute per IP
  • 50 requests per day per IP

Flow:

  1. Same-origin check (reject cross-origin POSTs)
  2. Rate limit check
  3. Parse and validate request with Zod schema
  4. Check semantic cache for cached answer
  5. If cache miss, stream response from Google Gemini
  6. Store completed answer in semantic cache asynchronously

The chat supports tool-scoped conversations (when toolSlug is provided, the system prompt includes context about that specific tool) and global conversations.

Key files:

  • app/api/chat/route.ts -- Chat endpoint handler
  • lib/rate-limit.ts -- Rate limiting with IP resolution
  • lib/semantic-cache.ts -- Answer caching
  • services/ai-chat-tools.ts -- YouTube search tool available to the LLM

RAG API (/api/rag)

Provides retrieval-augmented generation for tool-related queries. Uses the fused query router to classify intent and applies the appropriate retrieval strategy.

Key files:

  • app/api/rag/route.ts -- RAG endpoint handler
  • lib/rag.ts -- RAG pipeline with query routing
  • lib/fused-query-router.ts -- Intent classification

Inngest webhook (/api/inngest)

Receives events from Inngest and dispatches them to the registered functions. This is the bridge between Inngest's event system and the application's background job handlers.

Key files:

  • app/api/inngest/route.ts -- Inngest webhook handler
  • services/inngest.ts -- Inngest client and function registration
  • functions/ -- All job function implementations

See Background jobs for details on each job.

Authentication (/api/auth/[...nextauth])

NextAuth.js handlers for Google OAuth login. Used by the admin dashboard.

Key files:

  • app/api/auth/[...nextauth]/route.ts -- NextAuth route handler
  • lib/auth.ts -- Auth configuration
  • lib/auth.config.ts -- Auth provider config

Security

All API endpoints enforce:

  • Same-origin validation -- POST requests must originate from the same domain
  • Rate limiting -- per-IP limits with sliding window
  • Input validation -- Zod schemas on all request bodies
  • Security headers -- applied by Caddy reverse proxy (HSTS, X-Frame-Options, CSP, etc.)

See Deployment for header configuration and Background jobs for Inngest security.

Clone this wiki locally