API Reference

RAG-DocBot exposes a RESTful HTTP API. Interactive documentation (Swagger UI) is available at http://<host>:8000/docs.

---

Endpoints

Health

Method	Endpoint	Auth	Description
GET	/api/health	Public	Returns service health status

Authentication

Method	Endpoint	Auth	Description
POST	/api/auth/login	Public	Login and receive access + refresh tokens
POST	/api/auth/refresh	Public	Exchange a refresh token for a new access token
GET	/api/auth/me	Required	Get the current authenticated user
GET	/api/auth/users	Admin	List all users
POST	/api/auth/users	Admin	Create a new user
GET	/api/auth/users/{id}	Admin	Get a specific user
PUT	/api/auth/users/{id}	Admin	Update a user's password or role
DELETE	/api/auth/users/{id}	Admin	Delete a user
PUT	/api/auth/password	Required	Change the current user's password

Chat

Method	Endpoint	Auth	Description
POST	/api/chat	Required	Send a message and receive an AI response grounded in indexed documents. Supports SSE streaming via Accept: text/event-stream.

Standard (JSON) response

Add Content-Type: application/json or omit the Accept header to receive a single JSON object.

Response fields (selected):

Field	Type	Description
answer	string	The AI-generated answer
sources	array	Source chunks used to ground the answer
token_budget	object | null	Token budget diagnostics (see below)
retrieval_settings	object	Effective retrieval settings used for this query
timing	object	Per-stage timing information (classify, retrieve, generate)

token_budget object:

Field	Type	Description
limit	integer	Maximum tokens allowed in the context window
estimated_prompt	integer	Estimated tokens consumed by the assembled prompt
reserved_completion	integer	Tokens reserved for the model's completion
chunks_dropped	integer	Number of low-relevance chunks trimmed to fit the budget

token_budget is null when budget management was not applied (e.g. the prompt fit within the limit with no trimming needed).

SSE streaming response

Set Accept: text/event-stream to receive the answer as a stream of Server-Sent Events. The request body is identical to the standard JSON mode.

POST /api/chat HTTP/1.1
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{"query": "What is the refund policy?", "conversation_id": "..."}

Each event carries a JSON payload:

Event type	Payload	Description
delta	{"text": "..."}	Next token(s) from the LLM
done	{"sources": [...], "token_budget": {...}, "retrieval_settings": {...}, "timing": {...}}	Stream complete — same metadata fields as the JSON response
error	{"detail": "..."}	Pipeline error; stream is closed after this event

Conversation history is persisted after the stream completes, identical to non-streaming mode.

Documents

Method	Endpoint	Auth	Description
POST	/api/docs/upload	Editor+	Upload a document for indexing
GET	/api/docs	Required	List all indexed documents
DELETE	/api/docs/{id}	Editor+	Delete a document
DELETE	/api/docs/bulk	Editor+	Delete multiple documents

Connectors

Method	Endpoint	Auth	Description
GET	/api/connectors	Required	List connectors
POST	/api/connectors	Admin	Create a connector
GET	/api/connectors/{id}	Required	Get a connector
PUT	/api/connectors/{id}	Admin	Update a connector
DELETE	/api/connectors/{id}	Admin	Delete a connector
POST	/api/connectors/{id}/scan	Editor+	Trigger a connector scan
POST	/api/connectors/sync-all	Editor+	Sync all connectors

Metadata Rules

Method	Endpoint	Auth	Description
GET	/api/metadata/{source_id}/rules	Required	List all metadata extraction rules for a source
POST	/api/metadata/{source_id}/rules	Editor+	Create a new metadata rule
PUT	/api/metadata/{source_id}/rules/{rule_id}	Editor+	Update a metadata rule
DELETE	/api/metadata/{source_id}/rules/{rule_id}	Editor+	Delete a metadata rule
POST	/api/metadata/{source_id}/test-rule	Editor+	Test a pattern against sample text without saving
POST	/api/metadata/{source_id}/refresh	Editor+	Re-apply rules to existing chunks (async job)

source_id can be either a connector ID or an integration ID.

Metadata Rules endpoints require a Pro plan or higher.

Metadata rule fields:

Field	Type	Required	Description
field_name	string	Yes	The metadata key to extract (e.g. artikel, entity_id)
pattern	string	Yes	Python regex with one capture group — used during document ingestion
query_pattern	string | null	No	Optional separate regex used at query-time classification. When omitted, pattern is used for both ingestion and queries
scope	string	Yes	Where to search: full, header, or filename
level	string	Yes	document (once per document) or chunk (per chunk with inheritance)
chunk_boundary	boolean	No	When true, rule matches act as document pre-split boundaries during indexing. Default false.
priority	integer	No	Higher numbers are evaluated first; default 0
source_id	string	Response	Source identifier in responses (connector or integration ID)
source_type	string	Response	Source type in responses: connector or integration

Analytics

All Analytics endpoints require a Pro plan or higher.

Method	Endpoint	Auth	Description
GET	/api/analytics/{source_id}/chunk-size-distribution	Required	Histogram of chunk character lengths with summary stats
GET	/api/analytics/{source_id}/metadata-hit-rate	Required	Per-rule match rate across documents/chunks
GET	/api/analytics/{source_id}/metadata-coverage	Required	Per-field metadata coverage ratio
GET	/api/analytics/{source_id}/chunks-per-document	Required	Chunks produced per document with summary stats
GET	/api/analytics/{source_id}/inheritance-ratio	Required	Self-matched vs inherited vs empty breakdown for chunk-level rules
GET	/api/analytics/{source_id}/empty-metadata	Required	Count of chunks with no metadata and sample document IDs
GET	/api/analytics/{source_id}/rule-priority-audit	Required	Rule winner counts for overlapping field priorities

Index

Method	Endpoint	Auth	Description
GET	/api/index/stats	Required	View vector index statistics
POST	/api/index/rebuild	Editor+	Rebuild the entire vector index

Jobs

Method	Endpoint	Auth	Description
GET	/api/jobs	Required	List background jobs
GET	/api/jobs/{id}	Required	Get a specific job
POST	/api/jobs/{id}/cancel	Editor+	Cancel a running job

Integrations

Method	Endpoint	Auth	Description
GET	/api/integrations	Required	List integrations
POST	/api/integrations	Admin	Create an integration
GET	/api/integrations/{id}	Required	Get an integration
PUT	/api/integrations/{id}	Admin	Update an integration
DELETE	/api/integrations/{id}	Admin	Delete an integration
POST	/api/integrations/{id}/sync	Editor+	Trigger an integration sync

Job Schedules

Job Schedules endpoints require a Pro plan or higher.

Method	Endpoint	Auth	Description
GET	/api/schedules	Admin	List all configured job schedules
POST	/api/schedules	Admin	Create a new schedule (connector or integration sync)
GET	/api/schedules/{id}	Admin	Get a specific schedule
PUT	/api/schedules/{id}	Admin	Update a schedule (cron expression, enabled flag)
DELETE	/api/schedules/{id}	Admin	Delete a schedule

Schedule fields:

Field	Type	Description
source_type	string	connector or integration
source_id	string	ID of the connector or integration to sync
cron	string	Cron expression (e.g. 0 2 * * * for daily at 02:00 UTC)
enabled	boolean	Whether the schedule is active
last_run	string | null	ISO-8601 timestamp of the last triggered run
next_run	string | null	ISO-8601 timestamp of the next scheduled run

Audit Log

Audit Log endpoints require an Enterprise plan.

Method	Endpoint	Auth	Description
GET	/api/audit	Admin	Query the audit log (supports filtering by event type, user, and date range)
GET	/api/audit/{id}	Admin	Get a specific audit log entry
GET	/api/audit/config	Admin	Get current retention policy configuration
PUT	/api/audit/config	Admin	Update the retention policy

Audit event types:

Event	Description
chat.query	User submitted a chat query
sync.all	Sync-all triggered (connector or integration)
config.update	System configuration changed
license.apply	License key applied or updated
user.create / user.delete	User created or deleted

Audit entries are append-only — individual records cannot be modified or deleted. The retention policy controls the maximum age of entries kept in Postgres.

Conversations

Method	Endpoint	Auth	Description
GET	/api/conversations	Required	List conversations
GET	/api/conversations/{id}	Required	Get a specific conversation

Branding

Method	Endpoint	Auth	Description
GET	/api/branding	Public	Get branding configuration
GET	/api/branding/logo	Public	Get branding logo
PUT	/api/branding	Admin	Update branding configuration
POST	/api/branding/logo	Admin	Upload a branding logo

License

Method	Endpoint	Auth	Description
GET	/api/license	Required	Get license information and current plan
POST	/api/license	Admin	Apply or update the license key

Hardware & Model

Method	Endpoint	Auth	Description
GET	/api/hardware	Required	Get hardware information (CPU, GPU, memory)
GET	/api/model-info	Required	Get loaded model information

---

Interactive API Docs

Swagger UI is available at http://<host>:8000/docs and provides a full interactive reference with request/response schemas and the ability to test endpoints directly in the browser.