Create Topic
POST/kafka/v3/clusters/:cluster_id/topics
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.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 429
- 5XX
The created topic.
The created topic.
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
Indicates that a rate limit threshold has been reached, and the client should retry again later.
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.
OpenAPI definition (YAML)
paths:
/kafka/v3/clusters/{cluster_id}/topics:
post:
operationId: createKafkaTopic
description: '[](#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:
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:
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
nullable: true
validate_only:
type: boolean
title: 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
responses:
'200':
description: The created topic.
content:
application/json:
schema:
allOf:
- type: object
required:
- kind
- metadata
properties:
kind:
type: string
metadata:
type: object
required:
- self
properties:
self:
type: string
resource_name:
type: string
nullable: true
title: ResourceMetadata
title: 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:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
configs:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
partition_reassignments:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
authorized_operations:
type: array
items:
type: string
enum:
- UNKNOWN
- ALL
- READ
- WRITE
- CREATE
- DELETE
- ALTER
- DESCRIBE
- CLUSTER_ACTION
- DESCRIBE_CONFIGS
- ALTER_CONFIGS
- IDEMPOTENT_WRITE
title: AuthorizedOperations
title: 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
'201':
description: The created topic.
content:
application/json:
schema:
allOf:
- type: object
required:
- kind
- metadata
properties:
kind:
type: string
metadata:
type: object
required:
- self
properties:
self:
type: string
resource_name:
type: string
nullable: true
title: ResourceMetadata
title: 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:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
configs:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
partition_reassignments:
type: object
required:
- related
properties:
related:
type: string
title: Relationship
authorized_operations:
type: array
items:
type: string
enum:
- UNKNOWN
- ALL
- READ
- WRITE
- CREATE
- DELETE
- ALTER
- DESCRIBE
- CLUSTER_ACTION
- DESCRIBE_CONFIGS
- ALTER_CONFIGS
- IDEMPOTENT_WRITE
title: AuthorizedOperations
title: 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
'400':
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:
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
nullable: true
additionalProperties: false
title: 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.'
'401':
description: Indicates a client authentication error. Kafka authentication failures will contain
error code 40101 in the response body.
content:
application/json:
schema:
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
nullable: true
additionalProperties: false
title: Error
examples:
kafka_authentication_failed:
description: Thrown when using Basic authentication with wrong Kafka credentials.
value:
error_code: 40101
message: Authentication failed
'403':
description: Indicates a client authorization error. Kafka authorization failures will contain
error code 40301 in the response body.
content:
application/json:
schema:
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
nullable: true
additionalProperties: false
title: 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
'429':
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: <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many
Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr>
<th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td>
</tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>
5XX:
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:
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
nullable: true
additionalProperties: false
title: Error
examples:
generic_internal_server_error:
description: Thrown for generic HTTP 500 errors.
value:
error_code: 500
message: Internal Server Error
parameters:
- name: cluster_id
description: The Kafka cluster ID.
in: path
required: true
schema:
type: string
example: cluster-1
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
jsonRequestBodyExample:
topic_name: string
partitions_count: 0
replication_factor: 0
configs:
- name: string
value: string
validate_only: true