# 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
    }
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/data-analytics/kafka/api-howtos/create-topic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.