API reference

Complete specification for the RAGDC REST API.

Base URL

All API requests are made to https://ragdc.aivault.asia/api/v1. Every endpoint is POST, JSON over HTTPS.

Authentication

Include your API key in the Authorization header of every request.

Authorization: Bearer sk_...

Keys are created in the dashboard under API Keys. Revoked keys stop working immediately.

Conventions

Every response uses the envelope { "code", "message", "data" } — code 200 means success, non-zero is an error.
Each API key is rate-limited to 120 requests per minute.
Document ingestion is asynchronous: upload returns status "queued"; poll doc/list until status is "ready" (queued → processing → ready, or failed).
A key only reaches knowledge bases owned by its tenant, each stored in an isolated collection. /retrieve is free; /ask and chat consume credits.

Endpoints

All endpoints are POST and require the Authorization header above.

Retrieval

Retrieval-as-a-service: return the relevant chunks with sources, no LLM answer.

POST/api/v1/retrieve

Hybrid retrieval + rerank, returns ranked chunks. Body: knowledgeBaseId, query, topK, mode (quality | fast).

Q&A

Grounded answers from a knowledge base, with citations and token usage.

POST/api/v1/ask

One-shot RAG answer — retrieve + LLM answer + sources, no conversation needed. Body: knowledgeBaseId, question, model (optional).

POST/api/v1/chat/conversations/create

Create a persistent conversation bound to a knowledge base.

POST/api/v1/chat/messages/send

Send a message in a conversation and get a RAG answer with citations.

POST/api/v1/chat/messages/list

List the messages of a conversation.

Knowledge bases

Create and manage the knowledge bases that scope retrieval — one per isolation unit.

POST/api/v1/kb/create

Create a knowledge base. Body: name, description (optional).

POST/api/v1/kb/list

List the tenant's knowledge bases.

POST/api/v1/kb/detail

Get one knowledge base by id.

POST/api/v1/kb/update

Rename or update a knowledge base. Body: id, name, description.

POST/api/v1/kb/delete

Delete a knowledge base (soft delete + vector cleanup). Body: id.

Documents

Upload files into a knowledge base and track ingestion. Ingestion is asynchronous.

POST/api/v1/doc/upload

Upload a file (multipart/form-data). Fields: knowledgeBaseId, file. Returns a document with status "queued".

POST/api/v1/doc/list

List documents in a knowledge base with their ingestion status.

POST/api/v1/doc/detail

Get one document by id, including status and chunk count.

POST/api/v1/doc/delete

Delete a document and its vectors.

Examples

The two most common calls for an external integration, plus async upload.

POST /api/v1/retrieve
Authorization: Bearer sk_xxx
Content-Type: application/json

{
  "knowledgeBaseId": "kb-uuid",
  "query": "投标资质要求",
  "topK": 8,
  "mode": "fast"          // fast = 跳过 rerank,~一瞬;quality = 带精排,~8s
}

→ {
  "code": 200,
  "data": {
    "chunks": [
      { "text": "...", "source": "spec.pdf", "page": 1,
        "score": 0.83, "kbId": "kb-uuid", "documentId": "doc-uuid" }
    ],
    "count": 8,
    "usage": { "retrievalMs": 11 }
  }
}

POST /api/v1/ask
Authorization: Bearer sk_xxx
Content-Type: application/json

{
  "knowledgeBaseId": "kb-uuid",
  "question": "本项目对投标人的资质有什么要求?",
  "model": "claude-sonnet-4-6"   // 可选,留空走默认模型
}

→ {
  "code": 200,
  "data": {
    "answer": "...",                       // 基于知识库的成稿回答
    "sources": [ { "source": "spec.pdf", "documentId": "doc-uuid" } ],
    "model": "claude-sonnet-4-6",
    "usage": { "tokensInput": 772, "tokensOutput": 85 }
  }
}

POST /api/v1/doc/upload
Authorization: Bearer sk_xxx
Content-Type: multipart/form-data

  knowledgeBaseId = kb-uuid
  file            = @contract.pdf

→ { "code": 200, "data": { "id": "doc-uuid", "status": "queued" } }

# 入库是异步的,轮询 /api/v1/doc/list 直到 status = "ready"
#   queued → processing → ready   (失败为 failed)