---
title: "Create Knowledge Base"
method: POST
path: "/knowledge-bases/config"
tags: ["Knowledge Bases"]
---

# Create Knowledge Base

`POST /knowledge-bases/config`

Create a knowledge base pipeline, optionally deploying it.

Set deploy=false to save as draft without deploying to Flink.

## Query parameters

- `deploy` boolean

## Request body

- CreateKnowledgeBaseRequest — Request body for POST /knowledge-bases/config — create a knowledge base pipeline.
  - `name` string, required — Knowledge base display name
  - `description` string, nullable — Human-readable context
  - `source` KBSourceConfig, required — Kafka source configuration for the knowledge base pipeline. Exactly one of ``topic`` or ``topicPattern`` must be set: - ``topic`` — exact Kafka topic name (the FE wizard's single-topic picker emits this). The service layer composes ``^re.escape(topic)$`` for the Java ``--topicMatcherRegex`` CLI arg, so the Java side keeps the regex-only contract. - ``topicPattern`` — escape hatch for tenants who genuinely need a multi-topic regex (e.g. fan-in of a sharded topic family). Not exposed by the FE wizard today — programmatic API callers only. The XOR rule is enforced by ``_topic_xor`` below: empty payload (neither set) and over-specified payload (both set) both 422.
    - `topic` string, nullable — Exact Kafka topic name (Kafka's own limit is 249). Mutually exclusive with ``topicPattern``. The deploy-time builder turns this into ``^re.escape(topic)$`` for the Java runtime.
    - `topicPattern` string, nullable — Regex pattern for input topics, e.g. ``^source_.*\.orders$``. Mutually exclusive with ``topic`` — set this only for programmatic multi-topic fan-in.
    - `inputSerialization` 'JsonConfluent' | 'AvroConfluent'
    - `fields` string[], nullable — Column-level filter — only these fields processed
    - `textFields` string[], nullable — Fields to include in the embedded text (if not using textTemplate)
    - `metadataFields` string[], nullable — Fields to store as vector metadata (filterable at query time)
  - `text` KBTextConfig — Text template configuration for composing the embedding input from record fields.
    - `textTemplate` string — Template with ${field} placeholders, e.g. 'Customer ${customer_id} ordered ${product}'
  - `embedding` KBEmbeddingConfig, required — Embedding-side configuration for a knowledge base. Carries a reference to a saved ``AgentLlmConnection`` plus optional per-KB overrides of the connection's defaults. Credentials, provider, and the default model live on the connection — there is no inline apiKey / baseUrl path on a KB. The deploy-time resolver (``resolve_kb_connections``) reads the referenced connection's ``embedding`` defaults block, applies any per-KB overrides, and stamps the resulting bundle into the Flink CLI JSON. The referenced connection must carry ``'embedding'`` in its ``capabilities`` list and have a non-empty ``embedding.model`` — the validator inside ``resolve_saved_embedding_credentials`` raises 422 at deploy time otherwise so the FE error surfaces the cause without waiting for a Java runtime 4xx.
    - `embeddingConnectionId` string, required — Reference to a saved AgentLlmConnection. The connection must advertise the 'embedding' capability.
    - `model` string, nullable — Per-KB embedding-model override. ``None`` = use the connection's default embedding model (``embedding.model`` on the saved row).
    - `dimensions` integer, nullable — Per-KB dimensions override. ``None`` = use the connection's default (``embedding.dimensions`` on the saved row), or the provider default when neither is set.
    - `batchSize` integer, nullable — Per-KB batchSize override. ``None`` = use the connection's default (``embedding.batchSize`` on the saved row, falls back to 100).
  - `vectorStore` KBVectorStoreConfig, required — Vector store configuration for the knowledge base. References a lightweight ``AgentVectorStoreConnection`` by id. The BE resolves the connection's credentials (apiKey + endpoint) at deploy time. There is no inline-credentials path — KBs must reference a saved connection (the FE picker is the only authoring surface).
    - `vectorStoreConnectionId` string, required — Reference to a saved AgentVectorStoreConnection. BE resolves credentials at deploy time.
    - `indexName` string, required — Index or collection name in the vector store
    - `namespace` string, nullable — Namespace or partition within the index
    - `metric` 'cosine' | 'dot_product' | 'euclidean' — Distance metric
  - `processing` KBProcessingConfig — Processing configuration for the knowledge base pipeline.
    - `parallelism` integer — Flink parallelism
    - `checkpointIntervalMin` integer — Checkpoint interval in minutes
    - `chunkSize` integer — Text chunk size in tokens
    - `chunkOverlap` integer — Overlap tokens between chunks

## Response `200`

Successful Response

- KnowledgeBaseResponse — Response model for knowledge base entities. Mirrors FlinkJobResponse shape.
  - `_id` string, required
  - `name` string, required
  - `job_type` 'pyflink' | 'jar' | 'agent_config' | 'knowledge_base', required
  - `status` 'CREATED' | 'DEPLOYING' | 'RUNNING' | 'CANCELLING' | 'CANCELLED' | 'FAILED' | 'FINISHED', required
  - `desired_status` 'CREATED' | 'DEPLOYING' | 'RUNNING' | 'CANCELLING' | 'CANCELLED' | 'FAILED' | 'FINISHED'
  - `flink_job_name` string, required
  - `flink_job_id` string, nullable
  - `parallelism` integer
  - `error_message` string, nullable
  - `agent_config` object, nullable — KB config (secrets masked)
  - `created_by` string, nullable
  - `created_timestamp` string, date-time, nullable
  - `updated_timestamp` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/streamkap/apis/streamkap-rest-api.md) · [All operations](https://skmtc.net/streamkap/apis/streamkap-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/streamkap/streamkap-rest-api/versions/8aea6143d003/schema)