POST Knowledge Bases & Vector Search API
/api/v1/knowledge-bases
Manage AI knowledge bases, index FAQs, plain text, and PDF documents, and perform grounded vector search & Q&A.
Architecture Role & AI Definition
Knowledge Bases & Vector Search API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Required | Name of the Knowledge Base (e.g. "Support KB") |
description |
string | Optional | Optional description of the knowledge base content. |
status |
string | Optional | Status: active or inactive. Default is active. |
Management Operations are Free
Creating, listing, updating, and deleting Knowledge Bases, Items, and Documents are 0 AI credits. Credits are only charged when performing embedding generation, document processing, vector search, or AI question answering.
Integration Journey
- Create Knowledge Base:
POST /api/v1/knowledge-bases - Add Knowledge Items / FAQs:
POST /api/v1/knowledge-bases/{id}/items - Upload Documents (PDF / TXT):
POST /api/v1/knowledge-bases/{id}/documents - Perform Vector Search:
POST /api/v1/knowledge-bases/{id}/search - Perform Grounded Q&A:
POST /api/v1/knowledge-bases/{id}/ask
Example Knowledge Ask Request
{
"question": "What is the refund policy for annual subscriptions?",
"top_k": 3,
"min_confidence": 0.3
}curl -X POST https://rsflowhub.com/api/v1/knowledge-bases/1/ask \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "What is the refund policy for annual subscriptions?"
}'Example Response
{
"success": true,
"data": {
"answer": "Annual subscriptions are eligible for a full refund within 14 days of purchase.",
"sources": [
{
"id": "12",
"source_type": "faq",
"title": "Refund Policy",
"confidence": 0.94
}
],
"usage": {
"credits_used": 3,
"credits_remaining": 997
}
}
}Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (1 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |