Developer Documentation

1. Create an API Key

Go to Settings > API Keys in your dashboard and create a new key. Save it securely, it's only shown once.

2. Copy the snippet

Paste this code before the closing </body> tag in your HTML. Replace YOUR_API_KEY with your actual key.

<script
  src="https://citai.ai/widget.js"
  data-api-key="sk-YOUR_API_KEY"
  data-base-url="https://citai.ai"
  data-lang="EN">
</script>

3. Done

The widget will appear as a floating bubble on your site. Visitors can chat with your knowledge base instantly.

Create & upload documents

Each Knowledge Base (KB) is a document container with its own RAG configuration.

• Go to Knowledge Bases in the sidebar and click 'New KB'
• Upload documents by dragging files or pasting a URL (HTML, PDF, DOCX)
• Processing (chunking + embeddings) happens in the background with progress tracking

Access control

Each KB has a visibility level that determines who can query it.

Document processing

When you upload a document, Citai processes it automatically in multiple stages.

• Chunking: splits the document into semantic fragments of configurable size
• Embeddings: generates 384-dimension vectors with a multilingual model (ES/EN/PT/DE/FR/IT)
• Contextual Retrieval: optionally enriches each chunk with full document context via LLM

Manual creation

Create FAQs one by one from the FAQ section of each Knowledge Base. Define question, answer and optionally multimedia attachments (images, videos, links).

Bulk import (CSV)

Import hundreds of FAQs from a CSV file with columns: question, answer, category. Ideal for migrations or existing knowledge bases.

Multimedia & attachments

Each FAQ can include images (with crop editor), videos and links. Image limits depend on the plan: Starter 3/FAQ, Pro 5/FAQ, Enterprise 10/FAQ.

Auto-suggested FAQs

Citai detects recurring unanswered queries and automatically generates suggested FAQs using AI. Admins can approve or reject them from the suggested FAQs panel.

Matching flow

When a user asks a question, the system searches for similar FAQs before querying the LLM.

Creating API Keys

Generate keys with the sk- prefix from Dashboard > API Keys. Each key is associated with specific Knowledge Bases and can be configured with allowed CORS origins.

Security

API keys are shown only once upon creation. They are stored hashed with SHA-256 in the database. If you lose a key, you must regenerate it.

Rate Limiting

Each API key has a per-minute request limit implemented with Redis sliding window (sorted sets). If the limit is exceeded, HTTP 429 is returned. If Redis is unavailable, rate limiting fails open.

Dynamic CORS

Each API key can have configured allowed origins. The CORS middleware validates the origin of each request against the key's list. This ensures the widget only works on authorized domains.

How it works

When a widget visitor needs human help (due to low confidence or manual escalation), the session enters a waiting queue. A team agent can claim the session from the Live Chat panel and respond in real time via SSE.

Session states

Agent panel

Agents access the panel from the sidebar to manage live chat sessions.

• Waiting queue: sessions pending to be claimed
• Active sessions: ongoing conversations with the agent
• History: resolved sessions with complete records

When it triggers

Handoff triggers automatically when response confidence is below the configured threshold, or manually when the visitor clicks the escalation button. Concurrency is handled with SELECT FOR UPDATE to prevent two agents from claiming the same session.

How it works

Smart Routing computes centroids (average embeddings) of each KB and compares the user's query against these centroids using cosine similarity. It selects the top-3 most relevant KBs.

Usage in Chat & Widget

In chat, enable the 'Auto' toggle to use Smart Routing. It disables automatically when you manually select a KB. In the widget, auto-routing applies when the API key has access to multiple KBs.

Interactive charts

Visualize your assistant's performance with Chart.js charts.

• Time series: queries per day/week/month with range filters
• Resolution doughnut: resolved, escalated and negative
• Horizontal bars: tag distribution with per-conversation detail

Knowledge gap detection

The system identifies queries that didn't get good answers and groups them by frequency. You can mark them as resolved, filter by KB or generate suggested FAQs directly.

AI auto-tagging

Each conversation is automatically tagged with one of 15 canonical categories using a background LLM call (fire-and-forget). Tags are used for analytics and filtering.

Data export

Export all analytics metrics in CSV or JSON format from the export button on the dashboard. Includes queries, resolution, costs, tags and knowledge gaps.

Revenue vs Cost (super admin)

Super admin exclusive view showing revenue, costs, profit and margin per tenant. Includes global totals cards and a detailed per-organization table.

Download a ZIP file with all your organization's data: conversations, FAQs, documents, configurations and usage logs. Available from Settings > Account.

Request account deletion with password confirmation. A soft delete is performed, marking data for permanent deletion according to the retention policy.

Retention policies are configurable by the administrator. Define how long conversations, audit logs and widget session data are kept.

Records over 15 event types (login, creation, deletion, config changes). Configurable retention with date-based purge. Accessible from the admin panel.

Stored data

Citai stores the following data, all isolated per tenant:

• Conversations and messages (with confidence metadata and sources)
• Original documents and their processed chunks
• Vector embeddings (384 dimensions) associated with chunks and FAQs
• Usage logs (queries, tokens, provider, query type) and audit logs

How to request export or deletion

From the app: go to Settings > Account to export data or request deletion. By email: contact [email protected] with your registered email address.

How it works

Images are extracted during document processing, filtered (min 50x50px, dedup by hash, max 50/doc), and associated with chunks by page proximity. At runtime, images are included in the SSE sources event with zero latency impact.

SSE format: sources with images

The 'sources' event now includes an 'images' array in each source that has associated images:

{
  "sources": [{
    "document_name": "manual.pdf",
    "page": 21,
    "score": 0.73,
    "images": [
      { "url": "/api/v1/doc-images/.../img.jpg", "caption": null, "width": 800, "height": 600 }
    ]
  }]
}

RAG Configuration

Extraction is controlled via processing.extract_images (default: true). Can be toggled per-KB from the RAG Configuration dialog.

{
  "processing": {
    "extract_images": true
  }
}

Image Manager Endpoints

When it runs

After FAQ matching and before the RAG pipeline. Cache hits emit 'cached: true' in the SSE done event and are counted as query_type='cached' in usage_logs. Automatic invalidations happen on document reprocessing, FAQ create/update, and new doc upload.

RAGConfig parameters

Configurable per KB inside the retrieval block. Default: cache enabled with a 7-day TTL (168 hours). Valid range: 1 to 720 hours.

{
  "retrieval": {
    "cache_enabled": true,
    "cache_ttl_hours": 168
  }
}

Endpoints

Components

Each component returns a 0-100 score with detailed breakdown (counts and averages). The final score is the weighted average.

Endpoints

Smart Routing

When an API key has multiple KBs or the user enables 'Auto' in chat, route_query() compares the query embedding against each KB centroid (AVG of chunk embeddings) using cosine similarity. Returns up to top 3 KBs with score >= 0.15. Centroids cached in Redis for 24h.

Flow

1) A query is logged as a knowledge gap. 2) Admin invokes suggest-faq (single or batch top 5). 3) The service skips queries with an existing similar FAQ (>= 0.85) or pending suggestion. 4) Calls the LLM to generate an answer from the KB context. 5) Stores in suggested_faqs with embedding. 6) Admin approves or rejects from the UI.

Endpoints

Rule types

• BLOCKBLOCK — cuts the flow and emits SSE content_blocked with the custom response. Evaluated after FAQ + cache, before RAG.
• REDIRECTREDIRECT — same as block but with type='redirect' (e.g. handoff to human support).
• FILTERFILTER — does not cut the flow. Applied to retrieved chunks before passing them to the LLM, removing those that contain the triggers.

Schema in rag_config

Each rule has type, list of triggers (keywords that fire it), optional response (max 500 chars, only for block/redirect) and enabled.

{
  "content_rules": [
    {
      "type": "block",
      "triggers": ["password", "credit card"],
      "response": "I can't help with that.",
      "enabled": true
    },
    {
      "type": "filter",
      "triggers": ["internal-only"],
      "enabled": true
    }
  ]
}

SSE event content_blocked

Emitted when a query matches a BLOCK or REDIRECT rule. The widget and chat have native handlers to display the response without invoking the LLM.

event: content_blocked
data: {"type": "block", "response": "I can't help with that."}

Endpoints

Tracked actions

The backend emits these action keys via audit_service. You can filter by any of them.