# API Reference for Confluent REST Proxy
The Confluent REST Proxy API is a REST interface for producing and consuming messages,
and managing an Apache Kafka® cluster over HTTP.
For a tutorial using the REST Proxy API, see this [step-by-step guide](https://developer.confluent.io/get-started/rest/).
## Changes with Confluent Platform 8.0
Starting with Confluent Platform 8.0, SNI headers cannot be null due to an upgrade from Jetty 9 to Jetty 12.
Make sure your REST clients set the SNI header or turn off the SNI host check.
To turn off this check, you can set `confluent.http.server.sni.host.check.enabled` to false in the properties file.
If you are using basic authentication, the PropertyFileLoginModule Java package has changed. Instead of
`org.eclipse.jetty.jaas.spi.PropertyFileLoginModule`, use `org.eclipse.jetty.security.jaas.spi.PropertyFileLoginModule`
for Confluent Platform 8.0 and later.
Starting with Confluent Platform 8.0, the system accepts null request bodies only
if the schema allows null values or the schema is null itself. Earlier, all null request bodies defaulted to empty records. To enable the old behavior,
add `null.request.body.always.publishes.empty.record=true` to the properties file.
When posting a new record, if either the record key or value is null, then `key_schema` / `key_schema_id` or
`value_schema` / `value_schema_id` (respectively) must be excluded from the request.
For more information, see [Admin REST APIs Configuration Options for Confluent Server on Confluent Platform](production-deployment/confluent-server/config.md#confluent-server-rest-config).
## Content Types
The REST Proxy uses media types for both requests and responses to show these data properties:
- Serialization format: `json`
- API version: for example, `v2` or `v3`
- Embedded formats: `json`, `binary`, `avro`, `protobuf` and `jsonschema`
#### IMPORTANT
REST Proxy v2 and later supports the `jsonschema` and `protobuf` embedded types.
REST Proxy supports the [Avro®](https://avro.apache.org/docs/current/spec.html), [JSON Schema](https://json-schema.org/),
and [Protobuf](https://developers.google.com/protocol-buffers/) serialization formats. The versions
of the REST Proxy API are `v2` and `v3`.
The embedded format is the format of data you are producing or consuming. The serialization format
embeds these formats into requests or responses. For
example, you can provide `binary` data in a `json`-serialized request; in
this case, provide the data as a base64-encoded string.
- For `v2`, the media type is `application/vnd.kafka.binary.v2+json`.
- For `v3` the media type is `application/json`.
If your data is JSON, you can use `json` as the embedded format and embed it directly:
- For `v2`, the media type is `application/vnd.kafka.json.v2+json`.
- For `v3` the media type is `application/json`.
With `avro`, `protobuf`, and `jsonschema` embedded
types, you can directly embed JSON formatted data along with a schema or schema ID in the request.
These types use Schema Registry and serialize the schema ID with the data and payload.
- The Avro media type is `application/vnd.kafka.avro.v2+json`.
- The Protobuf media type is `application/vnd.kafka.protobuf.v2+json`.
- The JSON schema media type is `application/vnd.kafka.jsonschema.v2+json`.
The format for the media type is:
```none
application/vnd.kafka[.embedded_format].[api_version]+[serialization_format]
```
For more information, see [Schema Registry API Reference for Confluent Platform](../schema-registry/develop/api.md#schemaregistry-api).
You can omit the embedded format when there are no embedded messages
(for example, for metadata requests you can use `application/vnd.kafka.v2+json`).
The preferred media type for `v2` is `application/vnd.kafka.[embedded_format].v2+json`.
However, you can use other less specific media types, including `application/vnd.kafka+json`
to indicate no specific API version requirement (the most recent stable version
will be used), `application/json`, and `application/octet-stream`. The
latter two are only supported for compatibility and ease of use. In all cases,
if the embedded format is omitted, `binary` is assumed. Although using these
less specific values is permitted, to remain compatible with future versions you
*should* specify preferred media types in requests and check the media types
of responses.
Your requests *should* specify the most specific format and version information
possible via the HTTP `Accept` header
For `v2`, you can specify format and version as follows:
```none
Accept: application/vnd.kafka.v2+json
```
For `v3`, do not specify the version. The latest version (`v3`) will be used:
```none
Accept: application/json
```
The server also supports content negotiation, so you may include multiple,
weighted preferences:
```none
Accept: application/vnd.kafka.v2+json; q=0.9, application/json; q=0.5
```
This can be useful when, for example, a new version of the API is preferred but
you cannot be certain it is available yet.
#### SEE ALSO
[REST API Usage Examples (curl)](#rest-api-usage-examples), which show how to test the APIs from the command line using [curl](https://curl.haxx.se/)
## Errors
All API endpoints use a standard error message format for any requests that
return an HTTP status indicating an error (any 400 or 500 statuses). For
example, a request entity that omits a required field may generate the
following response:
```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.kafka.v3+json
{
"error_code": 422,
"message": "records may not be empty"
}
```
Although it is good practice to check the status code, you may safely parse the
response of any non-DELETE API calls and check for the presence of an
`error_code` field to detect errors.
**HTTP status codes versus record-level error codes**
HTTP status codes and the `error_code` field serve different purposes:
- HTTP status codes (such as 400, 401, 403, 422, and 500) indicate request-level failures: authentication errors, malformed JSON, invalid content types, or missing required request fields.
- The `error_code` field in the response body indicates record-level failures: invalid payloads, schema validation errors, bad binary or base64 encoding, or other data-specific issues.
#### IMPORTANT
**The v3 Produce API returns HTTP 200 even when individual records fail validation.**
A successful HTTP 200 response does not guarantee that all records were successfully produced. To detect failures, always parse the response body and check the `error_code` field for each record.
Relying solely on HTTP status codes can result in silent data loss.
Some error codes are used frequently across the entire API and you will probably want to have
general purpose code to handle these, whereas most other error codes will need to be handled on a
per-request basis.
### ANY /
* **Status Codes:**
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
* Error code 40101 – Kafka Authentication Error.
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
* Error code 40301 – Kafka Authorization Error.
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found.
* Error code 40402 – Partition not found.
* [422 Unprocessable Entity](https://www.rfc-editor.org/rfc/rfc4918#section-11.2) – The request payload is either improperly formatted or contains semantic errors
* [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) –
* Error code 50002 – Kafka error.
* Error code 50003 – Retriable Kafka error. Although the operation failed, it’s
possible that retrying the request will be successful.
* Error code 50101 – Only TLS/SSL endpoints were found for the specified broker, but
TLS/SSL is not supported for the invoked API yet.
## REST Proxy API v2
The following sections document the REST Proxy API v2 endpoints for topics, partitions, consumers, and brokers.
### Topics
The topics resource provides information about the topics in your Kafka cluster and their current state. It also lets
you produce messages by making `POST` requests to specific topics.
### GET /topics
Get a list of Kafka topics.
* **Response JSON Object:**
* **topics** (*array*) – List of topic names
**Example request**:
```http
GET /topics HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
["topic1", "topic2"]
```
### GET /topics/(*string:* topic_name)
Get metadata about a specific topic.
* **Parameters:**
* **topic_name** (*string*) – Name of the topic to get metadata about
* **Response JSON Object:**
* **name** (*string*) – Name of the topic
* **configs** (*map*) – Per-topic configuration overrides
* **partitions** (*array*) – List of partitions for this topic
* **partitions[i].partition** (*int*) – the ID of this partition
* **partitions[i].leader** (*int*) – the broker ID of the leader for this partition
* **partitions[i].replicas** (*array*) – list of replicas for this partition,
including the leader
* **partitions[i].replicas[j].broker** (*array*) – broker ID of the replica
* **partitions[i].replicas[j].leader** (*boolean*) – true if this replica is the
leader for the partition
* **partitions[i].replicas[j].in_sync** (*boolean*) – true if this replica is
currently in sync with the
leader
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
**Example request**:
```http
GET /topics/test HTTP/1.1
Accept: application/vnd.kafka.v2+json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"name": "test",
"configs": {
"cleanup.policy": "compact"
},
"partitions": [
{
"partition": 1,
"leader": 1,
"replicas": [
{
"broker": 1,
"leader": true,
"in_sync": true,
},
{
"broker": 2,
"leader": false,
"in_sync": true,
}
]
},
{
"partition": 2,
"leader": 2,
"replicas": [
{
"broker": 1,
"leader": false,
"in_sync": true,
},
{
"broker": 2,
"leader": true,
"in_sync": true,
}
]
}
]
}
```
### POST /topics/(*string:* topic_name)
Produce messages to a topic, optionally specifying keys or partitions for the
messages. If no partition is provided, one will be chosen based on the hash of
the key. If no key is provided, the partition will be chosen for each message
in a round-robin fashion.
For the `avro`, `protobuf`, and `jsonschema` embedded formats, you must provide information
about schemas and the REST Proxy must be configured with the URL to access
Schema Registry (`schema.registry.url`). Schemas may be provided as
the full schema encoded as a string, or, after the initial request may be
provided as the schema ID returned with the first response.
* **Parameters:**
* **topic_name** (*string*) – Name of the topic to produce the messages to
* **Request JSON Object:**
* **key_schema** (*string*) – Full schema encoded as a string (e.g. JSON
serialized for Avro data)
* **key_schema_id** (*int*) – ID returned by a previous request using the same
schema. This ID corresponds to the ID of the schema
in the registry.
* **value_schema** (*string*) – Full schema encoded as a string (e.g. JSON
serialized for Avro data)
* **value_schema_id** (*int*) – ID returned by a previous request using the same
schema. This ID corresponds to the ID of the schema
in the registry.
* **Request JSON Array of Objects:**
* **records** – A list of records to produce to the topic.
* **records[i].key** (*object*) – The message key, formatted according to the
embedded format, or null to omit a key (optional). If null,
you must exclude `key_schema` and `key_schema_id`.
* **records[i].value** (*object*) – The message value, formatted according to the
embedded format. If null, you must exclude `value_schema`
and `value_schema_id`.
* **records[i].partition** (*int*) – Partition to store the message in (optional)
* **Response JSON Object:**
* **key_schema_id** (*int*) – The ID for the schema used to produce keys, or null
if keys were not used
* **value_schema_id** (*int*) – The ID for the schema used to produce values.
* **Response JSON Array of Objects:**
* **offsets** (*object*) – List of partitions and offsets the messages were
published to
* **offsets[i].partition** (*int*) – Partition the message was published to, or null if
publishing the message failed
* **offsets[i].offset** (*long*) – Offset of the message, or null if publishing the message failed
* **offsets[i].error_code** (*long*) –
An error code classifying the reason this operation
failed, or null if it succeeded. If the error is a 400 Bad Request, no array of objects is returned.
* 1 - Non-retriable Kafka exception
* 2 - Retriable Kafka exception; the message might be sent
successfully if retried
* **offsets[i].error** (*string*) – An error message describing why the operation failed, or
null if it succeeded.
* **Status Codes:**
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
* Error code 400 - Serialization error. Response is a single error. No array of objects is returned.
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
* [422 Unprocessable Entity](https://www.rfc-editor.org/rfc/rfc4918#section-11.2) –
* Error code 42201 – Request includes keys and uses a format that requires schemas, but does
not include the `key_schema` or `key_schema_id` fields
* Error code 42202 – Request includes values and uses a format that requires schemas, but
does not include the `value_schema` or `value_schema_id` fields
* Error code 42205 – Request includes invalid schema.
* [408 Request Timeout](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9) –
* Error code 40801 – Schema registration or lookup failed.
**Example binary request**:
```http
POST /topics/test HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.binary.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"records": [
{
"key": "a2V5",
"value": "Y29uZmx1ZW50"
},
{
"value": "a2Fma2E=",
"partition": 1
},
{
"value": "bG9ncw=="
}
]
}
```
**Example binary response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": null,
"offsets": [
{
"partition": 2,
"offset": 100
},
{
"partition": 1,
"offset": 101
},
{
"partition": 2,
"offset": 102
}
]
}
```
**Example Avro request**:
```http
POST /topics/test HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.avro.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"value_schema": "{\"name\":\"int\",\"type\": \"int\"}",
"records": [
{
"value": 12
},
{
"value": 24,
"partition": 1
}
]
}
```
**Example Avro response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": 32,
"offsets": [
{
"partition": 2,
"offset": 103
},
{
"partition": 1,
"offset": 104
}
]
}
```
**Example JSON request**:
```http
POST /topics/test HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.json.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"records": [
{
"key": "somekey",
"value": {"foo": "bar"}
},
{
"value": [ "foo", "bar" ],
"partition": 1
},
{
"value": 53.5
}
]
}
```
**Example JSON response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": null,
"offsets": [
{
"partition": 2,
"offset": 100
},
{
"partition": 1,
"offset": 101
},
{
"partition": 2,
"offset": 102
}
]
}
```
**Example JSON Schema request:**
```http
POST /topics/test HTTP/1.1
Content-Type: application/vnd.kafka.jsonschema.v2+json
Accept: application/vnd.kafka.v2+json, application/json
{
"value_schema": "{\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}",
"records": [{"value": {"f1": "bar"}}]
}
```
**Example JSON Schema response:**
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"offsets": [
{
"partition": 0,
"offset": 26,
"error_code": null,
"error": null
}
],
"key_schema_id": null,
"value_schema_id": 16
}
```
### Partitions
The partitions resource provides per-partition metadata, including the current leaders and replicas for each partition.
It also allows you to consume and produce messages to single partition using `GET` and `POST` requests.
### GET /topics/(*string:* topic_name)/partitions
Get a list of partitions for the topic.
* **Parameters:**
* **topic_name** (*string*) – the name of the topic
* **Response JSON Array of Objects:**
* **partition** (*int*) – ID of the partition
* **leader** (*int*) – Broker ID of the leader for this partition
* **replicas** (*array*) – List of brokers acting as replicas for this partition
* **replicas[i].broker** (*int*) – Broker ID of the replica
* **replicas[i].leader** (*boolean*) – true if this broker is the leader for the partition
* **replicas[i].in_sync** (*boolean*) – true if the replica is in sync with the leader
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
**Example request**:
```http
GET /topics/test/partitions HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
[
{
"partition": 1,
"leader": 1,
"replicas": [
{
"broker": 1,
"leader": true,
"in_sync": true,
},
{
"broker": 2,
"leader": false,
"in_sync": true,
},
{
"broker": 3,
"leader": false,
"in_sync": false,
}
]
},
{
"partition": 2,
"leader": 2,
"replicas": [
{
"broker": 1,
"leader": false,
"in_sync": true,
},
{
"broker": 2,
"leader": true,
"in_sync": true,
},
{
"broker": 3,
"leader": false,
"in_sync": false,
}
]
}
]
```
### GET /topics/(*string:* topic_name)/partitions/(*int:* partition_id)
Get metadata about a single partition in the topic.
* **Parameters:**
* **topic_name** (*string*) – Name of the topic
* **partition_id** (*int*) – ID of the partition to inspect
* **Response JSON Object:**
* **partition** (*int*) – ID of the partition
* **leader** (*int*) – Broker ID of the leader for this partition
* **replicas** (*array*) – List of brokers acting as replicas for this partition
* **replicas[i].broker** (*int*) – Broker ID of the replica
* **replicas[i].leader** (*boolean*) – true if this broker is the leader for the partition
* **replicas[i].in_sync** (*boolean*) – true if the replica is in sync with the leader
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
* Error code 40402 – Partition not found
**Example request**:
```http
GET /topics/test/partitions/1 HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"partition": 1,
"leader": 1,
"replicas": [
{
"broker": 1,
"leader": true,
"in_sync": true,
},
{
"broker": 2,
"leader": false,
"in_sync": true,
},
{
"broker": 3,
"leader": false,
"in_sync": false,
}
]
}
```
### GET /topics/(*string:* topic_name)/partitions/(*int:* partition_id)/offsets
Get a summary of the offsets in this topic partition.
* **Parameters:**
* **topic_name** (*string*) – Name of the topic
* **partition_id** (*int*) – ID of the partition to inspect
* **Response JSON Object:**
* **beginning_offset** (*int*) – First offset in this partition
* **end_offset** (*int*) – Last offset in this partition
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
* Error code 40402 – Partition not found
**Example request**:
```http
GET /topics/test/partitions/1/offsets HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"beginning_offset": 10,
"end_offset": 50,
}
```
### POST /topics/(*string:* topic_name)/partitions/(*int:* partition_id)
Produce messages to one partition of the topic. For the Avro, JSON Schema, and Protobuf embedded
formats, you must provide information about schemas. This may be provided as
the full schema encoded as a string, or, after the initial request may be
provided as the schema ID returned with the first response.
* **Parameters:**
* **topic_name** (*string*) – Topic to produce the messages to
* **partition_id** (*int*) – Partition to produce the messages to
* **Request JSON Object:**
* **key_schema** (*string*) – Full schema encoded as a string (e.g. JSON
serialized for Avro data)
* **key_schema_id** (*int*) – ID returned by a previous request using the same
schema. This ID corresponds to the ID of the schema
in the registry.
* **value_schema** (*string*) – Full schema encoded as a string (e.g. JSON
serialized for Avro data)
* **value_schema_id** (*int*) – ID returned by a previous request using the same
schema. This ID corresponds to the ID of the schema
in the registry.
* **records** – A list of records to produce to the partition.
* **Request JSON Array of Objects:**
* **records[i].key** (*object*) – The message key, formatted according to the
embedded format, or null to omit a key (optional). If null,
you must exclude `key_schema` and `key_schema_id`.
* **records[i].value** (*object*) – The message value, formatted according to the
embedded format. If null, you must exclude `value_schema`
and `value_schema_id`.
* **Response JSON Object:**
* **key_schema_id** (*int*) – The ID for the schema used to produce keys, or null
if keys were not used
* **value_schema_id** (*int*) – The ID for the schema used to produce values.
* **Response JSON Array of Objects:**
* **offsets** (*object*) – List of partitions and offsets the messages were
published to
* **offsets[i].partition** (*int*) – Partition the message was published to. This
will be the same as the `partition_id`
parameter and is provided only to maintain
consistency with responses from producing to
a topic
* **offsets[i].offset** (*long*) – Offset of the message
* **offsets[i].error_code** (*long*) –
An error code classifying the reason this operation
failed, or null if it succeeded.
* 1 - Non-retriable Kafka exception
* 2 - Retriable Kafka exception; the message might be sent
successfully if retried
* **offsets[i].error** (*string*) – An error message describing why the operation failed, or
null if it succeeded
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40401 – Topic not found
* Error code 40402 – Partition not found
* [422 Unprocessable Entity](https://www.rfc-editor.org/rfc/rfc4918#section-11.2) –
* Error code 42201 – Request includes keys and uses a format that requires schemas, but does
not include the `key_schema` or `key_schema_id` fields
* Error code 42202 – Request includes values and uses a format that requires schemas, but
does not include the `value_schema` or `value_schema_id` fields
* Error code 42205 – Request includes invalid schema.
**Example binary request**:
```http
POST /topics/test/partitions/1 HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.binary.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"records": [
{
"key": "a2V5",
"value": "Y29uZmx1ZW50"
},
{
"value": "a2Fma2E="
}
]
}
```
**Example binary response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": null,
"offsets": [
{
"partition": 1,
"offset": 100,
},
{
"partition": 1,
"offset": 101,
}
]
}
```
**Example Avro request**:
```http
POST /topics/test/partitions/1 HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.avro.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"value_schema": "{\"name\":\"int\",\"type\": \"int\"}"
"records": [
{
"value": 25
},
{
"value": 26
}
]
}
```
**Example Avro response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": 32,
"offsets": [
{
"partition": 1,
"offset": 100,
},
{
"partition": 1,
"offset": 101,
}
]
}
```
**Example JSON request**:
```http
POST /topics/test/partitions/1 HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.json.v2+json
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"records": [
{
"key": "somekey",
"value": {"foo": "bar"}
},
{
"value": 53.5
}
]
}
```
**Example JSON response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": null,
"offsets": [
{
"partition": 1,
"offset": 100,
},
{
"partition": 1,
"offset": 101,
}
]
}
```
**Example PROTOBUF request**:
```http
POST /topics/test/partitions/1 HTTP/1.1
Content-Type: application/vnd.kafka.protobuf.v2+json
Accept: application/vnd.kafka.v2+json, application/json
{
"value_schema": "syntax=\"proto3\"; message Foo { string f1 = 1; }"
"records": [{"value": {"f1": "foo"}}]
}
```
**Example PROTOBUF response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": 32,
"offsets": [
{
"partition": 1,
"offset": 100,
},
{
"partition": 1,
"offset": 101,
}
]
}
```
**Example JSON Schema request**:
```http
POST /topics/test/partitions/1 HTTP/1.1
Content-Type: application/vnd.kafka.jsonschema.v2+json
Accept: application/vnd.kafka.v2+json, application/json
{
"value_schema": "{\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}",
"records": [{"value": {"f1": "bar"}}]
}
```
**Example JSON Schema response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"key_schema_id": null,
"value_schema_id": 32,
"offsets": [
{
"partition": 1,
"offset": 100,
},
{
"partition": 1,
"offset": 101,
}
]
}
```
### Consumers
The consumers resource provides access to the current state of consumer groups, allows you to create a consumer in a
consumer group and consume messages from topics and partitions. REST Proxy can convert data stored
in Kafka in serialized form into a JSON-compatible embedded format. These formats are
supported:
- Raw binary data is encoded as base64 strings
- Avro data is converted into embedded
- JSON objects, and JSON is embedded directly
- Protobuf
- JSON Schema
Because consumers are stateful, any consumer instances created with the REST API are tied to a specific REST Proxy
instance. A full URL is provided when the instance is created and it should be used to construct any subsequent
requests. Failing to use the returned URL for future consumer requests will result in 404 errors because the consumer
instance will not be found. If a REST Proxy instance is shutdown, it will attempt to cleanly destroy
any consumers before it is terminated.
### POST /consumers/(*string:* group_name)
Create a new consumer instance in the consumer group. The `format` parameter controls the
deserialization of data from Kafka and the media type that *must* be used in the
`Accept` header of subsequent read API requests performed against this consumer. For
example, if the creation request specifies `avro` for the format, subsequent read requests
should use `Accept: application/vnd.kafka.avro.v2+json`.
Note that the response includes a URL including the host since the consumer is stateful and tied
to a specific REST Proxy instance. Subsequent examples in this section use a `Host` header
for this specific REST Proxy instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group to join
* **Request JSON Object:**
* **name** (*string*) – Name for the consumer instance, which will be used in URLs for the
consumer. This must be unique, at least within REST Proxy process handling
the request. If omitted, falls back on the automatically generated ID. Using
automatically generated names is recommended for most use cases.
* **format** (*string*) – The format of consumed messages, which is used to convert messages into
a JSON-compatible form. Valid values: “binary”, “avro”, “json”, “jsonschema”,
and `protobuf`. If unspecified,
defaults to “binary”.
* **auto.offset.reset** (*string*) – Sets the `auto.offset.reset` setting for the consumer
* **auto.commit.enable** (*string*) – Sets the `auto.commit.enable` setting for the consumer
* **fetch.min.bytes** (*string*) – Sets the `fetch.min.bytes`
setting for this consumer specifically
* **consumer.request.timeout.ms** (*string*) – Sets the `consumer.request.timeout.ms` setting for this consumer specifically.
This setting controls the maximum total time to wait for messages for a request
if the maximum request size has not yet been reached.
It does not affect the underlying consumer->broker connection. Default value is taken from the REST Proxy config file
* **Response JSON Object:**
* **instance_id** (*string*) – Unique ID for the consumer instance in this group.
* **base_uri** (*string*) – Base URI used to construct URIs for subsequent requests against this consumer instance. This
will be of the form `http://hostname:port/consumers/consumer_group/instances/instance_id`.
* **Status Codes:**
* [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) –
* Error code 40902 – Consumer instance with the specified name already exists.
* [422 Unprocessable Entity](https://www.rfc-editor.org/rfc/rfc4918#section-11.2) –
* Error code 42204 – Invalid consumer configuration. One of the settings specified in
the request contained an invalid value.
**Example request**:
```http
POST /consumers/testgroup/ HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"name": "my_consumer",
"format": "binary",
"auto.offset.reset": "earliest",
"auto.commit.enable": "false"
}
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"instance_id": "my_consumer",
"base_uri": "http://proxy-instance.kafkaproxy.example.com/consumers/testgroup/instances/my_consumer"
}
```
**Example PROTOBUF request**:
```http
POST /consumers/testgroup/ HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.protobuf.v2+json
{
"name": "my_consumer",
"format": "protobuf",
"auto.offset.reset": "earliest",
"auto.commit.enable": "false"
}
```
**Example PROTOBUF response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.protobuf.v2+json
{
"instance_id": "my_consumer",
"base_uri": "http://proxy-instance.kafkaproxy.example.com/consumers/my_protobuf_consumer"
}
```
**Example JSON Schema request**:
```http
POST /consumers/testgroup/ HTTP/1.1
Host: kafkaproxy.example.com
Content-Type: application/vnd.kafka.jsonschema.v2+json
{
"name": "my_consumer",
"format": "jsonschema",
"auto.offset.reset": "earliest",
"auto.commit.enable": "false"
}
```
**Example JSON Schema response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.jsonschema.v2+json
{
"instance_id": "my_consumer",
"base_uri": "http://proxy-instance.kafkaproxy.example.com/consumers/my_jsonschema_consumer"
}
```
### DELETE /consumers/(*string:* group_name)/instances/(*string:* instance)
Destroy the consumer instance.
Note that this request *must* be made to the specific REST Proxy instance holding the consumer
instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
DELETE /consumers/testgroup/instances/my_consumer HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/offsets
Commit a list of offsets for the consumer. When the post body is empty, it commits
all the records that have been fetched by the consumer instance.
Note that this request *must* be made to the specific REST Proxy instance holding the consumer
instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **offsets** – A list of offsets to commit for partitions
* **offsets[i].topic** (*string*) – Name of the topic
* **offsets[i].partition** (*int*) – Partition ID
* **offset** – the offset to commit
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/offsets HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"offsets": [
{
"topic": "test",
"partition": 0,
"offset": 20
},
{
"topic": "test",
"partition": 1,
"offset": 30
}
]
}
```
### GET /consumers/(*string:* group_name)/instances/(*string:* instance)/offsets
Get the last committed offsets for the given partitions (whether the commit happened by this process or another).
Note that this request *must* be made to the specific REST Proxy instance holding the consumer
instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **partitions** – A list of partitions to find the last committed offsets for
* **partitions[i].topic** (*string*) – Name of the topic
* **partitions[i].partition** (*int*) – Partition ID
* **Response JSON Array of Objects:**
* **offsets** – A list of committed offsets
* **offsets[i].topic** (*string*) – Name of the topic for which an offset was committed
* **offsets[i].partition** (*int*) – Partition ID for which an offset was committed
* **offsets[i].offset** (*int*) – Committed offset
* **offsets[i].metadata** (*string*) – Metadata for the committed offset
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40402 – Partition not found
* Error code 40403 – Consumer instance not found
**Example request**:
```http
GET /consumers/testgroup/instances/my_consumer/offsets HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
{
"partitions": [
{
"topic": "test",
"partition": 0
},
{
"topic": "test",
"partition": 1
}
]
}
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{"offsets":
[
{
"topic": "test",
"partition": 0,
"offset": 21,
"metadata":""
},
{
"topic": "test",
"partition": 1,
"offset": 31,
"metadata":""
}
]
}
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/subscription
Subscribe to the given list of topics or a topic pattern to get dynamically assigned partitions. If a prior subscription exists, it would be replaced by the latest subscription.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **topics** – A list of topics to subscribe
* **topics[i].topic** (*string*) – Name of the topic
* **Request JSON Object:**
* **topic_pattern** (*string*) – A REGEX pattern. topics_pattern and topics fields are mutually exclusive.
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
* [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) –
* Error code 40903 – Subscription to topics, partitions and pattern are mutually exclusive.
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/subscription HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"topics": [
"test1",
"test2"
]
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/subscription HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"topic_pattern": "test.*"
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### GET /consumers/(*string:* group_name)/instances/(*string:* instance)/subscription
Get the current subscribed list of topics.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Response JSON Array of Objects:**
* **topics** – A list of subscribed topics
* **topics[i]** (*string*) – Name of the topic
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
GET /consumers/testgroup/instances/my_consumer/subscription HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json
```
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"topics": [
"test1",
"test2"
]
}
```
### DELETE /consumers/(*string:* group_name)/instances/(*string:* instance)/subscription
Unsubscribe from topics currently subscribed.
Note that this request *must* be made to the specific REST Proxy instance holding the consumer
instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
DELETE /consumers/testgroup/instances/my_consumer/subscription HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/assignments
Manually assign a list of partitions to this consumer.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **partitions** – A list of partitions to assign to this consumer
* **partitions[i].topic** (*string*) – Name of the topic
* **partitions[i].partition** (*int*) – Partition ID
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
* [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) –
* Error code 40903 – Subscription to topics, partitions and pattern are mutually exclusive.
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/assignments HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"partitions": [
{
"topic": "test",
"partition": 0
},
{
"topic": "test",
"partition": 1
}
]
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### GET /consumers/(*string:* group_name)/instances/(*string:* instance)/assignments
Get the list of partitions currently manually assigned to this consumer.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Response JSON Array of Objects:**
* **partitions** – A list of partitions that are manually assigned to this consumer
* **partitions[i].topic** (*string*) – Name of the topic
* **partitions[i].partition** (*int*) – Partition ID
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
GET /consumers/testgroup/instances/my_consumer/assignments HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json
```
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"partitions": [
{
"topic": "test",
"partition": 0
},
{
"topic": "test",
"partition": 1
}
]
}
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/positions
Overrides the fetch offsets that the consumer will use for the next set of records to fetch.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **offsets** – A list of offsets
* **offsets[i].topic** (*string*) – Name of the topic for
* **offsets[i].partition** (*int*) – Partition ID
* **offsets[i].offset** (*int*) – Seek to offset for the next set of records to fetch
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/positions HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"offsets": [
{
"topic": "test",
"partition": 0,
"offset": 20
},
{
"topic": "test",
"partition": 1,
"offset": 30
}
]
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/positions/beginning
Seek to the first offset for each of the given partitions.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **partitions** – A list of partitions
* **partitions[i].topic** (*string*) – Name of the topic
* **partitions[i].partition** (*int*) – Partition ID
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/positions/beginning HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"partitions": [
{
"topic": "test",
"partition": 0
},
{
"topic": "test",
"partition": 1
}
]
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### POST /consumers/(*string:* group_name)/instances/(*string:* instance)/positions/end
Seek to the last offset for each of the given partitions.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Request JSON Array of Objects:**
* **partitions** – A list of partitions
* **partitions[i].topic** (*string*) – Name of the topic
* **partitions[i].partition** (*int*) – Partition ID
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
**Example request**:
```http
POST /consumers/testgroup/instances/my_consumer/positions/end HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Content-Type: application/vnd.kafka.v2+json
{
"partitions": [
{
"topic": "test",
"partition": 0
},
{
"topic": "test",
"partition": 1
}
]
}
```
**Example response**:
```http
HTTP/1.1 204 No Content
```
### GET /consumers/(*string:* group_name)/instances/(*string:* instance)/records
Fetch data for the topics or partitions specified using one of the subscribe/assign APIs.
The format of the embedded data returned by this request is determined by the format specified
in the initial consumer instance creation request and must match the format of the `Accept`
header. Mismatches will result in error code `40601`.
Note that this request *must* be made to the specific REST Proxy instance holding the consumer
instance.
* **Parameters:**
* **group_name** (*string*) – The name of the consumer group
* **instance** (*string*) – The ID of the consumer instance
* **Query Parameters:**
* **timeout** – Maximum number of milliseconds the REST Proxy spends fetching
records. The other parameters that control the actual time
spent fetching records are `max_bytes` and
`fetch.min.bytes`. The base timeout is the per-consumer
`consumer.request.timeout.ms` set at instance creation.
If unset at creation, the consumer inherits the global
`consumer.request.timeout.ms` from the REST Proxy
configuration file. This query parameter can only shorten
the effective wait below that base timeout, not extend it
beyond it. The global default is 1,000 ms, so an idle
request returns after about one second by default.
Raising the base timeout extends this wait.
* **max_bytes** – The maximum number of bytes of unencoded keys and values that should be
included in the response. This provides approximate control over the size of
responses and the amount of memory required to store the decoded response. The
actual limit will be the minimum of this setting and the server-side
configuration `consumer.request.max.bytes`. Default is unlimited.
* **Response JSON Array of Objects:**
* **topic** (*string*) – The topic
* **key** (*string*) – The message key, formatted according to the embedded format
* **value** (*string*) – The message value, formatted according to the embedded format
* **partition** (*int*) – Partition of the message
* **offset** (*long*) – Offset of the message
* **Status Codes:**
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
* Error code 40403 – Consumer instance not found
* [406 Not Acceptable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) –
* Error code 40601 – Consumer format does not match the embedded format requested by the
`Accept` header.
**Example binary request**:
```http
GET /consumers/testgroup/instances/my_consumer/records?timeout=3000&max_bytes=300000 HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.binary.v2+json
```
**Example binary response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.binary.v2+json
[
{
"topic": "test",
"key": "a2V5",
"value": "Y29uZmx1ZW50",
"partition": 1,
"offset": 100,
},
{
"topic": "test",
"key": "a2V5",
"value": "a2Fma2E=",
"partition": 2,
"offset": 101,
}
]
```
**Example Avro request**:
```http
GET /consumers/avrogroup/instances/my_avro_consumer/records?timeout=3000&max_bytes=300000 HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.avro.v2+json
```
**Example Avro response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.avro.v2+json
[
{
"topic": "test",
"key": 1,
"value": {
"id": 1,
"name": "Bill"
},
"partition": 1,
"offset": 100,
},
{
"topic": "test",
"key": 2,
"value": {
"id": 2,
"name": "Melinda"
},
"partition": 2,
"offset": 101,
}
]
```
**Example JSON request**:
```http
GET /consumers/jsongroup/instances/my_json_consumer/records?timeout=3000&max_bytes=300000 HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.json.v2+json
```
**Example JSON response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.json.v2+json
[
{
"topic": "test",
"key": "somekey",
"value": {"foo":"bar"},
"partition": 1,
"offset": 10,
},
{
"topic": "test",
"key": "somekey",
"value": ["foo", "bar"],
"partition": 2,
"offset": 11,
}
]
```
### Brokers
The brokers resource provides access to the current state of Kafka brokers in the cluster.
### GET /brokers
Get a list of brokers.
* **Response JSON Object:**
* **brokers** (*array*) – List of broker IDs
**Example request**:
```http
GET /brokers HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json
```
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json
{
"brokers": [1, 2, 3]
}
```
## REST Proxy API v3 for Confluent Platform
There is a difference between the REST APIs available on Kafka brokers deployed
with Confluent Server and the REST APIs available with Standalone REST Proxy. Confluent Server provides
several REST APIs that are not available in the open-source Apache Kafka® distribution
provided with Standalone Kafka REST Proxy. The following REST API endpoints are
only available with a Confluent Server deployment:
### **Configs**
```bash
/clusters/{cluster_id}/topics/{topic_name}/default-configs
```
### **Broker**
```bash
/clusters/{cluster_id}/brokers:delete
```
```bash
/clusters/{cluster_id}/brokers/{broker_id}:unregister
```
The GET version of the following endpoint is available in open-source Kafka
REST APis. The DELETE option is available only with REST that runs with a Confluent Server
deployment.
```bash
/clusters/{cluster_id}/brokers/{broker_id}
```
### **Cluster Linking**
```bash
/clusters/{cluster_id}/links
/clusters/{cluster_id}/links/{link_name}
/clusters/{cluster_id}/links/{link_name}/configs
/clusters/{cluster_id}/links/{link_name}/configs/{config_name}
/clusters/{cluster_id}/links/{link_name}/configs:alter
/clusters/{cluster_id}/links/{link_name}/mirrors
/clusters/{cluster_id}/links/-/mirrors
/clusters/{cluster_id}/links/{link_name}/mirrors/{mirror_topic_name}
/clusters/{cluster_id}/links/{link_name}/mirrors:promote
/clusters/{cluster_id}/links/{link_name}/mirrors:failover
/clusters/{cluster_id}/links/{link_name}/mirrors:pause
/clusters/{cluster_id}/links/{link_name}/mirrors:resume
```
### **BalancerStatus**
```bash
/clusters/{cluster_id}/balancer
/clusters/{cluster_id}/balancer/any-uneven-load
```
### **BrokerTask**
```bash
/clusters/{cluster_id}/brokers/-/tasks
/clusters/{cluster_id}/brokers/{broker_id}/tasks
/clusters/{cluster_id}/brokers/-/tasks/{task_type}
/clusters/{cluster_id}/brokers/{broker_id}/tasks/{task_type}
```
### **BrokerReplicaExclusion**
```bash
/clusters/{cluster_id}/broker-replica-exclusions
/clusters/{cluster_id}/broker-replica-exclusions/{broker_id}
/clusters/{cluster_id}/broker-replica-exclusions:create
/clusters/{cluster_id}/broker-replica-exclusions:delete
```
### **RemoveBrokerTask**
```bash
/clusters/{cluster_id}/remove-broker-tasks
/clusters/{cluster_id}/remove-broker-tasks/{broker_id}
```
### **ReplicaStatus**
```bash
/clusters/{cluster_id}/topics/-/partitions/-/replica-status
/clusters/{cluster_id}/topics/{topic_name}/partitions/-/replica-status
/clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replica-status
```
REST that runs with a Confluent Server deployment provides the full set of REST APIs. REST
that runs in a Standalone deployment consists of the open-source Kafka REST APIs
only. For more information about the open-source Kafka REST APIs available, see
[Kafka REST Proxy](https://github.com/confluentinc/kafka-rest#kafka-rest-proxy) and the
[openapi yaml](https://github.com/confluentinc/kafka-rest/blob/master/api/v3/openapi.yaml).
When using the API in Confluent Server, all paths should be prefixed with `/kafka` as
opposed to Standalone REST Proxy. For example, the path to list clusters is:
* Confluent Server: `/kafka/v3/clusters`
* Standalone REST Proxy: `/v3/clusters`
Confluent Server provides an embedded instance of these APIs on the Kafka brokers for the v3 Admin API.
The embedded APIs run on the Confluent HTTP service, `confluent.http.server.listeners`. Therefore, if
you have the HTTP server running, the REST Proxy v3 API is automatically available to you through the brokers.
Note that the [Metadata Server (MDS)](../security/authorization/rbac/mds-api.md#mds-api) is also running on the Confluent HTTP service,
as another endpoint available to you with additional configurations.
When you use the Produce API (POST to `/clusters/{cluster_id}/topics/{topic_name}/records`),
HTTP status codes and the `error_code` field report different layers of failure:
- HTTP 200 indicates that the request envelope was valid (correct authentication, valid JSON, proper content type).
- HTTP 400 or 422 indicates request-level failures, such as malformed JSON, an invalid content type, or authentication issues.
- Record-level failures return HTTP 200 with `error_code` in the response body for each failed record.
Examples of record-level failures that return HTTP 200:
- Invalid base64 encoding in binary payloads.
- Schema validation errors.
- Malformed Avro, Protobuf, or JSON schema data.
- Invalid record headers.
#### WARNING
Always check the `error_code` field for each record in the response body, even on HTTP 200. Failing to do so can result in silent data loss.
### Cell (v3)
### GET /clusters/{cluster_id}/cells
**Get Cluster Cell Configuration**
[](#section/Versioning/API-Lifecycle-Policy)
Returns a list of cells that belong to the specified Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/cells HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of cells.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaCells",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/cells",
"resource_name": "crn:///kafka=cluster-1"
},
"cluster_id": "cluster-1",
"cells": [
{
"kind": "Cell",
"metadata": {
"self": "cells",
"resource_name": "cell"
},
"cell_id": 0,
"state": 1,
"brokers": [
0,
1,
2
],
"open-for-tenant-assignment": true
},
{
"kind": "Cell",
"metadata": {
"self": "cells",
"resource_name": "cell"
},
"cell_id": 1,
"state": 1,
"brokers": [
3,
4,
5
],
"open-for-tenant-assignment": true
},
{
"kind": "Cell",
"metadata": {
"self": "cells",
"resource_name": "cell"
},
"cell_id": 2,
"state": 1,
"brokers": [
6
],
"open-for-tenant-assignment": true
}
],
"cells_enabled": true
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Cluster (v3)
### GET /clusters
**List Clusters**
[](#section/Versioning/API-Lifecycle-Policy)
‘Return a list of known Kafka clusters. Currently both Kafka and Kafka REST
Proxy are only aware of the Kafka cluster pointed at by the
`bootstrap.servers` configuration. Therefore only one Kafka cluster will be returned in the
response.’
**Example request:**
```http
GET /clusters HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of Kafka clusters.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaClusterList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters",
"next": null
},
"data": [
{
"kind": "KafkaCluster",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1",
"resource_name": "crn:///kafka=cluster-1"
},
"cluster_id": "cluster-1",
"controller": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"acls": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls"
},
"brokers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers"
},
"broker_configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs"
},
"consumer_groups": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups"
},
"topics": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/partitions/-/reassignment"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}
**Get Cluster**
[](#section/Versioning/API-Lifecycle-Policy)
Return the Kafka cluster with the specified `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The Kafka cluster.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaCluster",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1",
"resource_name": "crn:///kafka=cluster-1"
},
"cluster_id": "cluster-1",
"controller": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"acls": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls"
},
"brokers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers"
},
"broker_configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs"
},
"consumer_groups": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups"
},
"topics": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/partitions/-/reassignment"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Configs (v3)
### GET /clusters/{cluster_id}/broker-configs
**List Dynamic Broker Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of dynamic cluster-wide broker configuration parameters for the specified Kafka
cluster. Returns an empty list if there are no dynamic cluster-wide broker configuration parameters.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/broker-configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of cluster configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaClusterConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs",
"next": null
},
"data": [
{
"kind": "KafkaClusterConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs/max.connections",
"resource_name": "crn:///kafka=cluster-1/broker-config=max.connections"
},
"cluster_id": "cluster-1",
"config_type": "BROKER",
"name": "max.connections",
"value": "1000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG",
"synonyms": [
{
"name": "max.connections",
"value": "1000",
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG"
},
{
"name": "max.connections",
"value": "2147483647",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaClusterConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/broker-config=compression.type"
},
"cluster_id": "cluster-1",
"config_type": "BROKER",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/broker-configs:alter
**Batch Alter Dynamic Broker Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Update or delete a set of dynamic cluster-wide broker configuration parameters.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/broker-configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "max.connections",
"operation": "DELETE"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/broker-configs/{name}
**Get Dynamic Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Return the dynamic cluster-wide broker configuration parameter specified by `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
GET /clusters/{cluster_id}/broker-configs/{name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The cluster configuration parameter.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaClusterConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/broker-config=compression.type"
},
"cluster_id": "cluster-1",
"config_type": "BROKER",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_DEFAULT_BROKER_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/broker-configs/{name}
**Update Dynamic Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Update the dynamic cluster-wide broker configuration parameter specified by `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
PUT /clusters/{cluster_id}/broker-configs/{name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "gzip"
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/broker-configs/{name}
**Reset Dynamic Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Reset the configuration parameter specified by `name` to its
default value by deleting a dynamic cluster-wide configuration.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **name** (*string*) – The configuration parameter name.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/-/configs
**List Dynamic Broker Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of dynamic configuration parameters for all the brokers in the given Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/-/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of broker configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs",
"next": null
},
"data": [
{
"kind": "KafkaBrokerConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs/max.connections",
"resource_name": "crn:///kafka=cluster-1/broker=1/config=max.connections"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"name": "max.connections",
"value": "1000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_BROKER_CONFIG",
"synonyms": [
{
"name": "max.connections",
"value": "1000",
"source": "DYNAMIC_BROKER_CONFIG"
},
{
"name": "max.connections",
"value": "2147483647",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaBrokerConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/broker=1/config=compression.type"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_BROKER_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_BROKER_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}/configs
**List Broker Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of configuration parameters that belong to the specified Kafka broker.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id}/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of broker configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs",
"next": null
},
"data": [
{
"kind": "KafkaBrokerConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs/max.connections",
"resource_name": "crn:///kafka=cluster-1/broker=1/config=max.connections"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"name": "max.connections",
"value": "1000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_BROKER_CONFIG",
"synonyms": [
{
"name": "max.connections",
"value": "1000",
"source": "DYNAMIC_BROKER_CONFIG"
},
{
"name": "max.connections",
"value": "2147483647",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaBrokerConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/broker=1/config=compression.type"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_BROKER_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_BROKER_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/brokers/{broker_id}/configs:alter
**Batch Alter Broker Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Update or delete a set of broker configuration parameters.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
POST /clusters/{cluster_id}/brokers/{broker_id}/configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "max.connections",
"operation": "DELETE"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}/configs/{name}
**Get Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Return the configuration parameter specified by `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id}/configs/{name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The broker configuration parameter.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/broker=1/config=compression.type"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_BROKER_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_BROKER_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/brokers/{broker_id}/configs/{name}
**Update Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Update the configuration parameter specified by `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
PUT /clusters/{cluster_id}/brokers/{broker_id}/configs/{name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "gzip"
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/brokers/{broker_id}/configs/{name}
**Reset Broker Config**
[](#section/Versioning/API-Lifecycle-Policy)
Reset the configuration parameter specified by `name` to its default value.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **name** (*string*) – The configuration parameter name.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/configs
**List Topic Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of configuration parameters that belong to the specified topic.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of cluster configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopicConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs",
"next": null
},
"data": [
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/cleanup.policy",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=cleanup.policy"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "cleanup.policy",
"value": "compact",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "cleanup.policy",
"value": "compact",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "cleanup.policy",
"value": "delete",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=compression.type"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/topics/{topic_name}/configs:alter
**Batch Alter Topic Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Update or delete a set of topic configuration parameters.
Also supports a dry-run mode that only validates whether the operation would succeed if the
`validate_only` request property is explicitly specified and set to true.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**batch_alter_topic_configs:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "cleanup.policy",
"operation": "DELETE"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
**validate_only_batch_alter_topic_configs:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "cleanup.policy",
"operation": "DELETE"
},
{
"name": "compression.type",
"value": "gzip"
}
],
"validate_only": true
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/configs/{name}
**Get Topic Config**
[](#section/Versioning/API-Lifecycle-Policy)
Return the configuration parameter with the given `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/configs/{name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The topic configuration parameter.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/compression.type",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=compression.type"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/topics/{topic_name}/configs/{name}
**Update Topic Config**
[](#section/Versioning/API-Lifecycle-Policy)
Update the configuration parameter with given `name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
PUT /clusters/{cluster_id}/topics/{topic_name}/configs/{name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "gzip"
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/topics/{topic_name}/configs/{name}
**Reset Topic Config**
[](#section/Versioning/API-Lifecycle-Policy)
Reset the configuration parameter with given `name` to its default value.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **name** (*string*) – The configuration parameter name.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/-/configs
**List All Topic Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of configuration parameters for all topics hosted by the specified
cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/-/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of cluster configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopicConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs",
"next": null
},
"data": [
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/cleanup.policy",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=cleanup.policy"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "cleanup.policy",
"value": "compact",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "cleanup.policy",
"value": "compact",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "cleanup.policy",
"value": "delete",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=compression.type"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/default-configs
**List New Topic Default Configs**
[](#section/Versioning/API-Lifecycle-Policy)
List the default configuration parameters used if the topic were to be newly created.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/default-configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of cluster configs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopicConfigList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs",
"next": null
},
"data": [
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/cleanup.policy",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=cleanup.policy"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "cleanup.policy",
"value": "compact",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "cleanup.policy",
"value": "compact",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "cleanup.policy",
"value": "delete",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaTopicConfig",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/compression.type",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/config=compression.type"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"name": "compression.type",
"value": "gzip",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_TOPIC_CONFIG",
"synonyms": [
{
"name": "compression.type",
"value": "gzip",
"source": "DYNAMIC_TOPIC_CONFIG"
},
{
"name": "compression.type",
"value": "producer",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/groups/{group_id}/configs
**List all configs of the group**
[](#section/Versioning/API-Lifecycle-Policy)
List all configurations for the specified group. This API supports consumer groups, share groups, and streams groups.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/groups/{group_id}/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Config name and value for group configurations.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaGroupConfigDataList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/groups/group-1/configs",
"next": null
},
"data": [
{
"kind": "KafkaGroupConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/groups/group-1/configs/share.session.timeout.ms",
"resource_name": "crn:///kafka=cluster-1/group=group-1/config=share.session.timeout.ms"
},
"cluster_id": "cluster-1",
"group_id": "group-1",
"name": "share.session.timeout.ms",
"value": "45000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_GROUP_CONFIG",
"synonyms": [
{
"name": "share.session.timeout.ms",
"value": "45000",
"source": "DYNAMIC_GROUP_CONFIG"
},
{
"name": "share.session.timeout.ms",
"value": "30000",
"source": "DEFAULT_CONFIG"
}
]
},
{
"kind": "KafkaGroupConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/groups/group-1/configs/share.heartbeat.interval.ms",
"resource_name": "crn:///kafka=cluster-1/group=group-1/config=share.heartbeat.interval.ms"
},
"cluster_id": "cluster-1",
"group_id": "group-1",
"name": "share.heartbeat.interval.ms",
"value": null,
"is_default": true,
"is_read_only": false,
"is_sensitive": false,
"source": "DEFAULT_CONFIG",
"synonyms": [
{
"name": "share.heartbeat.interval.ms",
"value": "3000",
"source": "DEFAULT_CONFIG"
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/groups/{group_id}/configs/{name}
**Get group config**
[](#section/Versioning/API-Lifecycle-Policy)
Get the configuration with the specified name for the specified group. This API supports consumer groups, share groups, and streams groups.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
GET /clusters/{cluster_id}/groups/{group_id}/configs/{name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Config name and value for group configuration.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaGroupConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/groups/group-1/configs/share.session.timeout.ms",
"resource_name": "crn:///kafka=cluster-1/group=group-1/config=share.session.timeout.ms"
},
"cluster_id": "cluster-1",
"group_id": "group-1",
"name": "share.session.timeout.ms",
"value": "45000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_GROUP_CONFIG",
"synonyms": [
{
"name": "share.session.timeout.ms",
"value": "45000",
"source": "DYNAMIC_GROUP_CONFIG"
},
{
"name": "share.session.timeout.ms",
"value": "30000",
"source": "DEFAULT_CONFIG"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/groups/{group_id}/configs/{name}
**Update group config**
[](#section/Versioning/API-Lifecycle-Policy)
Update the configuration with the specified name for the specified group. This API supports consumer groups, share groups, and streams groups.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **name** (*string*) – The configuration parameter name.
**Example request:**
```http
PUT /clusters/{cluster_id}/groups/{group_id}/configs/{name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "45000"
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/groups/{group_id}/configs/{name}
**Delete group config**
[](#section/Versioning/API-Lifecycle-Policy)
Delete the dynamic configuration override with the specified name for the specified group. After deletion, the default group configuration will be applied. This API supports consumer groups, share groups, and streams groups.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **name** (*string*) – The configuration parameter name.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/groups/{group_id}/configs:alter
**Batch Alter Group Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Batch alter configurations for the specified group. This API supports consumer groups, share groups, and streams groups.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**Example request:**
```http
POST /clusters/{cluster_id}/groups/{group_id}/configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "share.session.timeout.ms",
"operation": "DELETE"
},
{
"name": "share.heartbeat.interval.ms",
"value": "5000"
}
]
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Broker (v3)
### GET /clusters/{cluster_id}/brokers
**List Brokers**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of brokers that belong to the specified
Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of brokers.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers",
"next": null
},
"data": [
{
"kind": "KafkaBroker",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1",
"resource_name": "crn:///kafka=cluster-1/broker=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"host": "localhost",
"port": 9291,
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs"
},
"partition_replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/partition-replicas"
}
},
{
"kind": "KafkaBroker",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2",
"resource_name": "crn:///kafka=cluster-1/broker=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"host": "localhost",
"port": 9292,
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2/configs"
},
"partition_replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2/partition-replicas"
}
},
{
"kind": "KafkaBroker",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/3",
"resource_name": "crn:///kafka=cluster-1/broker=3"
},
"cluster_id": "cluster-1",
"broker_id": 3,
"host": "localhost",
"port": 9293,
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/3/configs"
},
"partition_replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/3/partition-replicas"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}
**Get Broker**
[](#section/Versioning/API-Lifecycle-Policy)
Return the broker specified by `broker_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The broker.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBroker",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1",
"resource_name": "crn:///kafka=cluster-1/broker=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"host": "localhost",
"port": 9291,
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/configs"
},
"partition_replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/partition-replicas"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/brokers/{broker_id}
**Delete Broker**
[](#section/Versioning/API-Lifecycle-Policy)
Delete the broker that is specified by `broker_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **Query Parameters:**
* **should_shutdown** (*boolean*) – To shutdown the broker or not, Default: true
* **Status Codes:**
* [202 Accepted](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) –
The single broker removal response
**Example response:**
```http
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"kind": "KafkaBrokerRemoval",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1",
"resource_name": "crn:///kafka=cluster-1/broker=1/"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"broker_task": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Bad broker or balancer request
**IllegalBrokerRemoval:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot remove broker 1 as there are partitions with replication factor equal to 1 on the broker. One such partition: test_topic_partition_0."
}
```
**BalancerOffline:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "The Confluent Balancer component is disabled or not started yet."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Broker not found.
**Example response:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Broker not found. Broker: 1 not found in the cluster: cluster-1"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}/partition-replicas
**List Replicas by Broker**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of replicas assigned to the specified broker.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id}/partition-replicas HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of replicas.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicaList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/partition-replicas",
"next": null
},
"data": [
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=2/replica=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 2,
"broker_id": 1,
"is_leader": true,
"is_in_sync": true,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/3/replicas/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-3/partition=3/replica=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-2",
"partition_id": 3,
"broker_id": 1,
"is_leader": false,
"is_in_sync": true,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/1/replicas/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-3/partition=1/replica=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-3",
"partition_id": 1,
"broker_id": 1,
"is_leader": false,
"is_in_sync": false,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/brokers:delete
**Delete several brokers**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **should_shutdown** (*boolean*) – To shutdown the broker or not, Default: true
**Example request:**
```http
POST /clusters/{cluster_id}/brokers:delete HTTP/1.1
Host: example.com
Content-Type: application/json
{
"broker_ids": [
1,
2,
3
]
}
```
* **Status Codes:**
* [202 Accepted](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) –
The multiple broker removal response
**Example response:**
```http
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"kind": "KafkaBrokerRemovalList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers:delete",
"next": null
},
"data": [
{
"kind": "KafkaBrokerRemoval",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1",
"resource_name": "crn:///kafka=cluster-1/broker=1/"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"broker_task": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaBrokerRemoval",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1",
"resource_name": "crn:///kafka=cluster-1/broker=1/"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"broker_task": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Bad broker or balancer request
**IllegalBrokerRemoval:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot remove broker 1 as there are partitions with replication factor equal to 1 on the broker. One such partition: test_topic_partition_0."
}
```
**BalancerOffline:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "The Confluent Balancer component is disabled or not started yet."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Broker not found.
**Example response:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Broker not found. Broker: 1 not found in the cluster: cluster-1"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/brokers:add
**Register brokers for SBC broker addition**
[](#section/Versioning/API-Lifecycle-Policy)
Register the given brokers with SBC’s broker-addition workflow, triggering rebalancing onto them that can be tracked to completion.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/brokers:add HTTP/1.1
Host: example.com
Content-Type: application/json
{
"broker_ids": [
6,
7
]
}
```
* **Status Codes:**
* [202 Accepted](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) – Request accepted for processing, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
The broker addition request is invalid, e.g. because the broker id list is empty, contains a null, negative, or duplicate broker id.
**invalid_broker_addition:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Invalid broker addition request: The request contains a null broker id."
}
```
**unrepresentable_broker_id:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Unrepresentable broker id: The request contains an unrepresentable broker id: -1."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates the specified cluster does not exist, or the request named broker ids that are not alive and registered in the cluster.
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**broker_id_not_registered:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "BrokerIdNotRegisteredException: Cannot add brokers [2] because the following broker ids are not alive and registered in the cluster: [2]"
}
```
* [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) –
The broker addition request conflicts with the current cluster state, e.g. an active broker exclusion, an in-progress broker removal, or a degraded broker.
**broker_excluded_for_replica_placement:**
```http
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error_code": 409,
"message": "Broker excluded from replica placement: Cannot add brokers [2] because the following broker ids have an active replica placement exclusion: [2]"
}
```
**broker_removal_in_progress:**
```http
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error_code": 409,
"message": "Broker removal in progress: Cannot add brokers [3] because a broker removal operation is currently in progress"
}
```
**broker_degraded:**
```http
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error_code": 409,
"message": "Broker degraded: Cannot add brokers [2] because the following broker ids are degraded: [2]"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* [503 Service Unavailable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) –
Confluent Balancer is not started or not enabled.
**Example response:**
```http
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{
"error_code": 503,
"message": "Balancer offline: Received request to add brokers [2] while DataBalancer is not started."
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Replica (v3)
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replicas
**List Replicas**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of replicas for the specified partition.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replicas HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of replicas.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicaList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas",
"next": null
},
"data": [
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/replica=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"broker_id": 1,
"is_leader": true,
"is_in_sync": true,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/2",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/replica=2"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"broker_id": 2,
"is_leader": false,
"is_in_sync": true,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
},
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/3",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/replica=3"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"broker_id": 3,
"is_leader": false,
"is_in_sync": false,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/3"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replicas/{broker_id}
**Get Replica**
[](#section/Versioning/API-Lifecycle-Policy)
Return the replica for the specified partition assigned to the specified broker.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replicas/{broker_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The replica.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplica",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/replica=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"broker_id": 1,
"is_leader": true,
"is_in_sync": true,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### ACL (v3)
### POST /clusters/{cluster_id}/acls:batch
**Batch Create ACLs**
[](#section/Versioning/API-Lifecycle-Policy)
Create ACLs.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/acls:batch HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"resource_type": "CLUSTER",
"resource_name": "kafka-cluster",
"pattern_type": "LITERAL",
"principal": "principalType:principalName",
"host": "*",
"operation": "DESCRIBE",
"permission": "DENY"
},
{
"resource_type": "TOPIC",
"resource_name": "kafka-cluster",
"pattern_type": "LITERAL",
"principal": "principalType:principalName",
"host": "*",
"operation": "READ",
"permission": "ALLOW"
}
]
}
```
* **Status Codes:**
* [201 Created](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) – Created
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**create_acls_cluster_name_invalid:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40002,
"message": "The only valid name for the CLUSTER resource is kafka-cluster\""
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/acls
**List ACLs**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of ACLs that match the search criteria. These are Apache Kafka ACLs, which differ from
the Confluent Metadata Service (MDS) based, centralized ACLs created with the Confluent CLI. MDS has a separate API for ACLs.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **resource_type** (*string*) – The ACL resource type.
* **resource_name** (*string*) – The ACL resource name.
* **pattern_type** (*string*) – The ACL pattern type.
* **principal** (*string*) – The ACL principal. This is the Service Account name or user name.
* **host** (*string*) – The ACL host.
* **operation** (*string*) – The ACL operation.
* **permission** (*string*) – The ACL permission.
**Example request:**
```http
GET /clusters/{cluster_id}/acls HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of ACLs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaAclList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?principal=User%3Aalice"
},
"data": [
{
"kind": "KafkaAcl",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=TOPIC&resource_name=topic-&pattern_type=PREFIXED&principal=User%3Aalice&host=*&operation=ALL&permission=ALLOW"
},
"cluster_id": "cluster-1",
"resource_type": "TOPIC",
"resource_name": "topic-",
"pattern_type": "PREFIXED",
"principal": "User:alice",
"host": "*",
"operation": "ALL",
"permission": "ALLOW"
},
{
"kind": "KafkaAcl",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=CLUSTER&resource_name=kafka-cluster&pattern_type=LITERAL&principal=User%3Aalice&host=*&operation=DESCRIBE&permission=DENY"
},
"cluster_id": "cluster-1",
"resource_type": "CLUSTER",
"resource_name": "kafka-cluster",
"pattern_type": "LITERAL",
"principal": "User:alice",
"host": "*",
"operation": "DESCRIBE",
"permission": "DENY"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/acls
**Create an ACL**
[](#section/Versioning/API-Lifecycle-Policy)
Create an Apache Kafka ACL.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/acls HTTP/1.1
Host: example.com
Content-Type: application/json
{
"resource_type": "CLUSTER",
"resource_name": "kafka-cluster",
"pattern_type": "LITERAL",
"principal": "principalType:principalName",
"host": "*",
"operation": "DESCRIBE",
"permission": "DENY"
}
```
* **Status Codes:**
* [201 Created](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) – Created
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**create_acls_cluster_name_invalid:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40002,
"message": "The only valid name for the CLUSTER resource is kafka-cluster\""
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/acls
**Delete ACLs**
[](#section/Versioning/API-Lifecycle-Policy)
Delete the list of Apache Kafka ACLs that matches the search criteria.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **resource_type** (*string*) – The ACL resource type.
(Required)
* **resource_name** (*string*) – The ACL resource name.
* **pattern_type** (*string*) – The ACL pattern type.
(Required)
* **principal** (*string*) – The ACL principal. This is the Service Account name or user name.
* **host** (*string*) – The ACL host.
* **operation** (*string*) – The ACL operation.
(Required)
* **permission** (*string*) – The ACL permission.
(Required)
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of deleted ACLs.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"kind": "KafkaAcl",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=TOPIC&resource_name=topic-&pattern_type=PREFIXED&principal=User%3Aalice&host=*&operation=ALL&permission=ALLOW"
},
"cluster_id": "cluster-1",
"resource_type": "TOPIC",
"resource_name": "topic-",
"pattern_type": "PREFIXED",
"principal": "User:alice",
"host": "*",
"operation": "ALL",
"permission": "ALLOW"
},
{
"kind": "KafkaAcl",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=CLUSTER&resource_name=kafka-cluster&pattern_type=LITERAL&principal=User%3Aalice&host=*&operation=DESCRIBE&permission=DENY"
},
"cluster_id": "cluster-1",
"resource_type": "CLUSTER",
"resource_name": "kafka-cluster",
"pattern_type": "LITERAL",
"principal": "User:alice",
"host": "*",
"operation": "DESCRIBE",
"permission": "DENY"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**delete_acls_unspecified_resource_type:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "resource_type cannot be unspecified or UNKNOWN"
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Consumer Group (v3)
### GET /clusters/{cluster_id}/consumer-groups
**List Consumer Groups**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of consumer groups that belong to the specified
Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of consumer groups.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerGroupList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups",
"next": null
},
"data": [
{
"kind": "KafkaConsumerGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"is_simple": false,
"partition_assignor": "org.apache.kafka.clients.consumer.RoundRobinAssignor",
"state": "STABLE",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers"
},
"lag_summary": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lag-summary"
}
},
{
"kind": "KafkaConsumerGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-2",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-2"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-2",
"is_simple": false,
"partition_assignor": "org.apache.kafka.clients.consumer.StickyAssignor",
"state": "PREPARING_REBALANCE",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-2/consumers"
},
"lag_summary": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-2/lag-summary"
}
},
{
"kind": "KafkaConsumerGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-3",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-3"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-3",
"is_simple": false,
"partition_assignor": "org.apache.kafka.clients.consumer.RangeAssignor",
"state": "DEAD",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/3"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-3/consumers"
},
"lag_summary": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-3/lag-summary"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}
**Get Consumer Group**
[](#section/Versioning/API-Lifecycle-Policy)
Return the consumer group specified by the `consumer_group_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The consumer group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"is_simple": false,
"partition_assignor": "org.apache.kafka.clients.consumer.RoundRobinAssignor",
"state": "STABLE",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers"
},
"lag_summary": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lag-summary"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers
**List Consumers**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of consumers that belong to the specified consumer
group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of consumers.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers",
"next": null
},
"data": [
{
"kind": "KafkaConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"instance_id": "consumer-instance-1",
"client_id": "client-1",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments"
}
},
{
"kind": "KafkaConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-2",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-2"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-2",
"instance_id": "consumer-instance-2",
"client_id": "client-2",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-2/assignments"
}
},
{
"kind": "KafkaConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-2",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-2"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-2",
"instance_id": "consumer-instance-2",
"client_id": "client-2",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-2/assignments"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lag-summary
**Get Consumer Group Lag Summary**
[](#section/Versioning/API-Lifecycle-Policy)
Return the maximum and total lag of the consumers belonging to the
specified consumer group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lag-summary HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The max and total consumer lag in a consumer group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerGroupLagSummary",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lag-summary",
"resource_name": "crn:///kafka=cluster-1/consumer-groups=consumer-group-1/lag-summary"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"max_lag_consumer_id": "consumer-1",
"max_lag_instance_id": "consumer-instance-1",
"max_lag_client_id": "client-1",
"max_lag_topic_name": "topic-1",
"max_lag_partition_id": 1,
"max_lag": 100,
"total_lag": 110,
"max_lag_consumer": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1"
},
"max_lag_partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lags
**List Consumer Lags**
[](#section/Versioning/API-Lifecycle-Policy)[](https://docs.confluent.io/cloud/current/clusters/cluster-types.html#dedicated-cluster)
Return a list of consumer lags of the consumers belonging to the
specified consumer group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lags HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of consumer lags.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerLagList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags",
"next": null
},
"data": [
{
"kind": "KafkaConsumerLag",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/lag=topic-1/partition=1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"topic_name": "topic-1",
"partition_id": 1,
"consumer_id": "consumer-1",
"instance_id": "consumer-instance-1",
"client_id": "client-1",
"current_offset": 1,
"log_end_offset": 101,
"lag": 100
},
{
"kind": "KafkaConsumerLag",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/2",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/lag=topic-1/partition=2"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"topic_name": "topic-1",
"partition_id": 2,
"consumer_id": "consumer-2",
"instance_id": "consumer-instance-2",
"client_id": "client-2",
"current_offset": 1,
"log_end_offset": 11,
"lag": 10
},
{
"kind": "KafkaConsumerLag",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/3",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/lag=topic-1/partition=3"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"topic_name": "topic-1",
"partition_id": 3,
"consumer_id": "consumer-3",
"instance_id": "consumer-instance-3",
"client_id": "client-3",
"current_offset": 1,
"log_end_offset": 1,
"lag": 0
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lags/{topic_name}/partitions/{partition_id}
**Get Consumer Lag**
[](#section/Versioning/API-Lifecycle-Policy)[](https://docs.confluent.io/cloud/current/clusters/cluster-types.html#dedicated-cluster)
Return the consumer lag on a partition with the given `partition_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lags/{topic_name}/partitions/{partition_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The consumer lag.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerLag",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/lag=topic-1/partition=1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"topic_name": "topic-1",
"partition_id": 1,
"consumer_id": "consumer-1",
"instance_id": "consumer-instance-1",
"client_id": "client-1",
"current_offset": 1,
"log_end_offset": 101,
"lag": 100
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}
**Get Consumer**
[](#section/Versioning/API-Lifecycle-Policy)
Return the consumer specified by the `consumer_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
* **consumer_id** (*string*) – The consumer ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The consumer.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"instance_id": "consumer-instance-1",
"client_id": "client-1",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}/assignments
**List Consumer Assignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of partition assignments for the specified consumer.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
* **consumer_id** (*string*) – The consumer ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}/assignments HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of consumer group assignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerAssignmentList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments",
"next": null
},
"data": [
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1/assignment=topic=1/partition=1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-1",
"partition_id": 1,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1"
},
"lag": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/1"
}
},
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments/topic-2/partitions/2",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1/assignment=topic=2/partition=2"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-2",
"partition_id": 2,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/2"
},
"lag": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-2/partitions/2"
}
},
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments/topic-3/partitions/3",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1/assignment=topic=3/partition=3"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-3",
"partition_id": 3,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/3"
},
"lag": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-3/partitions/3"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}/assignments/{topic_name}/partitions/{partition_id}
**Get Consumer Assignment**
[](#section/Versioning/API-Lifecycle-Policy)
Return information about the assignment for the specified consumer
to the specified partition.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **consumer_group_id** (*string*) – The consumer group ID.
* **consumer_id** (*string*) – The consumer ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}/assignments/{topic_name}/partitions/{partition_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The consumer group assignment.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1/assignments/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/consumer-group=consumer-group-1/consumer=consumer-1/assignment=topic=1/partition=1"
},
"cluster_id": "cluster-1",
"consumer_group_id": "consumer-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-1",
"partition_id": 1,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1"
},
"lag": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Partition (v3)
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions
**List Partitions**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of partitions that belong to the specified topic.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of partitions.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPartitionList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions",
"next": null
},
"data": [
{
"kind": "KafkaPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"leader": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1"
},
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas"
},
"reassignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment"
}
},
{
"kind": "KafkaPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=2"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 2,
"leader": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas/2"
},
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas"
},
"reassignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/reassignment"
}
},
{
"kind": "KafkaPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=3"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 3,
"leader": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/replicas/3"
},
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/replicas"
},
"reassignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/reassignment"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}
**Get Partition**
[](#section/Versioning/API-Lifecycle-Policy)
Return the partition with the given `partition_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The partition
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"leader": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas/1"
},
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas"
},
"reassignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/-/partitions/-/reassignment
**List All Replica Reassignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of all ongoing replica reassignments in the given Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/-/partitions/-/reassignment HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The ongoing replicas reassignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReassignmentList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/partitions/-/reassignment",
"next": null
},
"data": [
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"adding_replicas": [
1,
2
],
"removing_replicas": [
3
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas"
}
},
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/2/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-2/partition=2/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-2",
"partition_id": 2,
"adding_replicas": [
1
],
"removing_replicas": [
2,
3
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/2/replicas"
}
},
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/3/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-3/partition=3/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-3",
"partition_id": 3,
"adding_replicas": [
3
],
"removing_replicas": [
1,
2
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/3/replicas"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/-/reassignment
**List Replica Reassignments By Topic**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of ongoing replica reassignments for the given topic.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/-/reassignment HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The ongoing replicas reassignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReassignmentList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/partitions/-/reassignment",
"next": null
},
"data": [
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"adding_replicas": [
1,
2
],
"removing_replicas": [
3
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas"
}
},
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=2/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 2,
"adding_replicas": [
1
],
"removing_replicas": [
2,
3
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/2/replicas"
}
},
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=3/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 3,
"adding_replicas": [
3
],
"removing_replicas": [
1,
2
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/3/replicas"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/reassignment
**Get Replica Reassignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of ongoing replica reassignments for the given partition.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/reassignment HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The ongoing replicas reassignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReassignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/reassignment",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1/partition=1/reassignment"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"adding_replicas": [
1,
2
],
"removing_replicas": [
3
],
"replicas": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1/replicas"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Topic (v3)
### GET /clusters/{cluster_id}/topics
**List Topics**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of topics that belong to the specified Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of topics.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopicList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics",
"next": null
},
"data": [
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"is_internal": false,
"replication_factor": 3,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/-/reassignments"
}
},
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2",
"resource_name": "crn:///kafka=cluster-1/topic=topic-2"
},
"cluster_id": "cluster-1",
"topic_name": "topic-2",
"is_internal": true,
"replication_factor": 4,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/-/reassignments"
}
},
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3",
"resource_name": "crn:///kafka=cluster-1/topic=topic-3"
},
"cluster_id": "cluster-1",
"topic_name": "topic-3",
"is_internal": false,
"replication_factor": 5,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/-/reassignments"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/topics
**Create Topic**
[](#section/Versioning/API-Lifecycle-Policy)
Create a topic.
Also supports a dry-run mode that only validates whether the topic creation would succeed
if the `validate_only` request property is explicitly specified and set to true.
Note that when dry-run mode is used, a successful response status is 200 OK and not 201 Created.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**uniform_replication:**
```http
POST /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic_name": "topic-X",
"partitions_count": 64,
"replication_factor": 3,
"configs": [
{
"name": "cleanup.policy",
"value": "compact"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
**explicit_replicas_assignments:**
```http
POST /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic_name": "topic-X",
"replicas_assignments": {
"0": [
1,
2
],
"1": [
2,
3
],
"2": [
3,
1
]
},
"configs": [
{
"name": "cleanup.policy",
"value": "compact"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
**dry_run_create_topic:**
```http
POST /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic_name": "topic-X",
"partitions_count": 64,
"replication_factor": 3,
"validate_only": true
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The created topic.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X",
"resource_name": "crn:///kafka=cluster-1/topic=topic-X"
},
"cluster_id": "cluster-1",
"topic_name": "topic-X",
"is_internal": false,
"replication_factor": 3,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions/-/reassignments"
}
}
```
* [201 Created](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) –
The created topic.
**Example response:**
```http
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X",
"resource_name": "crn:///kafka=cluster-1/topic=topic-X"
},
"cluster_id": "cluster-1",
"topic_name": "topic-X",
"is_internal": false,
"replication_factor": 3,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-X/partitions/-/reassignments"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**create_topic_already_exists:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40002,
"message": "Topic 'my-topic' already exists."
}
```
**create_topic_replication_factor_too_large:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40002,
"message": "Replication factor: 2 larger than available brokers: 1."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}
**Get Topic**
[](#section/Versioning/API-Lifecycle-Policy)
Return the topic with the given `topic_name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **Query Parameters:**
* **include_authorized_operations** (*boolean*) – Specify if authorized operations should be included in the response.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The topic.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"is_internal": false,
"replication_factor": 3,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/-/reassignments"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PATCH /clusters/{cluster_id}/topics/{topic_name}
**Update Partition Count**
[](#section/Versioning/API-Lifecycle-Policy)
Increase the number of partitions for a topic.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
PATCH /clusters/{cluster_id}/topics/{topic_name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"partitions_count": 10
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The topic.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaTopic",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1",
"resource_name": "crn:///kafka=cluster-1/topic=topic-1"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"is_internal": false,
"replication_factor": 3,
"partitions_count": 1,
"partitions": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions"
},
"configs": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs"
},
"partition_reassignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/-/reassignments"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**topic_update_partitions_invalid:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40002,
"message": "Topic already has 1 partitions."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/topics/{topic_name}
**Delete Topic**
[](#section/Versioning/API-Lifecycle-Policy)
Delete the topic with the given `topic_name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Records (v3)
### POST /clusters/{cluster_id}/topics/{topic_name}/records
**Produce Records**
[](#section/Versioning/API-Lifecycle-Policy)
Produce records to the given topic, returning delivery reports for each
record produced. This API can be used in streaming mode by setting
“Transfer-Encoding: chunked” header. For as long as the connection is
kept open, the server will keep accepting records. For each record sent
to the server, the server will asynchronously send back a delivery
report, in the same order. Records are streamed to and from the server
as Concatenated JSON. Errors are reported per record. The HTTP status
code will be HTTP 200 OK as long as the connection is successfully
established.
Note that the cluster_id is validated only when running in Confluent
Cloud.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**binary_and_json:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"partition_id": 1,
"headers": [
{
"name": "Header-1",
"value": "SGVhZGVyLTE="
},
{
"name": "Header-2",
"value": "SGVhZGVyLTI="
}
],
"key": {
"type": "BINARY",
"data": "Zm9vYmFy"
},
"value": {
"type": "JSON",
"data": {
"foo": "bar"
}
},
"timestamp": "2021-02-05T19:14:42Z"
}
```
**binary_and_avro_with_subject_and_raw_schema:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"partition_id": 1,
"headers": [
{
"name": "Header-1",
"value": "SGVhZGVyLTE="
},
{
"name": "Header-2",
"value": "SGVhZGVyLTI="
}
],
"key": {
"type": "BINARY",
"data": "Zm9vYmFy"
},
"value": {
"type": "AVRO",
"subject": "topic-1-key",
"schema": "{\\\"type\\\":\\\"string\\\"}",
"data": "foobar"
},
"timestamp": "2021-02-05T19:14:42Z"
}
```
**string:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": {
"type": "STRING",
"data": "My message"
}
}
```
**schema_id_and_schema_version:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"key": {
"subject_name_strategy": "TOPIC_NAME",
"schema_id": 1,
"data": 1000
},
"value": {
"schema_version": 1,
"data": {
"foo": "bar"
}
}
}
```
**latest_schema:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"key": {
"data": 1000
},
"value": {
"data": "foobar"
}
}
```
**null_and_empty_data:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"key": {
"schema_id": 1
},
"value": {
"schema_version": 1,
"data": null
}
}
```
**empty_value:**
```http
POST /clusters/{cluster_id}/topics/{topic_name}/records HTTP/1.1
Host: example.com
Content-Type: application/json
{
"key": {
"data": 1000
}
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The response containing a delivery report for a record produced to a topic. In streaming mode,
for each record sent, a separate delivery report will be returned, in the same order,
each with its own error_code.
**produce_record_success:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"error_code": 200,
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"partition_id": 1,
"offset": 0,
"timestamp": "2021-02-05T19:14:42Z",
"key": {
"type": "BINARY",
"size": 7
},
"value": {
"type": "JSON",
"size": 15
}
}
```
**produce_record_bad_binary_data:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"error_code": 400,
"message": "Bad Request: data=1 is not a base64 string."
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**header_not_base64_encoded:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `byte[]` from String \"\": Unexpected end of base64-encoded String: base64 variant 'MIME-NO-LINEFEEDS' expects padding (one or more '=' characters) at the end. This Base64Variant might have been incorrectly configured"
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [413 Request Entity Too Large](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14) –
This implies the client is sending a request payload that is larger than the maximum message size the server can accept.
**produce_records_expects_json:**
```http
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
{
"error_code": 413,
"message": "The request included a message larger than the maximum message size the server can accept."
}
```
* [415 Unsupported Media Type](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16) –
This implies the client is sending the request payload format in an unsupported format.
**produce_records_expects_json:**
```http
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"error_code": 415,
"message": "HTTP 415 Unsupported Media Type"
}
```
* [422 Unprocessable Entity](https://www.rfc-editor.org/rfc/rfc4918#section-11.2) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**produce_record_empty_request_body:**
```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error_code": 422,
"message": "Payload error. Request body is empty. Data is required."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Cluster Linking (v3)
### GET /clusters/{cluster_id}/links
**List all cluster links in the dest cluster**
[](#section/Versioning/API-Lifecycle-Policy)
`link_id` in `ListLinksResponseData` is deprecated and may be removed in a future release. Use the new `cluster_link_id` instead.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/links HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
A list of link names and properties
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLinkDataList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links",
"next": null
},
"data": [
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/CIL-69l7S1CwoVNAhoQLug/links/my-new-link-1",
"resource_name": null
},
"remote_cluster_id": "src-cluster-id",
"link_name": "my-new-link-1",
"link_id": "7840644d-f7d8-4844-a577-a10ef3df31df",
"cluster_link_id": "eEBkTffYSESld6EO898x3w",
"topic_names": [
"topic-sb-1",
"topic-sb-2"
],
"link_state": "ACTIVE",
"remote_link_state": "UNMANAGED_SOURCE"
},
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/CIL-69l7S1CwoVNAhoQLug/links/my-new-link-2",
"resource_name": null
},
"remote_cluster_id": "src-cluster-id",
"link_name": "my-new-link-2",
"link_id": "f749116e-f847-4bd2-b1f6-5c4e518a0678",
"cluster_link_id": "90kRbvhHS9Kx9lxOUYoGeA",
"topic_names": [
"topic-db-1",
"topic-db-2"
],
"link_state": "UNAVAILABLE",
"remote_link_state": "UNMANAGED_SOURCE",
"link_error": "AUTHENTICATION_ERROR",
"link_error_message": "Please check your api key and secret"
},
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/CIL-69l7S1CwoVNAhoQLug/links/my-new-link-3",
"resource_name": null
},
"remote_cluster_id": "dest-cluster-id",
"link_name": "my-new-link-3",
"link_id": "9cd1711e-a4ef-4390-a35e-dfd758d97a82",
"cluster_link_id": "nNFxHqTvQ5CjXt_XWNl6gg",
"topic_names": [],
"link_state": "ACTIVE",
"remote_link_state": "ACTIVE"
},
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/CIL-69l7S1CwoVNAhoQLug/links/my-new-link-4",
"resource_name": null
},
"remote_cluster_id": "dest-cluster-id",
"link_name": "my-new-link-4",
"link_id": "56943567-ebc1-406b-880c-29c36c768dd3",
"cluster_link_id": "nNFxHqTvQ5CjXt_XWNl6gg",
"topic_names": [],
"link_state": "AUTHORIZATION_ERROR",
"remote_link_state": "REMOTE_LINK_NOT_FOUND"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links
**Create a cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
Cluster link creation requires source cluster security configurations in
the configs JSON section of the data request payload.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **link_name** (*string*) – The link name
(Required)
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
* **validate_link** (*boolean*) – To synchronously validate that the source cluster ID is expected and the dest cluster has the permission to read topics in the source cluster. Default: true
**destination_initiated_link:**
```http
POST /clusters/{cluster_id}/links?link_name=link-sb1 HTTP/1.1
Host: example.com
Content-Type: application/json
{
"remote_cluster_id": "cluster-1",
"configs": [
{
"name": "bootstrap.servers",
"value": "cluster-1-bootstrap-server"
},
{
"name": "acl.sync.enable",
"value": "false"
},
{
"name": "consumer.offset.sync.ms",
"value": "30000"
},
{
"name": "sasl.mechanism",
"value": "PLAIN"
},
{
"name": "security.protocol",
"value": "SASL_SSL"
},
{
"name": "sasl.jaas.config",
"value": "sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='' password='';"
}
]
}
```
**source_initiated_link_at_source_cluster:**
```http
POST /clusters/{cluster_id}/links?link_name=link-sb1 HTTP/1.1
Host: example.com
Content-Type: application/json
{
"remote_cluster_id": "cluster-2",
"configs": [
{
"name": "bootstrap.servers",
"value": "cluster-2-bootstrap-server"
},
{
"name": "link.mode",
"value": "SOURCE"
},
{
"name": "sasl.mechanism",
"value": "PLAIN"
},
{
"name": "security.protocol",
"value": "SASL_SSL"
},
{
"name": "sasl.jaas.config",
"value": "sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='' password='';"
},
{
"name": "local.sasl.mechanism",
"value": "PLAIN"
},
{
"name": "local.security.protocol",
"value": "SASL_SSL"
},
{
"name": "local.sasl.jaas.config",
"value": "sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='' password='';"
}
]
}
```
**source_initiated_link_at_destination_cluster:**
```http
POST /clusters/{cluster_id}/links?link_name=link-sb1 HTTP/1.1
Host: example.com
Content-Type: application/json
{
"remote_cluster_id": "cluster-1",
"configs": [
{
"name": "link.mode",
"value": "DESTINATION"
},
{
"name": "connection.mode",
"value": "INBOUND"
},
{
"name": "acl.sync.enable",
"value": "false"
}
]
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/{link_name}
**Describe the cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
`link_id` in `ListLinksResponseData` is deprecated and may be removed in a future release. Use the new `cluster_link_id` instead.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **include_tasks** (*boolean*) – Whether to include cluster linking tasks in the response. Default: false
**Example request:**
```http
GET /clusters/{cluster_id}/links/{link_name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Single link name and properties
**link_at_destination_cluster:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/my-new-link-1"
},
"resource_name": null,
"remote_cluster_id": "src-cluster-id",
"link_name": "my-new-link-1",
"link_id": "7840644d-f7d8-4844-a577-a10ef3df31df",
"cluster_link_id": "eEBkTffYSESld6EO898x3w",
"topic_names": [
"topic-db-1",
"topic-db-2"
]
}
```
**link_at_source_cluster:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLinkData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/my-new-link-1"
},
"resource_name": null,
"remote_cluster_id": "dst-cluster-id",
"link_name": "my-new-link-1",
"link_id": "7840644d-f7d8-4844-a577-a10ef3df31df",
"cluster_link_id": "eEBkTffYSESld6EO898x3w",
"topic_names": []
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/links/{link_name}
**Delete the cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **force** (*boolean*) – Force the action. Default: false
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/{link_name}/configs
**List all configs of the cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
**Example request:**
```http
GET /clusters/{cluster_id}/links/{link_name}/configs HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Config name and value
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLinkConfigDataList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/v-0Ce-CkTyKQol9v46LaCQ/links/link-nb-1/configs",
"next": null
},
"data": [
{
"kind": "KafkaLinkConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/links/my-new-link-1",
"resource_name": null
},
"cluster_id": "1Rh_4htxSuen7RYGvGmgNw",
"name": "consumer.offset.sync.ms",
"value": "3825940",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_CLUSTER_LINK_CONFIG",
"synonyms": [
"consumer.offset.sync.ms"
],
"link_name": "link-db-1"
},
{
"kind": "KafkaLinkConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/links/my-new-link-1",
"resource_name": null
},
"cluster_id": "1Rh_4htxSuen7RYGvGmgNw",
"name": "acl.sync.ms",
"value": "5000",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_CLUSTER_LINK_CONFIG",
"synonyms": [
"acl.sync.ms"
],
"link_name": "link-db-1"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/{link_name}/configs/{config_name}
**Describe the config under the cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **config_name** (*string*) – The link config name
**Example request:**
```http
GET /clusters/{cluster_id}/links/{link_name}/configs/{config_name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Config name and value
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLinkConfigData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/links/my-new-link-1",
"resource_name": null
},
"cluster_id": "1Rh_4htxSuen7RYGvGmgNw",
"name": "consumer.offset.sync.ms",
"value": "3825940",
"is_default": false,
"is_read_only": false,
"is_sensitive": false,
"source": "DYNAMIC_CLUSTER_LINK_CONFIG",
"synonyms": [
"consumer.offset.sync.ms"
],
"link_name": "link-db-1"
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/links/{link_name}/configs/{config_name}
**Alter the config under the cluster link**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **config_name** (*string*) – The link config name
**Example request:**
```http
PUT /clusters/{cluster_id}/links/{link_name}/configs/{config_name} HTTP/1.1
Host: example.com
Content-Type: application/json
{
"value": "300000"
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/links/{link_name}/configs/{config_name}
**Reset the given config to default value**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **config_name** (*string*) – The link config name
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/links/{link_name}/configs:alter
**Batch Alter Cluster Link Configs**
[](#section/Versioning/API-Lifecycle-Policy)
Batch Alter Cluster Link Configs
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**Example request:**
```http
PUT /clusters/{cluster_id}/links/{link_name}/configs:alter HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"name": "cleanup.policy",
"operation": "DELETE"
},
{
"name": "compression.type",
"value": "gzip"
}
]
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – No Content
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors
**Create a mirror topic**
[](#section/Versioning/API-Lifecycle-Policy)
Create a topic in the destination cluster mirroring a topic in
the source cluster
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
**generic_example:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors HTTP/1.1
Host: example.com
Content-Type: application/json
{
"source_topic_name": "topic-1",
"configs": [
{
"name": "unclean.leader.election.enable",
"value": "true"
}
],
"replication_factor": 1
}
```
**example_with_mirror_topic_name:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors HTTP/1.1
Host: example.com
Content-Type: application/json
{
"source_topic_name": "topic-1",
"mirror_topic_name": "link1_topic-1",
"configs": [
{
"name": "unclean.leader.election.enable",
"value": "true"
}
],
"replication_factor": 3
}
```
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/{link_name}/mirrors
**List mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
List all mirror topics under the link
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **mirror_status** (*string*) – The status of the mirror topic. If not specified, all mirror topics will be returned.
**Example request:**
```http
GET /clusters/{cluster_id}/links/{link_name}/mirrors HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Metadata of mirror topics
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaMirrorDataList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/link/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1",
"next": null
},
"data": [
{
"kind": "KafkaMirrorData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/link-1/mirrors/topic-1",
"resource_name": "crn:///kafka=cluster-1"
},
"link_name": "link-sb-1",
"resource_name": "crn:///kafka=cluster-1",
"mirror_topic_name": "topic-1",
"source_topic_name": "topic-1",
"num_partitions": 3,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
],
"mirror_status": "ACTIVE",
"mirror_topic_error": "NO_ERROR",
"state_time_ms": 1612550939300
},
{
"kind": "KafkaMirrorData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/link-1/mirrors/topic-2",
"resource_name": "crn:///kafka=cluster-1"
},
"link_name": "link-sb-2",
"resource_name": "crn:///kafka=cluster-1",
"mirror_topic_name": "topic-2",
"source_topic_name": "topic-2",
"num_partitions": 3,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
],
"mirror_status": "STOPPED",
"mirror_topic_error": "NO_ERROR",
"state_time_ms": 1612551353640
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/-/mirrors
**List mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
List all mirror topics in the cluster
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **mirror_status** (*string*) – The status of the mirror topic. If not specified, all mirror topics will be returned.
**Example request:**
```http
GET /clusters/{cluster_id}/links/-/mirrors HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Metadata of mirror topics
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaMirrorDataList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/link/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1",
"next": null
},
"data": [
{
"kind": "KafkaMirrorData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/link-1/mirrors/topic-1",
"resource_name": "crn:///kafka=cluster-1"
},
"link_name": "link-sb-1",
"resource_name": "crn:///kafka=cluster-1",
"mirror_topic_name": "topic-1",
"source_topic_name": "topic-1",
"num_partitions": 3,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
],
"mirror_status": "ACTIVE",
"mirror_topic_error": "NO_ERROR",
"state_time_ms": 1612550939300
},
{
"kind": "KafkaMirrorData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/Fds7TcT9TTqEXsoRLEKMcQ/links/link-1/mirrors/topic-2",
"resource_name": "crn:///kafka=cluster-1"
},
"link_name": "link-sb-2",
"resource_name": "crn:///kafka=cluster-1",
"mirror_topic_name": "topic-2",
"source_topic_name": "topic-2",
"num_partitions": 3,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
],
"mirror_status": "STOPPED",
"mirror_topic_error": "NO_ERROR",
"state_time_ms": 1612551353640
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/links/{link_name}/mirrors/{mirror_topic_name}
**Describe the mirror topic**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **mirror_topic_name** (*string*) – Cluster Linking mirror topic name
* **Query Parameters:**
* **include_state_transition_errors** (*boolean*) – Whether to include mirror state transition errors in the response. Default: false
**Example request:**
```http
GET /clusters/{cluster_id}/links/{link_name}/mirrors/{mirror_topic_name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Metadata of the mirror topic
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaMirrorData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/link/link-1/mirrors/topic-1",
"resource_name": "crn:///kafka=cluster-1"
},
"link_name": "link-sb-1",
"mirror_topic_name": "topic-1",
"source_topic_name": "topic-1",
"num_partitions": 3,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
],
"mirror_status": "ACTIVE",
"mirror_topic_error": "NO_ERROR",
"state_time_ms": 1612550939300
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:promote
**Promote the mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:promote HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:promote HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:failover
**Failover the mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:failover HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:failover HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:pause
**Pause the mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:pause HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:pause HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:resume
**Resume the mirror topics**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:resume HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:resume HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-start-mirror
**Reverse local mirror topic and start the remote mirror topic**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-start-mirror HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-start-mirror HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-pause-mirror
**Reverse local mirror topic and pause the remote mirror topic**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-pause-mirror HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:reverse-and-pause-mirror HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/links/{link_name}/mirrors:truncate-and-restore
**Truncates the local topic to the remote stopped mirror log end offsets and restores mirroring to the local topic to mirror from the remote topic**
[](#section/Versioning/API-Lifecycle-Policy)
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **link_name** (*string*) – The link name
* **Query Parameters:**
* **include_partition_level_truncation_data** (*boolean*) – Whether to include partition level truncation information when truncating and restoring a topic in the response. Default: false
* **validate_only** (*boolean*) – To validate the action can be performed successfully or not. Default: false
**mirror_topic_names:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:truncate-and-restore HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_names": [
"topic-1",
"topic-2"
]
}
```
**mirror_topic_name_pattern:**
```http
POST /clusters/{cluster_id}/links/{link_name}/mirrors:truncate-and-restore HTTP/1.1
Host: example.com
Content-Type: application/json
{
"mirror_topic_name_pattern": ".*"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Mirror status alternation result
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaPromoteMirror",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-1/mirrors",
"resource_name": "crn:///kafka=cluster-1"
},
"data": [
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-1",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-sb",
"error_code": null,
"error_message": null,
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
},
{
"kind": "AlterMirrorsData",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/my-new-link-1/mirrors/topic-2",
"resource": "crn:///kafka=cluster-1"
},
"mirror_topic_name": "topic-2",
"error_code": 400,
"error_message": "Topic 'topic-2' has already stopped its mirror from 'my-new-link-1'",
"mirror_lags": [
{
"partition": 0,
"lag": 0,
"last_source_fetch_offset": 0
},
{
"partition": 1,
"lag": 10000,
"last_source_fetch_offset": 1000
},
{
"partition": 2,
"lag": 40000,
"last_source_fetch_offset": 12030
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Share Group (v3)
### GET /clusters/{cluster_id}/share-groups
**List Share Groups**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of share groups that belong to the specified
Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/share-groups HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of share groups.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaShareGroupList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups",
"next": null
},
"data": [
{
"kind": "KafkaShareGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1"
},
"cluster_id": "cluster-1",
"share_group_id": "share-group-1",
"state": "STABLE",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers"
},
"consumer_count": 2,
"partition_count": 3,
"assigned_topic_partitions": [
{
"kind": "KafkaShareGroupTopicPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/assigned-topic-partitions/topic-1/0",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/topic-partition=topic-1:0"
},
"topic_name": "topic-1",
"partition_id": 0,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/0"
}
}
]
},
{
"kind": "KafkaShareGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-2",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-2"
},
"cluster_id": "cluster-1",
"share_group_id": "share-group-2",
"state": "EMPTY",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-2/consumers"
},
"consumer_count": 2,
"partition_count": 3,
"assigned_topic_partitions": [
{
"kind": "KafkaShareGroupTopicPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-2/assigned-topic-partitions/topic-1/0",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-2/topic-partition=topic-1:0"
},
"topic_name": "topic-1",
"partition_id": 0,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/0"
}
}
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/share-groups/{group_id}
**Get Share Group**
[](#section/Versioning/API-Lifecycle-Policy)
Return the share group specified by the `group_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/share-groups/{group_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The share group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaShareGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1"
},
"cluster_id": "cluster-1",
"share_group_id": "share-group-1",
"state": "STABLE",
"coordinator": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
},
"consumers": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers"
},
"consumer_count": 2,
"partition_count": 3,
"assigned_topic_partitions": [
{
"kind": "KafkaShareGroupTopicPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/assigned-topic-partitions/topic-1/0",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/topic-partition=topic-1:0"
},
"topic_name": "topic-1",
"partition_id": 0,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/0"
}
},
{
"kind": "KafkaShareGroupTopicPartition",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/assigned-topic-partitions/topic-1/1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/topic-partition=topic-1:1"
},
"topic_name": "topic-1",
"partition_id": 1,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### DELETE /clusters/{cluster_id}/share-groups/{group_id}
**Delete Share Group**
[](#section/Versioning/API-Lifecycle-Policy)
Delete the share group specified by the `group_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **Status Codes:**
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/share-groups/{group_id}/consumers
**List Share Group Consumers**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of consumers that belong to the specified share
group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/share-groups/{group_id}/consumers HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of consumers.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaShareConsumerList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers",
"next": null
},
"data": [
{
"kind": "KafkaShareGroupConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-1"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-1",
"client_id": "client-1",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments"
}
},
{
"kind": "KafkaShareGroupConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-2",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-2"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-2",
"client_id": "client-2",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-2/assignments"
}
},
{
"kind": "KafkaShareGroupConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-2",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-2"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-2",
"client_id": "client-2",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-2/assignments"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/share-groups/{group_id}/consumers/{consumer_id}
**Get Share Group Consumer**
[](#section/Versioning/API-Lifecycle-Policy)
Return the consumer specified by the `consumer_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **consumer_id** (*string*) – The consumer ID.
**Example request:**
```http
GET /clusters/{cluster_id}/share-groups/{group_id}/consumers/{consumer_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The consumer.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaShareGroupConsumer",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-1"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-1",
"client_id": "client-1",
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/share-groups/{group_id}/consumers/{consumer_id}/assignments
**List Share Group Consumer Assignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return the consumer assignments specified by the `consumer_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **consumer_id** (*string*) – The consumer ID.
**Example request:**
```http
GET /clusters/{cluster_id}/share-groups/{group_id}/consumers/{consumer_id}/assignments HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of share group assignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaConsumerAssignmentList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments",
"next": null
},
"data": [
{
"kind": "KafkaShareGroupConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments/topic-1/partitions/1",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-1/assignment=topic=1/partition=1"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-1",
"partition_id": 1,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/1"
}
},
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments/topic-2/partitions/2",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-1/assignment=topic=2/partition=2"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-2",
"partition_id": 2,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2/partitions/2"
}
},
{
"kind": "KafkaConsumerAssignment",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/share-groups/share-group-1/consumers/consumer-1/assignments/topic-3/partitions/3",
"resource_name": "crn:///kafka=cluster-1/share-group=share-group-1/consumer=consumer-1/assignment=topic=3/partition=3"
},
"cluster_id": "cluster-1",
"group_id": "share-group-1",
"consumer_id": "consumer-1",
"topic_name": "topic-3",
"partition_id": 3,
"partition": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-3/partitions/3"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PATCH /clusters/{cluster_id}/internal/share-groups/{group_id}/offsets
**Reset or Delete Share Group Offsets**
[](#section/Versioning/API-Lifecycle-Policy)
Alter the start offset for the share group specified by the `group_id`.
The share group must be inactive (no active members).
This operation supports three types of alterations:
* **Reset to earliest**: Reset offsets to the earliest available offset
* **Reset to latest**: Reset offsets to the latest available offset
* **Delete**: Delete all offsets for the specified topic
**Safety Note:** Delete operations require explicit topic specification and operate at topic level to prevent accidental partial deletions.
**Implementation Note:**
The alteration operation is performed as follows:
1. The server calls `alterShareGroupOffsets` to modify the start offset for the specified partitions.
2. After a successful alteration, the server calls `listShareGroupOffsets` to fetch the updated start offset values for the affected partitions.
The API response includes the updated start offset values for each partition after the alteration.
**Response Codes:**
* **200 OK**: Returned for reset operations (`reset_type: "EARLIEST"` or `"LATEST"`). The response body contains the updated offset values for each affected partition.
* **204 No Content**: Returned for delete operations (`reset_type: "DELETE"`). No response body is returned.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**reset_to_earliest - Reset all partitions to earliest offset:**
```http
PATCH /clusters/{cluster_id}/internal/share-groups/{group_id}/offsets HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic": "my-topic",
"reset_type": "earliest"
}
```
**reset_specific_partitions_to_latest - Reset specific partitions to latest offset:**
```http
PATCH /clusters/{cluster_id}/internal/share-groups/{group_id}/offsets HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic": "my-topic",
"partitions": [
0,
1,
2
],
"reset_type": "latest"
}
```
**delete_offsets - Delete offsets for entire topic:**
```http
PATCH /clusters/{cluster_id}/internal/share-groups/{group_id}/offsets HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic": "my-topic",
"reset_type": "delete"
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
Offsets altered successfully. The response includes the new start offset values for each affected partition. For delete operations, returns 204 No Content.
**successful_reset_earliest - Successful offset reset to earliest:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"topic": "my-topic",
"partitions": [
{
"partition": 0,
"start_offset": 0,
"status": "success"
},
{
"partition": 1,
"start_offset": 0,
"status": "success"
}
],
"share_group_id": "my-share-group",
"operation_type": "earliest"
}
```
**successful_reset_latest - Successful offset reset to latest:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"topic": "my-topic",
"partitions": [
{
"partition": 0,
"start_offset": 100,
"status": "success"
},
{
"partition": 1,
"start_offset": 200,
"status": "success"
}
],
"share_group_id": "my-share-group",
"operation_type": "latest"
}
```
**successful_delete - Successful topic offset deletion:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"topic": "my-topic",
"share_group_id": "my-share-group",
"operation_type": "delete"
}
```
* [204 No Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5) – Operation succeeded, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) –
Share group is not empty (has active members).
**share_group_not_empty - Share group has active members:**
```http
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error_code": "SHARE_GROUP_NOT_EMPTY",
"message": "Share group has active members and cannot be reset"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### BalancerStatus (v3)
### GET /clusters/{cluster_id}/balancer
**Get status of the balancer**
[](#section/Versioning/API-Lifecycle-Policy)
‘Return status about the balancer component for the cluster specified with `cluster_id`.’
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/balancer HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The balancer status
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBalancerStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/balancer",
"resource_name": "crn:///kafka=cluster-1/balancer"
},
"cluster_id": "cluster-1",
"status": "ERROR",
"error_code": 10014,
"error_message": "The Confluent Balancer failed to start as JBOD is enabled for the cluster.",
"any_uneven_load": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/even-cluster-load"
},
"broker_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/-/tasks"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/balancer/any-uneven-load
**Get AnyUnevenLoad status**
[](#section/Versioning/API-Lifecycle-Policy)
Return status of the AnyUnevenLoad for the cluster specified by `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/balancer/any-uneven-load HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The AnyUnevenLoad status
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaAnyUnevenLoad",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/any-uneven-load",
"resource_name": "crn:///kafka=cluster-1/any-uneven-load"
},
"cluster_id": "cluster-1",
"status": "BALANCING",
"previous_status": "BALANCING_FAILED",
"status_updated_at": "2019-10-12T07:20:50Z",
"previous_status_updated_at": "2019-10-12T07:20:35Z",
"error_code": 10013,
"error_message": "The Confluent Balancer operation was overridden by a higher priority operation.",
"broker_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/-/tasks"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Balancer offline
**Example response:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "The Confluent Balancer component is disabled or not started yet."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### BrokerTask (v3)
### GET /clusters/{cluster_id}/brokers/-/tasks
**List Broker Tasks**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of all tasks for all brokers in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/-/tasks HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of tasks.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerTaskList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/-/tasks",
"next": null
},
"data": [
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/tasks/add-broker",
"resource_name": "crn:///kafka=cluster-1/broker=1/task=add-broker"
},
"cluster_id": "cluster_id",
"broker_id": 1,
"task_type": "add-broker",
"task_status": "SUCCESS",
"sub_task_statuses": {
"partition_reassignment_status": "COMPLETED"
},
"created_at": "2019-10-12T10:20:40Z",
"updated_at": "2019-10-12T10:20:45Z",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2/tasks/remove-broker",
"resource_name": "crn:///kafka=cluster-1/broker=2/task=remove-broker"
},
"cluster_id": "cluster_id",
"broker_id": 2,
"task_type": "remove-broker",
"task_status": "FAILED",
"shutdown_scheduled": true,
"sub_task_statuses": {
"broker_replica_exclusion_status": "COMPLETED",
"partition_reassignment_status": "ERROR",
"broker_shutdown_status": "CANCELED"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"error_code": 10006,
"error_message": "Error while computing the initial remove broker plan for brokers [2] prior to shutdown.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}/tasks
**List Broker Tasks of a specific Broker**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of all broker tasks for broker specified with `broker_id` in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id}/tasks HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of tasks.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerTaskList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/-/tasks",
"next": null
},
"data": [
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/tasks/add-broker",
"resource_name": "crn:///kafka=cluster-1/broker=1/task=add-broker"
},
"cluster_id": "cluster_id",
"broker_id": 1,
"task_type": "add-broker",
"task_status": "IN_PROGRESS",
"sub_task_statuses": {
"partition_reassignment_status": "IN_PROGRESS"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/tasks/remove-broker",
"resource_name": "crn:///kafka=cluster-1/broker=1/task=remove-broker"
},
"cluster_id": "cluster_id",
"broker_id": 1,
"task_type": "remove-broker",
"task_status": "FAILED",
"shutdown_scheduled": false,
"sub_task_statuses": {
"broker_replica_exclusion_status": "EXCLUDED",
"partition_reassignment_status": "ERROR",
"broker_shutdown_status": "CANCELED"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"error_code": 10006,
"error_message": "Error while computing the initial remove broker plan for brokers [1] prior to shutdown.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/-/tasks/{task_type}
**List Broker Tasks of a specific TaskType**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of all broker tasks of specified `task_type` in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **task_type** (*string*) – The Kafka broker task type.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/-/tasks/{task_type} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of tasks.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerTaskList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/-/tasks",
"next": null
},
"data": [
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/tasks/add-broker",
"resource_name": "crn:///kafka=cluster-1/broker=1/task=add-broker"
},
"cluster_id": "cluster_id",
"broker_id": 1,
"task_type": "add-broker",
"task_status": "IN_PROGRESS",
"sub_task_statuses": {
"partition_reassignment_status": "IN_PROGRESS"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2/tasks/add-broker",
"resource_name": "crn:///kafka=cluster-1/broker=2/task=add-broker"
},
"cluster_id": "cluster_id",
"broker_id": 2,
"task_type": "add-broker",
"task_status": "FAILED",
"sub_task_statuses": {
"partition_reassignment_status": "ERROR"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"error_code": 10006,
"error_message": "Error while computing the initial add broker plan for brokers [2]",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/brokers/{broker_id}/tasks/{task_type}
**Get single Broker Task.**
[](#section/Versioning/API-Lifecycle-Policy)
Return a single Broker Task specified with `task_type` for broker specified with `broker_id` in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **task_type** (*string*) – The Kafka broker task type.
**Example request:**
```http
GET /clusters/{cluster_id}/brokers/{broker_id}/tasks/{task_type} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The broker task
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1/tasks/add-broker",
"resource_name": "crn:///kafka=cluster-1/broker=1/task=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"task_type": "add-broker",
"task_status": "FAILED",
"sub_task_statuses": {
"partition_reassignment_status": "ERROR"
},
"created_at": "2019-10-12T07:20:50Z",
"updated_at": "2019-10-12T07:20:55Z",
"error_code": 10013,
"error_message": "The Confluent Balancer operation was overridden by a higher priority operation",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### BrokerReplicaExclusion (v3)
### GET /clusters/{cluster_id}/broker-replica-exclusions
**Get all Broker Replica Exclusions.**
[](#section/Versioning/API-Lifecycle-Policy)
Return all Broker Replica Exclusions in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/broker-replica-exclusions HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of broker replica exclusions.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerReplicaExclusionList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions",
"next": null
},
"data": [
{
"kind": "KafkaBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/1",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"reason": "Broker is to be removed.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/2",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"reason": "Broker is to be removed.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/broker-replica-exclusions/{broker_id}
**Get a Broker Replica Exclusions.**
[](#section/Versioning/API-Lifecycle-Policy)
Return a Broker Replica Exclusions in the cluster specified with `cluster_id` and broker specified with `broker_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/broker-replica-exclusions/{broker_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
A Broker Replica Exclusion.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/1",
"next": null
},
"cluster_id": "cluster-1",
"broker_id": 1,
"reason": "Broker is to be removed.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/broker-replica-exclusions:create
**Create Broker Replica Exclusions**
[](#section/Versioning/API-Lifecycle-Policy)
Create Broker Replica Exclusions for brokers in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/broker-replica-exclusions:create HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"broker_id": 1,
"reason": "The broker is to be removed."
},
{
"broker_id": 2,
"reason": "The broker is to be removed."
}
]
}
```
* **Status Codes:**
* [201 Created](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) –
The list of alter broker replica exclusions.
**Example response:**
```http
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "KafkaAlterBrokerReplicaExclusionList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions",
"next": null
},
"data": [
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/1",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"exclusion": "SET",
"reason": "Broker is to be removed.",
"error_code": null,
"error_message": null,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/2",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"exclusion": "SET",
"reason": "Broker is to be removed.",
"error_code": null,
"error_message": null,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Unrepresentable broker id.
**Example response:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "The given broker id -10 is invalid"
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### POST /clusters/{cluster_id}/broker-replica-exclusions:delete
**Delete Broker Replica Exclusions**
[](#section/Versioning/API-Lifecycle-Policy)
Delete Broker Replica Exclusions for brokers in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
POST /clusters/{cluster_id}/broker-replica-exclusions:delete HTTP/1.1
Host: example.com
Content-Type: application/json
{
"data": [
{
"broker_id": 1,
"reason": "The broker is to be removed."
},
{
"broker_id": 2,
"reason": "The broker is to be removed."
}
]
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of alter broker replica exclusions.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaAlterBrokerReplicaExclusionList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions",
"next": null
},
"data": [
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/1",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"exclusion": "DELETE",
"reason": "Broker removal is completed.",
"error_code": null,
"error_message": null,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/2",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"exclusion": "DELETE",
"reason": "Broker removal is completed.",
"error_code": null,
"error_message": null,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
The list of alter broker replica exclusions.
**Example response:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"kind": "KafkaAlterBrokerReplicaExclusionList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions",
"next": null
},
"data": [
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/1",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"exclusion": "DELETE",
"reason": "Broker removal is completed.",
"error_code": 404,
"error_message": "No replica exclusion for broker 1 was present.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaAlterBrokerReplicaExclusion",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-replica-exclusions/2",
"resource_name": "crn:///kafka=cluster-1/broker-replica-exclusions=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"exclusion": "DELETE",
"reason": "Broker removal is completed.",
"error_code": null,
"error_message": null,
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### ReplicationFactorChange (v3)
### GET /clusters/{cluster_id}/topics/-/replication-factor-changes
**List Replication Factor Changes**
[](#section/Versioning/API-Lifecycle-Policy)
Return all tracked Replication Factor Changes in the cluster specified with `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/-/replication-factor-changes HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of tracked Replication Factor Changes.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicationFactorChangeList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"next": null
},
"data": [
{
"kind": "KafkaReplicationFactorChange",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"resource_name": "crn:///kafka=cluster-1/topic=-/replication-factor-changes"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"desired_replication_factor": 6,
"status": "IN_PROGRESS",
"created_at": "2026-08-07T07:20:50Z",
"updated_at": "2026-08-07T07:22:10Z",
"error_code": null,
"error_message": null,
"topic": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1"
}
},
{
"kind": "KafkaReplicationFactorChange",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"resource_name": "crn:///kafka=cluster-1/topic=-/replication-factor-changes"
},
"cluster_id": "cluster-1",
"topic_name": "topic-2",
"desired_replication_factor": 2,
"status": "FAILED",
"created_at": "2026-08-07T07:19:05Z",
"updated_at": "2026-08-07T07:19:40Z",
"error_code": 10038,
"error_message": "The requested replication factor is unattainable due to placement constraints.",
"topic": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PATCH /clusters/{cluster_id}/topics/-/replication-factor-changes
**Change Replication Factor**
[](#section/Versioning/API-Lifecycle-Policy)
Submit a Replication Factor change for one or more topics in the cluster specified with `cluster_id`. The change is applied asynchronously; poll the List Replication Factor Changes API to follow progress.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
PATCH /clusters/{cluster_id}/topics/-/replication-factor-changes HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topics": [
{
"topic_name": "topic-1",
"replication_factor": 6
},
{
"topic_name": "topic-2",
"replication_factor": 2
}
]
}
```
* **Status Codes:**
* [202 Accepted](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) – Request accepted for processing, no content in the response
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PATCH /clusters/{cluster_id}/topics/-/replication-factor-changes:cancel
**Cancel Replication Factor Change**
[](#section/Versioning/API-Lifecycle-Policy)
Cancel the in-flight Replication Factor Change for the topics specified in the request body, in the cluster specified with `cluster_id`. Cancellation does not roll back replicas already applied.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
PATCH /clusters/{cluster_id}/topics/-/replication-factor-changes:cancel HTTP/1.1
Host: example.com
Content-Type: application/json
{
"topic_names": [
"topic-1",
"topic-2"
]
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of canceled Replication Factor Changes. Topics for which no change was tracked are included with a non-null error_code and error_message.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicationFactorChangeCancellationList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"next": null
},
"data": [
{
"kind": "KafkaReplicationFactorChangeCancellation",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"resource_name": "crn:///kafka=cluster-1/topic=-/replication-factor-changes"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"prior_status": "IN_PROGRESS",
"error_code": null,
"error_message": null,
"canceled_partitions": [
0,
1
],
"topic": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1"
}
},
{
"kind": "KafkaReplicationFactorChangeCancellation",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/replication-factor-changes",
"resource_name": "crn:///kafka=cluster-1/topic=-/replication-factor-changes"
},
"cluster_id": "cluster-1",
"topic_name": "topic-2",
"prior_status": null,
"error_code": 10037,
"error_message": "No Replication Factor Change is in progress for topic topic-2.",
"canceled_partitions": [],
"topic": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### RemoveBrokerTask (v3)
### GET /clusters/{cluster_id}/remove-broker-tasks
**List Remove Broker Tasks**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of remove-broker-tasks for the specified Kafka cluster. `/remove-broker-tasks` is deprecated and may be removed in a future release. Use the new `/tasks` API instead.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/remove-broker-tasks HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of remove broker tasks.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaRemoveBrokerTaskList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/remove-broker-tasks",
"next": null
},
"data": [
{
"kind": "KafkaRemoveBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/remove-broker-tasks/1",
"resource_name": "crn:///kafka=cluster-1/remove-broker-task=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"shutdown_scheduled": true,
"broker_replica_exclusion_status": "COMPLETED",
"partition_reassignment_status": "FAILED",
"broker_shutdown_status": "CANCELED",
"error_code": 10006,
"error_message": "Error while computing the initial remove broker plan for brokers [1] prior to shutdown.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
},
{
"kind": "KafkaRemoveBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/remove-broker-tasks/2",
"resource_name": "crn:///kafka=cluster-1/remove-broker-task=2"
},
"cluster_id": "cluster-1",
"broker_id": 2,
"shutdown_scheduled": true,
"broker_replica_exclusion_status": "EXCLUDED",
"partition_reassignment_status": "FAILED",
"broker_shutdown_status": "CANCELED",
"error_code": 10006,
"error_message": "Error while computing the initial remove broker plan for brokers [2] prior to shutdown.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/2"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/remove-broker-tasks/{broker_id}
**Get Remove Broker Task**
[](#section/Versioning/API-Lifecycle-Policy)
Return the remove broker task for the specified `broker_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
**Example request:**
```http
GET /clusters/{cluster_id}/remove-broker-tasks/{broker_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The remove broker task.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaRemoveBrokerTask",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/remove-broker-tasks/1",
"resource_name": "crn:///kafka=cluster-1/remove-broker-task=1"
},
"cluster_id": "cluster-1",
"broker_id": 1,
"shutdown_scheduled": false,
"broker_replica_exclusion_status": "COMPLETED",
"partition_reassignment_status": "FAILED",
"broker_shutdown_status": "CANCELED",
"error_code": 10006,
"error_message": "Error while computing the initial remove broker plan for brokers [1] prior to shutdown.",
"broker": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/brokers/1"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Unregister (v3)
### POST /clusters/{cluster_id}/brokers/{broker_id}:unregister
**Unregister a Broker**
Unregister a broker from the cluster. This API is only supported for Kafka clusters running in KRaft mode.
If run against a cluster running with non-KRaft mode, a 400 response with
an unsupported version error code will be returned (see BadRequestErrorResponse for more detail).
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **broker_id** (*integer*) – The Kafka broker ID.
* **Status Codes:**
* [202 Accepted](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) –
A broker unregistration.
**Example response:**
```http
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"cluster_id": "cluster-1",
"broker_id": 1
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
The given broker ID was not registered in the cluster.
**Example response:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404102,
"message": "The given broker ID was not registered in the cluster."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### License (v3)
### GET /clusters/{cluster_id}/licenses
**List licenses**
[](#section/Versioning/API-Lifecycle-Policy)
List the licenses for the cluster specified by `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/licenses HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of licenses for the cluster.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLicenseList",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/cluster-1/licenses",
"next": null
},
"data": [
{
"kind": "KafkaLicense",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/cluster-1/licenses/cp"
},
"cluster_id": "cluster-1",
"category": "Confluent Platform",
"category_short_name": "cp",
"license_type": "ENTERPRISE",
"expires_at": "2026-10-30T07:00:00Z",
"audience": "006cV000005Kx8mQA0",
"license_jwt": "eyJ0eXAiOiJKV1Qi...",
"status": "ACTIVE",
"topic_name": "_confluent-command"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### PUT /clusters/{cluster_id}/licenses
**Update (validate and store) a license**
[](#section/Versioning/API-Lifecycle-Policy)
Validate and store a license for the cluster specified by `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **Query Parameters:**
* **dry_run** (*boolean*) – To validate the license without storing it. Default: false
**Example request:**
```http
PUT /clusters/{cluster_id}/licenses HTTP/1.1
Host: example.com
Content-Type: application/json
{
"license_jwt": "eyJ0eXAiOiJKV1Qi..."
}
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The result of validating and storing the license.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLicenseUpdateResult",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/cluster-1/licenses"
},
"updated_category": "Confluent Platform",
"licenses": [
{
"kind": "KafkaLicense",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/cluster-1/licenses/cp"
},
"cluster_id": "cluster-1",
"category": "Confluent Platform",
"category_short_name": "cp",
"license_type": "ENTERPRISE",
"expires_at": "2026-10-30T07:00:00Z",
"audience": "006cV000005Kx8mQA0",
"license_jwt": "eyJ0eXAiOiJKV1Qi...",
"status": "ACTIVE",
"topic_name": "_confluent-command"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/licenses/{category_short_name}
**Get license**
[](#section/Versioning/API-Lifecycle-Policy)
Get the license with the specified category short name for the cluster specified by `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **category_short_name** (*string*) – The short name of the license category.
**Example request:**
```http
GET /clusters/{cluster_id}/licenses/{category_short_name} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The license for the specified category short name.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaLicense",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/cluster-1/licenses/cp"
},
"cluster_id": "cluster-1",
"category": "Confluent Platform",
"category_short_name": "cp",
"license_type": "ENTERPRISE",
"expires_at": "2026-10-30T07:00:00Z",
"audience": "006cV000005Kx8mQA0",
"license_jwt": "eyJ0eXAiOiJKV1Qi...",
"status": "ACTIVE",
"topic_name": "_confluent-command"
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Replica Status (v3)
### GET /clusters/{cluster_id}/topics/-/partitions/-/replica-status
**List All Replica Statuses from a cluster.**
[](#section/Versioning/API-Lifecycle-Policy)
Return the all the replica statuses for the specified `cluster_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/-/partitions/-/replica-status HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of Replica Statuses.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicaStatusList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic_1/partitions/0/replica-status",
"resource_name": null
},
"data": [
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/1/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 1,
"partition_id": 0,
"is_leader": true,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
},
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/2/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 2,
"partition_id": 0,
"is_leader": false,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/-/replica-status
**List All Partition Replica Statuses.**
[](#section/Versioning/API-Lifecycle-Policy)
Return the all the replica statuses for the specified `topic_name`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/-/replica-status HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of Replica Statuses.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicaStatusList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic_1/partitions/0/replica-status",
"resource_name": null
},
"data": [
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/1/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 1,
"partition_id": 0,
"is_leader": true,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
},
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/2/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 2,
"partition_id": 0,
"is_leader": false,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replica-status
**List Partition Replica Statuses.**
[](#section/Versioning/API-Lifecycle-Policy)
Return the all the replica statuses for the specified `topic_name` and `partition_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **topic_name** (*string*) – The topic name.
* **partition_id** (*integer*) – The partition ID.
**Example request:**
```http
GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id}/replica-status HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of Replica Statuses.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaReplicaStatusList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic_1/partitions/0/replica-status",
"resource_name": null
},
"data": [
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/1/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 1,
"partition_id": 0,
"is_leader": true,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
},
{
"kind": "KafkaReplicaStatus",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/1Rh_4htxSuen7RYGvGmgNw/topics/topic-1/partitions/0/brokers/2/replica-status"
},
"cluster_id": "cluster-1",
"topic_name": "topic-1",
"broker_id": 2,
"partition_id": 0,
"is_leader": false,
"is_observer": false,
"is_isr_eligible": true,
"is_in_isr": true,
"is_caught_up": true,
"log_start_offset": 0,
"log_end_offset": 0,
"last_caught_up_time_ms": 100,
"last_fetch_time_ms": 200,
"link_name": "test-link"
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) –
Indicates attempted access to an unreachable or non-existing resource like e.g. an unknown topic or partition. GET requests to endpoints not allowed in the accesslists will also result in this response.
**endpoint_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "HTTP 404 Not Found"
}
```
**cluster_not_found:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 404,
"message": "Cluster my-cluster cannot be found."
}
```
**unknown_topic_or_partition:**
```http
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"error_code": 40403,
"message": "This server does not host this topic-partition."
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### Streams Group (v3)
### GET /clusters/{cluster_id}/streams-groups
**List Streams Groups**
[](#section/Versioning/API-Lifecycle-Policy)
Return the list of streams groups that belong to the specified Kafka cluster.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of streams groups.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupList",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups",
"next": null
},
"data": [
{
"kind": "KafkaStreamsGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"group_epoch": 1,
"target_assignment_epoch": 1,
"topology_epoch": 1,
"state": "STABLE",
"member_count": 2,
"subtopology_count": 1,
"members": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members"
},
"subtopologies": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/subtopologies"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}
**Get Streams Group**
[](#section/Versioning/API-Lifecycle-Policy)
Return the streams group specified by the `group_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroup",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"group_epoch": 1,
"target_assignment_epoch": 1,
"topology_epoch": 1,
"state": "STABLE",
"member_count": 2,
"subtopology_count": 1,
"members": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members"
},
"subtopologies": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/subtopologies"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/subtopologies
**List Streams Group Subtopologies**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of subtopologies that belong to the specified streams group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/subtopologies HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of subtopologies of the streams group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupSubtopologyList",
"metadata": {
"self": "http://localhost:8082/v3/clusters/cluster-1/streams-groups/streams-group-1/subtopologies"
},
"data": [
{
"kind": "KafkaStreamsSubtopology",
"metadata": {
"self": "http://localhost:8082/v3/clusters/cluster-1/streams-groups/streams-group-1/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/subtopology=subtopology-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"subtopology_id": "subtopology-1",
"source_topics": [
"topic-1",
"topic-2"
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/subtopologies/{subtopology_id}
**Get Streams Group Subtopology**
[](#section/Versioning/API-Lifecycle-Policy)
Return the subtopology specified by the `subtopology_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **subtopology_id** (*string*) – The streams subtopology ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/subtopologies/{subtopology_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group subtopology.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupSubtopology",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/subtopology=subtopology-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"subtopology_id": "subtopology-1",
"source_topics": [
"topic-1",
"topic-2"
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members
**List Streams Group Members**
[](#section/Versioning/API-Lifecycle-Policy)
Return a list of members that belong to the specified streams group.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The list of members of the streams group.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberList",
"metadata": {
"self": "http://localhost:8082/v3/clusters/cluster-1/streams-groups/streams-group-1/members"
},
"data": [
{
"kind": "KafkaStreamsMember",
"metadata": {
"self": "http://localhost:8082/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"member_id": "member-1",
"process_id": "process-1",
"client_id": "client-1",
"instance_id": "instance-1",
"member_epoch": 2,
"topology_epoch": 1,
"is_classic": false,
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments"
},
"target_assignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/target-assignment"
}
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}
**Get Streams Group Member**
[](#section/Versioning/API-Lifecycle-Policy)
Return the members specified by the `member_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group member.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMember",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"member_id": "member-1",
"process_id": "process-1",
"client_id": "client-1",
"instance_id": "instance-1",
"member_epoch": 2,
"topology_epoch": 1,
"is_classic": false,
"assignments": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments"
},
"target_assignment": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/target-assignment"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments
**Get Streams Group Member Assignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return the assignments of the member specified by the `member_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group member assignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"member_id": "member-1",
"active_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active"
},
"standby_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/standby"
},
"warmup_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/warmup"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments
**Get Streams Group Member Target Assignments**
[](#section/Versioning/API-Lifecycle-Policy)
Return the target assignments of the member specified by the `member_id`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group member assignments.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments"
},
"cluster_id": "cluster-1",
"group_id": "streams-group-1",
"member_id": "member-1",
"active_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active"
},
"standby_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/standby"
},
"warmup_tasks": {
"related": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/warmup"
}
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments/{assignments_type}
**List Streams Group Assignments of a Specific Type**
[](#section/Versioning/API-Lifecycle-Policy)
Return the tasks of the member specified by the `member_id`, and the type `assignments_type`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
* **assignments_type** (*string*) – The streams member Assignment type.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments/{assignments_type} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group member assignments of specific type.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"data": [
{
"kind": "GetStreamsTaskResponse",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"subtopology_id": "subtopology-1",
"partition_ids": [
0,
1,
2
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments/{assignments_type}
**List Streams Group Target Assignments of a Specific Type**
[](#section/Versioning/API-Lifecycle-Policy)
Return the target tasks of the member specified by the `member_id`, and the type `assignments_type`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
* **assignments_type** (*string*) – The streams member Assignment type.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments/{assignments_type} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The streams group member assignments of specific type.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"data": [
{
"kind": "GetStreamsTaskResponse",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"subtopology_id": "subtopology-1",
"partition_ids": [
0,
1,
2
]
}
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments/{assignments_type}/subtopologies/{subtopology_id}
**List Streams Group Assignments Task Partitions of a Specific Type and Subtopology**
[](#section/Versioning/API-Lifecycle-Policy)
Return the tasks of the member specified by the `member_id`, and the type `assignments_type`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
* **assignments_type** (*string*) – The streams member Assignment type.
* **subtopology_id** (*string*) – The streams subtopology ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/assignments/{assignments_type}/subtopologies/{subtopology_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The partitions of a streams member task.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"subtopology_id": "subtopology-1",
"partition_ids": [
0,
1,
2
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
### GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments/{assignments_type}/subtopologies/{subtopology_id}
**List Streams Group Target Assignments Task Partitions of a Specific Type and Subtopology**
[](#section/Versioning/API-Lifecycle-Policy)
Return the tasks of the member specified by the `member_id`, and the type `assignments_type`.
* **Parameters:**
* **cluster_id** (*string*) – The Kafka cluster ID.
* **group_id** (*string*) – The group ID.
* **member_id** (*string*) – The streams member ID.
* **assignments_type** (*string*) – The streams member Assignment type.
* **subtopology_id** (*string*) – The streams subtopology ID.
**Example request:**
```http
GET /clusters/{cluster_id}/streams-groups/{group_id}/members/{member_id}/target-assignments/{assignments_type}/subtopologies/{subtopology_id} HTTP/1.1
Host: example.com
```
* **Status Codes:**
* [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) –
The partitions of a streams member task.
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "KafkaStreamsGroupMemberAssignments",
"metadata": {
"self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/streams-groups/streams-group-1/members/member-1/assignments/active/subtopologies/subtopology-1",
"resource_name": "crn:///kafka=cluster-1/streams-group=streams-group-1/member=member-1/assignments=active/subtopology=subtopology-1"
},
"subtopology_id": "subtopology-1",
"partition_ids": [
0,
1,
2
]
}
```
* [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) –
Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure.
**bad_request_cannot_deserialize:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 400,
"message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}
```
**unsupported_version_exception:**
```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error_code": 40035,
"message": "The version of this API is not supported in the underlying Kafka cluster."
}
```
* [401 Unauthorized](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.
**kafka_authentication_failed:**
```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error_code": 40101,
"message": "Authentication failed"
}
```
* [403 Forbidden](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) –
Indicates a client authorization error. Kafka authorization failures will contain error code 40301 in the response body.
**kafka_authorization_failed:**
```http
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error_code": 40301,
"message": "Request is not authorized"
}
```
* [429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585#section-4) –
Indicates that a rate limit threshold has been reached, and the client should retry again later.
**Example response:**
```http
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
{
"description": "A sample response from Jetty's DoSFilter.",
"value": " Error 429 Too Many Requests HTTP ERROR 429 Too Many Requests
| URI: | /v3/clusters/my-cluster |
| STATUS: | 429 |
| MESSAGE: | Too Many Requests |
| SERVLET: | default |
"
}
```
* *5XX* –
A server-side problem that might not be addressable from the client side. Retriable Kafka errors will contain error code 50003 in the response body.
**generic_internal_server_error:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 500,
"message": "Internal Server Error"
}
```
**produce_v3_missing_schema:**
```http
HTTP/1.1 5XX -
Content-Type: application/json
{
"error_code": 50002,
"message": "Error when fetching latest schema version. subject = my-topic"
}
```
## REST API Usage Examples (curl)
This section provides a few examples of how to call the Confluent REST API using [curl](https://curl.haxx.se/) commands
to quickly test API endpoints from the command line. These examples demo the most recent API version, [REST Proxy API v3 for Confluent Platform](#rest-proxy-v3), and
JSON serialization format (see [Content Types](#kakarest-api-content-types)).
(To test API calls for [REST Proxy API v2](#rest-proxy-v2), swap out `v3` for `v2` and remove “`/kafka`”.
REST API v2 commands should not include “`kafka`”. Be sure to reference the [v2 API documentation](#rest-proxy-v2),
as not all APIs shown for v3 are available in v2.)
A few logistics to take note of:
- For your API testing, you may want to use [jq](https://stedolan.github.io/jq/)
along with `--silent` flag for [curl](https://curl.haxx.se/) to get nicely
formatted output for the given commands. These additional formatting options are used in the examples below.
- Although [jq has powerful filtering capabilities](https://stedolan.github.io/jq/manual/), you can pipe
the `curl` and `jq` output through simple `grep` commands to further filter the results. This is demo’ed in the examples.
- To get and set values using the APIs, you must know the URL for your cluster and the cluster ID.
You can get this from the [Cluster Settings](https://docs.confluent.io/control-center/current/clusters.html#controlcenter-userguide-cluster-settings) tab
on Control Center. ([http://localhost:9021/](http://localhost:9021/) on your web browser for a local cluster).
- The examples show the default host and port to access the Kafka cluster on a local host (`localhost:8090`).
### List and describe known clusters
To list and describe a cluster, use the API endpoint `GET /clusters` as shown.
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters/ | jq
```
Example and result:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters/ | jq
"kind": "KafkaClusterList",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters",
"next": null
},
"data": [
{
"kind": "KafkaCluster",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg",
"resource_name": "crn:///kafka=7cteo6omRwKaUFXj3BHxdg"
},
"cluster_id": "7cteo6omRwKaUFXj3BHxdg",
"controller": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/brokers/0"
},
"acls": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/acls"
},
"brokers": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/brokers"
},
"broker_configs": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/broker-configs"
},
"consumer_groups": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/consumer-groups"
},
"topics": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics"
},
"partition_reassignments": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/-/partitions/-/reassignment"
```
### Create a topic
To create a topic, use the topics endpoint `POST /clusters/{cluster_id}/topics` as shown below.
```none
curl --silent -X POST -H "Content-Type: application/json" \
--data '{"topic_name": ""}' http://localhost:8090/kafka/v3/clusters//topics | jq
```
Example and result:
```none
curl --silent -X POST -H "Content-Type: application/json" \
--data '{"topic_name": "my-cool-topic"}' http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics | jq
"kind": "KafkaTopic",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic",
"resource_name": "crn:///kafka=7cteo6omRwKaUFXj3BHxdg/topic=my-cool-topic"
},
"cluster_id": "7cteo6omRwKaUFXj3BHxdg",
"topic_name": "my-cool-topic",
"is_internal": false,
"replication_factor": 0,
"partitions": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions"
},
"configs": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/configs"
},
"partition_reassignments": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions/-/reassignment"
```
### Describe a specified topic
To get a full description of a specified topic, use the topics endpoint `GET /clusters/{cluster_id}/topics/{topic_name}` as shown below.
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters//topics/ | jq
```
Example and result:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic | jq
"kind": "KafkaTopic",
"metadata": {
"self": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic",
"resource_name": "crn:///kafka=7cteo6omRwKaUFXj3BHxdg/topic=my-cool-topic"
},
"cluster_id": "7cteo6omRwKaUFXj3BHxdg",
"topic_name": "my-cool-topic",
"is_internal": false,
"replication_factor": 1,
"partitions": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions"
},
"configs": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/configs"
},
"partition_reassignments": {
"related": "http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/my-cool-topic/partitions/-/reassignment"
```
### List all topics
To list detailed descriptions of all topics (internal and user created topics), use the topics endpoint
`GET /clusters/{cluster_id}/topics/`.
Example:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters//topics | jq
```
This will provide a full description of every topic on the cluster, including replication factors, partitions, configs, and so forth.
This output is similar to the Kafka command `kafka-topics --describe` (`kafka-topics --describe --bootstrap-server localhost:9092`).
### List all topic names
To filter the topic list to show only topic names, use the endpoint `GET /clusters/{cluster_id}/topics/` as shown.
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics | jq | grep '.topic_name'
```
This provides information similar to the Kafka command `kafka-topics --list` (`kafka-topics --list --bootstrap-server localhost:9092`).
### List topics with a specified prefix
To list all topics with a specified prefix, use the endpoint `GET /clusters/{cluster_id}/topics/` as shown.
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters//topics | jq | grep '.topic_name' | grep ''
```
Example and result:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics | jq | grep '.topic_name' | grep 'my-'
"topic_name": "my-cool-topic",
"topic_name": "my-hot-topic",
```
### Delete a topic
To delete a specified topic, use the API endpoint `DELETE /clusters/{cluster_id}/topics/{topic_name}`.
```none
curl --silent -X DELETE http://localhost:8090/kafka/v3/clusters//topics/{}
```
Example:
```none
curl --silent -X DELETE http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/{my-legacy-topic} | jq
```
You can list topics again (or check on Control Center) to verify that the topic has been deleted.
### Produce records in a batch
To produce records in a batch, use the API endpoint
`POST /clusters/{cluster_id}/topics/{topic_name}/records:batch`. Give
each entry an `id` of up to 80 characters, unique within the batch,
to match it against the corresponding entry in the response.
```none
curl --silent -X POST -H "Content-Type: application/json" \
-d '{"entries":[{"id":"","value":{"type":"JSON","data":}}]}' \
http://localhost:8090/kafka/v3/clusters//topics//records:batch
```
Example:
```none
curl --silent -X POST -H "Content-Type: application/json" \
-d '{"entries":[{"id":"first","value":{"type":"JSON","data":"ONE"}}, {"id":"second","value":{"type":"JSON","data":"TWO"}}]}' \
http://localhost:8090/kafka/v3/clusters/7cteo6omRwKaUFXj3BHxdg/topics/jsontest/records:batch | jq
```
Example response:
```none
{
"successes": [
{"id": "first", "cluster_id": "7cteo6omRwKaUFXj3BHxdg", "topic_name": "jsontest", "partition_id": 0, "offset": 3, "timestamp": "2023-03-09T14:07:23.592Z", "value": {"type": "JSON", "size": 5}},
{"id": "second", "cluster_id": "7cteo6omRwKaUFXj3BHxdg", "topic_name": "jsontest", "partition_id": 0, "offset": 4, "timestamp": "2023-03-09T14:07:23.592Z", "value": {"type": "JSON", "size": 5}}
],
"failures": []
}
```
The response separates `successes` and `failures` into their own
arrays. Check both arrays to determine which entries succeeded, using
each entry’s `id` to match it back to the request.
By default, a batch accepts up to 10 entries. To raise this limit to
as many as 50, set `api.v3.produce.batch.maximum.entries` in the
REST Proxy configuration. See [Standalone REST Proxy Configuration Options for Confluent Platform](production-deployment/rest-proxy/config.md#kafkarest-config).
### List broker tasks
You can list the broker tasks by querying the endpoint `GET/clusters/{cluster_id}/brokers/-/tasks` as shown.
This call will provide more interesting information if, for example, you are running a multi-broker cluster with [Manage Self-Balancing Kafka Clusters in Confluent Platform](../clusters/sbc/index.md#sbc) enabled,
and processing a lot of data resulting in active broker tasks.
To list tasks on all brokers:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters//brokers/-/tasks | jq
```
To list the tasks on a specified broker, for example broker 3:
```none
curl --silent -X GET http://localhost:8090/kafka/v3/clusters//brokers/3/tasks | jq
```
See the [Tutorial: Add and Remove Brokers with Self-Balancing in Confluent Platform](../clusters/sbc/sbc-tutorial.md#sbc-tutorial) to experiment with Self-Balancing.
## Accesslists
Confluent REST API now includes accesslists (`allowlist` and `blocklist`) to precisely
limit which APIs are accessible. These lists can be configured with
`api.endpoints.allowlist` and `api.endpoints.blocklist` configurations, for
which the values are comma-separated lists of API identifiers. The possible API
identifiers are the values of the `@ResourceName` annotation with which the
API resources (classes or methods) are annotated.
### Allowlist
When a non-empty `allowlist` is present, only the APIs that match an entry in the `allowlist` will be **accessible**.
For example, the following configuration makes only v3 cluster Admin APIs accessible.
```properties
api.endpoints.allowlist=api.v3.clusters.*
```
### Blocklist
When a non-empty `blocklist` is present, only the APIs that match an entry in the `blocklist` will be inaccessible (**not accessible**).
For example, the following configuration makes only v3 cluster Admin APIs not accessible.
```properties
api.endpoints.blocklist=api.v3.clusters.*
```
### Using both Allowlist and Blocklist
When **both** an `allowlist` and `blocklist` are present, only the APIs that match an entry in the `allowlist` will be accessible,
**except** the ones that also match an entry in the `blocklist`; which will not be accessible.
The following configuration makes only the v3 cluster Admin APIs accessible, except for `list` which is not accessible.
```properties
api.endpoints.allowlist=api.v3.clusters.*
api.endpoints.blocklist=api.v3.clusters.list
```
### API identifiers
Following is a list of the current API identifiers for Kafka REST.
#### NOTE
This list is provided as a convenience, and is subject to change as the API evolves.
Since it is currently compiled as a manual update, the list is not guaranteed to be always complete.
| API identifiers (v2 and v3) |
|---------------------------------------------------|
| api.v2.brokers.\* |
| api.v2.brokers.list |
| api.v2.consumers.\* |
| api.v2.consumers.assign |
| api.v2.consumers.commit-offsets |
| api.v2.consumers.consume-avro |
| api.v2.consumers.consume-binary |
| api.v2.consumers.consume-json |
| api.v2.consumers.consume-json-schema |
| api.v2.consumers.consume-protobuf |
| api.v2.consumers.create |
| api.v2.consumers.delete |
| api.v2.consumers.get-assignments |
| api.v2.consumers.get-committed-offsets |
| api.v2.consumers.get-subscription |
| api.v2.consumers.seek-to-beginning |
| api.v2.consumers.seek-to-end |
| api.v2.consumers.seek-to-offset |
| api.v2.consumers.subscribe |
| api.v2.consumers.unsubscribe |
| api.v2.partitions.\* |
| api.v2.partitions.get |
| api.v2.partitions.get-offsets |
| api.v2.partitions.list |
| api.v2.produce-to-partition.\* |
| api.v2.produce-to-partition.avro |
| api.v2.produce-to-partition.binary |
| api.v2.produce-to-partition.json |
| api.v2.produce-to-partition.json-schema |
| api.v2.produce-to-partition.protobuf |
| api.v2.produce-to-topic.\* |
| api.v2.produce-to-topic.avro |
| api.v2.produce-to-topic.binary |
| api.v2.produce-to-topic.json |
| api.v2.produce-to-topic.json-schema |
| api.v2.produce-to-topic.protobuf |
| api.v2.root.\* |
| api.v2.root.get |
| api.v2.root.post |
| api.v2.topics.\* |
| api.v2.topics.get |
| api.v2.topics.list |
| api.v3.acls.\* |
| api.v3.acls.create |
| api.v3.acls.delete |
| api.v3.acls.list |
| api.v3.balancer.\* |
| api.v3.balancer.any-uneven-load.get |
| api.v3.balancer.get |
| api.v3.broker-configs.\* |
| api.v3.broker-configs.alter |
| api.v3.broker-configs.delete |
| api.v3.broker-configs.get |
| api.v3.broker-configs.list |
| api.v3.broker-configs.update |
| api.v3.broker-replica-exclusions.\* |
| api.v3.broker-replica-exclusions.create |
| api.v3.broker-replica-exclusions.delete |
| api.v3.broker-replica-exclusions.list |
| api.v3.broker-replica-exclusions.search-by-broker |
| api.v3.broker-tasks.\* |
| api.v3.broker-tasks.list |
| api.v3.broker-tasks.remove-broker.get |
| api.v3.broker-tasks.remove-broker.list |
| api.v3.broker-tasks.search-by-type |
| api.v3.brokers-configs.\* |
| api.v3.brokers-configs.list |
| api.v3.brokers.\* |
| api.v3.brokers.broker-tasks.list |
| api.v3.brokers.broker-tasks.search-by-type |
| api.v3.brokers.delete |
| api.v3.brokers.get |
| api.v3.brokers.list |
| api.v3.cluster-configs.\* |
| api.v3.cluster-configs.alter |
| api.v3.cluster-configs.delete |
| api.v3.cluster-configs.get |
| api.v3.cluster-configs.list |
| api.v3.cluster-configs.update |
| api.v3.clusters.\* |
| api.v3.clusters.get |
| api.v3.clusters.list |
| api.v3.consumer-assignments.\* |
| api.v3.consumer-assignments.get |
| api.v3.consumer-assignments.list |
| api.v3.consumer-group-lag-summary.\* |
| api.v3.consumer-group-lag-summary.get |
| api.v3.consumer-groups.\* |
| api.v3.consumer-groups.get |
| api.v3.consumer-groups.list |
| api.v3.consumer-lags.\* |
| api.v3.consumer-lags.get |
| api.v3.consumer-lags.list |
| api.v3.consumers.\* |
| api.v3.consumers.get |
| api.v3.consumers.list |
| api.v3.last-produced-time.\* |
| api.v3.link-configs.\* |
| api.v3.link-configs.alter |
| api.v3.link-configs.delete |
| api.v3.link-configs.get |
| api.v3.link-configs.list |
| api.v3.link-configs.update |
| api.v3.links.\* |
| api.v3.links.create |
| api.v3.links.delete |
| api.v3.links.get |
| api.v3.links.list |
| api.v3.mirrors.\* |
| api.v3.mirrors.create |
| api.v3.mirrors.failover |
| api.v3.mirrors.get |
| api.v3.mirrors.list |
| api.v3.mirrors.list-all |
| api.v3.mirrors.pause |
| api.v3.mirrors.promote |
| api.v3.mirrors.resume |
| api.v3.partition-reassignments.\* |
| api.v3.partition-reassignments.get |
| api.v3.partition-reassignments.list |
| api.v3.partition-reassignments.search-by-topic |
| api.v3.partitions.\* |
| api.v3.partitions.get |
| api.v3.partitions.list |
| api.v3.partitions.replica-statuses.list |
| api.v3.produce.\* |
| api.v3.produce.produce-to-topic |
| api.v3.replica-statuses.\* |
| api.v3.replicas.\* |
| api.v3.replicas.get |
| api.v3.replicas.list |
| api.v3.replicas.search-by-broker |
| api.v3.topic-configs.\* |
| api.v3.topic-configs.alter |
| api.v3.topic-configs.delete |
| api.v3.topic-configs.get |
| api.v3.topic-configs.list |
| api.v3.topic-configs.update |
| api.v3.topics.\* |
| api.v3.topics.create |
| api.v3.topics.delete |
| api.v3.topics.get |
| api.v3.topics.last-produced-time |
| api.v3.topics.list |
| api.v3.topics.replica-statuses.list |
| api.v3.topics.replica-statuses.list-all |
## Suggested Resources
- Blog post: [Use Cases and Architectures for HTTP and REST APIs with Apache Kafka](https://www.confluent.io/blog/http-and-rest-api-use-cases-and-architecture-with-apache-kafka/)
- [Confluent Admin REST APIs demo](https://github.com/confluentinc/demo-scene/blob/master/adminrest)