Skip to main content

​
Knowledge Base API

Svantic exposes a full REST API for managing knowledge bases programmatically. All endpoints use POST with JSON request bodies. For the complete request/response schemas, see the API Reference.

​
Lifecycle

EndpointPurpose
POST /knowledge_base/newCreate a knowledge base. Returns a job_id for tracking
POST /knowledge_base/getList all knowledge bases for the tenant
POST /knowledge_base/get_by_idGet detail for a single knowledge base by namespace
POST /knowledge_base/updateUpdate config or metadata
POST /knowledge_base/deleteDelete a knowledge base and all its data

​
Content

EndpointPurpose
POST /knowledge_base/ingestIngest text content (markdown, plain text) into a namespace
POST /knowledge_base/querySemantic search — returns ranked results with scores
POST /knowledge_base/refreshRegenerate all embeddings (async, returns job_id)

​
Observability

EndpointPurpose
POST /knowledge_base/get_statsChunk and source counts for a namespace
POST /knowledge_base/get_sourcesList all ingested sources (documents)
POST /knowledge_base/delete_sourceRemove a specific source and its chunks
POST /knowledge_base/get_statusPoll processing job status (ingest, refresh, create)

​
Examples

​
Create a Knowledge Base

curl -X POST https://api.svantic.com/knowledge_base/new \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-docs",
    "display_name": "Product Documentation",
    "description": "Internal product docs and runbooks"
  }'

​
Ingest Content

curl -X POST https://api.svantic.com/knowledge_base/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-docs",
    "source_id": "runbook-deployments",
    "content": "## Deployment Runbook\n\nStep 1: Verify all tests pass...",
    "tags": ["runbook", "deployments"],
    "source_type": "markdown"
  }'

curl -X POST https://api.svantic.com/knowledge_base/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-docs",
    "query": "how do I deploy to production?",
    "top_k": 5
  }'
Returns ranked results with relevance scores, so you can inspect what the system knows about a topic.

​
Check Stats

curl -X POST https://api.svantic.com/knowledge_base/get_stats \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "namespace": "my-docs" }'

​
Poll Job Status

Long-running operations (create, ingest large content, refresh) return a job_id. Poll until completion: 
curl -X POST https://api.svantic.com/knowledge_base/get_status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "job_id": "job_abc123" }'

​
Request Schemas

​
Create

FieldTypeRequiredDescription
namespacestringYesUnique namespace identifier
display_namestringNoHuman-readable name
descriptionstringNoDescription of the knowledge base
configobjectNoRetrieval configuration (top_k, min_score, etc.)

​
Ingest

FieldTypeRequiredDescription
namespacestringYesTarget knowledge base namespace
source_idstringYesUnique identifier for the source document
contentstringYesText content to ingest (markdown, plain text)
tagsstring[]NoTags for filtering during retrieval
source_typestringNoContent type hint (e.g. “markdown”, “text”)
metadataobjectNoArbitrary metadata attached to the source

​
Query

FieldTypeRequiredDescription
namespacestringYesKnowledge base to search
querystringYesNatural language search query
top_kintegerNoNumber of results to return