Confluent Cloud REST API

---
openapi: 3.0.0
info:
  title: Confluent Cloud APIs
  version: ''  # TODO: figure out our aggregate API spec versioning strategy, this is here to pass the linter
  x-api-id: 46234552-5833-42eb-ba0f-883ad3f70d2b
  x-audience: external-public
  x-logo:
    url: https://assets.confluent.io/m/1661ef5e4ff82d3d/
  description: |
    # Introduction

    <div class="status-info">
    <p class="status-info-title">Note</p>
    This documents the collection of Confluent Cloud APIs. Each API documents its
    <a href="#api-lifecycle-policy">lifecycle phase</a>. 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.
    </div>

    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
    <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer" target="_blank">REST</a>
    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

    <div class="status-info">
    <p class="status-info-title">Note</p>
    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 <a href="../ccloud/connectors-connect-v-1/">Connect v1 API</a>
    to see its object model.
    </div>

    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](#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](https://docs.confluent.io/cloud/current/access-management/authenticate/api-keys/api-keys.html).

    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:

    ```text​
    Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=
    ```

    You can generate this header example from the API key:

    macOS:

    ```shell
    $ echo -n "ABCDEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

    ```

    Linux:

    ```shell
    $ 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. 

    ```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](https://docs.confluent.io/cloud/current/access-management/authenticate/oauth/overview.html)
    to authenticate and authorize access to applications and workloads for the
    following Confluent Cloud REST APIs:

    - **Kafka REST API**: [Kafka REST API for Clusters(V3)](../ccloud/cluster-v-3/).
      For an API overview and examples, see [Cluster Management with Kafka REST API](https://docs.confluent.io/cloud/current/kafka-rest/kafka-rest-cc.html).
    - **Schema Registry REST API**: [Schema Registry REST API for Schemas(V1)](../ccloud/schemas-v-1/)
      and [Subjects](../ccloud/subjects-v-1/).
      For an API overview and examples, see [Schema Registry REST API for Confluent Cloud](https://docs.confluent.io/cloud/current/sr/sr-rest-apis.html).

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

    <!-- TODO: port this back to the Confluent API Design Guide -->

    <SecurityDefinitions />

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

    <div class="status-info">
    <p class="status-info-title">Note</p>
    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 <a href="../ccloud/connectors-connect-v-1/">below</a> to see its error behavior.
    </div>

    ## 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](#status-codes) by Postman, a trusted API leader.

    ## HTTP status codes

    Confluent Cloud APIs return standard [HTTP status codes](#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](#status-codes) section.

    ## Error response structure

    Each API error response **should** include the following fields:

    **Top-level fields**

    | Field        | Type   | Required | Description                                                                                                                                             |
    | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | status       | String | Yes      | HTTP status code (for example, 400, 404, 500).                                                                                                          |
    | error        | Object | Yes      | Main object containing error details.                                                                                                                   |
    | requestId    | String | Optional | Unique identifier for the API request. Use for tracing, debugging, and support inquiries.                                                               |
    | doc_url      | String | Optional | Link to relevant documentation or troubleshooting steps.                                                                                                |

    **Fields inside `error` object**

    | Field       | Type   | Required | Description                                                                                                                                             |
    | ------------| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
    |  code       | String | Yes      | Unique, application-specific error code. Write error codes in uppercase letters, using underscores to separate words (for example, RESOURCE_NOT_FOUND). |
    |  message    | String | Yes      | Clear, actionable, user-friendly description of what went wrong using active voice.                                                                     |
    |  details    | String | Optional | Additional explanation or context about the error using active voice.                                                                                   |
    |  timestamp  | String | Yes      | ISO 8601 UTC timestamp indicating the date and time when the error occurred.                                                                            |
    |  path       | String | Yes      | The exact API endpoint or resource path related to the error.                                                                                           |
    |  suggestion | String | Optional | Recommend 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

    <div class="status-info">
    <p class="status-info-title">Note</p>
    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.
    </div>

    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 Relation](https://www.iana.org/assignments/link-relations/link-relations.xml) | Description                                                                                                                                                                             |
    | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `next`                                                                              | A link to the next page of results. A response that does not contain a next link does not have further data to fetch.                                                                   |
    | `prev`                                                                              | A 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. |
    | `first`                                                                             | A link to the first page of results. This link is **optional** for collections that cannot be indexed directly to a given page.                                                         |
    | `last`                                                                              | A 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)](../ccloud/cluster-v-3/).

    | Header                  | Description                                                                                                                                                                                                                                        |
    | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `X-RateLimit-Limit`     | The maximum number of requests you're permitted to make per time period.                                                                                                                                                                           |
    | `X-RateLimit-Reset`     | The relative time in seconds until the current rate limit window resets.                                                                                                                                                                           |
    | `Retry-After`           | The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.                                                                                                                                        |
    | `X-RateLimit-Remaining` | The 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](https://landing.google.com/sre/sre-book/chapters/addressing-cascading-failures/)
    ("retry storms") and also introduce some randomness ("jitter") to avoid the
    [thundering herd effect](https://en.wikipedia.org/wiki/Thundering_herd_problem).

    Rate limits are generally fixed and cannot be increased. If you require higher
    throughput, you can use a Dedicated cluster, where certain limits scale
    automatically with the number of CKUs. For example, each additional CKU
    increases the Kafka REST Produce v3 connection limit by 300 requests per
    second. For reference, see the
    [eCKU/CKU comparison table](https://docs.confluent.io/cloud/current/clusters/cluster-types.html#ecku-cku-comparison).

    If you’re running into this error and think you need a higher rate limit, contact Confluent at
    [support@confluent.io](mailto: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 `kind`s and `id`s necessary to uniquely identify a particular
      instance of this object `kind`. Because it uses object `id`s, 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
    <a href="https://docs.confluent.io/current/security/rbac/configure-mds/index.html" target="_blank">
    metadata service URL</a>, 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:

    | Resource                   | Example CRN                                                                                                                                                              |
    | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Organization               | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a                                                                                                  |
    | Environment                | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy                                                                            |
    | User                       | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/user=u-rst9876                                                                                   |
    | API Key                    | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/user=u-zyx98/api-key=ABCDEFG9876543210                                                           |
    | Service Account            | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/service-account=sa-abc1234                                                                       |
    | Kafka Cluster              | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc                                  |
    | Kafka Topic                | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc/topic=my_kafka_topic             |
    | Consumer Group             | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/kafka=lkc-123abc/group=confluent_cli_consumer_123 |
    | Network                    | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc                                                           |
    | Peering                    | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/peering=p-123abc                                          |
    | Private Link Access        | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/private-link-access=pla-123abc                            |
    | Transit Gateway Attachment | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/network=n-123abc/transit-gateway-attachment=tgwa-123abc                    |
    | Schema Registry Cluster    | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw                                                 |
    | Schema Subject             | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw/subject=test                                    |
    | KEK                        | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/schema-registry=lsrc-789qw//kek=test_kek                                   |
    | Connector                  | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/cloud-cluster=lkc-123abc/connector=my_datagen_connector                    |
    | Provider Integration       | crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-456xy/provider-integration=cspi-123j1                                            |

    # Data Types

    ## Primitive Types

    | Data Type | Representation                                                                                                                                                                                                                                                                                                                                                                                                                          |
    | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Integers  | Each 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.                                                                                                                                                                                                        |
    | Dates     | <a href="https://www.ietf.org/rfc/rfc3339.txt" target="_blank">RFC 3339</a> formatted string. UTC timezones are assumed, unless otherwise given.                                                                                                                                                                                                                                                                                        |
    | Times     | <a href="https://www.ietf.org/rfc/rfc3339.txt" target="_blank">RFC 3339</a> formatted string. UTC timezones are assumed, unless otherwise given.                                                                                                                                                                                                                                                                                        |
    | Durations | <a href="https://www.ietf.org/rfc/rfc3339.txt" target="_blank">RFC 3339</a> formatted string.                                                                                                                                                                                                                                                                                                                                           |
    | Periods   | <a href="https://www.ietf.org/rfc/rfc3339.txt" target="_blank">RFC 3339</a> formatted string. UTC timezones are assumed, unless otherwise given.                                                                                                                                                                                                                                                                                        |
    | Ranges    | All ranges are represented using half-open intervals with naming conventions like `[start_XXX, end_XXX)` such as `[start_time, end_time)`.                                                                                                                                                                                                                                                                                              |
    | Enums     | Most APIs use <a href="https://opensource.zalando.com/restful-api-guidelines/#112" target="_blank">`x-extensible-enum`</a> 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. |

    <!-- TODO
    ### Standard Objects

    | Money Object | https://schema.org

# --- truncated at 32 KB (2664 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/confluent-the-data-streaming-platform/refs/heads/main/openapi/confluent-the-data-streaming-platform-cloud-apis-openapi.yml