---
title: "Create connector"
method: POST
path: "/usm/v1/connect-clusters/{connect_cluster_id}/connectors"
tags: ["Connectors (usm/v1)"]
---

# Create connector

`POST /usm/v1/connect-clusters/{connect_cluster_id}/connectors`

## Request

- Base URL: `https://api.confluent.cloud`
- URL: `https://api.confluent.cloud/usm/v1/connect-clusters/{connect_cluster_id}/connectors`
- Auth: one of:
  - HTTP basic
  - HTTP basic
  - OAuth 2
    - Client credentials
    - Token URL: `https://api.confluent.cloud/sts/v1/oauth2/token`

Async, reconciled: `201` means the desired state passed best-effort synchronous control-plane validation and was accepted, not that the connector is confirmed running. Deeper validation (the connector's own `validate()`, which needs the on-prem worker) happens after the `2xx` and surfaces on `GET .../status`.

## Request body

- UsmConnectV1CreateConnectorRequest
  - `name` string, required: The connector's unique name within its environment. Immutable once created.
  - `config` UsmConnectV1ConfigMap, required: 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 ****.

## Response `201`

Created (accepted; not yet necessarily running)

- UsmConnectV1ConnectorInfo: The connector's desired-state configuration as last accepted by Cloud.
  - `id` string, required: The connector's unique Cloud-assigned ID (Cloud-only extension; not part of native Kafka Connect's ConnectorInfo).
  - `name` string, required: The connector's unique name within its environment.
  - `type` string, required: Whether the connector is a source or sink.
  - `config` UsmConnectV1ConfigMap, required: 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 ****.
  - `tasks` object[], required: 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.
    - `connector` string: The name of the connector this task belongs to.
    - `task` integer: The task's index.
  - `data_cluster_scope` string: 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.

## Other responses

- `400`: Bad request (malformed body, invalid page size/token)
- `401`: Unauthenticated
- `404`: Connector or cluster not found
- `409`: 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).
- `422`: Validation failed (SECRET_MUST_BE_REFERENCE, INVALID_CONNECTOR_CONFIG)
- `429`: Rate limited
- `500`: Internal server error

## Changes

- **2026-10-27** `018ddeaf203e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/confluent/apis/confluent-cloud-apis/changes/usm/v1/connect-clusters/:connect_cluster_id/connectors/post.md)

---

[API](https://skmtc.dev/confluent/apis/confluent-cloud-apis.md) - [All operations](https://skmtc.dev/confluent/apis/confluent-cloud-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/confluent/apis/confluent-cloud-apis/revisions/018ddeaf203e?raw)