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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy)' 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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy) 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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy) 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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy) 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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy) 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: '![Generally Available](#section/Versioning/API-Lifecycle-Policy) 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: Error 429 Too Many Requests

HTTP ERROR 429 Too Many Requests

URI: /v3/clusters/my-cluster
STATUS: 429
MESSAGE: Too Many Requests
SERVLET: default
NotFoundErrorResponse: description: Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response. content: application/json: schema: $ref: '#/components/schemas/Error' examples: endpoint_not_found: description: Thrown for generic HTTP 404 errors. value: error_code: 404 message: HTTP 404 Not Found cluster_not_found: description: Thrown when using a non-existing cluster ID. value: error_code: 404 message: Cluster my-cluster cannot be found. unknown_topic_or_partition: description: Thrown when using a non-existing topic name or partition ID. value: error_code: 40403 message: This server does not host this topic-partition. ServerErrorResponse: description: A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body. content: application/json: schema: $ref: '#/components/schemas/Error' examples: generic_internal_server_error: description: Thrown for generic HTTP 500 errors. value: error_code: 500 message: Internal Server Error requestBodies: CreateTopicRequest: description: The topic creation request. Note that Confluent Cloud allows only specific replication factor values. Because of that the replication factor field should either be omitted or it should use one of the allowed values (see https://docs.confluent.io/cloud/current/client-apps/optimizing/durability.html). content: application/json: schema: $ref: '#/components/schemas/CreateTopicRequestData' examples: uniform_replication: value: topic_name: topic-X partitions_count: 64 replication_factor: 3 configs: - name: cleanup.policy value: compact - name: compression.type value: gzip dry_run_create_topic: value: topic_name: topic-X partitions_count: 64 replication_factor: 3 validate_only: true parameters: IncludeAuthorizedOperations: name: include_authorized_operations description: Specify if authorized operations should be included in the response. in: query required: false schema: type: boolean TopicName: name: topic_name description: The topic name. in: path required: true schema: type: string example: topic-1 ClusterId: name: cluster_id description: The Kafka cluster ID. in: path required: true schema: type: string example: cluster-1 securitySchemes: cloud-api-key: type: http scheme: basic description: Authenticate with Cloud API Keys using HTTP Basic Auth. Treat the Cloud API Key ID as the username and Cloud API Key Secret as the password. confluent-sts-access-token: type: oauth2 description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0. flows: clientCredentials: tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token scopes: {} global-api-key: type: http scheme: basic description: Authenticate with Global API Keys using HTTP Basic Auth. Treat the Global API Key ID as the username and Global API Key Secret as the password. resource-api-key: type: http scheme: basic description: Authenticate with resource-specific API Keys using HTTP Basic Auth. Treat the resource-specific API Key ID as the username and resource-specific API Key Secret as the password. external-access-token: type: oauth2 description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0. flows: clientCredentials: tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token scopes: {} oauth: type: oauth2 description: Authenticate with OAuth 2.0. Currently this is only supported for partner APIs. flows: clientCredentials: tokenUrl: /oauth2/token scopes: partner:alter: enables partners to alter entitlements partner:create: enables partners to create entitlements and signup on behalf of customers partner:delete: enables partners to delete entitlements and organizations partner:describe: enables partners to read and list entitlements and organizations x-tagGroups: - name: Identity Access Management (v2) tags: - API Keys (iam/v2) - Users (iam/v2) - Service Accounts (iam/v2) - Invitations (iam/v2) - IP Groups (iam/v2) - IP Filters (iam/v2) - IP Filter Summaries (iam/v2) - Role Bindings (iam/v2) - Identity Providers (iam/v2) - Jwks (iam/v2) - Identity Pools (iam/v2) - Group Mappings (iam/v2/sso) - Certificate Authorities (iam/v2) - Certificate Identity Pools (iam/v2) - name: Org API (v2) tags: - Environments (org/v2) - Organizations (org/v2) - name: Notifications API (v1) tags: - Subscriptions (notifications/v1) - Integrations (notifications/v1) - Notification Types (notifications/v1) - Resource Preferences (notifications/v1) - Resource Subscriptions (notifications/v1) - User Notifications (notifications/v1) - name: Cluster Mgmt for Kafka (v2) tags: - Clusters (cmk/v2) - name: Cluster Mgmt for ksqlDB (v2) tags: - Clusters (ksqldbcm/v2) - name: Connect API (v1) tags: - Connectors (connect/v1) - Lifecycle (connect/v1) - Status (connect/v1) - Managed Connector Plugins (connect/v1) - Offsets (connect/v1) - Custom Connector Plugins (connect/v1) - Presigned Urls (connect/v1) - Custom Connector Runtimes (connect/v1) - name: Connect Artifact Management (v1) tags: - Connect Artifacts (cam/v1) - Presigned Urls (cam/v1) - name: Kafka API (v3) tags: - Cluster (v3) - Configs (v3) - ACL (v3) - Consumer Group (v3) - Partition (v3) - Topic (v3) - Records (v3) - Cluster Linking (v3) - Share Group (v3) - Streams Group (v3) - name: Service Quota API (v1) tags: - Applied Quotas (service-quota/v1) - Scopes (service-quota/v1) - name: Partner API (v2) tags: - Entitlements (partner/v2) - Organizations (partner/v2) - Signup (partner/v2) - name: Cluster Mgmt for Schema Registry (v2) tags: - Regions (srcm/v2) - Clusters (srcm/v2) - name: Cluster Mgmt for Schema Registry (v3) tags: - Clusters (srcm/v3) - name: Schema Registry API (v1) tags: - Compatibility (v1) - Config (v1) - Contexts (v1) - Exporters (v1) - Modes (v1) - Schemas (v1) - Subjects (v1) - Key Encryption Keys (v1) - Data Encryption Keys (v1) - name: Catalog API (v1) tags: - Entity (v1) - Search (v1) - Types (v1) - name: Stream Sharing API (v1) tags: - Provider Shared Resources (cdx/v1) - Provider Shares (cdx/v1) - Consumer Shared Resources (cdx/v1) - Consumer Shares (cdx/v1) - Shared Tokens (cdx/v1) - Opt Ins (cdx/v1) - name: Networking (v1) tags: - Networks (networking/v1) - Peerings (networking/v1) - Transit Gateway Attachments (networking/v1) - Private Link Accesses (networking/v1) - Network Link Services (networking/v1) - Network Link Endpoints (networking/v1) - Network Link Service Associations (networking/v1) - IP Addresses (networking/v1) - Private Link Attachments (networking/v1) - Private Link Attachment Connections (networking/v1) - DNS Forwarders (networking/v1) - Access Points (networking/v1) - DNS Records (networking/v1) - Gateways (networking/v1) - name: Security Token Service (v1) tags: - OAuth Tokens (sts/v1) - name: Kafka Quota (v1) tags: - Client Quotas (kafka-quotas/v1) - name: Bring Your Own Key (BYOK) Management (v1) tags: - Keys (byok/v1) - name: Billing API (v1) tags: - Costs (billing/v1) - name: Compute Pool Mgmt for Flink (v2) tags: - Compute Pools (fcpm/v2) - Regions (fcpm/v2) - Org Compute Pool Configs (fcpm/v2) - name: SQL API (v1) tags: - Statements (sql/v1) - Statement Results (sql/v1) - Statement Exceptions (sql/v1) - Connections (sql/v1) - Agents (sql/v1) - Tools (sql/v1) - Materialized Tables (sql/v1) - Materialized Table Versions (sql/v1) - name: Provider Integration Management (v1) tags: - Integrations (pim/v1) - name: Provider Integration Management (v2) tags: - Integrations (pim/v2) - name: Artifact API (v1) tags: - Flink Artifacts (artifact/v1) - Presigned Urls (artifact/v1) - Flink Artifact Versions (artifact/v1) - name: Custom Code Logging API (v1) tags: - Custom Code Loggings (ccl/v1) - name: Tableflow (v1) tags: - Regions (tableflow/v1) - Tableflow Topics (tableflow/v1) - Catalog Integrations (tableflow/v1) - name: Custom Connect Plugin Management (v1) tags: - Custom Connect Plugins (ccpm/v1) - Presigned Urls (ccpm/v1) - Custom Connect Plugin Versions (ccpm/v1) - name: Unified Stream Manager (v1) tags: - Kafka Clusters (usm/v1) - Connect Clusters (usm/v1) - name: Endpoint (v1) tags: - Endpoints (endpoint/v1) - name: Real Time Context Engine (v1) tags: - Rtce Topics (rtce/v1) - Regions (rtce/v1) - name: Analytics (v1alpha1) tags: - Statements (query/v1alpha1)