HTTP API Reference

When you run npm run dev:all, the documentation site serves on http://localhost:3001  and proxies the Next.js API under http://localhost:3001/api. (If you run only npm run dev, use http://localhost:3000/api.)

All routes live in src/app/api/**/* and are implemented as Route Handlers using the Repository and ActionResult patterns.

Authentication & Rate Limiting

• Identity – Each request reuses the Supabase session cookies (sb-access-token, sb-refresh-token). Server routes call getUser() to enforce auth.
• Admin boundaries – Admin endpoints assume the authenticated user already passed through the /admin middleware (we only expose them from the admin UI).
• Rate limits – src/app/lib/api-rate-limit.ts enforces per-route quotas:
  • AI chat: 20 requests/min per user (api-ai-chat).
  • AI upload: 5 uploads/hour per user (api-ai-upload).
  • Checkout: 5 sessions / 15 min per IP (api-stripe-checkout).
  • Image upload: 10 uploads/hour.
  • Webhooks: 100 events/min per provider.

Each response includes X-RateLimit-* headers when available.

AI Routes

/api/ai/chat (POST, SSE)

• Body (application/json):
  • conversationId? (uuid)
  • message (required string)
  • provider? (openai, gemini, ollama)
  • modelName?, systemPrompt?, temperature?, maxTokens?
  • imageData? { base64, mimeType } for vision models
• Response: text/event-stream. Every data: chunk contains { type: "delta" | "end" | "error", payload: StreamChunk }.
• Behavior: Creates a conversation if absent, saves the user message, optionally augments with RAG context, routes to the selected provider via StrategyRouter, and writes assistant messages back into Supabase.

curl -N \
  -H "Content-Type: application/json" \
  -b "sb-access-token=..." \
  -X POST http://localhost:3001/api/ai/chat \
  -d '{"message":"Summarize projects","provider":"openai"}'

/api/ai/upload (POST, multipart/form-data)

Fields:

• file – File blob (PDF, TXT, DOCX…)
• conversationId – Target conversation UUID
• skipEmbeddings? – true to store only metadata
• chunkSize? – Defaults to 1000 tokens
• chunkStrategy? – Defaults to “recursive”

Flow: validates file type/size, uploads to ai-documents bucket, persists metadata through DocumentRepository, extracts text, and (unless skipped) generates embeddings via DocumentProcessor.

/api/ai/share (POST, JSON)

Body: { "conversationId": "uuid", "title?": "optional" }

Returns { success: true, shareUrl, token } where shareUrl points to /ai/shared/{token}. Tokens are base64 payloads containing conversation and user identifiers; treat them as secret and expire them when revoking shares.

Admin Routes

curl -X POST http://localhost:3001/api/admin/upload-image \
  -H "Content-Type: application/json" \
  -b "sb-access-token=..." \
  -d '{"file":"data:image/png;base64,iVBORw0KGgo...","filename":"hero.png"}'

Stripe Integrations

/api/stripe/create-checkout

Body:

{
  "priceId": "price_123",
  "isSubscription": false,
  "locale": "en",
  "successUrl": "https://example.com/en/loja/success",
  "cancelUrl": "https://example.com/en/loja/cancelled",
  "metadata": { "templateId": "landing-pro" }
}

Response:

{ "sessionId": "cs_test_...", "url": "https://checkout.stripe.com/c/pay/cs_test..." }

Internals: getStripeClient() creates the session, metadata is normalized via buildStripeMetadata, and payment types include both card and boleto when not subscription.

/api/stripe/webhook

• Expects Stripe signatures via stripe-signature header.
• Replays events through stripe.webhooks.constructEvent and branches on:
  • checkout.session.completed – mark purchases successful, revalidate caches.
  • customer.subscription.created|updated|deleted – sync subscription state.
  • invoice.payment_succeeded|failed – log billing telemetry.

Always return 200 quickly; perform heavy work via server actions/repositories.

Resend Webhook

Requirements:

• Headers svix-id, svix-timestamp, svix-signature.
• Environment variable RESEND_WEBHOOK_SECRET.
• Responds with 401 on failed verification.

Testing the API

• Unit/Integration: src/app/test/integration/api/** contains Vitest suites mocking Supabase/Stripe/Resend clients.
• E2E: Playwright specs hit /api/ai/chat through the UI. Run npm run e2e:debug to watch SSE streaming in a real browser.
• Manual: Use the cURL snippets above or tools like HTTPie/Postman against http://localhost:3001/api.

Keep this reference current whenever you add or rename Route Handlers so the CLI and partners know which payloads and headers to provide.