Skip to main content

Restart connector

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

Early Access

Direct pass-through to the worker, bypassing desired-state reconciliation entirely, so there's no desired-vs-actual convergence to observe on /status (unlike Create/Update/ Delete/Pause/Resume). Instead, 202 means the restart was dispatched; poll GET .../restart/status to learn the outcome. ?includeTasks and ?onlyFailed are accepted and forwarded to the worker's native restart verbatim (Cloud does not interpret them, hence camelCase — native param names, not ours). You can only have one restart request in flight per connector at a time: a second POST while one is still IN_PROGRESS is rejected with 409 (RESTART_ALREADY_IN_PROGRESS) rather than dispatching a second restart. Exception to native parity: native Kafka Connect's default restart call (no query params) returns 200 OK with an empty body, synchronously. This endpoint always returns 202 Accepted regardless of query params — client automation expecting a synchronous 200/empty body from a bare restart call must be updated to poll instead.

Request​

Responses​

Accepted (restart dispatched, always async)

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


        Direct pass-through to the worker, bypassing desired-state reconciliation entirely, so there''s
        no desired-vs-actual convergence to observe on `/status` (unlike Create/Update/ Delete/Pause/Resume).
        Instead, `202` means the restart was dispatched; poll `GET .../restart/status` to learn the outcome.
        `?includeTasks` and `?onlyFailed` are accepted and forwarded to the worker''s native restart verbatim
        (Cloud does not interpret them, hence camelCase — native param names, not ours).

        You can only have one restart request in flight per connector at a time: a second `POST` while
        one is still `IN_PROGRESS` is rejected with `409` (`RESTART_ALREADY_IN_PROGRESS`) rather than
        dispatching a second restart.

        Exception to native parity: native Kafka Connect''s default restart call (no query params) returns
        `200 OK` with an empty body, synchronously. This endpoint always returns `202 Accepted` regardless
        of query params — client automation expecting a synchronous `200`/empty body from a bare restart
        call must be updated to poll instead.

        '
      security:
      - cloud-api-key: []
      - global-api-key: []
      - confluent-sts-access-token: []
      parameters:
      - name: includeTasks
        in: query
        required: false
        schema:
          type: boolean
        description: Forwarded to the worker's native restart verbatim (native param name).
      - name: onlyFailed
        in: query
        required: false
        schema:
          type: boolean
        description: Forwarded to the worker's native restart verbatim (native param name).
      - 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.

          '
      responses:
        '202':
          description: Accepted (restart dispatched, always async)
          content:
            application/json:
              schema:
                type: object
                description: The request made to restart the connector.
                required:
                - connector
                - requested_at
                properties:
                  connector:
                    type: string
                    example: s3-sink-01
                    description: The name of the connector this restart request targets.
                  include_tasks:
                    type: boolean
                    description: Echoes the `includeTasks` query param this restart request was made with.
                  only_failed:
                    type: boolean
                    description: Echoes the `onlyFailed` query param this restart request was made with.
                  requested_at:
                    type: string
                    format: date-time
                    readOnly: true
                    example: '2024-02-20 15:14:19+00:00'
                    description: The time at which the request was made. The time is in UTC, ISO 8601
                      format.
                title: usm-connect.v1.RestartRequestInfo
        '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
        '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
      servers:
      - url: https://api.confluent.cloud
        description: Confluent Cloud API