Confluent REST Proxy API Reference¶

For a tutorial using the Confluent REST Proxy API see this step-by-step guide.

Content Types¶

The REST Proxy uses content types for both requests and responses to indicate these data properties:

Serialization format: json
API version (e.g. v2 or v3)
Embedded formats: json, binary, avro, protobuf and jsonschema

Important

The jsonschema and protobuf embedded types are supported beginning with REST Proxy v2.

REST Proxy supports the Avro®, JSON Schema, and Protobuf 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. These formats are embedded into requests or responses in the serialization format. For example, you can provide binary data in a json-serialized request; in this case the data should be provided as a base64-encoded string.

For v2, the content type will be application/vnd.kafka.binary.v2+json.
For v3 the content type will be application/json.

If your data is JSON, you can use json as the embedded format and embed it directly:

For v2, the content type will be application/vnd.kafka.json.v2+json.
For v3 the content type will be 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 the ID of the schema is serialized in addition to the data and payload.

The Avro content type is application/vnd.kafka.avro.v2+json.
The Protobuf content type is application/vnd.kafka.protobuf.v2+json.
The JSON schema content type is application/vnd.kafka.jsonschema.v2+json.

The format for the content type is:

application/vnd.kafka[.embedded_format].[api_version]+[serialization_format]

For more information, see Schema Registry API Reference.

The embedded format can be omitted when there are no embedded messages (i.e. for metadata requests you can use application/vnd.kafka.v2+json). The preferred content type for v2 is application/vnd.kafka.[embedded_format].v2+json. However, other less specific content types are permitted, 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 content types in requests and check the content 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:

Accept: application/vnd.kafka.v2+json

For v3, do not specify the version. The latest version (v3) will be used:

Accept: application/json

The server also supports content negotiation, so you may include multiple, weighted preferences:

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.

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/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.

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 –
- Error code 40101 – Kafka Authentication Error.
403 Forbidden –
- Error code 40301 – Kafka Authorization Error.
404 Not Found –
- Error code 40401 – Topic not found.
- Error code 40402 – Partition not found.
422 Unprocessable Entity – The request payload is either improperly formatted or contains semantic errors
500 Internal Server Error –
- Error code 50001 – Zookeeper error.
- 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 SSL endpoints were found for the specified broker, but SSL is not supported for the invoked API yet.

REST Proxy API v2¶

Tip

See REST API Usage Examples (curl) to learn how to test these API endpoints from the command line.

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:

GET /topics HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json

Example response:

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.

Response JSON Object:
Parameters:	topic_name (string) – Name of the topic to get metadata about
	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 – Error code 40401 – Topic not found

Example request:

GET /topics/test HTTP/1.1
Accept: application/vnd.kafka.v2+json

Example response:

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.

Request JSON Object:
Parameters:	topic_name (string) – Name of the topic to produce the messages to
	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) records[i].value (object) – The message value, formatted according to the embedded format 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. 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 – Error code 40401 – Topic not found 422 Unprocessable Entity – 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 – Error code 40801 – Schema registration or lookup failed.

Example binary request:

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/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:

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/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:

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/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
    }
  ]
}

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.

Response JSON Array of Objects:
Parameters:	topic_name (string) – the name of the topic
	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 – Error code 40401 – Topic not found

Example request:

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/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.

Response JSON Object:
Parameters:	topic_name (string) – Name of the topic partition_id (int) – ID of the partition to inspect
	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 – Error code 40401 – Topic not found Error code 40402 – Partition not found

Example request:

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/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.

Response JSON Object:
Parameters:	topic_name (string) – Name of the topic partition_id (int) – ID of the partition to inspect
	beginning_offset (int) – First offset in this partition end_offset (int) – Last offset in this partition
Status Codes:	404 Not Found – Error code 40401 – Topic not found Error code 40402 – Partition not found

Example request:

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/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.

Request JSON Object:
Parameters:	topic_name (string) – Topic to produce the messages to partition_id (int) – Partition to produce the messages to
	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) records[i].value (object) – The message value, formatted according to the embedded format
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 – Error code 40401 – Topic not found Error code 40402 – Partition not found 422 Unprocessable Entity – 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:

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/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:

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/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:

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/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:

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/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 JSONSCHEMA request:

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 JSONSCHEMA response:

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 content 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.

Request JSON Object:
Parameters:	group_name (string) – The name of the consumer group to join
	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 – Error code 40902 – Consumer instance with the specified name already exists. 422 Unprocessable Entity – Error code 42204 – Invalid consumer configuration. One of the settings specified in the request contained an invalid value.

Example request:

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/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:

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/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 JSONSCHEMA request:

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 JSONSCHEMA response:

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 – Error code 40403 – Consumer instance not found

Example request:

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/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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40403 – Consumer instance not found

Example request:

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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40402 – Partition not found Error code 40403 – Consumer instance not found

Example request:

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/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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40403 – Consumer instance not found 409 Conflict – Error code 40903 – Subscription to topics, partitions and pattern are mutually exclusive.

Example request:

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/1.1 204 No Content

Example request:

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/1.1 204 No Content

GET /consumers/(string: group_name)/instances/(string: instance)/subscription¶

Get the current subscribed list of topics.

Response JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	topics – A list of subscribed topics topics[i] (string) – Name of the topic
Status Codes:	404 Not Found – Error code 40403 – Consumer instance not found

Example request:

GET /consumers/testgroup/instances/my_consumer/subscription HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json

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 – Error code 40403 – Consumer instance not found

Example request:

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/1.1 204 No Content

POST /consumers/(string: group_name)/instances/(string: instance)/assignments¶

Manually assign a list of partitions to this consumer.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40403 – Consumer instance not found 409 Conflict – Error code 40903 – Subscription to topics, partitions and pattern are mutually exclusive.

Example request:

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/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.

Response JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40403 – Consumer instance not found

Example request:

GET /consumers/testgroup/instances/my_consumer/assignments HTTP/1.1
Host: proxy-instance.kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json

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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	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 – Error code 40403 – Consumer instance not found

Example request:

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/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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	partitions – A list of partitions partitions[i].topic (string) – Name of the topic partitions[i].partition (int) – Partition ID
Status Codes:	404 Not Found – Error code 40403 – Consumer instance not found

Example request:

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/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.

Request JSON Array of Objects:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	partitions – A list of partitions partitions[i].topic (string) – Name of the topic partitions[i].partition (int) – Partition ID
Status Codes:	404 Not Found – Error code 40403 – Consumer instance not found

Example request:

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/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.

Query Parameters:
Parameters:	group_name (string) – The name of the consumer group instance (string) – The ID of the consumer instance
	timeout – Maximum amount of milliseconds the REST Proxy will spend fetching records. Other parameters controlling actual time spent fetching records: max_bytes and fetch.min.bytes. Default value is undefined. This parameter is used only if it’s smaller than the consumer.timeout.ms that is defined either during consumer instance creation or in the REST Proxy’s config file. 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 – Error code 40403 – Consumer instance not found 406 Not Acceptable – Error code 40601 – Consumer format does not match the embedded format requested by the `Accept` header.

Example binary request:

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/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:

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/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:

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/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:

GET /brokers HTTP/1.1
Host: kafkaproxy.example.com
Accept: application/vnd.kafka.v2+json, application/vnd.kafka+json, application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json

{
  "brokers": [1, 2, 3]
}

REST Proxy API v3¶

These APIs are available both on Confluent Server (as a part of Confluent Enterprise) and REST Proxy. When using the API in Confluent Server, all paths should be prefixed with /kafka. For example, the path to list clusters is:

Confluent Server: /kafka/v3/clusters
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) is also running on the Confluent HTTP service, as another endpoint available to you with additional configurations.

Tip

To learn more, see the following sections:

REST API Usage Examples (curl) for how to test these API endpoints from the command line. from the command line
Admin REST APIs Configuration Options
Admin operations in Kafka REST API Features
Confluent Admin REST APIs demo

Cluster (v3)¶

GET /clusters¶

List Clusters

‘Returns 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:

GET /clusters HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of Kafka clusters.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns the Kafka cluster with the specified cluster_id.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

GET /clusters/{cluster_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The Kafka cluster.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Cluster Configs

Returns a list of configuration parameters for the specified Kafka cluster.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

GET /clusters/{cluster_id}/broker-configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of cluster configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Cluster Configs

Updates or deletes a set of Kafka cluster configuration parameters.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Cluster Config

Returns the configuration parameter specified by name.

Parameters:	cluster_id (string) – The Kafka cluster ID. name (string) – The configuration parameter name.

Example request:

GET /clusters/{cluster_id}/broker-configs/{name} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The cluster configuration parameter.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Cluster Config

Updates the configuration parameter specified by name.

Parameters:	cluster_id (string) – The Kafka cluster ID. name (string) – The configuration parameter name.

Example request:

PUT /clusters/{cluster_id}/broker-configs/{name} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "value": "gzip"
}

Status Codes:

204 No Content – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Cluster Config

Resets the configuration parameter specified by name to its default value.

Parameters:

cluster_id (string) – The Kafka cluster ID.
name (string) – The configuration parameter name.

Status Codes:

204 No Content – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

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:

GET /clusters/{cluster_id}/brokers/-/configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of broker configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

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:

GET /clusters/{cluster_id}/brokers/{broker_id}/configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of broker configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Updates or deletes a set of broker configuration parameters.

Parameters:	cluster_id (string) – The Kafka cluster ID. broker_id (integer) – The Kafka broker ID.

Example request:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

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:

GET /clusters/{cluster_id}/brokers/{broker_id}/configs/{name} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The broker configuration parameter.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Updates 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:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Resets 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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Return the list of configs that belong to the specified topic.

Parameters:	cluster_id (string) – The Kafka cluster ID. topic_name (string) – The topic name.

Example request:

GET /clusters/{cluster_id}/topics/{topic_name}/configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of cluster configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Updates or deletes a set of topic configs. 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:

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:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Return the config 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:

GET /clusters/{cluster_id}/topics/{topic_name}/configs/{name} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The topic configuration parameter.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Updates the config 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:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Resets the config 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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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¶

Get All Topic Configs

Returns all topic configurations for topics hosted by the specified cluster.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

GET /clusters/{cluster_id}/topics/-/configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of cluster configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 Default Topic Configs

Parameters:	cluster_id (string) – The Kafka cluster ID. topic_name (string) – The topic name.

Example request:

GET /clusters/{cluster_id}/topics/{topic_name}/default-configs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of cluster configs.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Creates ACLs.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

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": "User:12345",
            "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:

204 No Content – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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¶

Search ACLs

Returns a list of ACLs that match the search criteria. These are Apache Kafka, ZooKeeper based ACLs, which differ from the Confluent Metadata Service (MDS) based, centralized ACLs created with the Confluent CLI. MDS has a separate API for ACLs.

Query Parameters:
Parameters:	cluster_id (string) – The Kafka cluster ID.
	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. host (string) – The ACL host. operation (string) – The ACL operation. permission (string) – The ACL permission.

Example request:

GET /clusters/{cluster_id}/acls HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of ACLs.

Example response:

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=alice"
    },
    "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=alice&host=*&operation=ALL&permission=ALLOW"
            },
            "cluster_id": "cluster-1",
            "resource_type": "TOPIC",
            "resource_name": "topic-",
            "pattern_type": "PREFIXED",
            "principal": "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=cluster-1&pattern_type=LITERAL&principal=bob&host=*&operation=DESCRIBE&permission=DENY"
            },
            "cluster_id": "cluster-1",
            "resource_type": "CLUSTER",
            "resource_name": "cluster-2",
            "pattern_type": "LITERAL",
            "principal": "alice",
            "host": "*",
            "operation": "DESCRIBE",
            "permission": "DENY"
        }
    ]
}

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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 ACLs

Creates an Apache Kafka, ZooKeeper based ACL.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Deletes the list of Apache Kafka, ZooKeeper based ACLs that match the search criteria.

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.
host (string) – The ACL host.
operation (string) – The ACL operation.
permission (string) – The ACL permission.

Status Codes:

200 OK –

The list of deleted ACLs.

Example response:

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=alice&host=*&operation=ALL&permission=ALLOW"
            },
            "cluster_id": "cluster-1",
            "resource_type": "TOPIC",
            "resource_name": "topic-",
            "pattern_type": "PREFIXED",
            "principal": "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=cluster-1&pattern_type=LITERAL&principal=bob&host=*&operation=DESCRIBE&permission=DENY"
            },
            "cluster_id": "cluster-1",
            "resource_type": "CLUSTER",
            "resource_name": "cluster-2",
            "pattern_type": "LITERAL",
            "principal": "alice",
            "host": "*",
            "operation": "DESCRIBE",
            "permission": "DENY"
        }
    ]
}

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns the list of consumer groups that belong to the specified Kafka cluster.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

GET /clusters/{cluster_id}/consumer-groups HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of consumer groups.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The consumer group.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of consumers.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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.

Request Access To Cluster Admin for Kafka (v3)

Returns the max 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lag-summary HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The max and total consumer lag in a consumer group.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/lags HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of consumer lags.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The consumer.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/consumer-groups/{consumer_group_id}/consumers/{consumer_id}/assignments HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of consumer group assignments.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

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 –

The consumer group assignment.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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}/consumer-groups/{consumer_group_id}/lags/{topic_name}/partitions/{partition_id}¶

Get Consumer Lag

Returns 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:

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 –

The consumer lag.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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¶

List Partitions

Returns 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:

GET /clusters/{cluster_id}/topics/{topic_name}/partitions HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of partitions.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns 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:

GET /clusters/{cluster_id}/topics/{topic_name}/partitions/{partition_id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The partition

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns the list of topics that belong to the specified Kafka cluster.

Parameters:	cluster_id (string) – The Kafka cluster ID.

Example request:

GET /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The list of topics.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Creates 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 being used the response status would be 200 OK instead of 201 Created.

Parameters:	cluster_id (string) – The Kafka cluster ID.

uniform_replication:

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:

POST /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "topic_name": "topic-Y",
    "replicas_assignments": [
        {
            "partition_id": 0,
            "broker_ids": [
                1,
                2
            ]
        },
        {
            "partition_id": 1,
            "broker_ids": [
                2,
                3
            ]
        },
        {
            "partition_id": 2,
            "broker_ids": [
                3,
                1
            ]
        }
    ],
    "configs": [
        {
            "name": "cleanup.policy",
            "value": "compact"
        },
        {
            "name": "compression.type",
            "value": "gzip"
        }
    ]
}

dry_run_create_topic:

POST /clusters/{cluster_id}/topics HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "topic_name": "topic-Z",
    "partitions_count": 64,
    "replication_factor": 3,
    "validate_only": true
}

Status Codes:

200 OK –

The created topic.

Example response:

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 –

The created topic.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Returns the topic with the given topic_name.

Parameters:	cluster_id (string) – The Kafka cluster ID. topic_name (string) – The topic name.

Example request:

GET /clusters/{cluster_id}/topics/{topic_name} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

The topic.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Increases number of partitions on a topic.

Parameters:	cluster_id (string) – The Kafka cluster ID. topic_name (string) – The topic name.

Example request:

PATCH /clusters/{cluster_id}/topics/{topic_name} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "partitions_count": 10
}

Status Codes:

200 OK –

The topic.

Example response:

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 –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

Deletes 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 – No Content

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

404 Not Found –

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/1.1 404 Not Found
Content-Type: application/json

{
    "error_code": 404,
    "message": "HTTP 404 Not Found"
}

cluster_not_found:

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/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 –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr> <tr> <th>STATUS:</th> <td>429</td> </tr> <tr> <th>MESSAGE:</th> <td>Too Many Requests</td> </tr> <tr> <th>SERVLET:</th> <td>default</td> </tr> </table> </body> </html>"
}

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/1.1 5XX -
Content-Type: application/json

{
    "error_code": 500,
    "message": "Internal Server Error"
}

produce_v3_missing_schema:

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

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:

GET /clusters/{cluster_id}/links HTTP/1.1
Host: example.com

Status Codes:

200 OK –

A list of link names and properties

Example response:

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
            },
            "source_cluster_id": "src-cluster-id",
            "destination_cluster_id": null,
            "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"
        },
        {
            "kind": "KafkaLinkData",
            "metadata": {
                "self": "https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/CIL-69l7S1CwoVNAhoQLug/links/my-new-link-2",
                "resource_name": null
            },
            "source_cluster_id": "src-cluster-id",
            "destination_cluster_id": null,
            "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",
            "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
            },
            "source_cluster_id": null,
            "destination_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": null,
            "link_state": "ACTIVE"
        }
    ]
}

400 Bad Request –

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure. Usually serves application/json content, although in some cases simple text/plain content can be returned.

create_topic_already_exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 40002,
    "message": "Topic 'my-topic' already exists."
}

produce_message_badly_escaped:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error_code": 400,
    "message": "Unexpected character ('k' (code 107)): was expecting double-quote to start field name\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 3]"
}

unsupported_version_exception:

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."
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "description": "Thrown when trying to create a topic and passing a string for the replication factor.",
    "value": "Cannot deserialize value of type `java.lang.Integer` from String \"all\": not a valid Integer value\\n at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 1, column: 53] (through reference chain: io.confluent.kafkarest.entities.v3.CreateTopicRequest[\"partitions_count\"])"
}

401 Unauthorized –
Indicates a client authentication error. Kafka authentication failures will contain error code 40101 in the response body.

kafka_authentication_failed:
```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error_code": 40101,
    "message": "Authentication failed"
}
```

429 Too Many Requests –

Indicates that a rate limit threshold has been reached, and the client should retry again later.

Example response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html

{
    "description": "A sample response from Jetty's DoSFilter.",
    "value": "<html> <head> <meta http-equiv=\"Content-Type\" content=\"text/html;charset=utf-8\"/> <title>Error 429 Too Many Requests</title> </head> <body> <h2>HTTP ERROR 429 Too Many Requests</h2> <table> <tr> <th>URI:</th> <td>/v3/clusters/my-cluster</td> </tr