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
| Parameter | Type | Description | Required |
|---|---|---|---|
overwrite | boolean | Set 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
| Field | Type | Description | Required |
|---|---|---|---|
name | string | Display name. Defaults to address. An empty name is rejected. | Optional |
address | string | Kafka bootstrap servers, or the address of another connection type | Yes |
type | string | Connection type. KAFKA when omitted. | Optional |
id | integer | Connection id from the source. Ignored unless overwrite=true. | Optional |
schemaregistry | string | Schema Registry URL | Optional |
security | object (Security) | TLS settings for the connection | Optional |
sasl | object (Sasl) | SASL settings | Optional |
schemasecurity | object (SchemaSecurity) | Security settings for the Schema Registry | Optional |
k_connectors | array of objects (Worker) | Kafka Connect workers | Optional |
ksql_connectors | array of objects (Worker) | ksqlDB servers | Optional |
properties | array of objects (Property) | Additional client properties | Optional |
jmx | object | JMX connection settings | Optional |
additionalConfigDetails | string | Additional details stored with the connection, such as the connection color | Optional |
enabled | boolean | Whether the connection is enabled | Optional |
Security Structure
| Field | Type | Description | Required |
|---|---|---|---|
protocol | string | Security protocol | Optional |
ts_loc | string | Truststore path on the server | Optional |
ts_pass | string | Truststore password | Optional |
ks_loc | string | Keystore path on the server | Optional |
ks_pass | string | Keystore password | Optional |
ks_ppass | string | Keystore private key password | Optional |
Sasl Structure
| Field | Type | Description | Required |
|---|---|---|---|
mechanism | string | SASL mechanism | Optional |
config | string | JAAS configuration | Optional |
SchemaSecurity Structure
| Field | Type | Description | Required |
|---|---|---|---|
protocol | string | Schema Registry security protocol | Optional |
userinfo | string | Credentials for the Schema Registry | Optional |
skiphostname | boolean | Skip hostname verification | Optional |
ts_loc | string | Truststore path on the server | Optional |
ts_pass | string | Truststore password | Optional |
ks_loc | string | Keystore path on the server | Optional |
ks_pass | string | Keystore password | Optional |
ks_ppass | string | Keystore private key password | Optional |
Worker Structure
Used for each entry in k_connectors and ksql_connectors.
| Field | Type | Description | Required |
|---|---|---|---|
name | string | Worker name | Yes |
address | string | Worker URL | Yes |
type | string | kconnect for Kafka Connect, ksql for ksqlDB | Yes |
id | integer | Worker id from the source. Ignored unless overwrite=true. | Optional |
authtype | string | Authentication type, such as NONE, BASIC, or BEARER | Optional |
userinfo | string | Authentication credentials | Optional |
tloc | string | Truststore path on the server | Optional |
tpass | string | Truststore password | Optional |
kloc | string | Keystore path on the server | Optional |
kpass | string | Keystore password | Optional |
kppass | string | Keystore private key password | Optional |
skipHostname | boolean | Skip hostname verification | Optional |
Property Structure
| Field | Type | Description | Required |
|---|---|---|---|
key | string | Property name | Yes |
value | string | Property value | Yes |
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 Code | Description | Solution |
|---|---|---|
| 400 | Invalid request | Check the payload. The body is { "messages": ["..."] }. Processing stops at the first invalid array entry. |
| 401 | Unauthorized | Check your API key |
| 403 | Forbidden | Use 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
overwriteunset when copying connections into another environment, so existing connections and workers are not replaced. - Use
overwrite=trueonly 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.