> ## Documentation Index
> Fetch the complete documentation index at: https://www.artie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Managed Kafka cluster

> Saves a Managed Kafka cluster with status deploying and starts deploying it. An account on a public or disposable email domain, or an API key it made, gets a 403, unless an app setting allows them. A company not yet paying Artie needs a card on file first, or gets a 402. Company admins only.

`POST /kafka-clusters`

## Authorization

* `Authorization` (header): API key passed as a Bearer token in the Authorization header.

## Body (application/json)

* `allowedCIDRs` (string[], required): Client IP ranges allowed to reach the cluster. Empty allows any IP; clients still need the password.
* `brokers` (integer, required, default `3`, range `3 ≤ x ≤ 30`)
* `instanceType` (string, required, default `"r8g.large"`) One of: `m8g.2xlarge`, `m8g.4xlarge`, `m8g.xlarge`, `m8i.2xlarge`, `m8i.4xlarge`, `m8i.xlarge`, `r8g.2xlarge`, `r8g.large`, `r8g.xlarge`, `r8i.2xlarge`, `r8i.large`, `r8i.xlarge`.
* `localRetentionBytes` (integer | null): Disk cap per partition: the most broker disk each partition of a tiered topic keeps, in bytes, at least 1073741824 (1 GiB). Null is no cap.
* `localRetentionMS` (integer | null): Days on disk: how long tiered topics keep data on broker disks, in ms, from 86400000 (one day) to 2592000000 (30 days), and no longer than retentionMS. Every topic that doesn't set log.local.retention.ms inherits it. Left out is 3 days.
* `name` (string, required, length `3–100`): The cluster's name, as customers see it. 3 to 100 characters. The cluster's ID, which its address and Kubernetes objects use, is generated.
* `region` (string, required)
* `retentionMS` (integer): How long topics keep messages unless they set their own retention.ms, in ms (the brokers' log.retention.ms): at least 86400000 (one day), and at least the days on disk, or -1 to keep them forever. Left out is 14 days.
* `storageAutoscale` (object): How Artie grows the brokers' disks before they fill. Left out is on, growing at 65% to 55%, with no limit.
  * `bumpAtPercent` (integer, required, range `1 ≤ x ≤ 99`): How full, in %, a broker's disk gets before every broker's disk grows. At most 99. Defaults to 65.
  * `enabled` (boolean, required): Whether Artie grows the brokers' disks before they fill.
  * `maxGiB` (integer | null, range `x ≥ 1`): The most disk per broker, in GiB, a grow goes to. Null is no limit.
  * `targetPercent` (integer, required, range `1 ≤ x ≤ 98`): How full, in %, the fullest broker's disk is after a grow. Less than bumpAtPercent. Defaults to 55.
* `storageGiB` (integer, required, range `20 ≤ x ≤ 1024`): Disk per broker in GiB: 20, 50 or 80, or any size from 100 to 1024 (1 TiB). Bigger sizes go through support.
* `tieredStorage` (boolean, required): Whether Artie turns tiered storage on for every topic that hasn't set it either way. The setup form starts it on.

## Example request

```bash
curl --request POST \
  --url https://api.artie.com/kafka-clusters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "allowedCIDRs": [
    "<string>"
  ],
  "brokers": 3,
  "instanceType": "r8g.large",
  "localRetentionBytes": 123,
  "localRetentionMS": 123,
  "name": "<string>",
  "region": "<string>",
  "retentionMS": 123,
  "storageAutoscale": {
    "bumpAtPercent": 1,
    "enabled": true,
    "maxGiB": 1,
    "targetPercent": 1
  },
  "storageGiB": 20,
  "tieredStorage": true
}'
```

## Responses

### 200 OK

* `cloud` (string, required)
* `createdAt` (string<date-time>, required)
* `dataKeptUntil` (string<date-time>): When a deleted Managed Kafka cluster's data is deleted for good. It can be restored until then. Only set while status is deleted.
* `deployStage` (string): The step a Managed Kafka cluster's deploy is on. Only set while status is deploying, or failed, where it is the step the deploy stopped at. One of: `applying_custom_resources`, `issuing_tls_certificate`, `provisioning_broker_nodes`, `starting_kafka_brokers`, `creating_load_balancer`.
* `disableTLS` (boolean, required)
* `externalBootstrapURL` (string, required)
* `isManaged` (boolean, required): Whether this is a Managed Kafka cluster that Artie runs for the company.
* `localRetentionBytes` (integer | null): Disk cap per partition: the most broker disk each partition of the cluster's tiered topics keeps, in bytes (log.local.retention.bytes). Missing when there is no cap.
* `localRetentionMS` (integer | null): Days on disk: how long the cluster's tiered topics keep data on broker disks, in ms (log.local.retention.ms). Missing on clusters made before it, whose brokers use Kafka's default.
* `managed` (object): A Managed Kafka cluster's configuration. Only set when isManaged, and only by Get a Kafka cluster.
  * `allowedCIDRs` (string[], required): Client IP ranges allowed to reach the cluster. Empty when any IP can connect.
  * `brokerConfigs` (object[], required): The broker config Artie sets on top of Kafka's defaults, sorted by name.
    * `name` (string, required)
    * `value` (string, required)
  * `brokerSettings` (object, required): The broker settings customers can change.
    * `retentionMS` (integer<int64>, required): How long topics keep messages unless they set their own retention.ms, in ms (the brokers' log.retention.ms). -1 keeps them forever.
  * `brokers` (integer, required)
  * `instanceType` (string, required)
  * `kafkaVersion` (string, required)
  * `pendingChange` (object): The cluster's latest change that isn't applied yet. Missing once every change is applied, and while the cluster isn't active.
    * `field` (string, required): The setting the change is to. The other fields already show its new value. One of: `allowedCIDRs`, `storageGiB`, `brokers`, `instanceType`, `tieredStorage`, `brokerSettings`.
    * `startedAt` (string<date-time>, required): When the change was saved.
    * `state` (string, required): Applying until the apply's time limit after the save has passed (15 minutes plus a broker roll per broker, plus 5 minutes), then failed: the apply failed or was lost. Saving the same value again retries it. One of: `applying`, `failed`.
    * `summary` (string, required): What the change does, as the Activity feed says it, such as "Grew broker storage from 50 GiB to 80 GiB".
  * `storageGiB` (integer, required): Disk per broker in GiB.
* `name` (string, required)
* `region` (string, required)
* `shuttingDown` (boolean): Whether a deleted Managed Kafka cluster is still being taken down. It can't be restored until that finishes. Only set in the clusters list.
* `status` (string, required) One of: `draft`, `active`, `deploying`, `failed`, `deleted`.
* `statusMessage` (string): Why the last deploy of a Managed Kafka cluster failed. Only set while status is failed.
* `storageAutoscale` (object): A Managed Kafka cluster's storage autoscaling. Only set when isManaged.
  * `bumpAtPercent` (integer, required, range `1 ≤ x ≤ 99`): How full, in %, a broker's disk gets before every broker's disk grows. At most 99. Defaults to 65.
  * `enabled` (boolean, required): Whether Artie grows the brokers' disks before they fill.
  * `maxGiB` (integer | null, range `x ≥ 1`): The most disk per broker, in GiB, a grow goes to. Null is no limit.
  * `targetPercent` (integer, required, range `1 ≤ x ≤ 98`): How full, in %, the fullest broker's disk is after a grow. Less than bumpAtPercent. Defaults to 55.
* `tierAllTopics` (boolean, required): Whether Artie turns tiered storage on for every topic of a Managed Kafka cluster that doesn't choose otherwise.
* `tieredStorageAvailable` (boolean, required): Whether tiered storage is available on this cluster. Artie turns it on once the cluster's brokers have tiered storage.
* `tieredStorageSyncedAt` (string<date-time>): When the sync last made a Managed Kafka cluster's topics match the tiered storage choice for each. Missing until its first run.
* `updatedAt` (string<date-time>, required): When the cluster row last changed. A deploying cluster can be retried 20 minutes after this.
* `usesScram` (boolean, required)
* `uuid` (string<uuid>, required)

```json
{
  "cloud": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "dataKeptUntil": "2023-11-07T05:31:56Z",
  "deployStage": "applying_custom_resources",
  "disableTLS": true,
  "externalBootstrapURL": "<string>",
  "isManaged": true,
  "localRetentionBytes": 123,
  "localRetentionMS": 123,
  "managed": {
    "allowedCIDRs": [
      "<string>"
    ],
    "brokerConfigs": [
      {
        "name": "<string>",
        "value": "<string>"
      }
    ],
    "brokerSettings": {
      "retentionMS": 123
    },
    "brokers": 123,
    "instanceType": "<string>",
    "kafkaVersion": "<string>",
    "pendingChange": {
      "field": "allowedCIDRs",
      "startedAt": "2023-11-07T05:31:56Z",
      "state": "applying",
      "summary": "<string>"
    },
    "storageGiB": 123
  },
  "name": "<string>",
  "region": "<string>",
  "shuttingDown": true,
  "status": "draft",
  "statusMessage": "<string>",
  "storageAutoscale": {
    "bumpAtPercent": 1,
    "enabled": true,
    "maxGiB": 1,
    "targetPercent": 1
  },
  "tierAllTopics": true,
  "tieredStorageAvailable": true,
  "tieredStorageSyncedAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "usesScram": true,
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

### 400 Bad Request

### 402 Payment Required

### 403 Forbidden

### 404 Not Found

### 424 Failed Dependency

### 500 Internal Server Error