Skip to main content

Create Connections

POST /public/v1/connections​

Imports one connection, or a list of connections, using the same JSON format as a connection export file from the Kadeck UI.

The request requires a bearer API key with administrator permissions.


Request​

The body is either one connection object or an array of connection objects. An exported connections file can be sent as the body.

Query Parameters​

ParameterTypeDescriptionRequired
overwritebooleanSet to true to keep ids from the body and update those configurations. Omitted or any other value creates new connections and new workers.Optional

Body Parameters​

FieldTypeDescriptionRequired
namestringDisplay name. Defaults to address. An empty name is rejected.Optional
addressstringKafka bootstrap servers, or the address of another connection typeYes
typestringConnection type. KAFKA when omitted.Optional
idintegerConnection id from the source. Ignored unless overwrite=true.Optional
schemaregistrystringSchema Registry URLOptional
securityobject (Security)TLS settings for the connectionOptional
saslobject (Sasl)SASL settingsOptional
schemasecurityobject (SchemaSecurity)Security settings for the Schema RegistryOptional
k_connectorsarray of objects (Worker)Kafka Connect workersOptional
ksql_connectorsarray of objects (Worker)ksqlDB serversOptional
propertiesarray of objects (Property)Additional client propertiesOptional
jmxobjectJMX connection settingsOptional
additionalConfigDetailsstringAdditional details stored with the connection, such as the connection colorOptional
enabledbooleanWhether the connection is enabledOptional

Security Structure​

FieldTypeDescriptionRequired
protocolstringSecurity protocolOptional
ts_locstringTruststore path on the serverOptional
ts_passstringTruststore passwordOptional
ks_locstringKeystore path on the serverOptional
ks_passstringKeystore passwordOptional
ks_ppassstringKeystore private key passwordOptional

Sasl Structure​

FieldTypeDescriptionRequired
mechanismstringSASL mechanismOptional
configstringJAAS configurationOptional

SchemaSecurity Structure​

FieldTypeDescriptionRequired
protocolstringSchema Registry security protocolOptional
userinfostringCredentials for the Schema RegistryOptional
skiphostnamebooleanSkip hostname verificationOptional
ts_locstringTruststore path on the serverOptional
ts_passstringTruststore passwordOptional
ks_locstringKeystore path on the serverOptional
ks_passstringKeystore passwordOptional
ks_ppassstringKeystore private key passwordOptional

Worker Structure​

Used for each entry in k_connectors and ksql_connectors.

FieldTypeDescriptionRequired
namestringWorker nameYes
addressstringWorker URLYes
typestringkconnect for Kafka Connect, ksql for ksqlDBYes
idintegerWorker id from the source. Ignored unless overwrite=true.Optional
authtypestringAuthentication type, such as NONE, BASIC, or BEAREROptional
userinfostringAuthentication credentialsOptional
tlocstringTruststore path on the serverOptional
tpassstringTruststore passwordOptional
klocstringKeystore path on the serverOptional
kpassstringKeystore passwordOptional
kppassstringKeystore private key passwordOptional
skipHostnamebooleanSkip hostname verificationOptional

Property Structure​

FieldTypeDescriptionRequired
keystringProperty nameYes
valuestringProperty valueYes

Example Request — import several connections​

curl --location 'https://your-instance.com/public/v1/connections' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-api-key>' \
--data-raw '[
{
"name": "Kafka A",
"address": "kafka-a:9092",
"type": "KAFKA",
"schemaregistry": "http://schema-registry-a:8081",
"k_connectors": [
{
"name": "Connect A",
"address": "http://connect-a:8083",
"type": "kconnect",
"authtype": "NONE"
}
],
"ksql_connectors": []
},
{
"name": "Kafka B",
"address": "kafka-b:9092",
"type": "KAFKA"
}
]'

Example Request — update existing connections​

curl --location 'https://your-instance.com/public/v1/connections?overwrite=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-api-key>' \
--data-raw '{
"id": 4,
"name": "Kafka A",
"address": "kafka-a:9092",
"type": "KAFKA"
}'

Response​

HTTP Status Code: 200 OK

A single connection object in the request returns the saved connection configuration, including the id assigned by Kadeck.

An array returns an array of saved connection configurations, in the same order as the request.

k_connectors and ksql_connectors are saved with the connection. They are not included in the response body.


Possible Errors​

Status CodeDescriptionSolution
400Invalid requestCheck the payload. The body is { "messages": ["..."] }. Processing stops at the first invalid array entry.
401UnauthorizedCheck your API key
403ForbiddenUse an API key with administrator permissions

When an array entry fails, entries saved before that entry remain saved. The error response does not list those entries.


Best Practices​

  • Export the connections in the source Kadeck and submit that file. The export format matches this endpoint.
  • Leave overwrite unset when copying connections into another environment, so existing connections and workers are not replaced.
  • Use overwrite=true only to update configurations whose ids you intend to replace.
  • Truststore and keystore files are not uploaded. Paths in the payload must already exist on the destination.
  • Validate a large file before importing it. A later invalid entry does not roll back entries that were already saved.