# Create a Kafka Topic

Allows you to create a new Kafka topic within a specified Kafka cluster.

## Endpoint

`POST /clusters/{clusterId}/topics`

The `POST /clusters/{clusterId}/topics` endpoint creates a new Kafka topic within the specified Kafka cluster (`clusterId`). The request body must include the topic's name; the other parameters are optional.

Upon successful creation, the endpoint returns detailed information about the newly created topic, including its ID (id), metadata, and properties. Use this endpoint to dynamically manage Kafka topics within your environment, ensuring efficient data distribution and retention policies.

Use this endpoint to dynamically manage Kafka topics within your environment, ensuring efficient data distribution and retention policies.

{% hint style="info" %}
**Note:**

* We recommend using a replication factor of 3.
* The number of partitions should be equal to or greater than the number of brokers. If high throughput is a priority, you can opt for 2x or 3x the number of brokers or more.
* Be sure to use only multiples of your number of brokers for the number of partitions (3, 6, 9, 12, and so on), to avoid an uneven distribution of partitions.
  {% endhint %}

## Request

```bash
curl -X 'POST' \
  'https://kafka.de-txl.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead/topics' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $Token' \
--data
'{
  "metadata": {},
  "properties": {
    "name": "my-kafka-cluster-topic",
    "replicationFactor": 3,
    "numberOfPartitions": 3,
    "logRetention": {
      "retentionTime": 604800000,
      "segmentBytes": 1073741824
    }
  }
}'
```

{% tabs %}
{% tab title="Request Header Parameters" %}
To make authenticated requests to the API, the following fields are mandatory in the request header:

| Header Parameters | Required | Type   | Description                                                  |
| ----------------- | -------- | ------ | ------------------------------------------------------------ |
| `Content-Type`    | yes      | string | Set this to `application/json`.                              |
| `Accept`          | yes      | string | Set this to `application/json`.                              |
| `Authorization`   | yes      | string | Provide a header value as `Bearer` followed by your `token`. |
| {% endtab %}      |          |        |                                                              |

{% tab title="Request Path Parameters" %}

| Path Parameters | Required | Type   | Description                                                                                                                         |
| --------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `clusterId`     | Yes      | string | <p>The UUID of the Kafka cluster where the topic will be created.<br>Example: <code>e69b22a5-8fee-56b1-b6fb-4a07e4205ead</code></p> |
| {% endtab %}    |          |        |                                                                                                                                     |

{% tab title="Request Body Parameters" %}
Below is the list of mandatory body parameters:

| Body Parameters      | Type   | Description                                                                                               | Example                |
| -------------------- | ------ | --------------------------------------------------------------------------------------------------------- | ---------------------- |
| `name`               | string | The name of the Kafka topic.                                                                              | my-kafka-cluster-topic |
| `replicationFactor`  | number | The number of replicas for the topic. This determines the fault tolerance.                                | 3                      |
| `numberOfPartitions` | number | The number of partitions for the topic. This affects the parallelism and throughput.                      | 3                      |
| `retentionTime`      | number | The retention time for logs in milliseconds. Defaults to 604800000 (7 days).                              | 604800000              |
| `segmentBytes`       | number | The maximum size of a log segment in bytes before a new segment is rolled. Defaults to 1073741824 (1 GB). | 1073741824             |
| {% endtab %}         |        |                                                                                                           |                        |
| {% endtabs %}        |        |                                                                                                           |                        |

## Response

**201 Successful operation**

```json
{
  "id": "ae085c4c-3626-5f1d-b4bc-cc53ae8267ce",
  "type": "topic",
  "href": "/clusters/{clusterId}/topics/ae085c4c-3626-5f1d-b4bc-cc53ae8267ce",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "state": "AVAILABLE",
    "message": "In progress."
  },
  "properties": {
    "name": "my-kafka-cluster-topic",
    "replicationFactor": 3,
    "numberOfPartitions": 3,
    "logRetention": {
      "retentionTime": 86400000,
      "segmentBytes": 1073741824
    }
  }
}
```