Create Knowledge Base

Create a knowledge base pipeline, optionally deploying it.

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

POST/knowledge-bases/config

Authorization

AuthorizationBearer token · headerrequired

Query parameters

deployboolean

default: true

Request body

requiredapplication/json

namestringrequired

Knowledge base display name

min length 1 · max length 200

descriptionstring | null

Human-readable context

Show properties

Any of:

string

string

null

null

sourceKBSourceConfigrequired

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.

Show properties

topicstring | null

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.

Show properties

Any of:

string

string

null

null

topicPatternstring | null

Regex pattern for input topics, e.g. ^source_.*\.orders$. Mutually exclusive with topic — set this only for programmatic multi-topic fan-in.

Show properties

Any of:

string

string

null

null

inputSerializationAgentSerializationEnum

Input deserialization format

Allowed:JsonConfluentAvroConfluent

fieldsstring[] | null

Column-level filter — only these fields processed

Show properties

Any of:

string[]

Array of string

string

null

null

textFieldsstring[] | null

Fields to include in the embedded text (if not using textTemplate)

Show properties

Any of:

string[]

Array of string

string

null

null

metadataFieldsstring[] | null

Fields to store as vector metadata (filterable at query time)

Show properties

Any of:

string[]

Array of string

string

null

null

textKBTextConfig

Text template configuration for composing the embedding input from record fields.

Show properties

textTemplatestring

Template with ${field} placeholders, e.g. 'Customer ${customer_id} ordered ${product}'

max length 8000 · default: ""

embeddingKBEmbeddingConfigrequired

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.

Show properties

embeddingConnectionIdstringrequired

Reference to a saved AgentLlmConnection. The connection must advertise the 'embedding' capability.

min length 1 · max length 64

modelstring | null

Per-KB embedding-model override. None = use the connection's default embedding model (embedding.model on the saved row).

Show properties

Any of:

string

string

null

null

dimensionsinteger | null

Per-KB dimensions override. None = use the connection's default (embedding.dimensions on the saved row), or the provider default when neither is set.

Show properties

Any of:

integer

integer

null

null

batchSizeinteger | null

Per-KB batchSize override. None = use the connection's default (embedding.batchSize on the saved row, falls back to 100).

Show properties

Any of:

integer

integer

null

null

vectorStoreKBVectorStoreConfigrequired

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).

Show properties

vectorStoreConnectionIdstringrequired

Reference to a saved AgentVectorStoreConnection. BE resolves credentials at deploy time.

min length 1 · max length 64

indexNamestringrequired

Index or collection name in the vector store

min length 1 · max length 200

namespacestring | null

Namespace or partition within the index

Show properties

Any of:

string

string

null

null

metricstring

Distance metric

default: "cosine"

Allowed:cosinedot_producteuclidean

processingKBProcessingConfig

Processing configuration for the knowledge base pipeline.

Show properties

parallelisminteger

Flink parallelism

min 1 · max 128 · default: 1

checkpointIntervalMininteger

Checkpoint interval in minutes

min 1 · max 60 · default: 5

chunkSizeinteger

Text chunk size in tokens

min 1 · max 8192 · default: 512

chunkOverlapinteger

Overlap tokens between chunks

min 0 · max 4096 · default: 50

Responses

200

Successful Response

_idstringrequired

namestringrequired

job_typeapp__models__api__agents_api_models__flink_jobs__FlinkJobTypeEnumrequired

Allowed:pyflinkjaragent_configknowledge_base

statusFlinkJobStatusEnumrequired

Allowed:CREATEDDEPLOYINGRUNNINGCANCELLINGCANCELLEDFAILEDFINISHED

desired_statusFlinkJobStatusEnum | null

Show properties

Any of:

FlinkJobStatusEnum

string

null

null

flink_job_namestringrequired

flink_job_idstring | null

Show properties

Any of:

string

string

null

null

parallelisminteger

default: 1

error_messagestring | null

Show properties

Any of:

string

string

null

null

agent_configobject | null

KB config (secrets masked)

Show properties

Any of:

object

object

null

null

created_bystring | null

Show properties

Any of:

string

string

null

null

created_timestampstring<date-time> | null

Show properties

Any of:

string<date-time>

string<date-time>

null

null

updated_timestampstring<date-time> | null

Show properties

Any of:

string<date-time>

string<date-time>

null

null

422

Validation Error

detailValidationError[]

Show properties

Array of ValidationError

locstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Request

curl -X POST 'https://api.streamkap.com/knowledge-bases/config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "source": {
    "topic": "string",
    "topicPattern": "string",
    "inputSerialization": "JsonConfluent",
    "fields": [
      "string"
    ],
    "textFields": [
      "string"
    ],
    "metadataFields": [
      "string"
    ]
  },
  "text": {
    "textTemplate": ""
  },
  "embedding": {
    "embeddingConnectionId": "string",
    "model": "string",
    "dimensions": 1,
    "batchSize": 1
  },
  "vectorStore": {
    "vectorStoreConnectionId": "string",
    "indexName": "string",
    "namespace": "string",
    "metric": "cosine"
  },
  "processing": {
    "parallelism": 1,
    "checkpointIntervalMin": 5,
    "chunkSize": 512,
    "chunkOverlap": 50
  }
}'

const response = await fetch("https://api.streamkap.com/knowledge-bases/config", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\n  \"description\": \"string\",\n  \"source\": {\n    \"topic\": \"string\",\n    \"topicPattern\": \"string\",\n    \"inputSerialization\": \"JsonConfluent\",\n    \"fields\": [\n      \"string\"\n    ],\n    \"textFields\": [\n      \"string\"\n    ],\n    \"metadataFields\": [\n      \"string\"\n    ]\n  },\n  \"text\": {\n    \"textTemplate\": \"\"\n  },\n  \"embedding\": {\n    \"embeddingConnectionId\": \"string\",\n    \"model\": \"string\",\n    \"dimensions\": 1,\n    \"batchSize\": 1\n  },\n  \"vectorStore\": {\n    \"vectorStoreConnectionId\": \"string\",\n    \"indexName\": \"string\",\n    \"namespace\": \"string\",\n    \"metric\": \"cosine\"\n  },\n  \"processing\": {\n    \"parallelism\": 1,\n    \"checkpointIntervalMin\": 5,\n    \"chunkSize\": 512,\n    \"chunkOverlap\": 50\n  }\n}"
});

import requests

response = requests.post(
    "https://api.streamkap.com/knowledge-bases/config",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\n  \"description\": \"string\",\n  \"source\": {\n    \"topic\": \"string\",\n    \"topicPattern\": \"string\",\n    \"inputSerialization\": \"JsonConfluent\",\n    \"fields\": [\n      \"string\"\n    ],\n    \"textFields\": [\n      \"string\"\n    ],\n    \"metadataFields\": [\n      \"string\"\n    ]\n  },\n  \"text\": {\n    \"textTemplate\": \"\"\n  },\n  \"embedding\": {\n    \"embeddingConnectionId\": \"string\",\n    \"model\": \"string\",\n    \"dimensions\": 1,\n    \"batchSize\": 1\n  },\n  \"vectorStore\": {\n    \"vectorStoreConnectionId\": \"string\",\n    \"indexName\": \"string\",\n    \"namespace\": \"string\",\n    \"metric\": \"cosine\"\n  },\n  \"processing\": {\n    \"parallelism\": 1,\n    \"checkpointIntervalMin\": 5,\n    \"chunkSize\": 512,\n    \"chunkOverlap\": 50\n  }\n}",
)

Response

{
  "_id": "string",
  "name": "string",
  "job_type": "pyflink",
  "status": "CREATED",
  "desired_status": "CREATED",
  "flink_job_name": "string",
  "flink_job_id": "string",
  "parallelism": 1,
  "error_message": "string",
  "agent_config": {},
  "created_by": "string",
  "created_timestamp": "2019-08-24T14:15:22Z",
  "updated_timestamp": "2019-08-24T14:15:22Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}