---
title: "Create Topic for a Kafka Cluster"
method: POST
path: "/v2/databases/{database_cluster_uuid}/topics"
tags: ["DigitalOcean-public.v2-new_Databases"]
---

# Create Topic for a Kafka Cluster

`POST /v2/databases/{database_cluster_uuid}/topics`

To create a topic attached to a Kafka cluster, send a POST request to
`/v2/databases/$DATABASE_ID/topics`.

The result will be a JSON object with a `topic` key.

## Path parameters

- `database_cluster_uuid` string, uuid, required

## Request body

- KafkaTopicCreate
  - `name` string — The name of the Kafka topic.
  - `replication_factor` integer — The number of nodes to replicate data across the cluster.
  - `partition_count` integer — The number of partitions available for the topic. On update, this value can only be increased.
  - `config` KafkaTopicConfig
    - `cleanup_policy` 'delete' | 'compact' | 'compact_delete' — The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key.
    - `compression_type` 'producer' | 'gzip' | 'snappy' | 'Iz4' | 'zstd' | 'uncompressed' — The compression_type specifies the compression type of the topic.
    - `delete_retention_ms` integer — The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics.
    - `file_delete_delay_ms` integer — The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem.
    - `flush_messages` integer — The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk.
    - `flush_ms` integer — The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk.
    - `index_interval_bytes` integer — The index_interval_bytes specifies the number of bytes between entries being added into te offset index.
    - `max_compaction_lag_ms` integer — The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled.
    - `max_message_bytes` integer — The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled.
    - `message_down_conversion_enable` boolean — The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients.
    - `message_format_version` '0.8.0' | '0.8.1' | '0.8.2' | '0.9.0' | '0.10.0-IV0' | '0.10.0-IV1' | '0.10.1-IV0' | '0.10.1-IV1' | '0.10.1-IV2' | '0.10.2-IV0' | '0.11.0-IV0' | '0.11.0-IV1' | '0.11.0-IV2' | '1.0-IV0' | '1.1-IV0' | '2.0-IV0' | '2.0-IV1' | '2.1-IV0' | '2.1-IV1' | '2.1-IV2' | '2.2-IV0' | '2.2-IV1' | '2.3-IV0' | '2.3-IV1' | '2.4-IV0' | '2.4-IV1' | '2.5-IV0' | '2.6-IV0' | '2.7-IV0' | '2.7-IV1' | '2.7-IV2' | '2.8-IV0' | '2.8-IV1' | '3.0-IV0' | '3.0-IV1' | '3.1-IV0' | '3.2-IV0' | '3.3-IV0' | '3.3-IV1' | '3.3-IV2' | '3.3-IV3' — The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version.
    - `message_timestamp_type` 'create_time' | 'log_append_time' — The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message.
    - `min_cleanable_dirty_ratio` number, float — The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin.
    - `min_compaction_lag_ms` integer — The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled.
    - `min_insync_replicas` integer — The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful.
    - `preallocate` boolean — The preallocate specifies whether a file should be preallocated on disk when creating a new log segment.
    - `retention_bytes` integer — The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit.
    - `retention_ms` integer — The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it.
    - `segment_bytes` integer — The segment_bytes specifies the maximum size of a single log file (in bytes).
    - `segment_jitter_ms` integer — The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling.
    - `segment_ms` integer — The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data.

## Response `201`

A JSON object with a key of `topic`.

- object
  - `topic` KafkaTopicVerbose
    - `name` string — The name of the Kafka topic.
    - `state` 'active' | 'configuring' | 'deleting' | 'unknown' — The state of the Kafka topic.
    - `replication_factor` integer — The number of nodes to replicate data across the cluster.
    - `partitions` KafkaTopicPartition[]
      - `size` integer — Size of the topic partition in bytes.
      - `id` integer — An identifier for the partition.
      - `in_sync_replicas` integer — The number of nodes that are in-sync (have the latest data) for the given partition
      - `earliest_offset` integer — The earliest consumer offset amongst consumer groups.
      - `consumer_groups` object[], nullable
        - `group_name` string — Name of the consumer group.
        - `offset` integer — The current offset of the consumer group.
    - `config` KafkaTopicConfig
      - `cleanup_policy` 'delete' | 'compact' | 'compact_delete' — The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key.
      - `compression_type` 'producer' | 'gzip' | 'snappy' | 'Iz4' | 'zstd' | 'uncompressed' — The compression_type specifies the compression type of the topic.
      - `delete_retention_ms` integer — The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics.
      - `file_delete_delay_ms` integer — The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem.
      - `flush_messages` integer — The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk.
      - `flush_ms` integer — The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk.
      - `index_interval_bytes` integer — The index_interval_bytes specifies the number of bytes between entries being added into te offset index.
      - `max_compaction_lag_ms` integer — The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled.
      - `max_message_bytes` integer — The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled.
      - `message_down_conversion_enable` boolean — The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients.
      - `message_format_version` '0.8.0' | '0.8.1' | '0.8.2' | '0.9.0' | '0.10.0-IV0' | '0.10.0-IV1' | '0.10.1-IV0' | '0.10.1-IV1' | '0.10.1-IV2' | '0.10.2-IV0' | '0.11.0-IV0' | '0.11.0-IV1' | '0.11.0-IV2' | '1.0-IV0' | '1.1-IV0' | '2.0-IV0' | '2.0-IV1' | '2.1-IV0' | '2.1-IV1' | '2.1-IV2' | '2.2-IV0' | '2.2-IV1' | '2.3-IV0' | '2.3-IV1' | '2.4-IV0' | '2.4-IV1' | '2.5-IV0' | '2.6-IV0' | '2.7-IV0' | '2.7-IV1' | '2.7-IV2' | '2.8-IV0' | '2.8-IV1' | '3.0-IV0' | '3.0-IV1' | '3.1-IV0' | '3.2-IV0' | '3.3-IV0' | '3.3-IV1' | '3.3-IV2' | '3.3-IV3' — The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version.
      - `message_timestamp_type` 'create_time' | 'log_append_time' — The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message.
      - `min_cleanable_dirty_ratio` number, float — The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin.
      - `min_compaction_lag_ms` integer — The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled.
      - `min_insync_replicas` integer — The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful.
      - `preallocate` boolean — The preallocate specifies whether a file should be preallocated on disk when creating a new log segment.
      - `retention_bytes` integer — The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit.
      - `retention_ms` integer — The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it.
      - `segment_bytes` integer — The segment_bytes specifies the maximum size of a single log file (in bytes).
      - `segment_jitter_ms` integer — The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling.
      - `segment_ms` integer — The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `404` — The resource was not found.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/revisions/cb3bf9b21459/schema)