Skip to main content

Confluent Cloud API Reference

Download Source

Introduction

Note

This documents the collection of Confluent Cloud APIs. Each API documents its lifecycle phase. APIs marked as Early Access or Preview are not ready for production usage. We're currently working with a select group of customers to get feedback and iterate on these APIs.

Confluent Cloud APIs are a core building block of Confluent Cloud. You can use the APIs to manage your own account or to integrate Confluent into your product.

Most of the APIs are organized around REST and the resources which make up Confluent Cloud. The APIs have predictable resource-oriented URLs, transport data using JSON, and use standard HTTP verbs, response codes, authentication, and design principles.

Object Model​

Note

This section describes the object model for many Confluent Cloud APIs, but not all. The Connect v1 API group has a different object model. You can review the example request and response bodies in Connect v1 API to see its object model.

Confluent Cloud APIs are primarily designed to be declarative and intent-oriented. In other words, tell the API what you want (for example, throughput or SLOs) and it will figure out how to make it happen (for example, cluster sizing). A Confluent object acts as a "record of intent" — after you create the object, Confluent Cloud will work tirelessly in the background to ensure that the object exists as specified.

Confluent APIs represent objects in JSON with media-type application/json.

Many objects follow a model consisting of spec and status. An object's spec tells Confluent the desired state (specification) of the resource. The object may not be immediately available or changes may not be immediately applied. For this reason, many objects also have a status property that provides info about the current state of the resource. Confluent Cloud is continuously and actively managing each resource's current state to match it's desired state.

All Confluent objects share a set of common properties:

  • api_version – API objects have an api_version field indicating their API version.
  • kind – API objects have a kind field indicating the kind of object it is.
  • id – Each object in the API will have an identifier, indicated via its id field, and should be treated as an opaque string unless otherwise specified.

There are a number of other standard properties and that you'll encounter used by many API objects. And of course, objects have plenty of non-standard fields that are specific to each object kind... this is what makes them interesting!

Authentication

Confluent uses API keys and JSON Web Tokens (JWTs) to integrate your applications and workflows to your Confluent Cloud resources using the Confluent Cloud REST APIs. Your applications and workflows must be authenticated and authorized in order to access and manage Confluent Cloud resources.

API keys​

You can create and manage your API keys using the Confluent Cloud Console or Confluent CLI. For more information, see Use API Keys to Control Access in Confluent Cloud.

Confluent Cloud uses the following two categories of API keys:

  • A Cloud API key grants access to the Confluent Cloud Management APIs, such as for Provisioning and Metrics integrations.
  • A resource-specific API key grants access to a Confluent Kafka cluster (Kafka API key), a Confluent Cloud Schema Registry (Schema Registry API key), Flink (Flink API key scoped to an Environment + Region pair), or a ksqlDB application.

Each Confluent Cloud API key is associated with a principal (specific user or service account) and inherits the permissions granted to the owner.

  • For example, if service account Armageddon is granted ACLs on Kafka cluster neptune, then a Kafka API Key for neptune owned by Armageddon will have these ACLs enforced.
  • Note: API keys are automatically deleted when the associated user or service account is deleted (for example, when an employee leaves the company or moves to a new department and an SSO integration removes the Confluent Cloud user as they no longer require access).
  • Confluent strongly recommends that you use service accounts for all production-critical access.

Confluent Cloud API keys grant access to Confluent Cloud resources, so keep them secure! Do not share your API keys and secrets in publicly-accessible locations, such as GitHub or client-side code.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

To use an API key, you must send it in an Authorization: Basic {credentials} header. Remember that HTTP Basic authentication requires you to provide your credentials as the API key ID and associated API secret separated by a colon and encoded using Base64 format. For example, if your API key ID is ABCDEFGH123456789 and the API key Secret is XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO, then the authorization header is:

Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=

You can generate this header example from the API key:

macOS:

$ echo -n "ABCDEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

Linux:

$ echo -n "ABCDEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64 -w 0

Windows (PowerShell only):

This command is only supported for PowerShell and will not work in the Command shell.

$ [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("ABCDEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO"))

To find out if an API operation supports Cloud API Keys, look in the AUTHORIZATIONS listing for cloud-api-key.

To find out if an API operation supports resource-specific API Keys, look in the AUTHORIZATIONS listing for resource-api-key.

External OAuth​

You can use OAuth/OIDC support for Confluent Cloud to authenticate and authorize access to applications and workloads for the following Confluent Cloud REST APIs:

Alternatively, to find out if an API operation supports external tokens, look in the AUTHORIZATIONS listing for external-access-token.

Confluent STS tokens​

Confluent Security Token Service (STS) issues access tokens (confluent-sts-access-token) by exchanging an external token (external-access-token) for a confluent-sts-access-token. You can use Confluent STS tokens to authenticate to Confluent Cloud APIs that support the confluent-sts-access-token notation.

To find out if an API operation supports Confluent STS tokens, look in the AUTHORIZATIONS listing for confluent-sts-access-token.

Partner OAuth​

Approved partners can fetch Partner tokens (confluent-partner-access-token) that validate their identity and grant access to the Partner API (partner/v2), which lets them sign up an organization on behalf of a customer, manage entitlements (create, read, and list), and read or list organizations they have signed up.

To find out an API operation supports Partner tokens, look in the AUTHORIZATIONS listing for confluent-partner-access-token.

cloud-api-key​

Authenticate with Cloud API Keys using HTTP Basic Auth. Treat the Cloud API Key ID as the username and Cloud API Key Secret as the password.

Security Scheme Type: HTTP

HTTP Authorization Scheme: basic

confluent-sts-access-token​

Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0.

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL: https://api.confluent.cloud/sts/v1/oauth2/token

resource-api-key​

Authenticate with resource-specific API Keys using HTTP Basic Auth. Treat the resource-specific API Key ID as the username and resource-specific API Key Secret as the password.

Security Scheme Type: HTTP

HTTP Authorization Scheme: basic

external-access-token​

Authenticate with OAuth 2.0.

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL: https://<oauth-identity-provider>/token

oauth​

Authenticate with OAuth 2.0. Currently this is only supported for partner APIs.

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL: /oauth2/token

Scopes:

  • partner:alter — enables partners to alter entitlements

  • partner:create — enables partners to create entitlements and signup on behalf of customers

  • partner:delete — enables partners to delete entitlements and organizations

  • partner:describe — enables partners to read and list entitlements and organizations

Errors

Confluent API error messages are a critical part of the developer experience. For Confluent Cloud, they must be clear, consistent, actionable, and designed for both developers and automated systems. Strong error handling supports fast troubleshooting, reliable integration, and efficient support–the foundation of a positive developer experience.

Our APIs are built on RESTful principles. They use resource-oriented URLs, standard HTTP verbs, and JSON for requests and responses. This section defines clear standards for structuring, formatting, and documenting error messages for all Confluent REST APIs.

Note

This error format applies to most Confluent Cloud APIs. However, the Connect v1 API group uses a different structure. For Connect v1-specific error behavior and examples, refer to the Connect v1 API documentation below to see its error behavior.

Key principles​

Use the following best practices when designing and documenting API error messages:

  • Ensure clarity and consistency: Messages must be easy to understand–use active voice and plain language–and consistently formatted across endpoints.

  • Write actionable messages: Always include a resolution or next step, enabling users to correct the problem.

  • Avoid exposing sensitive data: Never expose internal system details, stack traces, logs, or user-specific content.

  • Follow industry best practices: Don't use a period at the end of the message field, even if it is a full sentence. This follows industry standards. Use periods in the details and suggestion fields if the content is a complete sentence. View the API best practices blog by Postman, a trusted API leader.

HTTP status codes​

Confluent Cloud APIs return standard HTTP status codes to indicate the outcome of API request. Each error response includes a status field that reflects the appropriate HTTP code as a string (for example, "403" or "404"). For a list of supported codes and their meaning, see the HTTP status codes section.

Error response structure​

Each API error response should include the following fields:

Top-level fields

FieldTypeRequiredDescription
statusStringYesHTTP status code (for example, 400, 404, 500).
errorObjectYesMain object containing error details.
requestIdStringOptionalUnique identifier for the API request. Use for tracing, debugging, and support inquiries.
doc_urlStringOptionalLink to relevant documentation or troubleshooting steps.

Fields inside error object

FieldTypeRequiredDescription
codeStringYesUnique, application-specific error code. Write error codes in uppercase letters, using underscores to separate words (for example, RESOURCE_NOT_FOUND).
messageStringYesClear, actionable, user-friendly description of what went wrong using active voice.
detailsStringOptionalAdditional explanation or context about the error using active voice.
timestampStringYesISO 8601 UTC timestamp indicating the date and time when the error occurred.
pathStringYesThe exact API endpoint or resource path related to the error.
suggestionStringOptionalRecommend actions the user can take to fix or avoid the error using active voice.

Each Confluent API error includes a status and a structured error object with a code, message, and optional context to help you understand and resolve the issue. The following example shows a standard Confluent API error response in JSON format:

{ "status": 400, "error": { "code": "INVALID_SCHEMA_FIELD", "message": "The 'name' field in the schema is required and cannot be empty.", "details": "Schemas must include a top-level 'name' field with a non-empty string value.", "timestamp": "2025-08-01T20:36:45Z", "path": "/api/v1/schemas", "suggestion": "Ensure the 'name' field is included in the payload and is not an empty string." }, "requestId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k516m7n8", "doc_url": "https://docs.confluent.io/cloud/current/api/errors/INVALID_SCHEMA_FIELD.html" }

Note that if a request fails validation, it will return an HTTP 422 Unprocessable Entity with a list of fields that failed validation.

Pagination​

Note

This section describes the pagination behavior of “list” operations for many Confluent Cloud APIs, but not all. The Connect V1 and Kafka V3 API list operations do not support pagination.

All API resources have support for bulk reads via "list" API operations. For example, you can "list Kafka clusters", "list api keys", and "list environments". These "list" operations require pagination; by requesting smaller subsets of data, API clients receive a response much faster than requesting the entire, potentially large, data set.

All "list" operations follow the same pattern with the following parameters:

  • page_size – client-provided max number of items per page, only valid on the first request.
  • page_token – server-generated token used for traversing through the result set.

A paginated response may include any of the following pagination links. API clients may follow the respective link to page forward or backward through the result set as desired.

Link RelationDescription
nextA link to the next page of results. A response that does not contain a next link does not have further data to fetch.
prevA link to the previous page of results. A response that does not contain a prev link has no previous data. This link is optional for collections that cannot be traversed backward.
firstA link to the first page of results. This link is optional for collections that cannot be indexed directly to a given page.
lastA link to the last page of results. This link is optional for collections that cannot be indexed directly to a given page.

API clients must treat pagination links and the page_token parameter in particular as an opaque string.

An example paginated list response may look like

{
    "api_version": "v2",
    "kind": "KafkaClusterList",
    "metadata": {
        "next": "https://api.confluent.cloud/kafka-clusters?page_token=ABCDEFGHIJKLMNOP1234567890"
    }
    "data": [
        {
            "metadata": {
                "id": "lkc-abc123",
                "self": "https://api.confluent.cloud/kafka-clusters/lkc-abc123",
                "resource_name": "crn://confluent.cloud/kafka=lkc-abc123",
            }
            "spec": {
                "display_name": "My Kafka Cluster",
                <snip>
            },
            "status": {
                "phase": "RUNNING",
                <snip>
            }
        },
        <snip>
    ]
}

Rate Limiting

To protect the stability of the API and keep it available to all users, Confluent employs multiple safeguards. If you send too many requests in quick succession or perform too many concurrent operations, you may be throttled or have your request rejected with an error.

When a rate limit is breached, an HTTP 429 Too Many Requests error is returned. The following headers are sent back to provide assistance in dealing with rate limits. Note that headers are not returned for a 429 error response with Kafka REST API (v3).

HeaderDescription
X-RateLimit-LimitThe maximum number of requests you're permitted to make per time period.
X-RateLimit-ResetThe relative time in seconds until the current rate limit window resets.
Retry-AfterThe number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
X-RateLimit-RemainingThe number of requests remaining in the current rate-limit window. Important: This differs from Github and Twitter's same-named header which uses UTC epoch seconds. We use relative time to avoid client/server time synchronization issues.

Confluent enforces multiple kinds of limits, including request-rate and concurrency limits, both per user and organization-wide. Unauthenticated requests are associated with the originating IP address, not the user making requests.

Integrations should gracefully handle these limits by watching for 429 error responses and building in a retry mechanism. This mechanism should follow a capped exponential backoff policy to prevent retry amplification ("retry storms") and also introduce some randomness ("jitter") to avoid the thundering herd effect.

If you’re running into this error and think you need a higher rate limit, contact Confluent at support@confluent.io.

Identifiers and URLs

Most resources have multiple identifiers:

  • id is the "natural identifier" for an object. It is only unique within its parent resource. The id is unique across time: the ID will not be reclaimed and reused after an object is deleted.
  • resource_name is a Uniform Resource Identifier (URI) that is globally unique across all resources. This encompasses all parent resource kinds and ids necessary to uniquely identify a particular instance of this object kind. Because it uses object ids, the CRN will not be reclaimed and reused after an object is deleted. It is represented as a Confluent Resource Name (see below).
  • self is a Uniform Resource Locator (URL) at which an object can be addressed. This URL encodes the service location, API version, and other particulars necessary to locate the resource at a point in time.

To see how these relate to each other, consider KafkaBroker with broker.id=2 in a KafkaCluster in Confluent Cloud identified as lkc-xsi8201. In such an example, the KafkaBroker has id=2, the resource_name is crn://confluent.cloud/kafka=lkc-xsi8201/broker=2 and the self URL may be something like https://pkc-8wlk2n.us-west-2.aws.confluent.cloud. Note that different identifiers carry different information for different purposes, but the resource_name is the most complete and canonical identifier.

Confluent Resource Names (CRNs)​

Confluent Resource Names (CRNs) are used to uniquely identify all Confluent resources.

A CRN is a valid URI having an "authority" of confluent.cloud or a self-managed metadata service URL, followed by the minimal hierarchical set of key-value pairs necessary to uniquely identify a resource.

Here are some examples for basic resources in Confluent Cloud:

ResourceExample CRN
Organizationcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a
Environmentcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy
Usercrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/user=u-rst9876
API Keycrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/user=u-zyx98/api-key=ABCDEFG9876543210
Service Accountcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/service-account=sa-abc1234
Kafka Clustercrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc
Kafka Topiccrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc/topic=my_kafka_topic
Consumer Groupcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc/group=confluent_cli_consumer_123
Networkcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc
Peeringcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/peering=p-123abc
Private Link Accesscrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/private-link-access=pla-123abc
Transit Gateway Attachmentcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/transit-gateway-attachment=tgwa-123abc
Schema Registry Clustercrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw
Schema Subjectcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw/subject=test
KEKcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw//kek=test_kek
Connectorcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/connector=my_datagen_connector
Provider Integrationcrn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/provider-integration=cspi-123j1

Data Types

Primitive Types​

Data TypeRepresentation
IntegersEach API may specify the type as int32 or int64. Note that many languages, including JavaScript, are limited to a max size of approx 2**53 and don't correctly handle large int64 values with their default JSON parser.
DatesRFC 3339 formatted string. UTC timezones are assumed, unless otherwise given.
TimesRFC 3339 formatted string. UTC timezones are assumed, unless otherwise given.
DurationsRFC 3339 formatted string.
PeriodsRFC 3339 formatted string. UTC timezones are assumed, unless otherwise given.
RangesAll ranges are represented using half-open intervals with naming conventions like [start_XXX, end_XXX) such as [start_time, end_time).
EnumsMost APIs use x-extensible-enum as an open-ended list of values. This improves compatibility compared with a standard enum which by definition represents a closed set. All enums have a 0-valued entry which either serves as the default for common cases, or represents UNSPECIFIED when no default exists and results in an error.

Standard Properties​

Confluent uses this set of standard properties to ensure common concepts use the same name and semantics across different APIs.

NameDescription
api_version Many API objects have an api_version field indicating their API version. See the Object Model.
kind Many API objects have a kind field indicating the kind of object it is. See the Object Model.
idMany objects in the API will have an identifier, indicated via its id field, and should be treated as an opaque string unless otherwise specified. See the Object Model.
nameObjects which support a client-provided unique identifier instead of a generated id will indicate this identifier via its name field.
display_nameThe human-readable display name of an API object.
titleThe official name of an API object, such as a company name. It should be treated as the formal version of display_name.
descriptionOne or more paragraphs of text description of an entity.
created_at The date and time the object was created, represented as a string in RFC 3339 format.
updated_at  The date and time the object was last modified, represented as a string in RFC 3339 format.
deleted_atIf present, the date and time after which the object was/will be deleted, represented as a string in RFC 3339 format.
page_tokenThe pagination token in the List request. See Pagination.
page_sizeThe pagination size in the List request. See Pagination.
total_sizeThe total count of items in the list irrespective of pagination. See Pagination.
specThe desired state specification of the resource, as observed by Confluent Cloud.
statusThe current state of the resource, as observed by Confluent Cloud.

Versioning

Confluent APIs ensure stability for your integrations by avoiding the introduction of breaking changes to customers unexpectedly. Confluent will make non-breaking API changes without advance notice. Thus, API clients must follow the Compatibility Policy below to ensure your integration remains stable. All APIs follow the API Lifecycle Policy described below, which describes the guarantees API clients can rely on.

Breaking changes will be widely communicated in advance in accordance with the Confluent Deprecation Policy. Confluent will provide timelines and a migration path for all API changes, where available. Be sure to subscribe to one or more communication channels so you don't miss any updates!

One exception to these guidelines is for critical security issues. Confluent will take any necessary actions to mitigate any critical security issue as soon as possible, which may include disabling the vulnerable functionality until a proper solution is available.

Do not consume any Confluent API unless it is documented in the API Reference. All undocumented endpoints should be considered private, subject to change without notice, and not covered by any agreements.

Note

The version in the URL (e.g. "v1" or "v2") is not a "major version" in the Semantic Versioning sense. It is a "generational version" or "meta version", as seen in APIs like Github API or the Stripe API.

API Groups​

Confluent APIs are divided into API Groups, such as the Cluster Management for Apache Kafka (CMK) API group, the Connect API group, and the Data Catalog API group. Each group has its own set of endpoints and resources, as well as its own API group version.

Because different API groups have different versions, there is no single version for the "Confluent Cloud API". The latest version of the Connect API group may be connect/v1, while the latest version of the CMK API group may be cmk/v2.

When a breaking change is introduced into one API group, Confluent will increase the API version for that API group only, leaving the other API groups' versions unchanged. This makes it easier for you to understand whether a given breaking change impacts your usage of the APIs.

Known Issues​

During the Early Access and Preview periods, we have a few known issues.

IssueDescriptionProposed Resolution
Quota ExceededSome "Quota Exceeded" errors will be returned as HTTP 400 instead of HTTP 402Return 402 consistently for "Quota Exceeded" errors

API Lifecycle Policy​

The following status labels are applicable to APIs, features, and SDK versions, based on the current support status of each:

  • Early Access – May change at any time. Not recommended for production usage. Not officially supported by Confluent. Intended for user feedback only. Users must be granted explicit access to the API by Confluent.
  • Preview – Unlikely to change between Preview and General Availability. Not recommended for production usage. Officially supported by Confluent for non-production usage. Accessible to all users.
  • Limited Availability (LA) - Available to key select customers in a subset of regions/providers/networks and recommended for production usage.
  • Generally Available (GA) – Will not change at short notice. Recommended for production usage. Officially supported by Confluent for non-production and production usage.
  • Deprecated – Still supported, but no longer under active development. Existing usage will continue to function but migration following the upgrade guide is strongly recommended. New use cases should be built against the new version. Deprecated feature or version will be removed in the future at the announced date.
  • Sunset – Removed, and no longer supported or available.

An API is "Generally Available" unless explicitly marked otherwise.

Compatibility Policy​

Confluent Cloud APIs are governed by Confluent Cloud Upgrade Policy, which means that backward incompatible changes and deprecations will be made approximately once per year, and 180 days notice will be provided via email to all registered Confluent Cloud users.

Backward Compatibility​

An API version is backward compatible if a program written against the previous version of the API will continue to work the same way, without modification, against this version of the API.

Confluent considers the following changes to be backward compatible:

  • Adding new API resources.
  • Adding new optional parameters to existing API requests (e.g., query string).
  • Adding new properties to existing API resources (e.g., request body).
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
    • Unless otherwise documented, you can safely assume object IDs generated by Confluent will never exceed 255 characters, but you should be able to handle IDs of up to that length. If you're using MySQL, for example, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column.
    • This includes adding or removing fixed prefixes (such as lkc- on Kafka cluster IDs).
    • This includes API keys, API tokens, and similar authentication mechanisms.
    • This includes all strings described as "opaque" in the docs, such as pagination cursors.
  • Adding new API event types.
  • Adding new properties to existing API event types.
  • Omitting properties with null values from existing API responses.

Forward Compatibility​

An API version is forward compatible if a program written against the next version of the API will continue to work the same way, without modification, against this version of the API.

In other words, a forward compatible API will accept input intended for a later version of itself.

Confluent does not guarantee the forward compatibility of the APIs, but Confluent does generally follow the guidelines given by the Robustness principle. This means that the API determines what to do with a request based only on the parts that it recognizes.

This is often referred to as the MUST IGNORE rule.

  • Request parameters that are not recognized will be ignored (e.g., query string).
  • Request properties that are not recognized will be ignored (e.g., request body).
  • Request metadata that are not recognized will be ignored (e.g., request headers).

API clients must also follow the MUST IGNORE rule.

  • Response properties that are not recognized must be ignored (e.g., response body).
  • Response metadata that are not recognized must be ignored (e.g., response headers).

Additionally, there is a more subtle related rule called the MUST FORWARD rule. Any parts of a request that an API doesn't recognize must be forwarded unchanged.

  • Response properties that are not recognized must be included in any input subsequent updates (e.g., request body)
    • This includes future PUT requests in a read/modify/write operation. (This isn't required for PATCH partial updates, which is why Confluent APIs use PATCH.)
  • Event processors must not strip unknown properties before forwarding messages.

Compatibility Implementation Hints​

Confluent considers adding new properties to existing API resources (e.g., response bodies) to be a backward-compatible change. To ensure your integrations remain stable when new fields are introduced, your JSON parsers should be configured to ignore unknown properties rather than throwing an error.

For the Jackson library (Java), use one of these approaches:

1. Global Configuration (Recommended)

Configure ObjectMapper to ignore unknown properties globally.

ObjectMapper objectMapper = new ObjectMapper();
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

2. Class-Level Control

Use @JsonIgnoreProperties to ignore unknown fields on specific classes.

@JsonIgnoreProperties(ignoreUnknown = true)
public class MyResource { ... }

3. Capturing Unknown Fields

Use @JsonAnySetter to preserve unknown fields in a Map, in order to use them on future requests to fulfill the MUST FORWARD requirement.

public class MyResource {
    // ... existing fields ...
    private Map<String, Object> unknownProperties = new HashMap<>();

    @JsonAnySetter
    public void addUnknownProperty(String key, Object value) {
        this.unknownProperties.put(key, value);
    }

    public Map<String, Object> getUnknownProperties() {
        return unknownProperties;
    }
}

Client Responsibilities​

  • Resource and rate limits, and the default and maximum sizes of paginated data are not considered part of the API contract and may change (possibly dynamically). It is the client's responsibility to read the road signs and obey the speed limit.
  • If a property has a primitive type and the API documentation does not explicitly limit its possible values, clients must not assume the values are constrained to a particular set of possible responses.
  • If a property of an object is not explicitly declared as mandatory in the API, clients must not assume it will be present.
  • A resource may be modified to return a "redirection" response (e.g. 301, 307) instead of directly returning the resource. Clients must handle HTTP-level redirects, and respect HTTP headers (e.g. Location).

Deprecation Policy​

Confluent will announce deprecations at least 180 days in advance of a breaking change and will continue to maintain the deprecated APIs in their original form during this time.

Exceptions to this policy apply in case of critical security vulnerabilities or functional defects.

Communication​

When a deprecation is announced, the details and any relevant migration information will be available on one or more of the following channels:

HTTP Guidelines

Status Codes​

Confluent respects the meanings and behavior of HTTP status codes as defined in RFC2616 and elsewhere.

  • Codes in the 2xx range indicate success
  • Codes in the 3xx range indicate redirection
  • Codes in the 4xx range indicate an error caused by the client request (e.g., a required parameter was omitted, an invalid cluster configuration was provided, etc.)
  • Codes in the 5xx range indicate an error with Confluent's servers (these are rare)

The various HTTP status codes that might be returned are listed below.

CodeTitleDescription
200OKEverything worked as expected.
201CreatedThe resource was created. Follow the Location header.
204No ContentEverything worked and there is no content to return.
400Bad RequestThe request was unacceptable, often due to malformed syntax, or a missing or malformed parameter.
401UnauthorizedNo valid credentials provided. or the credentials are unsuitable, invalid, or unauthorized.
402Over QuotaThe request was valid, but you've exceeded your plan quota or limits.
404Not FoundThe requested resource doesn't exist or you're unauthorized to know it exists.
409ConflictThe request conflicts with another request (perhaps it already exists or was based on a stale version of data).
422Validation FailedThe request was parsed correctly but failed some sort of validation.
429Too Many RequestsToo many requests hit the API too quickly. Confluent recommends an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong on Confluent's end. (These are rare.)

This list is not exhaustive; other standard HTTP error codes may be used, including 304, 307, 308, 405, 406, 408, 410, and 415.

For more details, see https://httpstatuses.com.

Metrics APIs

For Metrics APIs, see Confluent Cloud Metrics API.

Authentication​

Authenticate with Cloud API Keys using HTTP Basic Auth. Treat the Cloud API Key ID as the username and Cloud API Key Secret as the password.

Security Scheme Type:

http

HTTP Authorization Scheme:

basic