> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/data-analytics/kafka/api-howtos/create-topic.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.