> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge base api

# 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](/api-reference).

***

## Lifecycle

| Endpoint                         | Purpose                                                  |
| -------------------------------- | -------------------------------------------------------- |
| `POST /knowledge_base/new`       | Create a knowledge base. Returns a `job_id` for tracking |
| `POST /knowledge_base/get`       | List all knowledge bases for the tenant                  |
| `POST /knowledge_base/get_by_id` | Get detail for a single knowledge base by namespace      |
| `POST /knowledge_base/update`    | Update config or metadata                                |
| `POST /knowledge_base/delete`    | Delete a knowledge base and all its data                 |

## Content

| Endpoint                       | Purpose                                                     |
| ------------------------------ | ----------------------------------------------------------- |
| `POST /knowledge_base/ingest`  | Ingest text content (markdown, plain text) into a namespace |
| `POST /knowledge_base/query`   | Semantic search — returns ranked results with scores        |
| `POST /knowledge_base/refresh` | Regenerate all embeddings (async, returns `job_id`)         |

## Observability

| Endpoint                             | Purpose                                              |
| ------------------------------------ | ---------------------------------------------------- |
| `POST /knowledge_base/get_stats`     | Chunk and source counts for a namespace              |
| `POST /knowledge_base/get_sources`   | List all ingested sources (documents)                |
| `POST /knowledge_base/delete_source` | Remove a specific source and its chunks              |
| `POST /knowledge_base/get_status`    | Poll processing job status (ingest, refresh, create) |

***

## Examples

### Create a Knowledge Base

```bash theme={null}
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

```bash theme={null}
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"
  }'
```

### Semantic Search

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

| Field          | Type   | Required | Description                                        |
| -------------- | ------ | -------- | -------------------------------------------------- |
| `namespace`    | string | Yes      | Unique namespace identifier                        |
| `display_name` | string | No       | Human-readable name                                |
| `description`  | string | No       | Description of the knowledge base                  |
| `config`       | object | No       | Retrieval configuration (top\_k, min\_score, etc.) |

### Ingest

| Field         | Type      | Required | Description                                   |
| ------------- | --------- | -------- | --------------------------------------------- |
| `namespace`   | string    | Yes      | Target knowledge base namespace               |
| `source_id`   | string    | Yes      | Unique identifier for the source document     |
| `content`     | string    | Yes      | Text content to ingest (markdown, plain text) |
| `tags`        | string\[] | No       | Tags for filtering during retrieval           |
| `source_type` | string    | No       | Content type hint (e.g. "markdown", "text")   |
| `metadata`    | object    | No       | Arbitrary metadata attached to the source     |

### Query

| Field       | Type    | Required | Description                   |
| ----------- | ------- | -------- | ----------------------------- |
| `namespace` | string  | Yes      | Knowledge base to search      |
| `query`     | string  | Yes      | Natural language search query |
| `top_k`     | integer | No       | Number of results to return   |