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. This is what the Streamkap app sets.
topicPattern — a regex for reading several topics (e.g. fan-in of a sharded topic family). Available through the API only.

Setting neither or both returns 422.

Show properties

topicstring | null

Exact Kafka topic name, 3 to 249 characters (249 is Kafka's own limit). Mutually exclusive with topicPattern.

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

default: "JsonConfluent"

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

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 — a KB cannot carry an inline apiKey / baseUrl. At deploy time Streamkap reads the referenced connection's embedding defaults and applies any per-KB overrides.

The referenced connection must carry 'embedding' in its capabilities list and have a non-empty embedding.model; otherwise the deploy fails with 422 naming the cause.

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 saved AgentVectorStoreConnection by id; Streamkap resolves its credentials server-side at deploy time. A KB cannot carry inline vector-store credentials.

Show properties

vectorStoreConnectionIdstringrequired

Reference to a saved AgentVectorStoreConnection. Credentials are resolved 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 'Accept: application/json' \
  -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",
    "Accept": "application/json",
    "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",
        "Accept": "application/json",
        "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": {}
    }
  ]
}