Skip to main content

Kodda Docs

Build, ship, and operate grounded AI bots with predictable limits.

This page is aligned with Kodda's server-enforced behavior: plans, ingestion constraints, API request contracts, and security policies.

Tutorial

Follow one end-to-end path to launch your first bot.

How-to

Apply repeatable workflows for ingestion and deployment.

Reference

Use exact limits, endpoint fields, and environment keys.

Explanation

Understand quotas, billing behavior, and guardrails.

Quickstart

  1. Create a workspace and activate a paid plan (default state is FREE).
  2. Create one Library and upload source files (max 5MB per file).
  3. Create a Bot and attach one or more Libraries.
  4. Publish the Bot for public link access or website embedding.
  5. For private programmatic access, create API keys on Pro and call /api/chat.

RAG Pipeline

Document Upload

Validate MIME + file signature, then persist a processing record.

Text Extraction

Parse PDF/DOCX/DOC/TXT/MD/CSV/JSON/XLSX/HTML/PPTX into plain text.

Chunking + Embedding

Split text into chunks and generate vectors via OpenAI-compatible embedding API.

Vector Search

Retrieve the most relevant chunks by semantic similarity and optional rerank.

Grounded Response

Generate answer + source list, with monthly usage enforcement.

Plan Matrix (Public Beta)

Limits are enforced server-side in bot, library, document, and chat APIs. Pro plan includes a 7-day free trial.

FeatureFreePro
Bots13
Libraries13
Storage15MB50MB
Messages / Month1005,000
Estimated Knowledge Base Pages10,00025,000
Public LinkYesYes
Website EmbedNoYes
API KeysNoYes
Platform IntegrationsNoYes
Remove BrandingNoYes
Auto-SyncNoYes
Advanced AnalyticsNoYes

Pro Paid Features

  • API Keys: Programmatic access via REST API with secure key authentication.
  • Remove Branding: Hide "Powered by Kodda" from embedded widgets.
  • Custom Rate Limiting: Configure per-bot request throttling.
  • Integrations: Connect to Slack, Discord, Zapier, and more.

Ingestion Spec

Supported Extensions

.PDF.DOCX.DOC.TXT.MD.CSV.JSON.XLSX.HTML.HTM.PPTX

Hard Limits

  • Single file max size: 15MB.
  • Workspace storage quota is enforced by plan.
  • Chunk count guardrail is enforced for each bot.

Upload validation includes MIME checks and content signature checks (for example PDF header, Office zip signatures, JSON parse validation, and text-binary safety checks).

Chat API Contract

Endpoint: POST /api/chat

  • Private bot: pass x-api-key header (Pro).
  • Published public bot: request can be unauthenticated (session-guarded).
  • Supports both single message and full messages array for conversation history.

Request with Messages Array (Recommended)

request-with-messages.sh
curl -X POST https://kodda.dev/api/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "botId": "BOT_ID",
    "messages": [
      { "role": "user", "content": "Hi, who are you?" },
      { "role": "assistant", "content": "I am your AI assistant." },
      { "role": "user", "content": "Summarize refund policy" }
    ],
    "stream": false
  }'

Request with Single Message

request-single-message.sh
curl -X POST https://kodda.dev/api/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "botId": "BOT_ID",
    "message": "Summarize refund policy",
    "conversationId": "optional_existing_conversation_id",
    "stream": false
  }'

Response

response.json
{
  "answer": "Refunds are accepted within 30 days...",
  "sources": [
    { "filename": "policy.pdf", "libraryName": "Product Docs", "score": 0.92, "content": "Relevant snippet..." }
  ],
  "conversationId": "c_123",
  "latencyMs": 842
 }

Request Parameters

botIdRequired. The bot ID to query.
messageSingle message string (use this OR messages).
messagesArray of { role, content } objects for conversation history. Last message must be from user.
conversationIdOptional. Continue an existing conversation. Ignored if messages is provided.
streamBoolean. Default false. If true, returns SSE events.

Streaming mode (stream=true) emits SSE events: sources, token, done, and error.

API Reference

Authentication

Pass your API key in the x-api-key header or Authorization Bearer header. API keys are available on STARTER plans and above.

curl -H "x-api-key: kodda_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST https://kodda.dev/api/chat \
  -d '{"botId": "...", "message": "..."}'

Response Conventions

2xxSuccess — JSON payload
4xxValidation or auth failure — { error: string }
5xxServer error — { error: string }

API Reference — Live Playground

Test any endpoint directly from your browser. Enter your API key, fill in parameters, and hit Send Request. Codes are generated automatically in cURL, JavaScript, and Python.

/chat

/feedback

Security and Guardrails

  • Plan gates are server-enforced for bots, libraries, documents, and chat quotas.
  • Chat usage is atomically incremented and rolled back on generation failure.
  • API keys are validated by secure hash lookup before request execution.
  • CORS whitelist is enforced for published bots when configured.
  • RevenueCat webhook sync is used as the source of billing entitlement truth.

REST API Integration

Request schema, auth setup, and integration examples.

Open guide

Website Chat Integration

Publish bots and embed chat with iframe or embed.js.

Open guide

Need clarification? Contact support@kodda.dev.