API Reference

RAG Engine exposes a REST API for direct integration and 5 MCP tools through the gateway for AI agent access.

Prefer the CLI?

The AppXen CLI is the easiest way to work with RAG Engine. Batch-upload entire directories, search from the terminal, and manage your knowledge base without writing any HTTP code.

pip install appxen

Authentication

RAG Engine is accessed through MCP Gateway Pro. All requests require an API key passed as a Bearer token. Get your API key from the AppXen Console under API Keys. 

curl https://api.appxen.ai/api/rag/sources \
  -H "Authorization: Bearer axgw_live_k1_your_key_here"

Gateway REST endpoints

The gateway proxies all RAG Engine endpoints under the /api/rag/ prefix. Your API key handles authentication and tenant routing automatically.

Method Gateway Path Description
GET /api/rag/sources List sources
GET /api/rag/sources/:id Get source details
POST /api/rag/sources/ingest Ingest text content
POST /api/rag/sources/upload Upload file (multipart)
DELETE /api/rag/sources/:id Delete source and chunks
POST /api/rag/search Semantic search
GET /api/rag/chunks/:id Get chunk by ID
GET /api/rag/stats Knowledge base stats

REST API Endpoints

All endpoints are accessed through the gateway at https://api.appxen.ai/api/rag/. Your API key handles authentication and tenant routing automatically.

POST /api/rag/sources/ingest

Ingest text content synchronously. The content is parsed, chunked, embedded, and indexed in a single request. Returns the source ID and chunk count.

Request Body

{
  "content": "Your document text content here...",
  "filename": "refund-policy.md",
  "metadata": { "category": "policy" }
}

Response (200)

{
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "chunk_count": 12
}
POST /api/rag/sources/upload

Upload a file for asynchronous ingestion. The file is stored and queued for background processing. Returns HTTP 202 immediately. Poll GET /api/rag/sources/{source_id} to check status.

Request (multipart/form-data)

Field Type Description
file File The document file (max 100 MB)
metadata string (JSON) Optional metadata as JSON string

Response (202)

{
  "source_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
GET /api/rag/sources

List all sources in your knowledge base. Optionally filter by status.

Query Parameters

Param Type Description
status string Filter: queued, processing, ready, failed
limit integer Max results (default: 20)
offset integer Pagination offset (default: 0)

Response (200)

{
  "sources": [
    {
      "source_id": "550e8400-...",
      "filename": "refund-policy.md",
      "mime_type": "text/markdown",
      "chunk_count": 12,
      "status": "ready",
      "error_message": null,
      "metadata": { "category": "policy" },
      "created_at": "2026-02-07T12:00:00Z",
      "updated_at": "2026-02-07T12:00:05Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}
GET /api/rag/sources/{source_id}

Get a single source by ID. Returns the same source object shape as the list endpoint. Returns 404 if not found.

DELETE /api/rag/sources/{source_id}

Delete a source and all its chunks. Returns 204 No Content on success.

Response (200)

{
  "status": "deleted",
  "source_id": "550e8400-..."
}
POST /api/rag/search

Semantic search over your knowledge base. The query is embedded and matched against indexed chunks using cosine similarity.

Request Body

{
  "query": "What is the refund policy?",
  "top_k": 5,
  "filters": { "source_id": "550e8400-..." }
}

Response (200)

{
  "results": [
    {
      "chunk_id": "chunk-uuid",
      "source_id": "550e8400-...",
      "content": "Refund requests must be submitted within 30 days...",
      "score": 0.89,
      "metadata": { ... }
    }
  ],
  "count": 5
}
GET /api/rag/chunks/{chunk_id}

Get a specific chunk by ID. Useful for citation follow-up after a search query.

GET /api/rag/stats

Get knowledge base statistics including source count, chunk count, and storage usage.

Response (200)

{
  "source_count": 24,
  "chunk_count": 1847,
  "storage_bytes": 52428800,
  "sources_by_status": {
    "ready": 22,
    "processing": 1,
    "failed": 1
  }
}

MCP Tools

RAG Engine is exposed as a built-in MCP server (rag-engine) through MCP Gateway Pro. These tools are available to any AI agent connected to your gateway endpoint. Tool names are prefixed with rag-engine/ in the gateway's unified tool catalog.

knowledge_query

Search your knowledge base using natural language. Returns the most relevant document chunks with similarity scores and source citations.

Parameters

query string (required) Natural language search query
top_k integer Number of results (default: 5)
filters object Optional filters (e.g., source_id)
knowledge_ingest

Add a document to your knowledge base. Provide text directly via content, or upload a binary file via file_base64. Do not provide both.

Parameters

filename string (required) Filename for the document
content string Text content to ingest
file_base64 string Base64-encoded file for binary formats
metadata object Optional metadata to attach
knowledge_list_sources

List all indexed documents in your knowledge base.

Parameters

status string Filter: queued, processing, ready, failed
limit integer Max results (default: 20)
knowledge_delete_source

Delete a document and all its chunks from the knowledge base.

Parameters

source_id string (required) The ID of the source to delete
knowledge_get_chunk

Get a specific chunk by ID. Useful for citation follow-up when a search result references a chunk and the agent needs the full context.

Parameters

chunk_id string (required) The ID of the chunk to retrieve

Example: Full Workflow via MCP

Here is a complete workflow an AI agent would follow to ingest a document and then search it:

1. Ingest a document

curl -X POST https://api.appxen.ai/mcp \
  -H "Authorization: Bearer axgw_live_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "rag-engine/knowledge_ingest",
      "arguments": {
        "filename": "company-faq.md",
        "content": "# FAQ\n\n## Refund Policy\nRefund requests must be submitted within 30 days..."
      }
    },
    "id": 1
  }'

2. Search the knowledge base

curl -X POST https://api.appxen.ai/mcp \
  -H "Authorization: Bearer axgw_live_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "rag-engine/knowledge_query",
      "arguments": {
        "query": "How do I get a refund?",
        "top_k": 3
      }
    },
    "id": 2
  }'

What's Next?