Update connector config (upsert, async, reconciled)
PUT/usm/v1/connect-clusters/:connect_cluster_id/connectors/:connector_name/config
Bare config map body (upsert), native-compatible. 200 if the connector already existed, 201 if this call created it (native Connect's own auto-create-on-PUT semantics — no separate create-then-update requirement, hence no 404 here). A 2xx means Cloud accepted the desired state; the Reconciler still has to push it through the worker's native config apply and a rebalance before it's actually running the new config — confirm via GET .../status, not the response code. If the worker rejects the new config, the connector keeps running its previous config and the error surfaces on /status. If the connector is changed by another request while this update is being applied, the update is rejected with 409 (CONNECTOR_MODIFIED); re-read the connector and retry.
Request
Responses
- 200
- 201
- 400
- 401
- 404
- 409
- 422
- 429
- 500
Updated (accepted)
Created (accepted)
Response Headers
Location
URL of the created/target connector
Bad request (malformed body, invalid page size/token)
Unauthenticated
Connector or cluster not found
CONNECTOR_ALREADY_EXISTS, CONNECTOR_ALREADY_DELETING, REBALANCE_IN_PROGRESS (retryable), CONNECTOR_MODIFIED (a PUT .../config raced with another change to the same connector; re-read the connector and retry), MANAGEABILITY_DISABLED (write ops when management mode is not CLOUD_MANAGED), or RESTART_ALREADY_IN_PROGRESS (a POST .../restart while the previous one for this connector is still IN_PROGRESS; retryable once that one reaches a terminal phase).
Validation failed (SECRET_MUST_BE_REFERENCE, INVALID_CONNECTOR_CONFIG)
Rate limited
Response Headers
Retry-After
Seconds to wait before retrying.
Internal server error
OpenAPI definition (YAML)
paths:
/usm/v1/connect-clusters/{connect_cluster_id}/connectors/{connector_name}/config:
put:
x-lifecycle-stage: Early Access
tags:
- Connectors (usm/v1)
operationId: updateUsmConnectV1ConnectorConfig
description: '[](#section/Versioning/API-Lifecycle-Policy)
Bare config map body (upsert), native-compatible. `200` if the connector already existed, `201`
if this call created it (native Connect''s own auto-create-on-PUT semantics — no separate create-then-update
requirement, hence no `404` here). A `2xx` means Cloud accepted the desired state; the Reconciler
still has to push it through the worker''s native config apply and a rebalance before it''s actually
running the new config — confirm via `GET .../status`, not the response code. If the worker rejects
the new config, the connector keeps running its previous config and the error surfaces on `/status`.
If the connector is changed by another request while this update is being applied, the update
is rejected with `409` (`CONNECTOR_MODIFIED`); re-read the connector and retry.
'
security:
- cloud-api-key: []
- global-api-key: []
- confluent-sts-access-token: []
requestBody:
required: true
content:
application/json:
schema:
type: object
description: 'Low-level connector config, native-compatible (all values strings, dotted
keys like `connector.class` — not snake_case, to match native Kafka Connect config verbatim).
Secret fields must be config-provider references (`${provider:path:key}`). Secrets set
as config-provider references are returned as the reference on read; all other secrets
are returned masked as ****.
'
additionalProperties:
type: string
example:
connector.class: io.confluent.connect.s3.S3SinkConnector
tasks.max: '2'
topics: orders
aws.secret.access.key: ${securepass:aws:secret}
title: usm-connect.v1.ConfigMap
responses:
'200':
description: Updated (accepted)
content:
application/json:
schema:
type: object
description: The connector's desired-state configuration as last accepted by Cloud.
required:
- id
- name
- type
- config
- tasks
properties:
id:
type: string
maxLength: 255
example: usmco-a1b2c3
readOnly: true
description: 'The connector''s unique Cloud-assigned ID (Cloud-only extension; not
part of native Kafka Connect''s ConnectorInfo).
'
name:
type: string
description: The connector's unique name within its environment.
type:
type: string
description: Whether the connector is a source or sink.
enum:
- SOURCE
- SINK
- UNKNOWN
config:
type: object
description: 'Low-level connector config, native-compatible (all values strings, dotted
keys like `connector.class` — not snake_case, to match native Kafka Connect config
verbatim). Secret fields must be config-provider references (`${provider:path:key}`).
Secrets set as config-provider references are returned as the reference on read; all
other secrets are returned masked as ****.
'
additionalProperties:
type: string
example:
connector.class: io.confluent.connect.s3.S3SinkConnector
tasks.max: '2'
topics: orders
aws.secret.access.key: ${securepass:aws:secret}
title: usm-connect.v1.ConfigMap
tasks:
type: array
description: 'The connector''s task assignments as last known at write time (informational
only, not read from the live worker); see `GET .../status` for current task state.
'
items:
type: object
properties:
connector:
type: string
description: The name of the connector this task belongs to.
task:
type: integer
format: int32
description: The task's index.
data_cluster_scope:
type: string
description: 'Whether the connector''s data Kafka cluster (distinct from the Connect
cluster''s metadata Kafka cluster) is a Confluent Cloud cluster. UNKNOWN is common
and must be handled as a first-class value.
'
enum:
- CLOUD
- ON_PREM
- UNKNOWN
title: usm-connect.v1.ConnectorInfo
'201':
description: Created (accepted)
headers:
Location:
description: URL of the created/target connector
schema:
type: string
format: uri
content:
application/json:
schema:
type: object
description: The connector's desired-state configuration as last accepted by Cloud.
required:
- id
- name
- type
- config
- tasks
properties:
id:
type: string
maxLength: 255
example: usmco-a1b2c3
readOnly: true
description: 'The connector''s unique Cloud-assigned ID (Cloud-only extension; not
part of native Kafka Connect''s ConnectorInfo).
'
name:
type: string
description: The connector's unique name within its environment.
type:
type: string
description: Whether the connector is a source or sink.
enum:
- SOURCE
- SINK
- UNKNOWN
config:
type: object
description: 'Low-level connector config, native-compatible (all values strings, dotted
keys like `connector.class` — not snake_case, to match native Kafka Connect config
verbatim). Secret fields must be config-provider references (`${provider:path:key}`).
Secrets set as config-provider references are returned as the reference on read; all
other secrets are returned masked as ****.
'
additionalProperties:
type: string
example:
connector.class: io.confluent.connect.s3.S3SinkConnector
tasks.max: '2'
topics: orders
aws.secret.access.key: ${securepass:aws:secret}
title: usm-connect.v1.ConfigMap
tasks:
type: array
description: 'The connector''s task assignments as last known at write time (informational
only, not read from the live worker); see `GET .../status` for current task state.
'
items:
type: object
properties:
connector:
type: string
description: The name of the connector this task belongs to.
task:
type: integer
format: int32
description: The task's index.
data_cluster_scope:
type: string
description: 'Whether the connector''s data Kafka cluster (distinct from the Connect
cluster''s metadata Kafka cluster) is a Confluent Cloud cluster. UNKNOWN is common
and must be handled as a first-class value.
'
enum:
- CLOUD
- ON_PREM
- UNKNOWN
title: usm-connect.v1.ConnectorInfo
'400':
description: Bad request (malformed body, invalid page size/token)
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'401':
description: Unauthenticated
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'404':
description: Connector or cluster not found
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'409':
description: 'CONNECTOR_ALREADY_EXISTS, CONNECTOR_ALREADY_DELETING, REBALANCE_IN_PROGRESS (retryable),
CONNECTOR_MODIFIED (a `PUT .../config` raced with another change to the same connector; re-read
the connector and retry), MANAGEABILITY_DISABLED (write ops when management mode is not CLOUD_MANAGED),
or RESTART_ALREADY_IN_PROGRESS (a `POST .../restart` while the previous one for this connector
is still `IN_PROGRESS`; retryable once that one reaches a terminal phase).
'
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'422':
description: Validation failed (SECRET_MUST_BE_REFERENCE, INVALID_CONNECTOR_CONFIG)
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'429':
description: Rate limited
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
'500':
description: Internal server error
content:
application/json:
schema:
type: object
description: 'Flat error envelope, native-compatible: native Kafka Connect clients only
need error_code + message; reason and request_id are backward-compatible extensions
for programmatic handling. Deliberately not this repo''s usual JSON:API {errors:[...]}
shape (same divergence connect/openapi.yaml already made) — see the companion Confluence
contract''s Design Notes for the full rationale.
'
required:
- error_code
- message
properties:
error_code:
type: integer
format: int32
description: Mirrors the HTTP status.
reason:
type: string
description: Optional machine-readable key. Not exhaustive; may grow without breaking
the envelope.
enum:
- INVALID_REQUEST_BODY
- MISSING_REQUIRED_FIELD
- INVALID_PAGE_SIZE
- INVALID_PAGE_TOKEN
- UNAUTHENTICATED
- AUTHORIZATION_FAILED
- CONNECTOR_NOT_FOUND
- CONNECT_CLUSTER_NOT_FOUND
- REQUEST_NOT_FOUND
- CONNECTOR_ALREADY_EXISTS
- CONNECTOR_ALREADY_DELETING
- CONNECTOR_MODIFIED
- MANAGEABILITY_DISABLED
- REBALANCE_IN_PROGRESS
- RESTART_ALREADY_IN_PROGRESS
- SECRET_MUST_BE_REFERENCE
- INVALID_CONNECTOR_CONFIG
- RATE_LIMITED
- INTERNAL_ERROR
- CONNECT_CLUSTER_UNREACHABLE
message:
type: string
description: Human-readable error message.
request_id:
type: string
description: Optional trace id; mirrors X-Request-Id.
title: usm-connect.v1.ErrorEnvelope
parameters:
- name: connect_cluster_id
in: path
required: true
schema:
type: string
example: usmcc-abc123
description: The ID of the Connect cluster the connector runs on, as returned by GET /usm/v1/connect-clusters.
- name: connector_name
in: path
required: true
schema:
type: string
example: s3-sink-01
description: The connector's unique name within its environment.
- name: environment
in: query
required: true
schema:
type: string
example: env-12345
description: 'Required on every connector and cluster-scoped call, consistent with the existing
USM cluster GET/List endpoints in usm/minispec.yaml. A missing value is rejected.
'
servers:
- url: https://api.confluent.cloud
description: Confluent Cloud API
jsonRequestBodyExample:
connector.class: io.confluent.connect.s3.S3SinkConnector
tasks.max: '2'
topics: orders
aws.secret.access.key: ${securepass:aws:secret}