Skip to main content

Create connector

POST 
/usm/v1/connect-clusters/:connect_cluster_id/connectors

Early Access

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​

Responses​

Created (accepted; not yet necessarily running)

Response Headers
    Location

    URL of the created/target connector

OpenAPI definition (YAML) 
paths:
  /usm/v1/connect-clusters/{connect_cluster_id}/connectors:
    post:
      x-lifecycle-stage: Early Access
      tags:
      - Connectors (usm/v1)
      operationId: createUsmConnectV1Connector
      description: '[![Early Access](https://img.shields.io/badge/Lifecycle%20Stage-Early%20Access-%2345c6e8)](#section/Versioning/API-Lifecycle-Policy)


        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`.

        '
      security:
      - cloud-api-key: []
      - global-api-key: []
      - confluent-sts-access-token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - config
              properties:
                name:
                  type: string
                  example: s3-sink-01
                  description: The connector's unique name within its environment. Immutable once created.
                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
              title: usm-connect.v1.CreateConnectorRequest
      responses:
        '201':
          description: Created (accepted; not yet necessarily running)
          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: 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:
        name: s3-sink-01
        config:
          connector.class: io.confluent.connect.s3.S3SinkConnector
          tasks.max: '2'
          topics: orders
          aws.secret.access.key: ${securepass:aws:secret}