openapi: 3.2.0 info: title: Confluent Cloud Topic (v3) API version: '' x-api-id: 46234552-5833-42eb-ba0f-883ad3f70d2b x-audience: external-public x-logo: url: https://assets.confluent.io/m/1661ef5e4ff82d3d/ description: '# Introduction Note This documents the collection of Confluent Cloud APIs.' servers: - url: https://api.confluent.cloud description: Confluent Cloud API tags: - name: Topic (v3) description: '' paths: /kafka/v3/clusters/{cluster_id}/topics: servers: - url: https://pkc-00000.region.provider.confluent.cloud x-audience: business-unit-internal description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud parameters: - $ref: '#/components/parameters/ClusterId' get: summary: List Topics operationId: listKafkaTopics description: ' Return the list of topics that belong to the specified Kafka cluster.' tags: - Topic (v3) security: - resource-api-key: [] - external-access-token: [] responses: '200': $ref: '#/components/responses/ListTopicsResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' post: summary: Create Topic operationId: createKafkaTopic description: ' Create a topic. Also supports a dry-run mode that only validates whether the topic creation would succeed if the ``validate_only`` request property is explicitly specified and set to true. Note that when dry-run mode is being used the response status would be 200 OK instead of 201 Created.' tags: - Topic (v3) security: - resource-api-key: [] - external-access-token: [] requestBody: $ref: '#/components/requestBodies/CreateTopicRequest' responses: '200': $ref: '#/components/responses/CreateTopicResponse' '201': $ref: '#/components/responses/CreateTopicResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse_CreateTopic' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' /kafka/v3/clusters/{cluster_id}/topics/{topic_name}: servers: - url: https://pkc-00000.region.provider.confluent.cloud x-audience: business-unit-internal description: Confluent Cloud REST Endpoint. For example https://pkc-00000.region.provider.confluent.cloud parameters: - $ref: '#/components/parameters/ClusterId' - $ref: '#/components/parameters/TopicName' get: summary: Get Topic operationId: getKafkaTopic description: ' Return the topic with the given `topic_name`.' tags: - Topic (v3) security: - resource-api-key: [] - external-access-token: [] parameters: - $ref: '#/components/parameters/IncludeAuthorizedOperations' responses: '200': $ref: '#/components/responses/GetTopicResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' patch: summary: Update Partition Count operationId: updatePartitionCountKafkaTopic description: ' Increase the number of partitions for a topic. To update other topic configurations, see https://docs.confluent.io/cloud/current/api.html#tag/Configs-(v3)/operation/updateKafkaTopicConfig.' tags: - Topic (v3) security: - resource-api-key: [] - external-access-token: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePartitionCountRequestData' responses: '200': $ref: '#/components/responses/GetTopicResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse_UpdatePartitionCountTopic' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' delete: summary: Delete Topic operationId: deleteKafkaTopic description: ' Delete the topic with the given `topic_name`.' tags: - Topic (v3) security: - resource-api-key: [] - external-access-token: [] responses: '204': description: No Content '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' components: schemas: Relationship: type: object required: - related properties: related: type: string Error: type: object description: Describes a particular error encountered while performing an operation. properties: id: description: A unique identifier for this particular occurrence of the problem. type: string maxLength: 255 status: description: The HTTP status code applicable to this problem, expressed as a string value. type: string code: description: An application-specific error code, expressed as a string value. type: string title: description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string source: type: object description: If this error was caused by a particular part of the API request, the source will point to the query string parameter or request body property that caused it. properties: pointer: description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field]. type: string parameter: description: A string indicating which query parameter caused the error. type: string error_code: type: integer format: int32 message: type: - string - 'null' additionalProperties: false TopicDataList: allOf: - $ref: '#/components/schemas/ResourceCollection' - type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/TopicData' ResourceCollectionMetadata: type: object required: - self properties: self: type: string next: type: - string - 'null' Resource: type: object required: - kind - metadata properties: kind: type: string metadata: $ref: '#/components/schemas/ResourceMetadata' AuthorizedOperations: type: array items: type: string x-extensible-enum: - UNKNOWN - ALL - READ - WRITE - CREATE - DELETE - ALTER - DESCRIBE - CLUSTER_ACTION - DESCRIBE_CONFIGS - ALTER_CONFIGS - IDEMPOTENT_WRITE CreateTopicRequestData: type: object required: - topic_name properties: topic_name: type: string partitions_count: type: integer replication_factor: type: integer configs: type: array items: type: object required: - name properties: name: type: string value: type: - string - 'null' validate_only: type: boolean UpdatePartitionCountRequestData: type: object required: - partitions_count properties: partitions_count: type: integer format: int32 TopicData: allOf: - $ref: '#/components/schemas/Resource' - type: object required: - cluster_id - topic_name - is_internal - replication_factor - partitions_count - partitions - configs - partition_reassignments properties: cluster_id: type: string topic_name: type: string is_internal: type: boolean replication_factor: type: integer partitions_count: type: integer partitions: $ref: '#/components/schemas/Relationship' configs: $ref: '#/components/schemas/Relationship' partition_reassignments: $ref: '#/components/schemas/Relationship' authorized_operations: $ref: '#/components/schemas/AuthorizedOperations' ResourceCollection: type: object required: - kind - metadata properties: kind: type: string metadata: $ref: '#/components/schemas/ResourceCollectionMetadata' ResourceMetadata: type: object required: - self properties: self: type: string resource_name: type: - string - 'null' responses: ListTopicsResponse: description: The list of topics. content: application/json: schema: $ref: '#/components/schemas/TopicDataList' example: kind: KafkaTopicList metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics next: null data: - kind: KafkaTopic metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1 resource_name: crn:///kafka=cluster-1/topic=topic-1 cluster_id: cluster-1 topic_name: topic-1 is_internal: false replication_factor: 3 partitions_count: 1 partitions: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions configs: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs partition_reassignments: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/-/reassignments - kind: KafkaTopic metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2 resource_name: crn:///kafka=cluster-1/topic=topic-2 cluster_id: cluster-1 topic_name: topic-2 is_internal: true replication_factor: 4 partitions_count: 1 partitions: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions configs: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/configs partition_reassignments: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/-/reassignments - kind: KafkaTopic metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3 resource_name: crn:///kafka=cluster-1/topic=topic-3 cluster_id: cluster-1 topic_name: topic-3 is_internal: false replication_factor: 5 partitions_count: 1 partitions: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions configs: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/configs partition_reassignments: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/-/reassignments ForbiddenErrorResponse: description: Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body. content: application/json: schema: $ref: '#/components/schemas/Error' examples: kafka_authorization_failed: description: Thrown when the caller is not authorized to perform the underlying operation. value: error_code: 40301 message: Request is not authorized GetTopicResponse: description: The topic. content: application/json: schema: $ref: '#/components/schemas/TopicData' example: kind: KafkaTopic metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1 resource_name: crn:///kafka=cluster-1/topic=topic-1 cluster_id: cluster-1 topic_name: topic-1 is_internal: false replication_factor: 3 partitions_count: 1 partitions: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions configs: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs partition_reassignments: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/-/reassignments CreateTopicResponse: description: The created topic. content: application/json: schema: $ref: '#/components/schemas/TopicData' example: kind: KafkaTopic metadata: self: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X resource_name: crn:///kafka=cluster-1/topic=topic-X cluster_id: cluster-1 topic_name: topic-X is_internal: false replication_factor: 3 partitions_count: 1 partitions: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions configs: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/configs partition_reassignments: related: https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions/-/reassignments BadRequestErrorResponse: description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. content: application/json: schema: $ref: '#/components/schemas/Error' examples: bad_request_cannot_deserialize: description: Thrown when trying to deserialize an integer from non-integer data. value: error_code: 400 message: 'Cannot deserialize value of type `java.lang.Integer` from String "A": not a valid `java.lang.Integer` value' unsupported_version_exception: description: Thrown when the version of this API is not supported in the underlying Kafka cluster. value: error_code: 40035 message: The version of this API is not supported in the underlying Kafka cluster. UnauthorizedErrorResponse: description: Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body. content: application/json: schema: $ref: '#/components/schemas/Error' examples: kafka_authentication_failed: description: Thrown when using Basic authentication with wrong Kafka credentials. value: error_code: 40101 message: Authentication failed BadRequestErrorResponse_UpdatePartitionCountTopic: description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. content: application/json: schema: $ref: '#/components/schemas/Error' examples: topic_update_partitions_invalid: description: Thrown when trying to update the number of partitions incorrectly. value: error_code: 40002 message: Topic already has 1 partitions. BadRequestErrorResponse_CreateTopic: description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. content: application/json: schema: $ref: '#/components/schemas/Error' examples: create_topic_already_exists: description: Thrown when trying to create a topic with a name already used by an existing topic. value: error_code: 40002 message: Topic 'my-topic' already exists. create_topic_replication_factor_too_large: description: Thrown when trying to create a topic with a replication factor larger than the number of brokers. value: error_code: 40002 message: 'Replication factor: 2 larger than available brokers: 1.' TooManyRequestsErrorResponse: description: Indicates that a rate limit threshold has been reached, and the client should retry again later. content: text/html: schema: type: string example: description: A sample response from Jetty's DoSFilter. value:
| URI: | /v3/clusters/my-cluster |
|---|---|
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |