Update Agent Connections

Bulk save the tenant’s agent connections. Secrets are encrypted at rest.

Service-layer ValueError (external MCP URL validation, intra-document duplicate id guard) surfaces as 422 with the message so the FE can point at the offending row. Unhandled, these would land as 500.

PUT/agents/connections

Authorization

AuthorizationBearer token · headerrequired

Request body

requiredapplication/json

llmConnectionsAgentLlmConnection[]

Saved LLM connections - credentials + default tuning. Reusable across many agents.

Show properties

Array of AgentLlmConnection

idstring | null

Server-generated UUID — stable across renames. Null on first create, BE assigns.

Show properties

Any of:

string

string

null

null

namestringrequired

User-facing name; unique per tenant by FE convention

min length 1 · max length 100

providerAgentLlmProviderEnumrequired

Unified LLM provider enum.

A single AgentLlmConnection row carries one provider and a set of capabilities (chat / embedding). PROVIDER_CAPABILITIES below pins which capabilities each provider can serve — picked by the FE Connections drawer and re-validated server-side on every write.

Allowed:anthropicopenaiopenai-responsesollamaazureazure-openaibedrockqwenopenai-compatible

apiKeystring

API key — KMS-wrapped at rest, masked on GET

max length 512 · default: ""

baseUrlstring | null

Base URL for Ollama / Azure / self-deployed OpenAI- or Anthropic-compatible servers (vLLM, LocalAI, TGI, LM Studio, LiteLLM gateways)

Show properties

Any of:

string

string

null

null

capabilitiesConnectionCapability[]required

Non-empty list of capabilities this connection powers. Each entry must be allowed by the provider per PROVIDER_CAPABILITIES, and each listed capability must have its defaults block populated.

min items 1

chatChatDefaults | null

Chat-capability defaults. Required iff 'chat' in capabilities.

Show properties

Any of:

ChatDefaults

modelstring

Default chat model, e.g. claude-sonnet-4-20250514. Empty = fill at agent creation.

max length 200 · default: ""

temperaturenumber | null

Default sampling temperature (null = matrix-skipped)

default: 0.1

Show properties

Any of:

number

number

null

null

maxTokensinteger | null

Default max output tokens (null = matrix-skipped)

default: 1024

Show properties

Any of:

integer

integer

null

null

timeoutinteger | null

Default request timeout (seconds, null = matrix-skipped)

default: 120

Show properties

Any of:

integer

integer

null

null

reasoningEffortstring | null

Default reasoning effort. Accepted set is per-model — the matrix in app/utils/llm_capabilities.py rejects values not in caps.reasoning_effort_values for the picked (provider, model).

Show properties

Any of:

string

string

null

null

thinkingBudgetTokensinteger | null

Default Anthropic Claude 4 extended-thinking budget (tokens). Non-null enables thinking.

Show properties

Any of:

integer

integer

null

null

ollamaThinkboolean | null

Default Ollama 'think' toggle for reasoning models

Show properties

Any of:

boolean

boolean

null

null

maxRetriesinteger | null

Universal — max retry attempts on LLM call. Accepted by every provider.

Show properties

Any of:

integer

integer

null

null

regionstring | null

Bedrock chat: AWS region (e.g. us-east-1). Ignored for non-bedrock providers.

Show properties

Any of:

string

string

null

null

strictboolean | null

openai-responses: enable JSON-schema strict mode. Ignored for other providers.

Show properties

Any of:

boolean

boolean

null

null

storeboolean | null

openai-responses: server-side response storage flag. Ignored for other providers.

Show properties

Any of:

boolean

boolean

null

null

instructionsstring | null

openai-responses: system-level instructions passed as a top-level Responses param.

Show properties

Any of:

string

string

null

null

additionalKwargsobject | null

openai-responses / azure-openai: free-form extra request params forwarded verbatim by the runtime. Use for provider-specific fields not modelled above.

Show properties

Any of:

object

object

null

null

apiVersionstring | null

azure-openai: Azure OpenAI API version (e.g. '2024-02-01'). Required for azure-openai.

Show properties

Any of:

string

string

null

null

azureEndpointstring | null

azure-openai: Azure resource endpoint (e.g. https://<resource>.openai.azure.com). Required.

Show properties

Any of:

string

string

null

null

azureUrlPathModestring | null

azure-openai: URL path resolution — AUTO / LEGACY / UNIFIED. Optional.

Show properties

Any of:

string

string

null

null

null

null

embeddingEmbeddingDefaults | null

Embedding-capability defaults. Required iff 'embedding' in capabilities.

Show properties

Any of:

EmbeddingDefaults

modelstring

Default embedding model, e.g. text-embedding-3-small. Empty = fill at KB creation.

max length 200 · default: ""

dimensionsinteger | null

Output embedding dimensions override (provider-dependent)

Show properties

Any of:

integer

integer

null

null

batchSizeinteger

Records per embedding batch call

min 1 · max 2048 · default: 100

regionstring | null

AWS region for bedrock embedding provider (e.g. us-east-1). Ignored for non-bedrock rows.

Show properties

Any of:

string

string

null

null

maxRetriesinteger | null

Bedrock retry cap. Ignored for non-bedrock rows.

Show properties

Any of:

integer

integer

null

null

null

null

descriptionstring | null

Optional human-readable context for the connection

Show properties

Any of:

string

string

null

null

mcpConnectionsStreamkapMcpConnection | ExternalMcpNoneConnection | ExternalMcpBearerConnection | ExternalMcpHeaderConnection[]

Saved MCP connections (external-source only)

Show properties

Array of StreamkapMcpConnection | ExternalMcpNoneConnection | ExternalMcpBearerConnection | ExternalMcpHeaderConnection

One of:

StreamkapMcpConnection

sourcestring

Discriminator - must be 'streamkap' for this variant

default: "streamkap"

namestringrequired

Connection name (e.g. 'Production Streamkap MCP')

min length 1 · max length 100

serverUrlstring

max length 2048

headersobject

Auth headers. Set 'X-Streamkap-Project-Key' to the base64-encoded credential file downloaded when the Project Key was created.

ExternalMcpNoneConnection

sourcestring

Discriminator - must be 'external'

default: "external"

namestringrequired

Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')

min length 1 · max length 100 · matches ^[^/\r\n\x00]+$

serverUrlstringrequired

min length 1 · max length 2048

authModestringrequired

ExternalMcpBearerConnection

sourcestring

Discriminator - must be 'external'

default: "external"

namestringrequired

Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')

min length 1 · max length 100 · matches ^[^/\r\n\x00]+$

serverUrlstringrequired

min length 1 · max length 2048

authModestringrequired

bearerTokenstringrequired

Bearer token - encrypted at rest, masked on GET

min length 1 · max length 8192

ExternalMcpHeaderConnection

sourcestring

Discriminator - must be 'external'

default: "external"

namestringrequired

Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')

min length 1 · max length 100 · matches ^[^/\r\n\x00]+$

serverUrlstringrequired

min length 1 · max length 2048

authModestringrequired

headerNamestringrequired

HTTP header name (RFC 7230 token alphabet, narrowed)

min length 1 · max length 200 · matches ^[A-Za-z0-9-]+$

headerValuestringrequired

Header value - encrypted at rest, masked on GET

min length 1 · max length 8192

httpConnectionsAgentHttpConnection[]

Saved HTTP API connections. Referenced by HTTP tool rows via connectionId to inherit baseUrl + headers without duplicating them per tool.

Show properties

Array of AgentHttpConnection

idstring | null

Server-generated UUID - stable across renames. Null on first create, BE assigns.

Show properties

Any of:

string

string

null

null

namestringrequired

User-facing name; unique per tenant by FE convention (e.g. 'Stripe API')

min length 1 · max length 100

baseUrlstring | null

Base URL prepended to a referencing tool's relative URL. Tools with an absolute URL ignore this. Optional - a connection can be header-only (e.g. shared auth across hosts).

Show properties

Any of:

string

string

null

null

headersobject

HTTP headers merged into every referencing tool's request. Values are KMS-encrypted at rest and full-masked on GET.

descriptionstring | null

Optional human-readable context for the connection

Show properties

Any of:

string

string

null

null

vectorStoreConnectionsAgentVectorStoreConnection[]

Lightweight vector store credentials (apiKey + endpoint). Used by KBs and agent long-term memory.

Show properties

Array of AgentVectorStoreConnection

idstring | null

Server-generated UUID. Null on first create, BE assigns.

Show properties

Any of:

string

string

null

null

namestringrequired

User-facing name

min length 1 · max length 100

providerVectorStoreProviderEnumrequired

Vector-store providers supported by the Flink runtime (integration guide §3b.4).

Two shape families:

Typed-field providers — pgvector and pinecone. Each has a fixed set of named fields on AgentVectorStoreConnection.
Pass-through providers — milvus, opensearch, elasticsearch, s3vectors. Each carries a free-form properties map that gets copied straight into the framework's ResourceDescriptor.addInitialArgument(key, value) pairs at deploy time. Framework validates required keys at open-time.

redis is retained for legacy saved connections but is not accepted by the current runtime.

Allowed:pgvectorpineconemilvusopensearchelasticsearchs3vectorsredis

apiKeystring

Pinecone API key — KMS-wrapped at rest, masked on GET

max length 512 · default: ""

endpointstring | null

Pinecone index host URL

Show properties

Any of:

string

string

null

null

defaultNamespacestring | null

Default namespace / collection (overridable per KB or agent)

Show properties

Any of:

string

string

null

null

allowHashFallbackboolean

Opt in to the non-semantic hash-embedding fallback when the vector index lacks integrated inference. Default False = fail-hard (throws instead of silently degrading recall).

default: false

jdbcUrlstring | null

pgvector: jdbc:postgresql://host:port/db. Never embed userinfo here; put credentials in username / password.

Show properties

Any of:

string

string

null

null

usernamestring | null

pgvector username. Supports ${SECRET:...} template.

Show properties

Any of:

string

string

null

null

passwordstring | null

pgvector password. Supports ${SECRET:...} template.

Show properties

Any of:

string

string

null

null

tablestring | null

pgvector table name used as the vector collection.

Show properties

Any of:

string

string

null

null

dimsinteger | null

pgvector: embedding output dimensions. 0/unset inherits from the embedding model. Must match the embedding model's output.

Show properties

Any of:

integer

integer

null

null

metricstring | null

pgvector distance metric. Only cosine is currently supported.

Show properties

Any of:

string

string

null

null

propertiesobject | null

Free-form Map<String, Object> for pass-through providers. Copied straight into the framework's ResourceDescriptor.addInitialArgument pairs at deploy time. Framework validates required keys at open-time. Not used for pinecone or pgvector (they have named typed fields).

Show properties

Any of:

object

object

null

null

descriptionstring | null

Optional human-readable context

Show properties

Any of:

string

string

null

null

Responses

200

Successful Response

object

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 PUT 'https://api.streamkap.com/agents/connections' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "llmConnections": [
    {
      "id": "string",
      "name": "string",
      "provider": "anthropic",
      "apiKey": "",
      "baseUrl": "string",
      "capabilities": [
        "chat"
      ],
      "chat": {
        "model": "",
        "temperature": 0.1,
        "maxTokens": 1024,
        "timeout": 120,
        "reasoningEffort": "none",
        "thinkingBudgetTokens": 0,
        "ollamaThink": true,
        "maxRetries": 0,
        "region": "string",
        "strict": true,
        "store": true,
        "instructions": "string",
        "additionalKwargs": {},
        "apiVersion": "string",
        "azureEndpoint": "string",
        "azureUrlPathMode": "AUTO"
      },
      "embedding": {
        "model": "",
        "dimensions": 1,
        "batchSize": 100,
        "region": "string",
        "maxRetries": 0
      },
      "description": "string"
    }
  ],
  "mcpConnections": [
    {
      "source": "streamkap",
      "name": "string",
      "serverUrl": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],
  "httpConnections": [
    {
      "id": "string",
      "name": "string",
      "baseUrl": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "description": "string"
    }
  ],
  "vectorStoreConnections": [
    {
      "id": "string",
      "name": "string",
      "provider": "pgvector",
      "apiKey": "",
      "endpoint": "string",
      "defaultNamespace": "string",
      "allowHashFallback": false,
      "jdbcUrl": "string",
      "username": "string",
      "password": "string",
      "table": "string",
      "dims": 0,
      "metric": "string",
      "properties": {},
      "description": "string"
    }
  ]
}'

const response = await fetch("https://api.streamkap.com/agents/connections", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"llmConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"provider\": \"anthropic\",\n      \"apiKey\": \"\",\n      \"baseUrl\": \"string\",\n      \"capabilities\": [\n        \"chat\"\n      ],\n      \"chat\": {\n        \"model\": \"\",\n        \"temperature\": 0.1,\n        \"maxTokens\": 1024,\n        \"timeout\": 120,\n        \"reasoningEffort\": \"none\",\n        \"thinkingBudgetTokens\": 0,\n        \"ollamaThink\": true,\n        \"maxRetries\": 0,\n        \"region\": \"string\",\n        \"strict\": true,\n        \"store\": true,\n        \"instructions\": \"string\",\n        \"additionalKwargs\": {},\n        \"apiVersion\": \"string\",\n        \"azureEndpoint\": \"string\",\n        \"azureUrlPathMode\": \"AUTO\"\n      },\n      \"embedding\": {\n        \"model\": \"\",\n        \"dimensions\": 1,\n        \"batchSize\": 100,\n        \"region\": \"string\",\n        \"maxRetries\": 0\n      },\n      \"description\": \"string\"\n    }\n  ],\n  \"mcpConnections\": [\n    {\n      \"source\": \"streamkap\",\n      \"name\": \"string\",\n      \"serverUrl\": \"string\",\n      \"headers\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      }\n    }\n  ],\n  \"httpConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"baseUrl\": \"string\",\n      \"headers\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"description\": \"string\"\n    }\n  ],\n  \"vectorStoreConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"provider\": \"pgvector\",\n      \"apiKey\": \"\",\n      \"endpoint\": \"string\",\n      \"defaultNamespace\": \"string\",\n      \"allowHashFallback\": false,\n      \"jdbcUrl\": \"string\",\n      \"username\": \"string\",\n      \"password\": \"string\",\n      \"table\": \"string\",\n      \"dims\": 0,\n      \"metric\": \"string\",\n      \"properties\": {},\n      \"description\": \"string\"\n    }\n  ]\n}"
});

import requests

response = requests.put(
    "https://api.streamkap.com/agents/connections",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"llmConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"provider\": \"anthropic\",\n      \"apiKey\": \"\",\n      \"baseUrl\": \"string\",\n      \"capabilities\": [\n        \"chat\"\n      ],\n      \"chat\": {\n        \"model\": \"\",\n        \"temperature\": 0.1,\n        \"maxTokens\": 1024,\n        \"timeout\": 120,\n        \"reasoningEffort\": \"none\",\n        \"thinkingBudgetTokens\": 0,\n        \"ollamaThink\": true,\n        \"maxRetries\": 0,\n        \"region\": \"string\",\n        \"strict\": true,\n        \"store\": true,\n        \"instructions\": \"string\",\n        \"additionalKwargs\": {},\n        \"apiVersion\": \"string\",\n        \"azureEndpoint\": \"string\",\n        \"azureUrlPathMode\": \"AUTO\"\n      },\n      \"embedding\": {\n        \"model\": \"\",\n        \"dimensions\": 1,\n        \"batchSize\": 100,\n        \"region\": \"string\",\n        \"maxRetries\": 0\n      },\n      \"description\": \"string\"\n    }\n  ],\n  \"mcpConnections\": [\n    {\n      \"source\": \"streamkap\",\n      \"name\": \"string\",\n      \"serverUrl\": \"string\",\n      \"headers\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      }\n    }\n  ],\n  \"httpConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"baseUrl\": \"string\",\n      \"headers\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"description\": \"string\"\n    }\n  ],\n  \"vectorStoreConnections\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"provider\": \"pgvector\",\n      \"apiKey\": \"\",\n      \"endpoint\": \"string\",\n      \"defaultNamespace\": \"string\",\n      \"allowHashFallback\": false,\n      \"jdbcUrl\": \"string\",\n      \"username\": \"string\",\n      \"password\": \"string\",\n      \"table\": \"string\",\n      \"dims\": 0,\n      \"metric\": \"string\",\n      \"properties\": {},\n      \"description\": \"string\"\n    }\n  ]\n}",
)

Response

{}

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