Get Confluent | Sign up for Confluent Cloud or download Confluent Platform

Confluent Cloud APIs

Download OpenAPI specification:Download

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

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

api-key

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

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

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

Note

This section describes the structure of error responses for many Confluent Cloud APIs, but not all. The Connect v1 API group has a different set of structures for error responses. Please review the example request and response bodies in the Connect v1 API documentation below to see its error behaviour.

Confluent uses conventional HTTP status codes to indicate the success or failure of an API request.

Failures follow a standard model to tell you about what went wrong. They may include one or more error objects with the following fields:

Field Type Description
id* UUID A unique identifier for this particular occurrence of the problem.
status String The HTTP status code applicable to this problem.
code String An application-specific error code.
title String A short, human-readable summary of the problem that should not change from occurrence to occurrence of the problem, except for purposes of localization.
detail* String A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source Object An object that references the source of the error, and optionally includes any of the following members:
  pointer String A JSON Pointer to the associated entity in the request document (e.g. "/spec/title" for a specific attribute).
  parameter String A string indicating which URI query parameter caused the error.
meta Object A meta object that contains non-standard meta-information about the error.
resolution String Instructions for the end-user for correcting the error.

* indicates a required field

All errors include an id and some detail message. The id is a unique identifier — use it when you're working with Confluent support to debug a problem with a specific API call. The detail describes what went wrong.

Some errors that could be handled programmatically (e.g., a Kafka cluster config is invalid) may include an error code that briefly explains the error reported.

Validation issues and similar errors include a source which tells you exactly what in the request was responsible for the error.

For example, a failure may look like

{
  "errors": [{
    "status": "422",
    "code": "invalid_configuration",
    "id": "30ce6058-87da-11e4-b116-123b93f75cba",
    "title": "The Kafka cluster configuration is invalid",
    "detail": "The property '/cluster/storage_size' of type string did not match the following type: integer",
    "source": {
      "pointer": "/cluster/storage_size"
    }
  }]
}

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 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 Relation 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).

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 ("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:

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

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 RFC 3339 formatted string. UTC timezones are assumed, unless otherwise given.
Times RFC 3339 formatted string. UTC timezones are assumed, unless otherwise given.
Durations RFC 3339 formatted string.
Periods RFC 3339 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 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.

Name Description
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.
id Many 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.
name Objects which support a client-provided unique identifier instead of a generated id will indicate this identifier via its name field.
display_name The human-readable display name of an API object.
title The official name of an API object, such as a company name. It should be treated as the formal version of display_name.
description One 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_at If present, the date and time after which the object was/will be deleted, represented as a string in RFC 3339 format.
page_token The pagination token in the List request. See Pagination.
page_size The pagination size in the List request. See Pagination.
total_size The total count of items in the list irrespective of pagination. See Pagination.
spec The desired state specification of the resource, as observed by Confluent Cloud.
status The 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 ingtegration 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.

Issue Description Proposed Resolution
Quota Exceeded Some "Quota Exceeded" errors will be returned as HTTP 400 instead of HTTP 402 Return 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.

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.

Code Title Description
200 OK Everything worked as expected.
201 Created The resource was created. Follow the Location header.
204 No Content Everything worked and there is no content to return.
400 Bad Request The request was unacceptable, often due to malformed syntax, or a missing or malformed parameter.
401 Unauthorized No valid credentials provided. or the credentials are unsuitable, invalid, or unauthorized.
402 Over Quota The request was valid, but you've exceeded your plan quota or limits.
404 Not Found The requested resource doesn't exist or you're unauthorized to know it exists.
409 Conflict The request conflicts with another request (perhaps it already exists or was based on a stale version of data).
422 Validation Failed The request was parsed correctly but failed some sort of validation.
429 Too Many Requests Too many requests hit the API too quickly. Confluent recommends an exponential backoff of your requests.
500, 502, 503, 504 Server Errors Something 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.

API Keys (iam/v2)

General Availability

ApiKey objects represent access to different parts of Confluent Cloud. Some types of API keys represent access to a single cluster/resource such as a Kafka cluster, Schema Registry cluster or a ksqlDB cluster. Cloud API Keys represent access to resources within an organization that are not tied to a specific cluster, such as the Org API, IAM API, Metrics API or Connect API.

The API allows you to list, create, update and delete your API Keys.

Related guide: API Keys in Confluent Cloud.

The API Keys Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ApiKey"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (iam.v2.ApiKeySpec)

The desired state of the Api Key

{
  • "api_version": "iam/v2",
  • "kind": "ApiKey",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
apikeys_per_org API Keys in one Confluent Cloud organization

List of API Keys

General Availability

Retrieve a sorted, filtered, paginated list of all API keys.

This can show all keys for a single owner (across resources - Kafka clusters), or all keys for a single resource (across owners). If no owner or resource filters are specified, returns all API Keys in the organization. You will only see the keys that are accessible to the account making the API request.

Authorizations:
cloud-api-key
query Parameters
spec.owner
string (SearchFilter)

Filter the results by exact match for spec.owner.

spec.resource
string (SearchFilter)

Filter the results by exact match for spec.resource.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/api-keys?spec.owner=SOME_STRING_VALUE&spec.resource=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an API Key

General Availability

Make a request to create an API key.

Authorizations:
cloud-api-key
Request Body schema: application/json
required
object

The desired state of the Api Key

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read an API Key

General Availability

Make a request to read an API key.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the API key.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/api-keys/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update an API Key

General Availability

Make a request to update an API key.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the API key.

Request Body schema: application/json
object (iam.v2.ApiKeySpecUpdate)

The desired state of the Api Key

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete an API Key

General Availability

Make a request to delete an API key.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the API key.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/api-keys/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Users (iam/v2)

General Availability

User objects represent individuals who may access your Confluent resources.

The API allows you to retrieve, update, and delete individual users, as well as list of all your users. This API cannot be used to create new user accounts.

Related guide: Users in Confluent Cloud.

The Users Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "User"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

email
string <email>

The user's email address

full_name
string

The user's full name

auth_type
string
extensible-enum: ["AUTH_TYPE_LOCAL","AUTH_TYPE_SSO"]

The user's authentication method

{
  • "api_version": "iam/v2",
  • "kind": "User",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "email": "marty.mcfly@example.com",
  • "full_name": "Marty McFly",
  • "auth_type": "AUTH_TYPE_SSO"
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
users_per_org Users in one Confluent Cloud organization

List of Users

General Availability

Retrieve a sorted, filtered, paginated list of all users.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/users \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a User

General Availability

Make a request to read a user.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the user.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/users/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "User",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "email": "marty.mcfly@example.com",
  • "full_name": "Marty McFly",
  • "auth_type": "AUTH_TYPE_SSO"
}

Update a User

General Availability

Make a request to update a user.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the user.

Request Body schema: application/json
full_name
string

The user's full name

Responses

Request samples

Content type
application/json
{
  • "full_name": "Marty McFly"
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "User",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "email": "marty.mcfly@example.com",
  • "full_name": "Marty McFly",
  • "auth_type": "AUTH_TYPE_SSO"
}

Delete a User

General Availability

Make a request to delete a user.

If successful, this request will also recursively delete all of the user's associated resources, including its cloud and cluster API keys.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the user.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/users/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Service Accounts (iam/v2)

General Availability

ServiceAccount objects are typically used to represent applications and other non-human principals that may access your Confluent resources.

The API allows you to create, retrieve, update, and delete individual service accounts, as well as list all your service accounts.

Related guide: Service Accounts in Confluent Cloud.

The Service Accounts Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ServiceAccount"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

A human-readable name for the Service Account

description
string

A free-form description of the Service Account

{
  • "api_version": "iam/v2",
  • "kind": "ServiceAccount",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "DeLorean_auto_repair",
  • "description": "Doc's repair bot for the DeLorean"
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
service_accounts_per_org Service Accounts in one Confluent Cloud organization

List of Service Accounts

General Availability

Retrieve a sorted, filtered, paginated list of all service accounts.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/service-accounts \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Service Account

General Availability

Make a request to create a service account.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
display_name
required
string

A human-readable name for the Service Account

description
string

A free-form description of the Service Account

Responses

Request samples

Content type
application/json
{
  • "display_name": "DeLorean_auto_repair",
  • "description": "Doc's repair bot for the DeLorean"
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "ServiceAccount",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "DeLorean_auto_repair",
  • "description": "Doc's repair bot for the DeLorean"
}

Read a Service Account

General Availability

Make a request to read a service account.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the service account.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/service-accounts/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "ServiceAccount",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "DeLorean_auto_repair",
  • "description": "Doc's repair bot for the DeLorean"
}

Update a Service Account

General Availability

Make a request to update a service account.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the service account.

Request Body schema: application/json
description
string

A free-form description of the Service Account

Responses

Request samples

Content type
application/json
{
  • "description": "Doc's repair bot for the DeLorean"
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "ServiceAccount",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "DeLorean_auto_repair",
  • "description": "Doc's repair bot for the DeLorean"
}

Delete a Service Account

General Availability

Make a request to delete a service account.

If successful, this request will also recursively delete all of the service account's associated resources, including its cloud and cluster API keys.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the service account.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/service-accounts/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Invitations (iam/v2)

General Availability

Invitation objects represent invitations to invite users to join your organizations in Confluent Cloud.

The API allows you to list all your invitations, as well as create, read, and delete a specified invitation.

Related guide: User invitations in Confluent Cloud.

The Invitations Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Invitation"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

email
string <email>

The user/invitee's email address

auth_type
string
extensible-enum: ["AUTH_TYPE_LOCAL","AUTH_TYPE_SSO"]

The user/invitee's authentication type. Note that only the OrganizationAdmin role can invite AUTH_TYPE_LOCAL users to SSO organizations. The user's auth_type is set as AUTH_TYPE_SSO by default if the organization has SSO enabled. Otherwise, the user's auth_type is AUTH_TYPE_LOCAL by default.

status
string
extensible-enum: ["INVITE_STATUS_SENT","INVITE_STATUS_STAGED","INVITE_STATUS_ACCEPTED","INVITE_STATUS_EXPIRED","INVITE_STATUS_DEACTIVATED"]

The status of invitations

accepted_at
string or null <date-time>

The timestamp that the invitation was accepted

expires_at
string <date-time>

The timestamp that the invitation will expire

object

The user/invitee

object

The invitation creator

{
  • "api_version": "iam/v2",
  • "kind": "Invitation",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "email": "johndoe@confluent.io",
  • "auth_type": "AUTH_TYPE_SSO",
  • "status": "INVITE_STATUS_SENT",
  • "accepted_at": "2022-07-06T17:21:33Z",
  • "expires_at": "2022-07-07T17:22:39Z",
  • "user": {},
  • "creator": {}
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
invitations_per_org Invitations in a Confluent Cloud organization

List of Invitations

General Availability

Retrieve a sorted, filtered, paginated list of all invitations.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
email
string (SearchFilter)
Example: email=johndoe@confluent.io

Filter the results by exact match for email.

status
string (SearchFilter)
Example: status=INVITE_STATUS_SENT

Filter the results by exact match for status.

user
string (SearchFilter)
Example: user=u-j93dy8

Filter the results by exact match for user.

creator
string (SearchFilter)
Example: creator=u-m2r9o7

Filter the results by exact match for creator.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/invitations?email=johndoe@confluent.io&status=INVITE_STATUS_SENT&user=u-j93dy8&creator=u-m2r9o7' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Invitation

General Availability

Make a request to create an invitation.

The newly invited user will not have any permissions. Give the user permission by assigning them to one or more roles by creating role bindings for the created user.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
email
required
string <email>

The user/invitee's email address

auth_type
string
extensible-enum: ["AUTH_TYPE_LOCAL","AUTH_TYPE_SSO"]

The user/invitee's authentication type. Note that only the OrganizationAdmin role can invite AUTH_TYPE_LOCAL users to SSO organizations. The user's auth_type is set as AUTH_TYPE_SSO by default if the organization has SSO enabled. Otherwise, the user's auth_type is AUTH_TYPE_LOCAL by default.

Responses

Request samples

Content type
application/json
{
  • "email": "johndoe@confluent.io",
  • "auth_type": "AUTH_TYPE_SSO"
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "Invitation",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "email": "johndoe@confluent.io",
  • "auth_type": "AUTH_TYPE_SSO",
  • "status": "INVITE_STATUS_SENT",
  • "accepted_at": "2022-07-06T17:21:33Z",
  • "expires_at": "2022-07-07T17:22:39Z",
  • "user": {},
  • "creator": {}
}

Read an Invitation

General Availability

Make a request to read an invitation.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the invitation.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/invitations/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "Invitation",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "email": "johndoe@confluent.io",
  • "auth_type": "AUTH_TYPE_SSO",
  • "status": "INVITE_STATUS_SENT",
  • "accepted_at": "2022-07-06T17:21:33Z",
  • "expires_at": "2022-07-07T17:22:39Z",
  • "user": {},
  • "creator": {}
}

Delete an Invitation

General Availability

Make a request to delete an invitation.

Delete will deactivate the user if the user didn't accept the invitation yet.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the invitation.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/invitations/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

IP Groups (iam/v2)

Limited Availability Request Access To IP Groups API

Definitions of networks which can be named and referred by IP blocks, commonly used to attach to IP Filter rules.

The IP Groups Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "IpGroup"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

group_name
string [ 1 .. 64 ] characters

A human readable name for an IP Group. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

cidr_blocks
Array of strings non-empty

A list of CIDRs.

{
  • "api_version": "iam/v2",
  • "kind": "IpGroup",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

List of IP Groups

Limited Availability Request Access To IP Groups API

Retrieve a sorted, filtered, paginated list of all IP groups.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 25

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/ip-groups \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an IP Group

Limited Availability Request Access To IP Groups API

Make a request to create an IP group.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
group_name
required
string [ 1 .. 64 ] characters

A human readable name for an IP Group. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

cidr_blocks
required
Array of strings non-empty

A list of CIDRs.

Responses

Request samples

Content type
application/json
{
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpGroup",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

Read an IP Group

Limited Availability Request Access To IP Groups API

Make a request to read an IP group.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP group.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/ip-groups/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpGroup",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

Update an IP Group

Limited Availability Request Access To IP Groups API

Make a request to update an IP group.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP group.

Request Body schema: application/json
group_name
string [ 1 .. 64 ] characters

A human readable name for an IP Group. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

cidr_blocks
Array of strings non-empty

A list of CIDRs.

Responses

Request samples

Content type
application/json
{
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpGroup",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "group_name": "CorpNet",
  • "cidr_blocks": [
    ]
}

Delete an IP Group

Limited Availability Request Access To IP Groups API

Make a request to delete an IP group.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP group.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/ip-groups/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

IP Filters (iam/v2)

Limited Availability Request Access To IP Filters API

IP Filter objects are bindings between IP Groups and Confluent resource(s). For example, a binding between "CorpNet" and "Management APIs" will enforce that access must come from one of the CIDR blocks associated with CorpNet. If there are multiple IP filters bound to a resource, a request matching any of the CIDR blocks for any of the IP Group will allow the request. If there are no IP Filters for a resource, then access will be granted to requests originating from any IP Address.

The IP Filters Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "IpFilter"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

filter_name
string [ 1 .. 64 ] characters

A human readable name for an IP Filter. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

resource_group
string

Scope of resources covered by this IP filter. The only resource_group currently available is "management".

Array of objects (GlobalObjectReference) non-empty

A list of IP Groups.

{
  • "api_version": "iam/v2",
  • "kind": "IpFilter",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": []
}

List of IP Filters

Limited Availability Request Access To IP Filters API

Retrieve a sorted, filtered, paginated list of all IP filters.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 25

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/ip-filters \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an IP Filter

Limited Availability Request Access To IP Filters API

Make a request to create an IP filter.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
filter_name
required
string [ 1 .. 64 ] characters

A human readable name for an IP Filter. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

resource_group
required
string

Scope of resources covered by this IP filter. The only resource_group currently available is "management".

required
Array of objects (GlobalObjectReference) non-empty

A list of IP Groups.

Responses

Request samples

Content type
application/json
{
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpFilter",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": []
}

Read an IP Filter

Limited Availability Request Access To IP Filters API

Make a request to read an IP filter.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP filter.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/ip-filters/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpFilter",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": []
}

Update an IP Filter

Limited Availability Request Access To IP Filters API

Make a request to update an IP filter.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP filter.

Request Body schema: application/json
filter_name
string [ 1 .. 64 ] characters

A human readable name for an IP Filter. Can contain any unicode letter or number, the ASCII space character, or any of the following special characters: [, ], |, &, +, -, _, /, ., ,.

resource_group
string

Scope of resources covered by this IP filter. The only resource_group currently available is "management".

Array of objects (GlobalObjectReference) non-empty

A list of IP Groups.

Responses

Request samples

Content type
application/json
{
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IpFilter",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "filter_name": "Management API Rules",
  • "resource_group": "management",
  • "ip_groups": []
}

Delete an IP Filter

Limited Availability Request Access To IP Filters API

Make a request to delete an IP filter.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the IP filter.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/ip-filters/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Role Bindings (iam/v2)

General Availability

A role binding grants a Principal a role on resources that match a pattern.

The API allows you to perform create, delete, and list operations on role bindings.

Related guide: Role-Based Access Control (RBAC).

The Role Bindings Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "RoleBinding"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

principal
string(^User:.+$)|(^Group:.+$)

The principal User or Group to bind the role to

role_name
string

The name of the role to bind to the principal

crn_pattern
string <uri> ^crn://.+$

A CRN that specifies the scope and resource patterns necessary for the role to bind

{
  • "api_version": "iam/v2",
  • "kind": "RoleBinding",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "principal": "User:u-111aaa",
  • "role_name": "CloudClusterAdmin",
  • "crn_pattern": "crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa"
}

List of Role Bindings

General Availability

Retrieve a sorted, filtered, paginated list of all role bindings.

Authorizations:
api-keyconfluent-sts-access-token
query Parameters
principal
string (SearchFilter)
Example: principal=User:u-111aaa

Filter the results by exact match for principal.

role_name
string (SearchFilter)
Example: role_name=CloudClusterAdmin

Filter the results by exact match for role_name.

crn_pattern
required
string (SearchFilter)
Example: crn_pattern=crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa

Filter the results by a partial search of crn_pattern.

page_size
integer <= 1000
Default: 100

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/role-bindings?principal=User:u-111aaa&role_name=CloudClusterAdmin&crn_pattern=crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Role Binding

General Availability

Make a request to create a role binding.

Authorizations:
api-keyconfluent-sts-access-token
Request Body schema: application/json
principal
required
string(^User:.+$)|(^Group:.+$)

The principal User or Group to bind the role to

role_name
required
string

The name of the role to bind to the principal

crn_pattern
required
string <uri> ^crn://.+$

A CRN that specifies the scope and resource patterns necessary for the role to bind

Responses

Request samples

Content type
application/json
{
  • "principal": "User:u-111aaa",
  • "role_name": "CloudClusterAdmin",
  • "crn_pattern": "crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa"
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "RoleBinding",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "principal": "User:u-111aaa",
  • "role_name": "CloudClusterAdmin",
  • "crn_pattern": "crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa"
}

Read a Role Binding

General Availability

Make a request to read a role binding.

Authorizations:
api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the role binding.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/role-bindings/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "RoleBinding",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "principal": "User:u-111aaa",
  • "role_name": "CloudClusterAdmin",
  • "crn_pattern": "crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa"
}

Delete a Role Binding

General Availability

Make a request to delete a role binding.

Authorizations:
api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the role binding.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/role-bindings/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "RoleBinding",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "principal": "User:u-111aaa",
  • "role_name": "CloudClusterAdmin",
  • "crn_pattern": "crn://confluent.cloud/organization=1111aaaa-11aa-11aa-11aa-111111aaaaaa/environment=env-aaa1111/cloud-cluster=lkc-1111aaa"
}

Identity Providers (iam/v2)

General Availability

IdentityProvider objects represent external OAuth-OIDC providers in Confluent Cloud.

The API allows you to list, create, read, update, and delete your Identity Provider.

Related guide: OAuth for Confluent Cloud.

The Identity Providers Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "IdentityProvider"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

The human-readable name of the OAuth identity provider.

description
string

A description of the identity provider.

state
string
extensible-enum: ["ENABLED"]

The current state of the identity provider.

issuer
string <uri>

A publicly accessible URL uniquely identifying the OAuth identity provider authorized to issue access tokens.

jwks_uri
string <uri>

A publicly accessible JSON Web Key Set (JWKS) URI for the OAuth identity provider. JWKS provides a set of crypotgraphic keys used to verify the authenticity and integrity of JSON Web Tokens (JWTs) issued by the OAuth identity provider.

Array of objects (iam.v2.JwksObject)

The JWKS issued by the OAuth identity provider. Only kid (key ID) and alg (algorithm) properties for each key set are included.

{}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
identity_providers_per_org Number of OAuth identity providers per organization
public_keys_per_provider Number of public keys saved per identity provider

List of Identity Providers

General Availability

Retrieve a sorted, filtered, paginated list of all identity providers.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/identity-providers \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Identity Provider

General Availability

Make a request to create an identity provider.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
display_name
required
string

The human-readable name of the OAuth identity provider.

description
required
string

A description of the identity provider.

issuer
required
string <uri>

A publicly accessible URL uniquely identifying the OAuth identity provider authorized to issue access tokens.

jwks_uri
required
string <uri>

A publicly accessible JSON Web Key Set (JWKS) URI for the OAuth identity provider. JWKS provides a set of crypotgraphic keys used to verify the authenticity and integrity of JSON Web Tokens (JWTs) issued by the OAuth identity provider.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Read an Identity Provider

General Availability

Make a request to read an identity provider.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the identity provider.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update an Identity Provider

General Availability

Make a request to update an identity provider.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the identity provider.

Request Body schema: application/json
display_name
string

The human-readable name of the OAuth identity provider.

description
string

A description of the identity provider.

issuer
string <uri>

A publicly accessible URL uniquely identifying the OAuth identity provider authorized to issue access tokens.

jwks_uri
string <uri>

A publicly accessible JSON Web Key Set (JWKS) URI for the OAuth identity provider. JWKS provides a set of crypotgraphic keys used to verify the authenticity and integrity of JSON Web Tokens (JWTs) issued by the OAuth identity provider.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete an Identity Provider

General Availability

Make a request to delete an identity provider.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the identity provider.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Jwks (iam/v2)

General Availability

JWKS objects represent public key sets for a specific OAuth/OpenID Connect provider within Confluent Cloud.

The API allows you to refresh JWKS public key data.

Related guide: OAuth for Confluent Cloud.

The Jwks Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Jwks"

Kind defines the object this REST resource represents.

object (iam.v2.JwksSpec)

The desired state of the Jwks

object (iam.v2.JwksStatus)

The status of the Jwks

{
  • "api_version": "iam/v2",
  • "kind": "Jwks",
  • "spec": {
    },
  • "status": {
    }
}

Refresh a provider's JWKS

General Availability

Make a request to refresh the provider's JWKS

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

Request Body schema: application/json
object (iam.v2.JwksSpec)

The desired state of the Jwks

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "Jwks",
  • "spec": {
    },
  • "status": {
    }
}

Identity Pools (iam/v2)

General Availability

IdentityPool objects represent groups of identities tied to a given a IdentityProvider that authorizes them to Confluent Cloud resources.

It provides a mapping functionality of your Identity Provider user to a Confluent identity pool that is then used to provide access to Confluent Resources.

Related guide: Use identity pools with your OAuth provider.

The Identity Pools Model

api_version
string
Value: "iam/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "IdentityPool"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

The name of the IdentityPool.

description
string

A description of how this IdentityPool is used

identity_claim
string

The JSON Web Token (JWT) claim to extract the authenticating identity to Confluent resources from (see Registered Claim Names for more details). This appears in the audit log records, showing, for example, that "identity Z used identity pool X to access topic A".

filter
string <= 300 characters

A filter expression in Supported Common Expression Language (CEL) that specifies which identities can authenticate using your identity pool (see Set identity pool filters for more details).

principal
string

Represents the federated identity associated with this pool.

state
string
extensible-enum: ["ENABLED"]

The current state of the identity pool

{
  • "api_version": "iam/v2",
  • "kind": "IdentityPool",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\"",
  • "principal": "pool-abc",
  • "state": "ENABLED"
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
identity_pools_per_provider Number of Identity Pools per Identity Provider

List of Identity Pools

General Availability

Retrieve a sorted, filtered, paginated list of all identity pools.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{provider_id}/identity-pools' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Identity Pool

General Availability

Make a request to create an identity pool.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

Request Body schema: application/json
display_name
required
string

The name of the IdentityPool.

description
required
string

A description of how this IdentityPool is used

identity_claim
required
string

The JSON Web Token (JWT) claim to extract the authenticating identity to Confluent resources from (see Registered Claim Names for more details). This appears in the audit log records, showing, for example, that "identity Z used identity pool X to access topic A".

filter
required
string <= 300 characters

A filter expression in Supported Common Expression Language (CEL) that specifies which identities can authenticate using your identity pool (see Set identity pool filters for more details).

Responses

Request samples

Content type
application/json
{
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\""
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IdentityPool",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\"",
  • "principal": "pool-abc",
  • "state": "ENABLED"
}

Read an Identity Pool

General Availability

Make a request to read an identity pool.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

id
required
string

The unique identifier for the identity pool.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{provider_id}/identity-pools/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IdentityPool",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\"",
  • "principal": "pool-abc",
  • "state": "ENABLED"
}

Update an Identity Pool

General Availability

Make a request to update an identity pool.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

id
required
string

The unique identifier for the identity pool.

Request Body schema: application/json
display_name
string

The name of the IdentityPool.

description
string

A description of how this IdentityPool is used

identity_claim
string

The JSON Web Token (JWT) claim to extract the authenticating identity to Confluent resources from (see Registered Claim Names for more details). This appears in the audit log records, showing, for example, that "identity Z used identity pool X to access topic A".

filter
string <= 300 characters

A filter expression in Supported Common Expression Language (CEL) that specifies which identities can authenticate using your identity pool (see Set identity pool filters for more details).

Responses

Request samples

Content type
application/json
{
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\""
}

Response samples

Content type
application/json
{
  • "api_version": "iam/v2",
  • "kind": "IdentityPool",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "My Identity Pool",
  • "description": "Prod Access to Kafka clusters to Release Engineering",
  • "identity_claim": "claims.sub",
  • "filter": "claims.aud==\"confluent\" && claims.group!=\"invalid_group\"",
  • "principal": "pool-abc",
  • "state": "ENABLED"
}

Delete an Identity Pool

General Availability

Make a request to delete an identity pool.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
provider_id
required
string

The Provider

id
required
string

The unique identifier for the identity pool.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/identity-providers/{provider_id}/identity-pools/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Group Mappings (iam/v2/sso)

General Availability

GroupMapping objects establish relationships between user groups in your SSO identity provider and specific RBAC roles in Confluent Cloud.

Group mappings enable automated and secure access control to Confluent Cloud resources, reducing administrative workload by streamlining user provisioning and authorization.

Related guide: Use group mappings with your SSO identity provider.

The Group Mappings Model

api_version
string
Value: "iam.v2/sso"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "GroupMapping"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

The name of the group mapping.

description
string

A description explaining the purpose and use of the group mapping.

filter
string <= 300 characters

A single group identifier or a condition based on supported CEL operators that defines which groups are included.

principal
string

The unique federated identity associated with this group mapping.

state
string
extensible-enum: ["ENABLED"]

The current state of the group mapping.

{
  • "api_version": "iam.v2/sso",
  • "kind": "GroupMapping",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups",
  • "principal": "group-a1b2",
  • "state": "ENABLED"
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
group_mappings_per_org Number of group mappings per organization

List of Group Mappings

General Availability

Retrieve a sorted, filtered, paginated list of all group mappings.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/iam/v2/sso/group-mappings \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Group Mapping

General Availability

Make a request to create a group mapping.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
display_name
required
string

The name of the group mapping.

description
required
string

A description explaining the purpose and use of the group mapping.

filter
required
string <= 300 characters

A single group identifier or a condition based on supported CEL operators that defines which groups are included.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups"
}

Response samples

Content type
application/json
{
  • "api_version": "iam.v2/sso",
  • "kind": "GroupMapping",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups",
  • "principal": "group-a1b2",
  • "state": "ENABLED"
}

Read a Group Mapping

General Availability

Make a request to read a group mapping.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the group mapping.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/sso/group-mappings/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "iam.v2/sso",
  • "kind": "GroupMapping",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups",
  • "principal": "group-a1b2",
  • "state": "ENABLED"
}

Update a Group Mapping

General Availability

Make a request to update a group mapping.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the group mapping.

Request Body schema: application/json
display_name
string

The name of the group mapping.

description
string

A description explaining the purpose and use of the group mapping.

filter
string <= 300 characters

A single group identifier or a condition based on supported CEL operators that defines which groups are included.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups"
}

Response samples

Content type
application/json
{
  • "api_version": "iam.v2/sso",
  • "kind": "GroupMapping",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "Application Developers",
  • "description": "Admin access to production environment for Engineering",
  • "filter": "\"kafka\" in groups && \"all\" in groups || \"everyone\" in groups",
  • "principal": "group-a1b2",
  • "state": "ENABLED"
}

Delete a Group Mapping

General Availability

Make a request to delete a group mapping.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the group mapping.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/sso/group-mappings/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Environments (org/v2)

General Availability

Environment objects represent an isolated namespace for your Confluent resources for organizational purposes.

The API allows you to create, delete, and update your environments. You can retrieve individual environments as well as a list of all your environments.

Related guide: Environments in Confluent Cloud.

The Environments Model

api_version
string
Value: "org/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Environment"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

A human-readable name for the Environment

object

Stream Governance configurations for the environment

{
  • "api_version": "org/v2",
  • "kind": "Environment",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
environments_per_org Environments in one Confluent Cloud organization

List of Environments

General Availability

Retrieve a sorted, filtered, paginated list of all environments.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/org/v2/environments \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Environment

General Availability

Make a request to create an environment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
display_name
required
string

A human-readable name for the Environment

object

Stream Governance configurations for the environment

Responses

Request samples

Content type
application/json
{
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "org/v2",
  • "kind": "Environment",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Read an Environment

General Availability

Make a request to read an environment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/org/v2/environments/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "org/v2",
  • "kind": "Environment",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Update an Environment

General Availability

Make a request to update an environment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the environment.

Request Body schema: application/json
display_name
string

A human-readable name for the Environment

object

Stream Governance configurations for the environment

Responses

Request samples

Content type
application/json
{
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "org/v2",
  • "kind": "Environment",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "prod-finance01",
  • "stream_governance_config": {
    }
}

Delete an Environment

General Availability

Make a request to delete an environment.

If successful, this request will also recursively delete all of the environment's associated resources, including all Kafka clusters, connectors, etc.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/org/v2/environments/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Organizations (org/v2)

General Availability

Organization objects represent a customer organization. An organization contains all customer resources (e.g., Environments, Kafka Clusters, Service Accounts, API Keys) and is tied to a billing agreement (including any annual commitment or support plan).

The API allows you to list, view, and update your organizations.

Related guide: Organizations for Confluent Cloud.

The Organizations Model

api_version
string
Value: "org/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Organization"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string^[^<>#%'*^`{|}~\"]{1,31}$

A human-readable name for the Organization

jit_enabled
boolean

The flag to toggle Just-In-Time user provisioning for SSO-enabled organization. Available for early access only.

{
  • "api_version": "org/v2",
  • "kind": "Organization",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Finance Org",
  • "jit_enabled": true
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
organizations_per_user Confluent Cloud organizations a user belongs to

List of Organizations

General Availability

Retrieve a sorted, filtered, paginated list of all organizations.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/org/v2/organizations \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read an Organization

General Availability

Make a request to read an organization.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the organization.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/org/v2/organizations/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "org/v2",
  • "kind": "Organization",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Finance Org",
  • "jit_enabled": true
}

Update an Organization

General Availability

Make a request to update an organization.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the organization.

Request Body schema: application/json
display_name
string^[^<>#%'*^`{|}~\"]{1,31}$

A human-readable name for the Organization

jit_enabled
boolean

The flag to toggle Just-In-Time user provisioning for SSO-enabled organization. Available for early access only.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Finance Org",
  • "jit_enabled": true
}

Response samples

Content type
application/json
{
  • "api_version": "org/v2",
  • "kind": "Organization",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Finance Org",
  • "jit_enabled": true
}

Subscriptions (notifications/v1)

General Availability

Subscription objects represent the intent of the customers to get notifications of particular types. A subscription is created for a particular NotificationType and the user will get notifications on the Integrations that are provided while creating the subscription.

This API allows you to create, retrieve, and update subscriptions, as well as to view the list of all your subscriptions. You can also delete subscriptions with RECOMMENDED or OPTIONAL notification types. Subscriptions with REQUIRED notification types cannot be deleted.

Related guide: Cloud Notifications.

The Subscriptions Model

api_version
string
Value: "notifications/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Subscription"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

current_state
string
extensible-enum: ["ENABLED","DISABLED"]

Denotes the state of the subscription. When the subscription is ENABLED, the user will receive notification on the configured Integrations. If the subscription is DISABLED, the user will not recieve any notification for the configured notification type. Note that, you cannot disable a subscription for REQUIRED notification type.

object

The type of notification to subscribe to.

Array of objects (GlobalObjectReference) non-empty

Integrations to which notifications are to be sent.

{}

List of Subscriptions

General Availability

Retrieve a sorted, filtered, paginated list of all subscriptions.

Authorizations:
api-key
query Parameters
page_size
integer <= 250
Default: 100

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/notifications/v1/subscriptions \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Subscription

General Availability

Make a request to create a subscription.

Authorizations:
api-key
Request Body schema: application/json
current_state
string
extensible-enum: ["ENABLED","DISABLED"]

Denotes the state of the subscription. When the subscription is ENABLED, the user will receive notification on the configured Integrations. If the subscription is DISABLED, the user will not recieve any notification for the configured notification type. Note that, you cannot disable a subscription for REQUIRED notification type.

required
object

The type of notification to subscribe to.

required
Array of objects (GlobalObjectReference) non-empty

Integrations to which notifications are to be sent.

Responses

Request samples

Content type
application/json
{
  • "current_state": "ENABLED",
  • "notification_type": {
    },
  • "integrations": [
    ]
}

Response samples

Content type
application/json
{}

Read a Subscription

General Availability

Make a request to read a subscription.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the subscription.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/notifications/v1/subscriptions/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Subscription

General Availability

Make a request to update a subscription.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the subscription.

Request Body schema: application/json
current_state
string
extensible-enum: ["ENABLED","DISABLED"]

Denotes the state of the subscription. When the subscription is ENABLED, the user will receive notification on the configured Integrations. If the subscription is DISABLED, the user will not recieve any notification for the configured notification type. Note that, you cannot disable a subscription for REQUIRED notification type.

Array of objects (GlobalObjectReference) non-empty

Integrations to which notifications are to be sent.

Responses

Request samples

Content type
application/json
{
  • "current_state": "ENABLED",
  • "integrations": [
    ]
}

Response samples

Content type
application/json
{}

Delete a Subscription

General Availability

Make a request to delete a subscription.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the subscription.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/notifications/v1/subscriptions/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Integrations (notifications/v1)

General Availability

You can create an Integration to specify how we can notify you when we receive an alert/notification for a subscription. Please note that you can only perform create, update and delete operations for integrations of type Webhook, Slack and MsTeams. You cannot create, update or delete integrations of type RoleEmail and UserEmail.

Related guide: Cloud Notifications.

The Integrations Model

api_version
string
Value: "notifications/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Integration"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string <= 64 characters

A human readable name for the particular integration

description
string <= 128 characters

A human readable description for the particular integration

any

Integration-specific details (integration targets)

{
  • "api_version": "notifications/v1",
  • "kind": "Integration",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Slack integration",
  • "description": "A Slack channel integration",
  • "target": {}
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
integrations_per_org Maximum number of integrations in one Confluent Cloud organization

List of Integrations

General Availability

Retrieve a sorted, filtered, paginated list of all integrations.

Authorizations:
api-key
query Parameters
page_size
integer <= 250
Default: 100

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/notifications/v1/integrations \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Integration

General Availability

Make a request to create an integration.

Authorizations:
api-key
Request Body schema: application/json
display_name
required
string <= 64 characters

A human readable name for the particular integration

description
string <= 128 characters

A human readable description for the particular integration

required
any

Integration-specific details (integration targets)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "Integration",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Slack integration",
  • "description": "A Slack channel integration",
  • "target": {}
}

Read an Integration

General Availability

Make a request to read an integration.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the integration.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/notifications/v1/integrations/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "Integration",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Slack integration",
  • "description": "A Slack channel integration",
  • "target": {}
}

Update an Integration

General Availability

Make a request to update an integration.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the integration.

Request Body schema: application/json
display_name
string <= 64 characters

A human readable name for the particular integration

description
string <= 128 characters

A human readable description for the particular integration

any

Integration-specific details (integration targets)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "Integration",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Slack integration",
  • "description": "A Slack channel integration",
  • "target": {}
}

Delete an Integration

General Availability

Make a request to delete an integration.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the integration.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/notifications/v1/integrations/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Test a Webhook, Slack or Microsoft Teams integration

General Availability

Sends a test notification to validate the integration. This is supported only for Webhook, Slack and MsTeams targets

Authorizations:
api-key
Request Body schema: application/json
display_name
required
string <= 64 characters

A human readable name for the particular integration

description
string <= 128 characters

A human readable description for the particular integration

required
any

Integration-specific details (integration targets)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Notification Types (notifications/v1)

General Availability

The type of notifications (and their corresponding metadata) supported by Confluent.

Related guide: Cloud Notifications.

The Notification Types Model

api_version
string
Value: "notifications/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "NotificationType"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

Human readable display name of the notification type

category
string
extensible-enum: ["BILLING_LICENSING","SECURITY","SERVICE","ACCOUNT"]

Represents the group with which the notification is associated. Notifications are grouped under certain categories for better organization.

  • BILLING_LICENSING: All billing, payments or licensing related notifications are grouped here.
  • SECURITY: All Confluent Cloud and Platform security related notifications are grouped here.
  • SERVICE: All Confluent services (eg. Kafka, Schema Registry, Connect etc.) related notifications are grouped here.
  • ACCOUNT: All Confluent account related notifications are grouped here. For example: Billing, payment or license related notifications are grouped in BILLING_LICENSING category.
description
string

Human readable description of the notification type

subscription_priority
string
extensible-enum: ["REQUIRED","RECOMMENDED","OPTIONAL"]

Indicates whether the notification is auto-subscribed and if the user can opt-out.

  • REQUIRED: the user is auto-subscribed to this notification and can't opt-out.
  • RECOMMENDED: the user is auto-subscribed to this notification and can opt-out.
  • OPTIONAL: the user is not auto-subscribed to this notification but can explicitly subscribe to it.
is_included_in_plan
boolean

Whether this notification is available to subscribe or not as per the user's current billing plan.

severity
string
extensible-enum: ["CRITICAL","WARN","INFO"]

Severity indicates the impact of this notification.

  • CRITICAL: a high impact notification which needs immediate attention.
  • WARN: a warning notification which can be addressed now or later.
  • INFO: an informational notification.
{
  • "api_version": "notifications/v1",
  • "kind": "NotificationType",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Cluster Shrink",
  • "category": "BILLING_LICENSING",
  • "description": "Cluster shrink operation is completed",
  • "subscription_priority": "REQUIRED",
  • "is_included_in_plan": true,
  • "severity": "INFO"
}

List of Notification Types

General Availability

Retrieve a sorted, filtered, paginated list of all notification types.

Authorizations:
api-key
query Parameters
page_size
integer <= 250
Default: 100

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/notifications/v1/notification-types \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Notification Type

General Availability

Make a request to read a notification type.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the notification type.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/notifications/v1/notification-types/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "NotificationType",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "Cluster Shrink",
  • "category": "BILLING_LICENSING",
  • "description": "Cluster shrink operation is completed",
  • "subscription_priority": "REQUIRED",
  • "is_included_in_plan": true,
  • "severity": "INFO"
}

Clusters (cmk/v2)

General Availability

Clusters objects represent Apache Kafka Clusters on Confluent Cloud.

The API allows you to list, create, read, update, and delete your Kafka clusters.

Related guide: Confluent Cloud Cluster Management for Apache Kafka APIs.

The Clusters Model

api_version
string
Value: "cmk/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Cluster"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (cmk.v2.ClusterSpec)

The desired state of the Cluster

object (cmk.v2.ClusterStatus)

The status of the Cluster

{}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
kafka_clusters_per_environment Number of clusters in one Confluent Cloud environment

List of Clusters

General Availability

Retrieve a sorted, filtered, paginated list of all clusters.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

spec.network
Array of strings (MultipleSearchFilter)
Example: spec.network=n-00000&spec.network=n-00001

Filter the results by exact match for spec.network. Pass multiple times to see results matching any of the values.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cmk/v2/clusters?environment=env-00000&spec.network=n-00000,n-00001' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Cluster

General Availability

Make a request to create a cluster.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Cluster

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Cluster

General Availability

Make a request to read a cluster.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cmk/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Cluster

General Availability

Make a request to update a cluster.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the cluster.

Request Body schema: application/json
required
object

The desired state of the Cluster

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Cluster

General Availability

Make a request to delete a cluster.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/cmk/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Clusters (ksqldbcm/v2)

General Availability

Cluster represents a ksqlDB runtime that you can issue queries to using its API endpoint. It executes SQL statements and queries which under the hood get built into corresponding Kafka Streams topologies. The API allows you to list, create, read, and delete your ksqlDB clusters.

Related guide: ksqlDB in Confluent Cloud.

The Clusters Model

api_version
string
Value: "ksqldbcm/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Cluster"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (ksqldbcm.v2.ClusterSpec)

The desired state of the Cluster

object (ksqldbcm.v2.ClusterStatus)

The status of the Cluster

{}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
ksql.limits.max_apps_per_cluster Clusters in one Confluent Cloud Kafka Cluster.

List of Clusters

General Availability

Retrieve a sorted, filtered, paginated list of all clusters.

Authorizations:
api-keyconfluent-sts-access-token
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/ksqldbcm/v2/clusters?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Cluster

General Availability

Make a request to create a cluster.

Authorizations:
api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Cluster

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Cluster

General Availability

Make a request to read a cluster.

Authorizations:
api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/ksqldbcm/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Delete a Cluster

General Availability

Make a request to delete a cluster.

Authorizations:
api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/ksqldbcm/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Connectors (connect/v1)

General Availability

API for Managed Connectors or Custom Connectors in Confluent Cloud.

The API allows you to list, create, get, update and delete a Managed Connector or Custom Connector in Confluent Cloud.

Connect metrics are available through the Metrics v2 API.

Related guide: Confluent Cloud API and Managed Connectors.

List of Connectors

General Availability

Retrieve a list of "names" of the active connectors. You can then make a read request for a specific connector by name.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
[
  • "MyGcsLogsBucketConnector",
  • "MyS3BucketConnector",
  • "MyDatagenConnector"
]

Create a Connector

General Availability

Create a new connector. Returns the new connector information if successful.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Request Body schema: application/json
name
string

Name of the connector to create.

object

Configuration parameters for the connector. All values should be strings.

Responses

Request samples

Content type
application/json
{
  • "name": "MyGcsLogsBucketConnector",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "name": "MyGcsLogsBucketConnector",
  • "config": {
    },
  • "tasks": [
    ],
  • "type": "sink"
}

List of Connectors with Expansions

General Availability

Retrieve an object with the queried expansions of all connectors. Without expand query parameter, this list connector’s endpoint will return a list of only the connector names.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

query Parameters
expand
string
Enum: "id" "info" "status"
  • id : Returns metadata of each connector such as id and id type.
  • info : Returns metadata of each connector such as the configuration, task information, and type of connector.
  • status : Returns additional state information of each connector including their status and tasks.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors?expand=info,status,id' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "MyGcsLogsBucketConnector": {
    },
  • "MyS3BucketConnector": {
    },
  • "MyDatagenConnector": {
    }
}

Read a Connector Configuration

General Availability

Get the configuration for the connector.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/config' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "cloud.environment": "prod",
  • "cloud.provider": "aws",
  • "connector.class": "GcsSink",
  • "data.format": "BYTES",
  • "flush.size": "1000",
  • "gcs.bucket.name": "APILogsBucket",
  • "gcs.credentials.config": "****************",
  • "kafka.api.key": "****************",
  • "kafka.api.secret": "****************",
  • "kafka.endpoint": "SASL_SSL://pkc-xxxxx.us-west-2.aws.confluent.cloud:9092",
  • "kafka.region": "us-west-2",
  • "name": "MyGcsLogsBucketConnector",
  • "tasks.max": "2",
  • "time.interval": "DAILY",
  • "topics": "APILogsTopic"
}

Create or Update a Connector Configuration

Create a new connector using the given configuration, or update the configuration for an existing connector. Returns information about the connector after the change has been made.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Request Body schema: application/json

Configuration parameters for the connector. All values should be strings.

connector.class
required
string

[Required for Managed Connector, Ignored for Custom Connector] The connector class name. E.g. BigQuerySink, GcsSink, etc.

name
required
string

Name or alias of the class (plugin) for this connector.

kafka.api.key
required
string

The kafka cluster api key.

kafka.api.secret
required
string

The kafka cluster api secret key.

confluent.connector.type
string
Default: "MANAGED"
extensible-enum: ["CUSTOM","MANAGED"]

[Required for Custom Connector] The connector type.

confluent.custom.plugin.id
string

[Required for Custom Connector] The custom plugin id of custom connector, e.g., ccp-lq5m06

confluent.custom.connection.endpoints
string

[Optional for Custom Connector] Egress endpoint(s) for the connector to use when attaching to the sink or source data system.

confluent.custom.schema.registry.auto
string
Default: "FALSE"
extensible-enum: ["TRUE","FALSE"]

[Optional for Custom Connector] Automatically add the required schema registry properties in a custom connector config if schema registry is enabled.

property name*
additional property
string

Other configuration parameters for the connector. All values should be strings. See the connector's docs for details.

Responses

Request samples

Content type
application/json
{
  • "connector.class": "GcsSink",
  • "data.format": "BYTES",
  • "flush.size": "1000",
  • "gcs.bucket.name": "APILogsBucket",
  • "gcs.credentials.config": "****************",
  • "kafka.api.key": "****************",
  • "kafka.api.secret": "****************",
  • "name": "MyGcsLogsBucketConnector",
  • "tasks.max": "2",
  • "time.interval": "DAILY",
  • "topics": "APILogsTopic"
}

Response samples

Content type
application/json
{
  • "name": "MyGcsLogsBucketConnector",
  • "config": {
    },
  • "tasks": [
    ],
  • "type": "sink"
}

Read a Connector

General Availability

Get information about the connector.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "name": "MyGcsLogsBucketConnector",
  • "config": {
    },
  • "tasks": [
    ],
  • "type": "sink"
}

Delete a Connector

General Availability

Delete a connector. Halts all tasks and deletes the connector configuration.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "error": null
}

Lifecycle (connect/v1)

General Availability

API for managing the lifecycle for a Managed Connector or Custom Connector in Confluent Cloud. Operations currently supported are Pause and Resume.

Pause a Connector

General Availability

Pause the connector and its tasks. Stops message processing until the connector is resumed. This call is asynchronous and the tasks will not transition to PAUSED state at the same time.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request PUT \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/pause' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "error": {
    }
}

Resume a Connector

General Availability

Resume a paused connector or do nothing if the connector is not paused. This call is asynchronous and the tasks will not transition to RUNNING state at the same time.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request PUT \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/resume' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "error": {
    }
}

Status (connect/v1)

General Availability

API for requesting the status or the tasks for a Managed Connector or Custom Connector in Confluent Cloud.

Read a Connector Status

Get current status of the connector. This includes whether it is running, failed, or paused. Also includes which worker it is assigned to, error information if it has failed, and the state of all its tasks.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/status' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "name": "MyGcsLogsBucketConnector",
  • "connector": {
    },
  • "tasks": [ ],
  • "type": "source"
}

List of Connector Tasks

General Availability

Get a list of tasks currently running for the connector.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
connector_name
required
string

The unique name of the connector.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connectors/{connector_name}/tasks' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
[
  • {
    }
]

Managed Connector Plugins (connect/v1)

General Availability

API for Managed connectors in Confluent Cloud.

List of Managed Connector plugins

General Availability

Return a list of Managed Connector plugins installed in the Kafka Connect cluster.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/environments/{environment_id}/clusters/{kafka_cluster_id}/connector-plugins' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Validate a Managed Connector Plugin

General Availability

Validate the provided configuration values against the configuration definition. This API performs per config validation and returns suggested values and validation error messages.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
plugin_name
required
string

The unique name of the connector plugin.

environment_id
required
string

The unique identifier of the environment this resource belongs to.

kafka_cluster_id
required
string

The unique identifier for the Kafka cluster.

Request Body schema: application/json

Configuration parameters for the connector. All values should be strings.

property name*
additional property
string

Other configuration parameters for the connector. All values should be strings. See the connector's docs for the list of options.

Responses

Request samples

Content type
application/json
{
  • "cloud.environment": "prod",
  • "cloud.provider": "aws",
  • "connector.class": "GcsSink",
  • "data.format": "BYTES",
  • "flush.size": "500",
  • "gcs.bucket.name": "APILogsBucket",
  • "gcs.credentials.config": "****************",
  • "kafka.api.key": "****************",
  • "kafka.api.secret": "****************",
  • "kafka.endpoint": "SASL_SSL://pkc-xxxxx.us-west-2.aws.confluent.cloud:9092",
  • "kafka.region": "us-west-2",
  • "name": "MyGcsLogsBucketConnector",
  • "tasks.max": "2",
  • "time.interval": "DAILY",
  • "topics": "APILogsTopic"
}

Response samples

Content type
application/json
{
  • "name": "io.confluent.connect.gcs.GcsSinkConnector",
  • "groups": [
    ],
  • "error_count": 1,
  • "configs": [
    ]
}

Custom Connector Plugins (connect/v1)

General Availability

CustomConnectorPlugins objects represent Custom Connector Plugins on Confluent Cloud. The API allows you to list, create, read, update, and delete your Custom Connector Plugins. Related guide: Custom Connector Plugin API.

The Custom Connector Plugins Model

api_version
string
Value: "connect/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "CustomConnectorPlugin"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string <= 60 characters

Display name of Custom Connector Plugin.

content_format
string
extensible-enum: ["ZIP","JAR"]

Archive format of Custom Connector Plugin.

description
string <= 256 characters

Description of Custom Connector Plugin.

documentation_link
string <= 512 characters ^$|^(http://|https://).+

Document link of Custom Connector Plugin.

connector_class
string <= 150 characters ^(([a-zA-Z][a-zA-Z_$0-9]*(\.[a-zA-Z][a-zA-Z_$...

Java class or alias for connector. You can get connector class from connector documentation provided by developer.

connector_type
string
extensible-enum: ["SOURCE","SINK"]

Custom Connector type.

sensitive_config_properties
Array of strings[ items <= 150 characters ^[\w\+\.-]+$ ]

A sensitive property is a connector configuration property that must be hidden after a user enters property value when setting up connector.

object

[immutable] Upload source of Custom Connector Plugin. Only required in create request, will be ignored in read, update or list.

{
  • "api_version": "connect/v1",
  • "kind": "CustomConnectorPlugin",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "string",
  • "content_format": "ZIP",
  • "description": "string",
  • "connector_class": "io.confluent.kafka.connect.datagen.DatagenConnector",
  • "connector_type": "SOURCE",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

List of Custom Connector Plugins

General Availability

Retrieve a sorted, filtered, paginated list of all custom connector plugins.

Authorizations:
cloud-api-key
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/connect/v1/custom-connector-plugins \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Custom Connector Plugin

General Availability

Make a request to create a custom connector plugin.

Authorizations:
cloud-api-key
Request Body schema: application/json
display_name
required
string <= 60 characters

Display name of Custom Connector Plugin.

description
string <= 256 characters

Description of Custom Connector Plugin.

documentation_link
string <= 512 characters ^$|^(http://|https://).+

Document link of Custom Connector Plugin.

connector_class
required
string <= 150 characters ^(([a-zA-Z][a-zA-Z_$0-9]*(\.[a-zA-Z][a-zA-Z_$...

Java class or alias for connector. You can get connector class from connector documentation provided by developer.

connector_type
required
string
extensible-enum: ["SOURCE","SINK"]

Custom Connector type.

sensitive_config_properties
Array of strings[ items <= 150 characters ^[\w\+\.-]+$ ]

A sensitive property is a connector configuration property that must be hidden after a user enters property value when setting up connector.

required
object

[immutable] Upload source of Custom Connector Plugin. Only required in create request, will be ignored in read, update or list.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "description": "string",
  • "connector_class": "io.confluent.kafka.connect.datagen.DatagenConnector",
  • "connector_type": "SOURCE",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "connect/v1",
  • "kind": "CustomConnectorPlugin",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "string",
  • "content_format": "ZIP",
  • "description": "string",
  • "connector_class": "io.confluent.kafka.connect.datagen.DatagenConnector",
  • "connector_type": "SOURCE",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

Read a Custom Connector Plugin

General Availability

Make a request to read a custom connector plugin.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the custom connector plugin.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/connect/v1/custom-connector-plugins/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "connect/v1",
  • "kind": "CustomConnectorPlugin",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "string",
  • "content_format": "ZIP",
  • "description": "string",
  • "connector_class": "io.confluent.kafka.connect.datagen.DatagenConnector",
  • "connector_type": "SOURCE",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

Update a Custom Connector Plugin

General Availability

Make a request to update a custom connector plugin.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the custom connector plugin.

Request Body schema: application/json
display_name
string <= 60 characters

Display name of Custom Connector Plugin.

description
string <= 256 characters

Description of Custom Connector Plugin.

documentation_link
string <= 512 characters ^$|^(http://|https://).+

Document link of Custom Connector Plugin.

sensitive_config_properties
Array of strings[ items <= 150 characters ^[\w\+\.-]+$ ]

A sensitive property is a connector configuration property that must be hidden after a user enters property value when setting up connector.

object

[immutable] Upload source of Custom Connector Plugin. Only required in create request, will be ignored in read, update or list.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "description": "string",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "connect/v1",
  • "kind": "CustomConnectorPlugin",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "display_name": "string",
  • "content_format": "ZIP",
  • "description": "string",
  • "connector_class": "io.confluent.kafka.connect.datagen.DatagenConnector",
  • "connector_type": "SOURCE",
  • "sensitive_config_properties": [
    ],
  • "upload_source": {
    }
}

Delete a Custom Connector Plugin

General Availability

Make a request to delete a custom connector plugin.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the custom connector plugin.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/connect/v1/custom-connector-plugins/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Presigned Urls (connect/v1)

General Availability

Request a presigned upload URL for new Custom Connector Plugin. Note that the URL policy expires in one hour. If the policy expires, you can request a new presigned upload URL.

Related guide: Custom Connector Plugin API.

The Presigned Urls Model

api_version
string
Value: "connect/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "PresignedUrl"

Kind defines the object this REST resource represents.

content_format
string
extensible-enum: ["ZIP","JAR"]

Content format of the Custom Connector Plugin archive.

upload_id
string

Unique identifier of this upload.

upload_url
string <uri>

Upload URL for the Custom Connector Plugin archive.

upload_form_data
object

Upload form data of the Custom Connector Plugin. All values should be strings.

{
  • "api_version": "connect/v1",
  • "kind": "PresignedUrl",
  • "content_format": "ZIP",
  • "upload_id": "e53bb2e8-8de3-49fa-9fb1-4e3fd9a16b66",
  • "upload_form_data": {
    }
}

Request a presigned upload URL for a new Custom Connector Plugin.

General Availability

Request a presigned upload URL to upload a Custom Connector Plugin archive.

Authorizations:
cloud-api-key
Request Body schema: application/json
content_format
required
string
extensible-enum: ["JAR","ZIP"]

Archive format of the Custom Connector Plugin.

Responses

Request samples

Content type
application/json
{
  • "content_format": "ZIP"
}

Response samples

Content type
application/json
{
  • "api_version": "connect/v1",
  • "kind": "PresignedUrl",
  • "content_format": "ZIP",
  • "upload_id": "e53bb2e8-8de3-49fa-9fb1-4e3fd9a16b66",
  • "upload_form_data": {
    }
}

Cluster (v3)

Generally Available

Get Cluster

Generally Available

Return the Kafka cluster with the specified cluster_id.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Configs (v3)

Generally Available

List Dynamic Broker Configs

Generally Available

Return a list of dynamic cluster-wide broker configuration parameters for the specified Kafka cluster. Returns an empty list if there are no dynamic cluster-wide broker configuration parameters.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Batch Alter Dynamic Broker Configs

Generally Available

Update or delete a set of dynamic cluster-wide broker configuration parameters.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Request Body schema: application/json

The alter cluster configuration parameter batch request.

required
Array of objects
validate_only
boolean

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Get Dynamic Broker Config

Generally Available

Return the dynamic cluster-wide broker configuration parameter specified by name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

name
required
string
Example: compression.type

The configuration parameter name.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs/compression.type \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "kind": "KafkaClusterConfig",
  • "metadata": {},
  • "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": [
    ]
}

Update Dynamic Broker Config

Generally Available

Update the dynamic cluster-wide broker configuration parameter specified by name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

name
required
string
Example: compression.type

The configuration parameter name.

Request Body schema: application/json

The cluster configuration parameter update request.

value
string or null

Responses

Request samples

Content type
application/json
{
  • "value": "gzip"
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Reset Dynamic Broker Config

Generally Available

Reset the configuration parameter specified by name to its default value by deleting a dynamic cluster-wide configuration.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

name
required
string
Example: compression.type

The configuration parameter name.

Responses

Request samples

curl --request DELETE \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/broker-configs/compression.type \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

List Topic Configs

Generally Available

Return the list of configuration parameters that belong to the specified topic.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Batch Alter Topic Configs

Generally Available

Update or delete a set of topic configuration parameters. Also supports a dry-run mode that only validates whether the operation would succeed if the validate_only request property is explicitly specified and set to true.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Request Body schema: application/json

The alter topic configuration parameter batch request.

required
Array of objects
validate_only
boolean

Responses

Request samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Get Topic Config

Generally Available

Return the configuration parameter with the given name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

name
required
string
Example: compression.type

The configuration parameter name.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/compression.type \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "kind": "KafkaTopicConfig",
  • "metadata": {},
  • "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": [
    ]
}

Update Topic Config

Generally Available

Update the configuration parameter with given name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

name
required
string
Example: compression.type

The configuration parameter name.

Request Body schema: application/json

The topic configuration parameter update request.

value
string or null

Responses

Request samples

Content type
application/json
{
  • "value": "gzip"
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Reset Topic Config

Generally Available

Reset the configuration parameter with given name to its default value.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

name
required
string
Example: compression.type

The configuration parameter name.

Responses

Request samples

curl --request DELETE \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/configs/compression.type \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

List All Topic Configs

Generally Available

Return the list of configuration parameters for all topics hosted by the specified cluster.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/-/configs \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

List New Topic Default Configs

Generally Available

List the default configuration parameters used if the topic were to be newly created.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/default-configs \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

ACL (v3)

Generally Available

Batch Create ACLs

Generally Available

Create ACLs.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Request Body schema: application/json

The batch ACL creation request.

required
Array of objects (CreateAclRequestData)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json

Thrown when creating an ACL for a CLUSTER resource specifying the wrong resource name.

{
  • "error_code": 40002,
  • "message": "The only valid name for the CLUSTER resource is kafka-cluster\""
}

List ACLs

Generally Available

Return a list of ACLs that match the search criteria.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

query Parameters
resource_type
string (AclResourceType)
Enum: "UNKNOWN" "ANY" "TOPIC" "GROUP" "CLUSTER" "TRANSACTIONAL_ID" "DELEGATION_TOKEN"

The ACL resource type.

resource_name
string

The ACL resource name.

pattern_type
string (AclPatternType)
extensible-enum: ["UNKNOWN","ANY","MATCH","LITERAL","PREFIXED"]

The ACL pattern type.

principal
string

The ACL principal. This is the Service Account name or user name.

host
string

The ACL host.

operation
string (AclOperation)
extensible-enum: ["UNKNOWN","ANY","ALL","READ","WRITE","CREATE","DELETE","ALTER","DESCRIBE","CLUSTER_ACTION","DESCRIBE_CONFIGS","ALTER_CONFIGS","IDEMPOTENT_WRITE"]

The ACL operation.

permission
string (AclPermission)
extensible-enum: ["UNKNOWN","ANY","DENY","ALLOW"]

The ACL permission.

Responses

Request samples

curl --request GET \
  --url 'https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=SOME_STRING_VALUE&pattern_type=SOME_STRING_VALUE&operation=SOME_STRING_VALUE&permission=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an ACL

Generally Available

Create an ACL.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Request Body schema: application/json

The ACL creation request.

resource_type
required
string (AclResourceType)
Enum: "UNKNOWN" "ANY" "TOPIC" "GROUP" "CLUSTER" "TRANSACTIONAL_ID" "DELEGATION_TOKEN"
resource_name
required
string
pattern_type
required
string (AclPatternType)
extensible-enum: ["UNKNOWN","ANY","MATCH","LITERAL","PREFIXED"]
principal
required
string
host
required
string
operation
required
string (AclOperation)
extensible-enum: ["UNKNOWN","ANY","ALL","READ","WRITE","CREATE","DELETE","ALTER","DESCRIBE","CLUSTER_ACTION","DESCRIBE_CONFIGS","ALTER_CONFIGS","IDEMPOTENT_WRITE"]
permission
required
string (AclPermission)
extensible-enum: ["UNKNOWN","ANY","DENY","ALLOW"]

Responses

Request samples

Content type
application/json
{
  • "resource_type": "CLUSTER",
  • "resource_name": "kafka-cluster",
  • "pattern_type": "LITERAL",
  • "principal": "principalType:principalName",
  • "host": "*",
  • "operation": "DESCRIBE",
  • "permission": "DENY"
}

Response samples

Content type
application/json

Thrown when creating an ACL for a CLUSTER resource specifying the wrong resource name.

{
  • "error_code": 40002,
  • "message": "The only valid name for the CLUSTER resource is kafka-cluster\""
}

Delete ACLs

Generally Available

Delete the ACLs that match the search criteria.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

query Parameters
resource_type
required
string (AclResourceType)
Enum: "UNKNOWN" "ANY" "TOPIC" "GROUP" "CLUSTER" "TRANSACTIONAL_ID" "DELEGATION_TOKEN"

The ACL resource type.

resource_name
string

The ACL resource name.

pattern_type
required
string (AclPatternType)
extensible-enum: ["UNKNOWN","ANY","MATCH","LITERAL","PREFIXED"]

The ACL pattern type.

principal
string

The ACL principal. This is the Service Account name or user name.

host
string

The ACL host.

operation
required
string (AclOperation)
extensible-enum: ["UNKNOWN","ANY","ALL","READ","WRITE","CREATE","DELETE","ALTER","DESCRIBE","CLUSTER_ACTION","DESCRIBE_CONFIGS","ALTER_CONFIGS","IDEMPOTENT_WRITE"]

The ACL operation.

permission
required
string (AclPermission)
extensible-enum: ["UNKNOWN","ANY","DENY","ALLOW"]

The ACL permission.

Responses

Request samples

curl --request DELETE \
  --url 'https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/acls?resource_type=SOME_STRING_VALUE&pattern_type=SOME_STRING_VALUE&operation=SOME_STRING_VALUE&permission=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Consumer Group (v3)

Generally Available

List Consumer Groups

Generally Available

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

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Get Consumer Group

Generally Available

Return the consumer group specified by the consumer_group_id.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

List Consumers

Generally Available

Return a list of consumers that belong to the specified consumer group.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Get Consumer Group Lag Summary

Generally Available Available in dedicated clusters only

Return the maximum and total lag of the consumers belonging to the specified consumer group.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lag-summary \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

List Consumer Lags

Generally Available Available in dedicated clusters only

Return a list of consumer lags of the consumers belonging to the specified consumer group.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Get Consumer Lag

Generally Available Available in dedicated clusters only

Return the consumer lag on a partition with the given partition_id.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

topic_name
required
string
Example: topic-1

The topic name.

partition_id
required
integer

The partition ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/lags/topic-1/partitions/0 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Get Consumer

Generally Available

Return the consumer specified by the consumer_id.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

consumer_group_id
required
string
Example: consumer-group-1

The consumer group ID.

consumer_id
required
string
Example: consumer-1

The consumer ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/consumer-groups/consumer-group-1/consumers/consumer-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Partition (v3)

Generally Available

List Partitions

Generally Available

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

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Get Partition

Generally Available

Return the partition with the given partition_id.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

partition_id
required
integer

The partition ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1/partitions/0 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json

Topic (v3)

Generally Available

List Topics

Generally Available

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

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create Topic

Generally Available

Create a topic. Also supports a dry-run mode that only validates whether the topic creation would succeed if the validate_only request property is explicitly specified and set to true. Note that when dry-run mode is being used the response status would be 200 OK instead of 201 Created.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

Request Body schema: application/json

The topic creation request. Note that Confluent Cloud allows only specific replication factor values. Because of that the replication factor field should either be omitted or it should use one of the allowed values (see https://docs.confluent.io/cloud/current/client-apps/optimizing/durability.html).

topic_name
required
string
partitions_count
integer
replication_factor
integer
Array of objects
validate_only
boolean

Responses

Request samples

Content type
application/json
Example
{
  • "topic_name": "topic-X",
  • "partitions_count": 64,
  • "replication_factor": 3,
  • "configs": [
    ]
}

Response samples

Content type
application/json
{}

Get Topic

Generally Available

Return the topic with the given topic_name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

query Parameters
include_authorized_operations
boolean

Specify if authorized operations should be included in the response.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update Partition Count

Generally Available

Increase the number of partitions for a topic.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Request Body schema: application/json
partitions_count
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "partitions_count": 0
}

Response samples

Content type
application/json
{}

Delete Topic

Generally Available

Delete the topic with the given topic_name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Responses

Request samples

curl --request DELETE \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/topics/topic-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Records (v3)

Generally Available

Produce Records

Generally Available

Produce records to the given topic, returning delivery reports for each record produced. This API can be used in streaming mode by setting "Transfer-Encoding: chunked" header. For as long as the connection is kept open, the server will keep accepting records. Records are streamed to and from the server as Concatenated JSON. For each record sent to the server, the server will asynchronously send back a delivery report, in the same order, each with its own error_code. An error_code of 200 indicates success. The HTTP status code will be HTTP 200 OK as long as the connection is successfully established. To identify records that have encountered an error, check the error_code of each delivery report.

Note that the cluster_id is validated only when running in Confluent Cloud.

This API currently does not support Schema Registry integration. Sending schemas is not supported. Only BINARY, JSON, and STRING formats are supported.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

topic_name
required
string
Example: topic-1

The topic name.

Request Body schema: application/json

A single record to be produced to Kafka. To produce multiple records in the same request, simply concatenate the records. The delivery reports are concatenated in the same order as the records are sent.

partition_id
integer or null <int32>
Array of objects (ProduceRequestHeader)
object or null (ProduceRequestData)
object or null (ProduceRequestData)
timestamp
string or null <date-time>

Responses

Request samples

Content type
application/json
Example

If using type, one of "BINARY", "JSON" or "STRING" is required.

{
  • "partition_id": 1,
  • "headers": [
    ],
  • "key": {
    },
  • "value": {
    },
  • "timestamp": "2021-02-05T19:14:42Z"
}

Response samples

Content type
application/json
Example

The record was successfully produced to the topic.

{
  • "error_code": 200,
  • "cluster_id": "cluster-1",
  • "topic_name": "topic-1",
  • "partition_id": 1,
  • "offset": 0,
  • "timestamp": "2021-02-05T19:14:42Z",
  • "key": {
    },
  • "value": {
    }
}

Cluster Linking (v3)

Generally Available

List all configs of the cluster link

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-sb1/configs \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Describe the config under the cluster link

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

config_name
required
string
Example: consumer.offset.sync.enable

The link config name

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-sb1/configs/consumer.offset.sync.enable \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Alter the config under the cluster link

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

config_name
required
string
Example: consumer.offset.sync.enable

The link config name

Request Body schema: application/json

Link config value to update

value
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "300000"
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Reset the given config to default value

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

config_name
required
string
Example: consumer.offset.sync.enable

The link config name

Responses

Request samples

curl --request DELETE \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-sb1/configs/consumer.offset.sync.enable \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Batch Alter Cluster Link Configs

Generally Available

Batch Alter Cluster Link Configs

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json
required
Array of objects
validate_only
boolean

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

Create a mirror topic

Generally Available

Create a topic in the destination cluster mirroring a topic in the source cluster

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

Request Body schema: application/json

Name and configs of the topics mirroring from and mirroring to. Note that Confluent Cloud allows only specific replication factor values. Because of that the replication factor field should either be omitted or it should use one of the allowed values (see https://docs.confluent.io/cloud/current/client-apps/optimizing/durability.html).

source_topic_name
required
string
mirror_topic_name
string
replication_factor
integer
Array of objects (ConfigData)

Responses

Request samples

Content type
application/json
Example

Generic example of creating a mirror topic

{
  • "source_topic_name": "topic-1",
  • "configs": [
    ],
  • "replication_factor": 1
}

Response samples

Content type
application/json
Example

Thrown when trying to deserialize an integer from non-integer data.

{
  • "error_code": 400,
  • "message": "Cannot deserialize value of type `java.lang.Integer` from String \"A\": not a valid `java.lang.Integer` value"
}

List mirror topics

Generally Available

List all mirror topics in the cluster

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

query Parameters
mirror_status
string (MirrorTopicStatus)
Enum: "ACTIVE" "FAILED" "LINK_FAILED" "LINK_PAUSED" "PAUSED" "PENDING_STOPPED" "SOURCE_UNAVAILABLE" "STOPPED" "PENDING_MIRROR" "PENDING_SYNCHRONIZE"
Example: mirror_status=ACTIVE

The status of the mirror topic. If not specified, all mirror topics will be returned.

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/-/mirrors \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Describe the mirror topic

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

mirror_topic_name
required
string
Example: topic-1

Cluster Linking mirror topic name

query Parameters
include_state_transition_errors
boolean

Whether to include mirror state transition errors in the response. Default: false

Responses

Request samples

curl --request GET \
  --url https://pkc-00000.region.provider.confluent.cloud/kafka/v3/clusters/cluster-1/links/link-sb1/mirrors/topic-1 \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "kind": "KafkaMirrorData",
  • "link_name": "link-sb-1",
  • "mirror_topic_name": "topic-1",
  • "source_topic_name": "topic-1",
  • "num_partitions": 3,
  • "mirror_lags": [
    ],
  • "mirror_status": "ACTIVE",
  • "state_time_ms": 1612550939300
}

Promote the mirror topics

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Failover the mirror topics

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Pause the mirror topics

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Resume the mirror topics

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Reverse the local mirror topic and start the remote mirror topic

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Reverse the local mirror topic and Pause the remote mirror topic

Generally Available

Authorizations:
resource-api-keyexternal-access-token
path Parameters
cluster_id
required
string
Example: cluster-1

The Kafka cluster ID.

link_name
required
string
Example: link-sb1

The link name

query Parameters
validate_only
boolean

To validate the action can be performed successfully or not. Default: false

Request Body schema: application/json

Mirror topics to be altered.

mirror_topic_names
Array of strings

The mirror topics specified as a list of topic names.

mirror_topic_name_pattern
string

The mirror topics specified as a pattern.

Responses

Request samples

Content type
application/json
Example

Example using mirror topic names

{
  • "mirror_topic_names": [
    ]
}

Response samples

Content type
application/json
{}

Applied Quotas (service-quota/v1)

General Availability

A quota object represents a quota configuration for a specific Confluent Cloud resource. Use this API to retrieve an individual quota or list of quotas for a given scope.

Related guide: Service Quotas for Confluent Cloud.

The Applied Quotas Model

api_version
string
Value: "service-quota/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "AppliedQuota"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

scope
string
extensible-enum: ["ORGANIZATION","ENVIRONMENT","NETWORK","KAFKA_CLUSTER","SERVICE_ACCOUNT","USER_ACCOUNT"]

The applied scope that this quota belongs to.

display_name
string

A human-readable name for the quota type name.

default_limit
integer <int32>

The default service quota value.

applied_limit
integer <int32>

The latest applied service quota value, taking into account any limit adjustments.

usage
integer <int32>

Show the quota usage value if the quota usage is available for this quota.

object

The user associated with this object.

object or null

A unique organization id to associate a specific organization to this quota.

object or null

The environment ID the quota is associated with.

object or null

The network ID the quota is associated with.

object or null

The kafka cluster ID the quota is associated with.

{}

List of Applied Quotas

General Availability

Retrieve a sorted, filtered, paginated list of all applied quotas.

Shows all quotas for a given scope.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
scope
required
string (SearchFilter)
Example: scope=ORGANIZATION

The applied scope the quota belongs to.

environment
string (SearchFilter)
Example: environment=env-00000

The environment ID the quota is associated with.

network
string (SearchFilter)
Example: network=n-12034

The network ID the quota is associated with.

kafka_cluster
string (SearchFilter)
Example: kafka_cluster=lkc-00000

The kafka cluster ID the quota is associated with.

id
string (SearchFilter)
Example: id=iam.max_environments.per_org

The id (quota code) that this quota belongs to.

page_size
integer <= 200
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/service-quota/v1/applied-quotas?scope=ORGANIZATION&environment=env-00000&network=n-12034&kafka_cluster=lkc-00000&id=iam.max_environments.per_org' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read an Applied Quota

General Availability

Make a request to read an applied quota.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the applied quota.

query Parameters
environment
string (SearchFilter)
Example: environment=env-00000

The environment ID the quota is associated with. This field is only required when retrieving a single quota and the scope of quota is "ENVIRONMENT" or "NETWORK" or "KAFKA_CLUSTER".

network
string (SearchFilter)
Example: network=n-12034

The network ID the quota is associated with. This field is only required when retrieving a single quota and the scope of quota is "NETWORK".

kafka_cluster
string (SearchFilter)
Example: kafka_cluster=lkc-00000

The kafka cluster ID the quota is associated with. This field is required only when the scope of quota is "KAFKA_CLUSTER".

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/service-quota/v1/applied-quotas/{id}?environment=env-00000&network=n-12034&kafka_cluster=lkc-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Scopes (service-quota/v1)

General Availability

Gets a list of all available scopes for applied quotas.

Related guide: Quota Scopes.

The Scopes Model

api_version
string
Value: "service-quota/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Scope"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

description
string

the quota scope for listing quotas queries

{
  • "api_version": "service-quota/v1",
  • "kind": "Scope",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "description": "ORGANIZATION scope that quotas would be applied to"
}

List of Scopes

General Availability

Retrieve a sorted, filtered, paginated list of all scopes.

Authorizations:
cloud-api-key
query Parameters
page_size
integer <= 200
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/service-quota/v1/scopes \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Scope

General Availability

Make a request to read a scope.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the scope.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/service-quota/v1/scopes/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "service-quota/v1",
  • "kind": "Scope",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "description": "ORGANIZATION scope that quotas would be applied to"
}

Entitlements (partner/v2)

Early Access Request Access To Partner v2

Entitlement objects represent metadata about a marketplace entitlement.

An entitlement includes metadata about a marketplace purchase (start date, end date, billing information, partner IDs, etc). The API allows partners to create, read, and list entitlements. (Unless you need entitlement creation and customer registration to be separate, we recommend using the Signup API to create an organization and entitlement at the same time)

The API only allows authorized partners to interact with the Entitlements API.

List of Entitlements

Early Access Request Access To Partner v2

Retrieve a sorted, filtered, paginated list of all entitlements.

Authorizations:
oauth
query Parameters
organization.id
string (SearchFilter)
Example: organization.id=b3a17773-05cc-4431-9560-433fb4613da8

Filter the results by exact match for organization.id.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/partner/v2/entitlements?organization.id=SOME_STRING_VALUE&page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

Create an Entitlement

Early Access Request Access To Partner v2

Make a request to create an entitlement.

Authorizations:
oauth
Request Body schema: application/json
external_id
required
string

The unique external ID of the entitlement (this should be unique to customer)

name
required
string

The name of the entitlement

plan_id
required
string
extensible-enum: ["confluent-cloud-payg-prod","payg-prod.gcpmarketplace.confluent.cloud"]

The plan ID the entitlement

product_id
required
string
extensible-enum: ["confluent-cloud-kafka-service-azure","confluent-cloud-for-apache-kafka","payg-prod.gcpmarketplace.confluent.cloud"]

The product ID of the entitlement

usage_reporting_id
string

The usage reporting ID of the entitlement (if usage reporting uses a different ID, otherwise, same as external_id)

resource_id
string

The resource ID of the entitlement

object

The organization associated with this object.

Responses

Request samples

Content type
application/json
{
  • "external_id": "1111-2222-3333-4444",
  • "name": "Acme Prod Entitlement",
  • "plan_id": "confluent-cloud-payg-prod",
  • "product_id": "confluent-cloud-kafka-service-azure",
  • "usage_reporting_id": "1111-2222-3333-4444",
  • "resource_id": "1111-2222-3333-4444",
  • "organization": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "partner/v2",
  • "kind": "Entitlement",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "external_id": "1111-2222-3333-4444",
  • "name": "Acme Prod Entitlement",
  • "plan_id": "confluent-cloud-payg-prod",
  • "product_id": "confluent-cloud-kafka-service-azure",
  • "usage_reporting_id": "1111-2222-3333-4444",
  • "resource_id": "1111-2222-3333-4444",
  • "organization": {}
}

Read an Entitlement

Early Access Request Access To Partner v2

Make a request to read an entitlement.

Authorizations:
oauth
path Parameters
id
required
string

The unique identifier for the entitlement.

query Parameters
organization.id
string (SearchFilter)
Example: organization.id=b3a17773-05cc-4431-9560-433fb4613da8

Scope the operation to the given organization.id.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/partner/v2/entitlements/{id}?organization.id=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "api_version": "partner/v2",
  • "kind": "Entitlement",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "external_id": "1111-2222-3333-4444",
  • "name": "Acme Prod Entitlement",
  • "plan_id": "confluent-cloud-payg-prod",
  • "product_id": "confluent-cloud-kafka-service-azure",
  • "usage_reporting_id": "1111-2222-3333-4444",
  • "resource_id": "1111-2222-3333-4444",
  • "organization": {}
}

Organizations (partner/v2)

Early Access Request Access To Partner v2

Organizations objects represent an entire Confluent Cloud organization. Partners are allowed to get an organization they have signed up or list all organizations they have signed up.

Read an Organization

Early Access Request Access To Partner v2

Make a request to read an organization.

Authorizations:
oauth
path Parameters
id
required
string

The unique identifier for the organization.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/partner/v2/organizations/{id}' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

List of Organizations

Early Access Request Access To Partner v2

Retrieve a sorted, filtered, paginated list of all organizations.

Authorizations:
oauth
query Parameters
page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/partner/v2/organizations?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

Signup (partner/v2)

Early Access Request Access To Partner v2

Signup APIs can only be performed by partners.

Signup an Organization on behalf of a Customer

Early Access Request Access To Partner v2

Create an organization for a customer. You must pass in either an entitlement object reference (a url to a previously created entitlement) or entitlement details. If you pass in an entitlement object reference, we will link with the created entitlement. If you pass in the entitlement details, we will create the entitlement with the organization in a single transaction. If you pass in user details (email, given name, and family name), we will create a user as well. If you do not pass in user details, you MUST call /partner/v2/signup/activate with user details to complete signup.

Authorizations:
oauth
query Parameters
dry_run
boolean

If true, only perform validation of signup

Request Body schema: application/json

A JSON object containing signup information

required
object

Organizations objects represent an entire Confluent Cloud organization.

user
object
required
object or object

Responses

Request samples

Content type
application/json
{
  • "organization": {
    },
  • "user": { },
  • "entitlement": {
    }
}

Response samples

Content type
application/json
{
  • "organization_id": "b3a17773-05cc-4431-9560-433fb4613da8",
  • "display_message": "Your support plan will remain the same, to change the plan, follow this [link](https://docs.confluent.io/cloud/current/faq.html#how-do-i-change-support-plans)."
}

Activate an Incomplete Signup

Early Access Request Access To Partner v2

Creates a user in the organization previously created in /partner/v2/signup. This completes the signup process if you did not pass in user details to /partner/v2/signup. Calling this endpoint if the signup process has been completed will result in a 409 Conflict error.

Authorizations:
oauth
Request Body schema: application/json

A JSON object containing signup information

user
required
object
organization_id
required
string

The ID of the organization

Responses

Request samples

Content type
application/json
{
  • "user": { },
  • "organization_id": "b3a17773-05cc-4431-9560-433fb4613da8"
}

Response samples

Content type
application/json
{
  • "organization_id": "b3a17773-05cc-4431-9560-433fb4613da8",
  • "display_message": "Your support plan will remain the same, to change the plan, follow this [link](https://docs.confluent.io/cloud/current/faq.html#how-do-i-change-support-plans)."
}

Regions (srcm/v2)

General Availability

Region objects represent cloud provider regions available when placing Schema Registry clusters. The API allows you to list Schema Registry regions.

Related guide: Confluent Cloud Schema Registry Regions.

The Regions Model

api_version
string
Value: "srcm/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Region"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (srcm.v2.RegionSpec)

The desired state of the Region

{
  • "api_version": "srcm/v2",
  • "kind": "Region",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    }
}

List of Regions

General Availability

Retrieve a sorted, filtered, paginated list of all regions.

Authorizations:
cloud-api-key
query Parameters
spec.cloud
string (SearchFilter)
Example: spec.cloud=AWS

Filter the results by exact match for spec.cloud.

spec.region_name
string (SearchFilter)
Example: spec.region_name=us-east-2

Filter the results by exact match for spec.region_name.

spec.packages
Array of strings (MultipleSearchFilter)
Example: spec.packages=ESSENTIALS&spec.packages=ADVANCED

Filter the results by exact match for spec.packages. Pass multiple times to see results matching any of the values.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v2/regions?spec.cloud=AWS&spec.region_name=us-east-2&spec.packages=ESSENTIALS,ADVANCED' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Region

General Availability

Make a request to read a region.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the region.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v2/regions/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "srcm/v2",
  • "kind": "Region",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    }
}

Clusters (srcm/v2)

General Availability

Clusters objects represent Schema Registry Clusters on Confluent Cloud.

The API allows you to list, create, read, and delete your Schema Registry clusters.

Related guide: Confluent Cloud Schema Registry Cluster APIs.

The Clusters Model

api_version
string
Value: "srcm/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Cluster"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (srcm.v2.ClusterSpec)

The desired state of the Cluster

object (srcm.v2.ClusterStatus)

The status of the Cluster

{}

List of Clusters

General Availability

Retrieve a sorted, filtered, paginated list of all clusters.

Authorizations:
cloud-api-key
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v2/clusters?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Cluster

General Availability

Make a request to create a cluster.

Authorizations:
cloud-api-key
Request Body schema: application/json
required
object

The desired state of the Cluster

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Cluster

General Availability

Make a request to read a cluster.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Cluster

General Availability

Make a request to update a cluster.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the cluster.

Request Body schema: application/json
required
object

The desired state of the Cluster

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Cluster

General Availability

Make a request to delete a cluster.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/srcm/v2/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Clusters (srcm/v3)

General Availability

Clusters objects represent Schema Registry Clusters on Confluent Cloud.

The API allows you to list and read your Schema Registry clusters.

Related guide: Confluent Cloud Schema Registry Cluster APIs.

The Clusters Model

api_version
string
Value: "srcm/v3"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Cluster"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (srcm.v3.ClusterSpec)

The desired state of the Cluster

object (srcm.v3.ClusterStatus)

The status of the Cluster

{
  • "api_version": "srcm/v3",
  • "kind": "Cluster",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {},
  • "status": {
    }
}

List of Clusters

General Availability

Retrieve a sorted, filtered, paginated list of all clusters.

Authorizations:
cloud-api-key
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v3/clusters?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Cluster

General Availability

Make a request to read a cluster.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the cluster.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/srcm/v3/clusters/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Compatibility (v1)

Generally Available

The API allows you to test schema compatibility.

Related guide: Manage Schemas in Confluent Cloud.

Test schema compatibility against a particular schema subject-version

Test input schema against a particular version of a subject's schema for compatibility. The compatibility level applied for the check is the configured compatibility level for the subject (http:get:: /config/(string: subject)). If this subject's compatibility level was never changed, then the global compatibility level applies (http:get:: /config).

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Subject of the schema version against which compatibility is to be tested

version
required
string

Version of the subject's schema against which compatibility is to be tested. Valid values for versionId are between [1,2^31-1] or the string "latest"."latest" checks compatibility of the input schema with the last registered schema under the specified subject

query Parameters
verbose
boolean

Whether to return detailed error messages

Request Body schema:

Schema

version
integer <int32>

Version number

id
integer <int32>

Globally unique identifier of the schema

schemaType
string

Schema type

Array of objects (SchemaReference)

References to other schemas

schema
string

Schema definition string

Responses

Request samples

Content type
{
  • "version": 0,
  • "id": 0,
  • "schemaType": "string",
  • "references": [
    ],
  • "schema": "string"
}

Response samples

Content type
{
  • "is_compatible": true,
  • "messages": [ ]
}

Test schema compatibility against all schemas under a subject

Test input schema against a subject's schemas for compatibility, based on the configured compatibility level of the subject. In other words, it will perform the same compatibility check as register for that subject. The compatibility level applied for the check is the configured compatibility level for the subject (http:get:: /config/(string: subject)). If this subject's compatibility level was never changed, then the global compatibility level applies (http:get:: /config).

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Subject of the schema version against which compatibility is to be tested

query Parameters
verbose
boolean

Whether to return detailed error messages

Request Body schema:

Schema

version
integer <int32>

Version number

id
integer <int32>

Globally unique identifier of the schema

schemaType
string

Schema type

Array of objects (SchemaReference)

References to other schemas

schema
string

Schema definition string

Responses

Request samples

Content type
{
  • "version": 0,
  • "id": 0,
  • "schemaType": "string",
  • "references": [
    ],
  • "schema": "string"
}

Response samples

Content type
{
  • "is_compatible": true,
  • "messages": [ ]
}

Config (v1)

Generally Available

The API allows you to manage and query schema compatibility settings and cluster configurations.

Related guide: Manage Schemas in Confluent Cloud.

Get cluster config

Retrieves cluster config information.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/clusterconfig \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "maxSchemas": 20000,
  • "maxRequestsPerSec": 25
}

Get subject compatibility level

Retrieves compatibility level, compatibility group, normalization, default metadata, and rule set for a subject.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
defaultToGlobal
boolean

Whether to return the global compatibility level if subject compatibility level not found

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/config/{subject}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibilityLevel": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Update subject compatibility level

Update compatibility level, compatibility group, normalization, default metadata, and rule set for the specified subject. On success, echoes the original request back to the client.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

Request Body schema:

Config Update Request

alias
string

If alias is specified, then this subject is an alias for the subject named by the alias. That means that any reference to this subject will be replaced by the alias.

normalize
boolean

If true, then schemas are automatically normalized when registered or when passed during lookups. This means that clients do not have to pass the "normalize" query parameter to have normalization occur.

compatibility
string
extensible-enum: ["BACKWARD","BACKWARD_TRANSITIVE","FORWARD","FORWARD_TRANSITIVE","FULL","FULL_TRANSITIVE","NONE"]

Compatibility Level

compatibilityGroup
string

Only schemas that belong to the same compatibility group will be checked for compatibility.

object

Default value for the metadata to be used during schema registration.

object

Override value for the metadata to be used during schema registration.

object

Default value for the ruleSet to be used during schema registration.

object

Override value for the ruleSet to be used during schema registration.

Responses

Request samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibility": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Response samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibility": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Delete subject compatibility level

Deletes the specified subject-level compatibility level config and reverts to the global default.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/config/{subject}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
"FULL_TRANSITIVE"

Get global compatibility level

Retrieves the global compatibility level, compatibility group, normalization, default metadata, and rule set.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/config \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibilityLevel": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Update global compatibility level

Updates the global compatibility level, compatibility group, schema normalization, default metadata, and rule set. On success, echoes the original request back to the client.

Authorizations:
resource-api-keyexternal-access-token
Request Body schema:

Config Update Request

alias
string

If alias is specified, then this subject is an alias for the subject named by the alias. That means that any reference to this subject will be replaced by the alias.

normalize
boolean

If true, then schemas are automatically normalized when registered or when passed during lookups. This means that clients do not have to pass the "normalize" query parameter to have normalization occur.

compatibility
string
extensible-enum: ["BACKWARD","BACKWARD_TRANSITIVE","FORWARD","FORWARD_TRANSITIVE","FULL","FULL_TRANSITIVE","NONE"]

Compatibility Level

compatibilityGroup
string

Only schemas that belong to the same compatibility group will be checked for compatibility.

object

Default value for the metadata to be used during schema registration.

object

Override value for the metadata to be used during schema registration.

object

Default value for the ruleSet to be used during schema registration.

object

Override value for the ruleSet to be used during schema registration.

Responses

Request samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibility": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Response samples

Content type
{
  • "alias": "string",
  • "normalize": true,
  • "compatibility": "FULL_TRANSITIVE",
  • "compatibilityGroup": "string",
  • "defaultMetadata": {
    },
  • "overrideMetadata": {
    },
  • "defaultRuleSet": {
    },
  • "overrideRuleSet": {
    }
}

Delete global compatibility level

Deletes the global compatibility level config and reverts to the default.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request DELETE \
  --url https://psrc-00000.region.provider.confluent.cloud/config \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
"FULL_TRANSITIVE"

Contexts (v1)

Generally Available

The API allows you to retrieve information about schema contexts.

Related guide: Manage Schemas in Confluent Cloud.

List contexts

Retrieves a list of contexts.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/contexts \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • "."
]

Exporters (v1)

Generally Available

The API allows you to create, retrieve, update, and delete exporters.

Related guide: Manage Schemas in Confluent Cloud.

Gets all schema exporters.

Retrieves a list of schema exporters that have been created.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/exporters \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
[
  • "[\"exporter1\", \"exporter2\"]"
]

Creates a new schema exporter.

Creates a new schema exporter. All attributes in request body are optional except config.

Authorizations:
resource-api-keyexternal-access-token
Request Body schema:

Schema

name
string

Name of the exporter

contextType
string
extensible-enum: ["CUSTOM","AUTO","NONE"]

Context type of the exporter. One of CUSTOM, NONE or AUTO (default)

context
string

Customized context of the exporter if contextType equals CUSTOM.

subjects
Array of strings

Name of each exporter subject

subjectRenameFormat
string

Format string for the subject name in the destination cluster, which may contain ${subject} as a placeholder for the originating subject name. For example, dc_${subject} for the subject orders will map to the destination subject name dc_orders.

object

The map containing exporter’s configurations

Responses

Request samples

Content type
{
  • "name": "test-exporter",
  • "contextType": "CUSTOM",
  • "context": "User",
  • "subjects": [
    ],
  • "subjectRenameFormat": "string",
  • "config": {
    }
}

Response samples

Content type
application/json; qs=0.5
{
  • "name": "test-exporter"
}

Gets schema exporter by name.

Retrieves the information of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter",
  • "contextType": "CUSTOM",
  • "context": "User",
  • "subjects": [
    ],
  • "subjectRenameFormat": "string",
  • "config": {
    }
}

Update schema exporter by name.

Updates the information or configurations of the schema exporter. All attributes in request body are optional.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Request Body schema:

Exporter Update Request

contextType
string
extensible-enum: ["CUSTOM","AUTO","NONE"]

Context type of the exporter. One of CUSTOM, NONE or AUTO (default)

context
string

Customized context of the exporter if contextType equals CUSTOM.

subjects
Array of strings

Name of each exporter subject

subjectRenameFormat
string

Format string for the subject name in the destination cluster, which may contain ${subject} as a placeholder for the originating subject name. For example, dc_${subject} for the subject orders will map to the destination subject name dc_orders.

object

The map containing exporter’s configurations

Responses

Request samples

Content type
{
  • "contextType": "CUSTOM",
  • "context": "User",
  • "subjects": [
    ],
  • "subjectRenameFormat": "string",
  • "config": {
    }
}

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter"
}

Delete schema exporter by name.

Deletes the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "error_code": 400,
  • "message": "Bad Request"
}

Gets schema exporter status by name.

Retrieves the status of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}/status' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter",
  • "state": "RUNNING",
  • "offset": 100,
  • "ts": 1631206325,
  • "trace": ""
}

Gets schema exporter config by name.

Retrieves the config of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}/config' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "schema.registry.url": "<Physical SR Endpoint>",
  • "basic.auth.credentials.source": "USER_INFO",
  • "basic.auth.user.info": "string"
}

Update schema exporter config by name.

Retrieves the config of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Request Body schema:

Exporter Update Request

schema.registry.url
string

Config SR URL

basic.auth.credentials.source
string

Config SR Auth

basic.auth.user.info
string

Config SR User Info

Responses

Request samples

Content type
{
  • "schema.registry.url": "<Physical SR Endpoint>",
  • "basic.auth.credentials.source": "USER_INFO",
  • "basic.auth.user.info": "string"
}

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter"
}

Pause schema exporter by name.

Pauses the state of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request PUT \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}/pause' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter"
}

Reset schema exporter by name.

Reset the state of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request PUT \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}/reset' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter"
}

Resume schema exporter by name.

Resume running of the schema exporter.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
name
required
string

Name of the exporter

Responses

Request samples

curl --request PUT \
  --url 'https://psrc-00000.region.provider.confluent.cloud/exporters/{name}/resume' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/vnd.schemaregistry.v1+json
{
  • "name": "test-exporter"
}

Modes (v1)

Generally Available

The API allows you to create, retrieve, update, and delete schema subjects modes of operation.

Related guide: Manage Schemas in Confluent Cloud.

Get subject mode

Retrieves the subject mode.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
defaultToGlobal
boolean

Whether to return the global mode if subject mode not found

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/mode/{subject}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "mode": "READWRITE"
}

Update subject mode

Update mode for the specified subject. On success, echoes the original request back to the client.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
force
boolean

Whether to force update if setting mode to IMPORT and schemas currently exist

Request Body schema:

Update Request

mode
string
extensible-enum: ["READWRITE","READONLY","READONLY_OVERRIDE","IMPORT"]

Schema Registry operating mode

Responses

Request samples

Content type
{
  • "mode": "READWRITE"
}

Response samples

Content type
{
  • "mode": "READWRITE"
}

Delete subject mode

Deletes the specified subject-level mode and reverts to the global default.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/mode/{subject}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "mode": "READWRITE"
}

Get global mode

Retrieves global mode.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/mode \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "mode": "READWRITE"
}

Update global mode

Update global mode. On success, echoes the original request back to the client.

Authorizations:
resource-api-keyexternal-access-token
query Parameters
force
boolean

Whether to force update if setting mode to IMPORT and schemas currently exist

Request Body schema:

Update Request

mode
string
extensible-enum: ["READWRITE","READONLY","READONLY_OVERRIDE","IMPORT"]

Schema Registry operating mode

Responses

Request samples

Content type
{
  • "mode": "READWRITE"
}

Response samples

Content type
{
  • "mode": "READWRITE"
}

Schemas (v1)

Generally Available

The API allows you to create, retrieve, update, and delete schemas.

Related guide: Manage Schemas in Confluent Cloud.

Get schema string by ID

Retrieves the schema string identified by the input ID.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
id
required
integer <int32>

Globally unique identifier of the schema

query Parameters
subject
string

Name of the subject

format
string
Default: ""

Desired output format, dependent on schema type

fetchMaxId
boolean
Default: false

Whether to fetch the maximum schema identifier that exists

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/schemas/ids/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "schemaType": "AVRO",
  • "schema": "{\"schema\": \"{\"type\": \"string\"}\"}",
  • "references": [
    ],
  • "maxId": 1
}

Get schema by ID

Retrieves the schema identified by the input ID.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
id
required
integer <int32>

Globally unique identifier of the schema

query Parameters
subject
string

Name of the subject

format
string
Default: ""

Desired output format, dependent on schema type

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/schemas/ids/{id}/schema' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
"{\"schema\": \"{\"type\": \"string\"}\"}"

List supported schema types

Retrieve the schema types supported by this registry.

Authorizations:
resource-api-keyexternal-access-token

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/schemas/types \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • "AVRO"
]

List schemas

Get the schemas matching the specified parameters.

Authorizations:
resource-api-keyexternal-access-token
query Parameters
subjectPrefix
string
Default: ""

Filters results by the respective subject prefix

deleted
boolean
Default: false

Whether to return soft deleted schemas

latestOnly
boolean
Default: false

Whether to return latest schema versions only for each matching subject

offset
integer <int32>
Default: 0

Pagination offset for results

limit
integer <int32>
Default: -1

Pagination size for results. Ignored if negative

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/schemas \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • {
    }
]

List subjects associated to schema ID

Retrieves all the subjects associated with a particular schema ID.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
id
required
integer <int32>

Globally unique identifier of the schema

query Parameters
subject
string

Filters results by the respective subject

deleted
boolean

Whether to include subjects where the schema was deleted

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/schemas/ids/{id}/subjects' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • "User"
]

List subject-versions associated to schema ID

Get all the subject-version pairs associated with the input ID.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
id
required
integer <int32>

Globally unique identifier of the schema

query Parameters
subject
string

Filters results by the respective subject

deleted
boolean

Whether to include subject versions where the schema was deleted

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/schemas/ids/{id}/versions' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • {
    }
]

Subjects (v1)

Generally Available

The API allows you to create, retrieve, update, and delete schema subjects and versions.

Related guide: Manage Schemas in Confluent Cloud.

Get schema by version

Retrieves a specific version of the schema registered under this subject.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

version
required
string

Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string "latest". "latest" returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.

query Parameters
deleted
boolean

Whether to include deleted schema

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}/versions/{version}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
{
  • "subject": "User",
  • "version": 1,
  • "id": 100001,
  • "schemaType": "AVRO",
  • "references": [
    ],
  • "schema": "{\"schema\": \"{\"type\": \"string\"}\"}"
}

Delete schema version

Deletes a specific version of the schema registered under this subject. This only deletes the version and the schema ID remains intact making it still possible to decode data using the schema ID. This API is recommended to be used only in development environments or under extreme circumstances where-in, its required to delete a previously registered schema for compatibility purposes or re-register previously registered schema.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

version
required
string

Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string "latest". "latest" returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.

query Parameters
permanent
boolean

Whether to perform a permanent delete

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}/versions/{version}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
1

List schemas referencing a schema

Retrieves the IDs of schemas that reference the specified schema.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

version
required
string

Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string "latest". "latest" returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}/versions/{version}/referencedby' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • 100001
]

Get schema string by version

Retrieves the schema for the specified version of this subject. Only the unescaped schema string is returned.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

version
required
string

Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string "latest". "latest" returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.

query Parameters
deleted
boolean

Whether to include deleted schema

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}/versions/{version}/schema' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
"{\"schema\": \"{\"type\": \"string\"}\"}"

List versions under subject

Retrieves a list of versions registered under the specified subject.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
deleted
boolean

Whether to include deleted schemas

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}/versions' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • 1
]

Register schema under a subject

Register a new schema under the specified subject. If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema's version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects. A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. The configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get:: /config When there are multiple instances of Schema Registry running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
normalize
boolean

Whether to register the normalized schema

Request Body schema:

Schema

version
integer <int32>

Version number

id
integer <int32>

Globally unique identifier of the schema

schemaType
string

Schema type

Array of objects (SchemaReference)

References to other schemas

schema
string

Schema definition string

Responses

Request samples

Content type
{
  • "version": 0,
  • "id": 0,
  • "schemaType": "string",
  • "references": [
    ],
  • "schema": "string"
}

Response samples

Content type
{
  • "id": 100001
}

Lookup schema under subject

Check if a schema has already been registered under the specified subject. If so, this returns the schema string along with its globally unique identifier, its version under this subject and the subject name.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Subject under which the schema will be registered

query Parameters
normalize
boolean

Whether to lookup the normalized schema

deleted
boolean

Whether to lookup deleted schemas

Request Body schema:

Schema

version
integer <int32>

Version number

id
integer <int32>

Globally unique identifier of the schema

schemaType
string

Schema type

Array of objects (SchemaReference)

References to other schemas

schema
string

Schema definition string

Responses

Request samples

Content type
{
  • "version": 0,
  • "id": 0,
  • "schemaType": "string",
  • "references": [
    ],
  • "schema": "string"
}

Response samples

Content type
{
  • "subject": "User",
  • "version": 1,
  • "id": 100001,
  • "schemaType": "AVRO",
  • "references": [
    ],
  • "schema": "{\"schema\": \"{\"type\": \"string\"}\"}"
}

Delete subject

Deletes the specified subject and its associated compatibility level if registered. It is recommended to use this API only when a topic needs to be recycled or in development environment.

Authorizations:
resource-api-keyexternal-access-token
path Parameters
subject
required
string

Name of the subject

query Parameters
permanent
boolean

Whether to perform a permanent delete

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/subjects/{subject}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • 1
]

List subjects

Retrieves a list of registered subjects matching specified parameters.

Authorizations:
resource-api-keyexternal-access-token
query Parameters
subjectPrefix
string
Default: ":*:"

Subject name prefix

deleted
boolean

Whether to look up deleted subjects

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/subjects \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
[
  • "User"
]

Entity (v1)

Generally Available

The API allows you to create, retrieve, update, and delete catalog entities.

Related guide: Catalog API Documentation.

Bulk Create Business Metadata

Generally Available

Bulk API to create multiple business metadata.

Request Body schema: application/json

The business metadata

Array
typeName
string

The business metadata name

attributes
object

The business metadata attributes

entityType
string

The entity type

entityName
string

The qualified name of the entity

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Update Business Metadata

Generally Available

Bulk API to update multiple business metadata.

Request Body schema: application/json

The business metadata

Array
typeName
string

The business metadata name

attributes
object

The business metadata attributes

entityType
string

The entity type

entityName
string

The qualified name of the entity

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Read Business Metadata for an Entity

Generally Available

Gets the list of business metadata for a given entity represented by a qualified name.

path Parameters
typeName
required
string

The type of the entity

qualifiedName
required
string

The qualified name of the entity

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/entity/type/{typeName}/name/{qualifiedName}/businessmetadata'

Response samples

Content type
application/json
[
  • {
    }
]

Delete a Business Metadata for an Entity

Generally Available

Delete a business metadata on an entity.

path Parameters
typeName
required
string

The type of the entity

qualifiedName
required
string

The qualified name of the entity

bmName
required
string

The name of the business metadata

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/entity/type/{typeName}/name/{qualifiedName}/businessmetadata/{bmName}'

Bulk Update Tags

Generally Available

Bulk API to update multiple tags.

Request Body schema: application/json

The tags

Array
typeName
string

The tag name

attributes
object

The tag attributes

entityGuid
string

The internal entity guid

entityStatus
string
Enum: "ACTIVE" "DELETED" "PURGED"

The entity status

propagate
boolean

Whether to propagate the tag

Array of objects (TimeBoundary)

The validity periods

removePropagationsOnEntityDelete
boolean

Whether to remove propagations on entity delete

entityType
string

The entity type

entityName
string

The qualified name of the entity

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Create Tags

Generally Available

Bulk API to create multiple tags.

Request Body schema: application/json

The tags

Array
typeName
string

The tag name

attributes
object

The tag attributes

entityGuid
string

The internal entity guid

entityStatus
string
Enum: "ACTIVE" "DELETED" "PURGED"

The entity status

propagate
boolean

Whether to propagate the tag

Array of objects (TimeBoundary)

The validity periods

removePropagationsOnEntityDelete
boolean

Whether to remove propagations on entity delete

entityType
string

The entity type

entityName
string

The qualified name of the entity

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Read an Entity

Generally Available

Fetch complete definition of an entity given its type and unique attribute.

path Parameters
typeName
required
string

The type of the entity

qualifiedName
required
string

The qualified name of the entity

query Parameters
minExtInfo
boolean
Default: false

Whether to populate on header and schema attributes

ignoreRelationships
boolean
Default: false

Whether to ignore relationships

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/entity/type/{typeName}/name/{qualifiedName}'

Response samples

Content type
application/json
{
  • "referredEntities": {
    },
  • "entity": {
    }
}

Read Tags for an Entity

Generally Available

Gets the list of tags for a given entity represented by a qualified name.

path Parameters
typeName
required
string

The type of the entity

qualifiedName
required
string

The qualified name of the entity

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/entity/type/{typeName}/name/{qualifiedName}/tags'

Response samples

Content type
application/json
[
  • {
    }
]

Update an Entity Attribute

Generally Available

Partially update an entity attribute.

Request Body schema: application/json

The entity to update

object

The referred entities

object (Entity)

The entity

Responses

Request samples

Content type
application/json
{
  • "referredEntities": {
    },
  • "entity": {
    }
}

Response samples

Content type
application/json
{
  • "mutatedEntities": {
    }
}

Delete a Tag for an Entity

Generally Available

Delete a tag for an entity.

path Parameters
typeName
required
string

The type of the entity

qualifiedName
required
string

The qualified name of the entity

tagName
required
string

The name of the tag

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/entity/type/{typeName}/name/{qualifiedName}/tags/{tagName}'

Search (v1)

Generally Available

The API allows you to search for entities.

Related guide: Catalog API Documentation.

Search by Attribute

Generally Available

Retrieve data for the specified attribute search query.

query Parameters
type
Array of strings

Limit the result to only entities of specified types

attr
Array of strings

One of more additional attributes to return in the response

attrName
Array of strings

The attribute to search

attrValuePrefix
Array of strings

The prefix for the attribute value to search

tag
string

Limit the result to only entities tagged with the given tag

sortBy
string

An attribute to sort by

sortOrder
string
Enum: "ASCENDING" "DESCENDING"

Sort order, either ASCENDING (default) or DESCENDING

deleted
boolean

Whether to include deleted entities

limit
integer <int32>

Limit the result set to only include the specified number of entries

offset
integer <int32>

Start offset of the result set (useful for pagination)

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/catalog/v1/search/attribute

Response samples

Content type
application/json
{
  • "searchParameters": {
    },
  • "types": [
    ],
  • "entities": [
    ],
  • "referredEntities": {
    }
}

Search by Fulltext Query

Generally Available

Retrieve data for the specified fulltext query.

query Parameters
query
string

The full-text query

type
Array of strings

Limit the result to only entities of specified types

attr
Array of strings

One of more additional attributes to return in the response

tag
string

Limit the result to only entities tagged with the given tag

sortBy
string

An attribute to sort by

sortOrder
string
Enum: "ASCENDING" "DESCENDING"

Sort order, either ASCENDING (default) or DESCENDING

deleted
boolean

Whether to include deleted entities

limit
integer <int32>

Limit the result set to only include the specified number of entries

offset
integer <int32>

Start offset of the result set (useful for pagination)

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/catalog/v1/search/basic

Response samples

Content type
application/json
{
  • "searchParameters": {
    },
  • "types": [
    ],
  • "entities": [
    ],
  • "referredEntities": {
    }
}

Types (v1)

Generally Available

The API allows you to create, retrieve, update, and delete catalog types such as tag definitions.

Related guide: Catalog API Documentation.

Bulk Read Business Metadata Definitions

Generally Available

Bulk retrieval API for retrieving business metadata definitions.

query Parameters
prefix
string

The prefix of a business metadata definition name

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/businessmetadatadefs

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Create Business Metadata Definitions

Generally Available

Bulk create API for business metadata definitions.

Request Body schema: application/json

The business metadata definitions to create

Array
category
string
Enum: "PRIMITIVE" "OBJECT_ID_TYPE" "ENUM" "STRUCT" "CLASSIFICATION" "ENTITY" "ARRAY" "MAP" "RELATIONSHIP" "BUSINESS_METADATA"

The category

guid
string

The internal guid

createdBy
string

The creator

updatedBy
string

The updater

createTime
integer <int64>

The create time

updateTime
integer <int64>

The update time

version
integer <int32>

The version

name
string

The name

description
string

The description

typeVersion
string

The type version

serviceType
string

The service type

object

The options

Array of objects (AttributeDef)

The attribute definitions

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Update Business Metadata Definitions

Generally Available

Bulk update API for business metadata definitions.

Request Body schema: application/json

The business metadata definitions to update

Array
category
string
Enum: "PRIMITIVE" "OBJECT_ID_TYPE" "ENUM" "STRUCT" "CLASSIFICATION" "ENTITY" "ARRAY" "MAP" "RELATIONSHIP" "BUSINESS_METADATA"

The category

guid
string

The internal guid

createdBy
string

The creator

updatedBy
string

The updater

createTime
integer <int64>

The create time

updateTime
integer <int64>

The update time

version
integer <int32>

The version

name
string

The name

description
string

The description

typeVersion
string

The type version

serviceType
string

The service type

object

The options

Array of objects (AttributeDef)

The attribute definitions

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete Business Metadata Definition

Generally Available

Delete API for business metadata definition identified by its name.

path Parameters
bmName
required
string

The name of the business metadata definition

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/businessmetadatadefs/{bmName}'

Read Business Metadata Definition

Generally Available

Get the business metadata definition with the given name.

path Parameters
bmName
required
string

The name of the business metadata definition

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/businessmetadatadefs/{bmName}'

Response samples

Content type
application/json
{
  • "category": "PRIMITIVE",
  • "guid": "string",
  • "createdBy": "string",
  • "updatedBy": "string",
  • "createTime": 0,
  • "updateTime": 0,
  • "version": 0,
  • "name": "string",
  • "description": "string",
  • "typeVersion": "string",
  • "serviceType": "string",
  • "options": {
    },
  • "attributeDefs": [
    ]
}

Bulk Read Tag Definitions

Generally Available

Bulk retrieval API for retrieving tag definitions.

query Parameters
prefix
string

The prefix of a tag definition name

Responses

Request samples

curl --request GET \
  --url https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/tagdefs

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Update Tag Definitions

Generally Available

Bulk update API for tag definitions.

Request Body schema: application/json

The tag definitions to update

Array
category
string
Enum: "PRIMITIVE" "OBJECT_ID_TYPE" "ENUM" "STRUCT" "CLASSIFICATION" "ENTITY" "ARRAY" "MAP" "RELATIONSHIP" "BUSINESS_METADATA"

The category

guid
string

The internal guid

createdBy
string

The creator

updatedBy
string

The updater

createTime
integer <int64>

The create time

updateTime
integer <int64>

The update time

version
integer <int32>

The version

name
string

The name

description
string

The description

typeVersion
string

The type version

serviceType
string

The service type

object

The options

Array of objects (AttributeDef)

The attribute definitions

superTypes
Array of strings unique

The supertypes

entityTypes
Array of strings unique

The entity types

subTypes
Array of strings unique

The subtypes

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Bulk Create Tag Definitions

Generally Available

Bulk create API for tag definitions.

Request Body schema: application/json

The tag definitions to create

Array
category
string
Enum: "PRIMITIVE" "OBJECT_ID_TYPE" "ENUM" "STRUCT" "CLASSIFICATION" "ENTITY" "ARRAY" "MAP" "RELATIONSHIP" "BUSINESS_METADATA"

The category

guid
string

The internal guid

createdBy
string

The creator

updatedBy
string

The updater

createTime
integer <int64>

The create time

updateTime
integer <int64>

The update time

version
integer <int32>

The version

name
string

The name

description
string

The description

typeVersion
string

The type version

serviceType
string

The service type

object

The options

Array of objects (AttributeDef)

The attribute definitions

superTypes
Array of strings unique

The supertypes

entityTypes
Array of strings unique

The entity types

subTypes
Array of strings unique

The subtypes

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Read Tag Definition

Generally Available

Get the tag definition with the given name.

path Parameters
tagName
required
string

The name of the tag definiton

Responses

Request samples

curl --request GET \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/tagdefs/{tagName}'

Response samples

Content type
application/json
{
  • "category": "PRIMITIVE",
  • "guid": "string",
  • "createdBy": "string",
  • "updatedBy": "string",
  • "createTime": 0,
  • "updateTime": 0,
  • "version": 0,
  • "name": "string",
  • "description": "string",
  • "typeVersion": "string",
  • "serviceType": "string",
  • "options": {
    },
  • "attributeDefs": [
    ],
  • "superTypes": [
    ],
  • "entityTypes": [
    ],
  • "subTypes": [
    ]
}

Delete Tag Definition

Generally Available

Delete API for tag definition identified by its name.

path Parameters
tagName
required
string

The name of the tag definition

Responses

Request samples

curl --request DELETE \
  --url 'https://psrc-00000.region.provider.confluent.cloud/catalog/v1/types/tagdefs/{tagName}'

Provider Shared Resources (cdx/v1)

General Availability

ProviderSharedResource object contains details of the data stream (topic, schema registry subjects, sharing metadata) that you have shared through Stream Sharing.

The Provider Shared Resources Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ProviderSharedResource"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

crn
string <uri> ^crn://.+$

Deprecated please use resources attribute.

resources
Array of strings <uri> non-empty

List of resource crns that are shared together

display_name
string

Shared resource display name

description
string

Description of shared resource

tags
Array of strings

list of tags

Array of objects

List of schemas in JSON format. This field is work in progress and subject to changes.

organization_description
string

Shared resource's organization description

organization_contact
string <email>

Email of contact person from the organization

logo_url
string <uri>

Resource logo url

organization_name
any

Organization to which the shared resource belongs. Deprecated

environment_name
string

The environment name of the shared resource. Deprecated

cluster_name
string

The cluster display name of the shared resource. Deprecated

object

The cloud cluster to which this belongs.

{
  • "api_version": "cdx/v1",
  • "kind": "ProviderSharedResource",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "crn": "crn://confluent.cloud/environment=env-123/cloud-cluster=lkc-1111aaa/kafka=lkc-111aaa/topic=my.topic",
  • "resources": [
    ],
  • "display_name": "Stock Trades",
  • "description": "This topic provides realtime data for the orders placed through the website",
  • "tags": [
    ],
  • "schemas": [
    ],
  • "organization_description": "ABC Corp is the biggest online retailer",
  • "organization_contact": "jane.doe@example.com",
  • "organization_name": "ABC Corp",
  • "environment_name": "Public Env",
  • "cluster_name": "Published Trades",
  • "cloud_cluster": {}
}

List of Provider Shared Resources

General Availability

Retrieve a sorted, filtered, paginated list of all provider shared resources.

Authorizations:
api-key
query Parameters
stream_share
string (SearchFilter)
Example: stream_share=ss-1234

Filter the results by exact match for stream_share.

crn
string (SearchFilter)
Example: crn=crn://confluent.cloud/cloud-cluster=lkc-111aaa/kafka=lkc-111aaa/topic=my.topic

Filter the results by exact match for crn.

include_deleted
boolean (BooleanFilter)

Include deactivated shared resources

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shared-resources?stream_share=ss-1234&crn=crn://confluent.cloud/cloud-cluster=lkc-111aaa/kafka=lkc-111aaa/topic=my.topic&include_deleted=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Provider Shared Resource

General Availability

Make a request to read a provider shared resource.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider shared resource.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shared-resources/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Provider Shared Resource

General Availability

Make a request to update a provider shared resource.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider shared resource.

Request Body schema: application/json
resources
Array of strings <uri> non-empty

List of resource crns that are shared together

display_name
string

Shared resource display name

organization_description
string

Shared resource's organization description

organization_contact
string <email>

Email of contact person from the organization

Responses

Request samples

Content type
application/json
{
  • "resources": [
    ],
  • "display_name": "Stock Trades",
  • "organization_description": "ABC Corp is the biggest online retailer",
  • "organization_contact": "jane.doe@example.com"
}

Response samples

Content type
application/json
{}

Upload image for shared resource

General Availability

Upload the image file for the shared resource

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider shared resource.

file_name
required
string

The File Name

Request Body schema: image/*
string <base64>

Responses

Request samples

curl --request POST \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shared-resources/{id}/images/{file_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: image/*'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get image for shared resource

General Availability

Returns the image file for the shared resource

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider shared resource.

file_name
required
string

The File Name

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shared-resources/{id}/images/{file_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete the shared resource's image

General Availability

Deletes the image file for the shared resource

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider shared resource.

file_name
required
string

The File Name

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shared-resources/{id}/images/{file_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Provider Shares (cdx/v1)

General Availability

ProviderShare object respresents the share that you have created through Stream Sharing.

Related guide: Provider Stream Shares in Confluent Cloud.

The Provider Shares Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ProviderShare"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

consumer_user_name
string

Name of the consumer

consumer_organization_name
string

Consumer organization name

provider_user_name
string

Name or email of the provider user. Deprecated

delivery_method
string
extensible-enum: ["EMAIL"]

Method by which the invite will be delivered

any

Restrictions on the consumer that can redeem this token

invited_at
string <date-time>

The date and time at which consumer was invited

invite_expires_at
string <date-time>

The date and time at which the invitation will expire. Only for invited shares

redeemed_at
string <date-time>

The date and time at which the invite was redeemed

object

The provider user/inviter

object

The service account associated with this object.

object

The cloud cluster to which this belongs.

object (cdx.v1.ProviderShareStatus)

The status of the Provider Share

{
  • "api_version": "cdx/v1",
  • "kind": "ProviderShare",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "consumer_user_name": "John Doe",
  • "consumer_organization_name": "Nasdaq",
  • "provider_user_name": "Jane Doe",
  • "delivery_method": "EMAIL",
  • "consumer_restriction": {
    },
  • "invited_at": "2006-01-02T15:04:05-07:00",
  • "invite_expires_at": "2006-01-02T15:04:05-07:00",
  • "redeemed_at": "2006-01-02T15:04:05-07:00",
  • "provider_user": {},
  • "service_account": {},
  • "cloud_cluster": {},
  • "status": {
    }
}

List of Provider Shares

General Availability

Retrieve a sorted, filtered, paginated list of all provider shares.

Authorizations:
api-key
query Parameters
shared_resource
string (SearchFilter)
Example: shared_resource=sr-1234

Filter the results by exact match for shared_resource.

crn
string (SearchFilter)
Example: crn=crn://confluent.cloud/cloud-cluster=lkc-111aaa/kafka=lkc-111aaa/topic=my.topic

Filter the results by exact match for crn.

include_deleted
boolean (BooleanFilter)

Include deactivated shares

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shares?shared_resource=sr-1234&crn=crn://confluent.cloud/cloud-cluster=lkc-111aaa/kafka=lkc-111aaa/topic=my.topic&include_deleted=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a provider share

General Availability

Creates a share based on delivery method.

Authorizations:
api-key
Request Body schema: application/json
delivery_method
required
string
extensible-enum: ["EMAIL"]

Method by which the invite will be delivered

required
any

Restrictions on the consumer that can redeem this token

resources
required
Array of strings <uri> non-empty

List of resource crns to be shared

Responses

Request samples

Content type
application/json
{
  • "delivery_method": "EMAIL",
  • "consumer_restriction": {
    },
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "ProviderShare",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "consumer_user_name": "John Doe",
  • "consumer_organization_name": "Nasdaq",
  • "provider_user_name": "Jane Doe",
  • "delivery_method": "EMAIL",
  • "consumer_restriction": {
    },
  • "invited_at": "2006-01-02T15:04:05-07:00",
  • "invite_expires_at": "2006-01-02T15:04:05-07:00",
  • "redeemed_at": "2006-01-02T15:04:05-07:00",
  • "provider_user": {},
  • "service_account": {},
  • "cloud_cluster": {},
  • "status": {
    }
}

Read a Provider Share

General Availability

Make a request to read a provider share.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider share.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shares/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Delete a Provider Share

General Availability

Make a request to delete a provider share.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider share.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shares/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Resend

General Availability

Resend provider share

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the provider share.

Responses

Request samples

curl --request POST \
  --url 'https://api.confluent.cloud/cdx/v1/provider-shares/{id}:resend' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Consumer Shared Resources (cdx/v1)

General Availability

ConsumerSharedResource object contains details of the data stream (topic, schema registry subjects, sharing metadata) that you received through Stream Sharing.

The Consumer Shared Resources Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ConsumerSharedResource"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

cloud
string
extensible-enum: ["AWS","AZURE","GCP"]

The cloud service provider of the provider shared cluster.

network_connection_types
Array of strings unique

The network connection types of the provider shared cluster. If the shared cluster is on public internet, then the list will be empty

display_name
string

Consumer resource display name

description
string

Description of consumer resource

tags
Array of strings

list of tags

Array of objects

List of schemas in JSON format. This field is work in progress and subject to changes.

organization_name
string

Shared resource's organization name

organization_description
string

Shared resource's organization description

organization_contact
string <email>

Email of the shared resource's organization contact

logo_url
string <uri>

Resource logo url

{
  • "api_version": "cdx/v1",
  • "kind": "ConsumerSharedResource",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "cloud": "AWS",
  • "network_connection_types": [
    ],
  • "display_name": "Stock Trades",
  • "description": "This topic provides realtime data for the orders placed through the website",
  • "tags": [
    ],
  • "schemas": [
    ],
  • "organization_name": "ABC Corp",
  • "organization_description": "ABC Corp is the biggest online retailer",
  • "organization_contact": "jane.doe@example.com",
}

List of Consumer Shared Resources

General Availability

Retrieve a sorted, filtered, paginated list of all consumer shared resources.

Authorizations:
api-key
query Parameters
stream_share
string (SearchFilter)
Example: stream_share=ss-1234

Filter the results by exact match for stream_share.

include_deleted
boolean (BooleanFilter)

Include deactivated shared resources

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shared-resources?stream_share=ss-1234&include_deleted=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Consumer Shared Resource

General Availability

Make a request to read a consumer shared resource.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the consumer shared resource.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shared-resources/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "ConsumerSharedResource",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "cloud": "AWS",
  • "network_connection_types": [
    ],
  • "display_name": "Stock Trades",
  • "description": "This topic provides realtime data for the orders placed through the website",
  • "tags": [
    ],
  • "schemas": [
    ],
  • "organization_name": "ABC Corp",
  • "organization_description": "ABC Corp is the biggest online retailer",
  • "organization_contact": "jane.doe@example.com",
}

Get image for shared resource

General Availability

Returns the image file for the shared resource

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the consumer shared resource.

file_name
required
string

The File Name

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shared-resources/{id}/images/{file_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get shared resource's network configuration

General Availability

Returns network information of the shared resource

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the consumer shared resource.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shared-resources/{id}:network' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "Network",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "kafka_bootstrap_url": "SASL://pkc-xxxxx.us-west-2.aws.confluent.cloud:9092",
  • "zones": [
    ],
  • "dns_domain": "00000.us-east-1.aws.glb.confluent.cloud",
  • "zonal_subdomains": {
    },
  • "cloud": {
    }
}

Consumer Shares (cdx/v1)

General Availability

ConsumerShare object respresents the share that you received through Stream Sharing.

Related guide: Consumer Stream Shares in Confluent Cloud.

The Consumer Shares Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ConsumerShare"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

provider_organization_name
string

Provider organization name

provider_user_name
string

Name or email of the provider user

invite_expires_at
string <date-time>

The date and time at which the invitation will expire. Only for invited shares

consumer_organization_name
string

Consumer organization name. Deprecated

consumer_user_name
string

Name of the consumer. Deprecated

object

The consumer user/invitee

object (cdx.v1.ConsumerShareStatus)

The status of the Consumer Share

{
  • "api_version": "cdx/v1",
  • "kind": "ConsumerShare",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "provider_organization_name": "Nasdaq",
  • "provider_user_name": "Jane Doe",
  • "invite_expires_at": "2006-01-02T15:04:05-07:00",
  • "consumer_organization_name": "Nasdaq",
  • "consumer_user_name": "John Doe",
  • "consumer_user": {},
  • "status": {
    }
}

List of Consumer Shares

General Availability

Retrieve a sorted, filtered, paginated list of all consumer shares.

Authorizations:
api-key
query Parameters
shared_resource
string (SearchFilter)
Example: shared_resource=sr-1234

Filter the results by exact match for shared_resource.

include_deleted
boolean (BooleanFilter)

Include deactivated shares

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shares?shared_resource=sr-1234&include_deleted=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Consumer Share

General Availability

Make a request to read a consumer share.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the consumer share.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shares/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "ConsumerShare",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "provider_organization_name": "Nasdaq",
  • "provider_user_name": "Jane Doe",
  • "invite_expires_at": "2006-01-02T15:04:05-07:00",
  • "consumer_organization_name": "Nasdaq",
  • "consumer_user_name": "John Doe",
  • "consumer_user": {},
  • "status": {
    }
}

Delete a Consumer Share

General Availability

Make a request to delete a consumer share.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the consumer share.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/cdx/v1/consumer-shares/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Shared Tokens (cdx/v1)

General Availability

Encrypted Token shared with consumer

The Shared Tokens Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "SharedToken"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

token
string

The encrypted token

{
  • "api_version": "cdx/v1",
  • "kind": "SharedToken",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "token": "string"
}

Validate token to view shared resources

General Availability

Validate and decrypt the shared token and view token's shared resources

Authorizations:
api-key
Request Body schema: application/json
token
required
string

The encrypted token

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "consumer_shared_resources": [
    ]
}

Redeem token

General Availability

Redeem the shared token for shared topic and cluster access information

Authorizations:
api-key
Request Body schema: application/json
token
required
string

The encrypted token

aws_account
string

Consumer's AWS account ID for PrivateLink access.

azure_subscription
string

Consumer's Azure subscription ID for PrivateLink access.

gcp_project
string non-empty

Consumer's GCP project ID for Private Service Connect access.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "aws_account": "000000000000",
  • "azure_subscription": "00000000-0000-0000-0000-000000000000",
  • "gcp_project": "string"
}

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "RedeemTokenResponse",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "api_key": "string",
  • "secret": "string",
  • "kafka_bootstrap_url": "SASL://pkc-xxxxx.us-west-2.aws.confluent.cloud:9092",
  • "schema_registry_api_key": "string",
  • "schema_registry_secret": "string",
  • "resources": [
    ]
}

Opt Ins (cdx/v1)

General Availability

Stream sharing opt in options

The Opt Ins Model

api_version
string
Value: "cdx/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "OptIn"

Kind defines the object this REST resource represents.

stream_share_enabled
boolean

Enable stream sharing for the organization

{
  • "api_version": "cdx/v1",
  • "kind": "OptIn",
  • "stream_share_enabled": true
}

Read the organization's stream sharing opt-in settings

General Availability

Returns the organization's stream sharing opt-in settings.

Authorizations:
api-key

Responses

Request samples

curl --request GET \
  --url https://api.confluent.cloud/cdx/v1/opt-in \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "OptIn",
  • "stream_share_enabled": true
}

Set the organization's stream sharing opt-in settings

General Availability

Updates the organization's stream sharing opt-in settings.

Authorizations:
api-key
Request Body schema: application/json
stream_share_enabled
boolean

Enable stream sharing for the organization

Responses

Request samples

Content type
application/json
{
  • "stream_share_enabled": true
}

Response samples

Content type
application/json
{
  • "api_version": "cdx/v1",
  • "kind": "OptIn",
  • "stream_share_enabled": true
}

Networks (networking/v1)

General Availability

Network represents a network (VPC) in Confluent Cloud. All Networks exist within Confluent-managed cloud provider accounts. Dedicated networks support more networking options but can only contain Dedicated clusters. Shared networks can contain any cluster type.

The API allows you to list, create, read, update, and delete your networks.

Related guide: APIs to manage networks in Confluent Cloud.

The Networks Model

api_version
string
Value: "networking/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Network"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (networking.v1.NetworkSpec)

The desired state of the Network

object (networking.v1.NetworkStatus)

The status of the Network

{
  • "api_version": "networking/v1",
  • "kind": "Network",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
dedicated_networks_per_environment Number of dedicated networks per Confluent Cloud environment

List of Networks

General Availability

Retrieve a sorted, filtered, paginated list of all networks.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
spec.display_name
Array of strings (MultipleSearchFilter)
Example: spec.display_name=prod-gcp-us-central1&spec.display_name=prod-aws-us-east1

Filter the results by exact match for spec.display_name. Pass multiple times to see results matching any of the values.

spec.cloud
Array of strings (MultipleSearchFilter)
Example: spec.cloud=GCP&spec.cloud=AWS

Filter the results by exact match for spec.cloud. Pass multiple times to see results matching any of the values.

spec.region
Array of strings (MultipleSearchFilter)
Example: spec.region=us-central1&spec.region=us-east-1

Filter the results by exact match for spec.region. Pass multiple times to see results matching any of the values.

spec.connection_types
Array of strings (MultipleSearchFilter)
Example: spec.connection_types=peering&spec.connection_types=privatelink

Filter the results by exact match for spec.connection_types. Pass multiple times to see results matching any of the values.

spec.cidr
Array of strings (MultipleSearchFilter)
Example: spec.cidr=10.200.0.0/16

Filter the results by exact match for spec.cidr. Pass multiple times to see results matching any of the values.

status.phase
Array of strings (MultipleSearchFilter)
Example: status.phase=PROVISIONING&status.phase=READY

Filter the results by exact match for status.phase. Pass multiple times to see results matching any of the values.

environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/networks?spec.display_name=prod-gcp-us-central1,prod-aws-us-east1&spec.cloud=GCP,AWS&spec.region=us-central1,us-east-1&spec.connection_types=peering,privatelink&spec.cidr=10.200.0.0/16&status.phase=PROVISIONING,READY&environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Network

General Availability

Make a request to create a network.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Network

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "networking/v1",
  • "kind": "Network",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {},
  • "status": {
    }
}

Read a Network

General Availability

Make a request to read a network.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the network.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/networks/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "networking/v1",
  • "kind": "Network",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {},
  • "status": {
    }
}

Update a Network

General Availability

Make a request to update a network.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the network.

Request Body schema: application/json
required
object

The desired state of the Network

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "networking/v1",
  • "kind": "Network",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {},
  • "status": {
    }
}

Delete a Network

General Availability

Make a request to delete a network.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the network.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/networking/v1/networks/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Peerings (networking/v1)

The Peerings Model

api_version
string
Value: "networking/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Peering"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (networking.v1.PeeringSpec)

The desired state of the Peering

object (networking.v1.PeeringStatus)

The status of the Peering

{
  • "api_version": "networking/v1",
  • "kind": "Peering",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
peerings_per_network Number of peerings per network

List of Peerings

General Availability

Retrieve a sorted, filtered, paginated list of all peerings.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
spec.display_name
Array of strings (MultipleSearchFilter)
Example: spec.display_name=prod-peering-uscentral1&spec.display_name=prod-peering-use1

Filter the results by exact match for spec.display_name. Pass multiple times to see results matching any of the values.

status.phase
Array of strings (MultipleSearchFilter)
Example: status.phase=PROVISIONING&status.phase=READY

Filter the results by exact match for status.phase. Pass multiple times to see results matching any of the values.

environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

spec.network
Array of strings (MultipleSearchFilter)
Example: spec.network=n-00000&spec.network=n-00001

Filter the results by exact match for spec.network. Pass multiple times to see results matching any of the values.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/peerings?spec.display_name=prod-peering-uscentral1,prod-peering-use1&status.phase=PROVISIONING,READY&environment=env-00000&spec.network=n-00000,n-00001' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Peering

General Availability

Make a request to create a peering.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Peering

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Peering

General Availability

Make a request to read a peering.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the peering.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/peerings/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Peering

General Availability

Make a request to update a peering.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the peering.

Request Body schema: application/json
required
object

The desired state of the Peering

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Peering

General Availability

Make a request to delete a peering.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the peering.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/networking/v1/peerings/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Transit Gateway Attachments (networking/v1)

General Availability

AWS Transit Gateway Attachments

Related guide: APIs to manage AWS Transit Gateway Attachments.

The Transit Gateway Attachments Model

api_version
string
Value: "networking/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "TransitGatewayAttachment"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (networking.v1.TransitGatewayAttachmentSpec)

The desired state of the Transit Gateway Attachment

object (networking.v1.TransitGatewayAttachmentStatus)

The status of the Transit Gateway Attachment

{
  • "api_version": "networking/v1",
  • "kind": "TransitGatewayAttachment",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "spec": {
    },
  • "status": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
tgw_attachments_per_network Number of TGW attachments per network

List of Transit Gateway Attachments

General Availability

Retrieve a sorted, filtered, paginated list of all transit gateway attachments.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
spec.display_name
Array of strings (MultipleSearchFilter)
Example: spec.display_name=prod-tgw-use1&spec.display_name=prod-tgw-usw2

Filter the results by exact match for spec.display_name. Pass multiple times to see results matching any of the values.

status.phase
Array of strings (MultipleSearchFilter)
Example: status.phase=PROVISIONING&status.phase=READY

Filter the results by exact match for status.phase. Pass multiple times to see results matching any of the values.

environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

spec.network
Array of strings (MultipleSearchFilter)
Example: spec.network=n-00000&spec.network=n-00001

Filter the results by exact match for spec.network. Pass multiple times to see results matching any of the values.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/transit-gateway-attachments?spec.display_name=prod-tgw-use1,prod-tgw-usw2&status.phase=PROVISIONING,READY&environment=env-00000&spec.network=n-00000,n-00001' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Transit Gateway Attachment

General Availability

Make a request to create a transit gateway attachment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Transit Gateway Attachment

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Transit Gateway Attachment

General Availability

Make a request to read a transit gateway attachment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the transit gateway attachment.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/transit-gateway-attachments/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Transit Gateway Attachment

General Availability

Make a request to update a transit gateway attachment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the transit gateway attachment.

Request Body schema: application/json
required
object

The desired state of the Transit Gateway Attachment

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Transit Gateway Attachment

General Availability

Make a request to delete a transit gateway attachment.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the transit gateway attachment.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/networking/v1/transit-gateway-attachments/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

IP Addresses (networking/v1)

The IP Addresses Model

api_version
string
Value: "networking/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "IpAddress"

Kind defines the object this REST resource represents.

ip_prefix
string^\d+\.\d+\.\d+\.\d+/\d+$

The IP Address range.

cloud
string
extensible-enum: ["AWS","GCP","AZURE","ANY"]

The cloud service provider in which the address exists.

region
string

The region/location where the IP Address is in use.

services
Array of strings non-empty unique

The service types that will use the address.

address_type
string
extensible-enum: ["INGRESS","EGRESS"]

Whether the address is used for egress or ingress.

{
  • "api_version": "networking/v1",
  • "kind": "IpAddress",
  • "ip_prefix": "10.200.0.0/28",
  • "cloud": "AWS",
  • "region": "us-east-1",
  • "services": [
    ],
  • "address_type": "EGRESS"
}

List of IP Addresses

General Availability

Related guide: Use Public Egress IP addresses on Confluent Cloud

Retrieve a sorted, filtered, paginated list of all IP Addresses.

Authorizations:
cloud-api-key
query Parameters
cloud
Array of strings (MultipleSearchFilter)
Example: cloud=GCP&cloud=AWS

Filter the results by exact match for cloud. Pass multiple times to see results matching any of the values.

region
Array of strings (MultipleSearchFilter)
Example: region=us-central1&region=us-east-1

Filter the results by exact match for region. Pass multiple times to see results matching any of the values.

services
Array of strings (MultipleSearchFilter)
Example: services=KAFKA&services=CONNECT

Filter the results by exact match for services. Pass multiple times to see results matching any of the values.

address_type
Array of strings (MultipleSearchFilter)
Example: address_type=INGRESS&address_type=EGRESS

Filter the results by exact match for address_type. Pass multiple times to see results matching any of the values.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/ip-addresses?cloud=GCP,AWS&region=us-central1,us-east-1&services=KAFKA,CONNECT&address_type=INGRESS,EGRESS' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

DNS Forwarders (networking/v1)

General Availability

Add, remove, and update DNS forwarder for your gateway.

Related guides:

The DNS Forwarders Model

api_version
string
Value: "networking/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "DnsForwarder"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (networking.v1.DnsForwarderSpec)

The desired state of the Dns Forwarder

object (networking.v1.DnsForwarderStatus)

The status of the Dns Forwarder

{
  • "api_version": "networking/v1",
  • "kind": "DnsForwarder",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

List of DNS Forwarders

General Availability

Retrieve a sorted, filtered, paginated list of all DNS forwarders.

Authorizations:
cloud-api-keyconfluent-sts-access-token
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/dns-forwarders?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a DNS Forwarder

General Availability

Make a request to create a DNS forwarder.

Authorizations:
cloud-api-keyconfluent-sts-access-token
Request Body schema: application/json
required
object

The desired state of the Dns Forwarder

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a DNS Forwarder

General Availability

Make a request to read a DNS forwarder.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the DNS forwarder.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/networking/v1/dns-forwarders/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a DNS Forwarder

General Availability

Make a request to update a DNS forwarder.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the DNS forwarder.

Request Body schema: application/json
required
object

The desired state of the Dns Forwarder

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a DNS Forwarder

General Availability

Make a request to delete a DNS forwarder.

Authorizations:
cloud-api-keyconfluent-sts-access-token
path Parameters
id
required
string

The unique identifier for the DNS forwarder.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/networking/v1/dns-forwarders/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

OAuth Tokens (sts/v1)

General Availability

OAuth Token is a JSON Web Token (JWT) that enables the use of external identities to access Confluent Cloud APIs

Exchange an OAuth Token

General Availability

Use this operation to exchange an access token (JWT) issued by an external identity provider for an access token (JWT) issued by Confluent.This enables the use of external identities to access Confluent Cloud APIs.

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string
extensible-enum: ["urn:ietf:params:oauth:grant-type:token-exchange"]

The grant type. Must be urn:ietf:params:oauth:grant-type:token-exchange, which indicates a token exchange.

subject_token
required
string

Confluent Cloud only accepts JSON Web Token (JWT) access tokens from customer identity provider

identity_pool_id
required
string

Identity pool is a group of external identities that are assigned a certain level of access based on policy

subject_token_type
required
string
extensible-enum: ["urn:ietf:params:oauth:token-type:jwt"]

An identifier for the type of requested security token. Supported values is urn:ietf:params:oauth:token-type:jwt.

requested_token_type
required
string
extensible-enum: ["urn:ietf:params:oauth:token-type:access_token"]

An identifier for the type of requested security token. Supported values is urn:ietf:params:oauth:token-type:access_token.

expires_in
integer <int32> <= 900
Default: 900

The amount of time, in seconds, between the time when the access token was issued and the time when the access token will expire

Responses

Request samples

curl --request POST \
  --url https://api.confluent.cloud/sts/v1/oauth2/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange \
  --data subject_token=test_jwt_token \
  --data identity_pool_id=pool_1 \
  --data subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt \
  --data requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token \
  --data expires_in=900

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Client Quotas (kafka-quotas/v1)

General Availability

ClientQuota objects represent Client Quotas you can set at the service account level.

The API allows you to list, create, read, update, and delete your client quotas.

Related guide: Client Quotas in Confluent Cloud.

The Client Quotas Model

api_version
string
Value: "kafka-quotas/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ClientQuota"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (kafka-quotas.v1.ClientQuotaSpec)

The desired state of the Client Quota

{
  • "api_version": "kafka-quotas/v1",
  • "kind": "ClientQuota",
  • "id": "dlz-f3a90de",
  • "metadata": {},
  • "spec": {}
}

List of Client Quotas

General Availability

Retrieve a sorted, filtered, paginated list of all client quotas.

Authorizations:
api-key
query Parameters
spec.cluster
required
string (SearchFilter)
Example: spec.cluster=lkc-xxxxx

Filter the results by exact match for spec.cluster.

environment
required
string (SearchFilter)
Example: environment=env-xxxxx

Filter the results by exact match for environment.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/kafka-quotas/v1/client-quotas?spec.cluster=lkc-xxxxx&environment=env-xxxxx' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Client Quota

General Availability

Make a request to create a client quota.

Authorizations:
api-key
Request Body schema: application/json
required
object

The desired state of the Client Quota

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Client Quota

General Availability

Make a request to read a client quota.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the client quota.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/kafka-quotas/v1/client-quotas/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Client Quota

General Availability

Make a request to update a client quota.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the client quota.

Request Body schema: application/json
required
object

The desired state of the Client Quota

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Client Quota

General Availability

Make a request to delete a client quota.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the client quota.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/kafka-quotas/v1/client-quotas/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Pipelines (sd/v1)

General Availability

Pipeline objects represent information about a user-defined pipeline of Confluent Cloud components. The pipeline's content is available separately.

The API allows you to create, retrieve, update, and delete your pipelines, as well as list all of your pipelines for the particular environment and Kafka cluster.

Related guide: Pipelines in Confluent Cloud.

The Pipelines Model

api_version
string
Value: "sd/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Pipeline"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (sd.v1.PipelineSpec)

The desired state of the Pipeline

object (sd.v1.PipelineStatus)

The status of the Pipeline

{
  • "api_version": "sd/v1",
  • "kind": "Pipeline",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
pipelines_per_org Pipelines in one Confluent Cloud organization
pipelines_per_cluster Pipelines in one Confluent Cloud Kafka cluster

List of Pipelines

General Availability

Retrieve a sorted, filtered, paginated list of all pipelines.

Authorizations:
api-key
query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

spec.kafka_cluster
required
string (SearchFilter)
Example: spec.kafka_cluster=lkc-00000

Filter the results by exact match for spec.kafka_cluster.

page_size
integer <= 100
Default: 100

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/sd/v1/pipelines?environment=env-00000&spec.kafka_cluster=lkc-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Pipeline

General Availability

Make a request to create a pipeline.

Authorizations:
api-key
Request Body schema: application/json
required
object

The desired state of the Pipeline

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Pipeline

General Availability

Make a request to read a pipeline.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the pipeline.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

spec.kafka_cluster
required
string (SearchFilter)
Example: spec.kafka_cluster=lkc-00000

Scope the operation to the given spec.kafka_cluster.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/sd/v1/pipelines/{id}?environment=env-00000&spec.kafka_cluster=lkc-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Pipeline

General Availability

Make a request to update a pipeline.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the pipeline.

Request Body schema: application/json
required
object

The desired state of the Pipeline

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Pipeline

General Availability

Make a request to delete a pipeline.

Authorizations:
api-key
path Parameters
id
required
string

The unique identifier for the pipeline.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

spec.kafka_cluster
required
string (SearchFilter)
Example: spec.kafka_cluster=lkc-00000

Scope the operation to the given spec.kafka_cluster.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/sd/v1/pipelines/{id}?environment=env-00000&spec.kafka_cluster=lkc-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Keys (byok/v1)

General Availability

Key objects represent customer managed keys on dedicated Confluent Cloud clusters.

Keys are used to protect data at rest stored in your dedicated Confluent Cloud clusters on AWS, Azure, and GCP. This API allows you to upload and retrieve self-managed keys on Confluent Cloud.

Related guide: Confluent Cloud Bring Your Own Key (BYOK) Management API.

The Keys Model

api_version
string
Value: "byok/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Key"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object

The cloud-specific key details.

For AWS, provide the corresponding key_arn.

For Azure, provide the corresponding key_id.

For GCP, provide the corresponding key_id.

provider
string
extensible-enum: ["AWS","AZURE","GCP"]

The cloud provider of the Key.

state
string
extensible-enum: ["AVAILABLE","IN_USE"]

The state of the key: AVAILABLE: key can be used for a Kafka cluster provisioning IN_USE: key is already in use by a Kafka cluster provisioning

{
  • "api_version": "byok/v1",
  • "kind": "Key",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "key": {
    },
  • "provider": "AWS",
  • "state": "IN_USE"
}

Quotas and Limits

This resource is subject to the following quotas:

Quota Description
byok.max_keys.per_org BYOK keys in one Confluent Cloud organisation.

List of Keys

General Availability

Retrieve a sorted, filtered, paginated list of all keys.

Authorizations:
cloud-api-key
query Parameters
provider
string (SearchFilter)
Example: provider=AWS

Filter the results by exact match for provider.

state
string (SearchFilter)
Example: state=IN_USE

Filter the results by exact match for state.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/byok/v1/keys?provider=AWS&state=IN_USE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Key

General Availability

Make a request to create a key.

Authorizations:
cloud-api-key
Request Body schema: application/json
required
object

The cloud-specific key details.

For AWS, provide the corresponding key_arn.

For Azure, provide the corresponding key_id.

For GCP, provide the corresponding key_id.

Responses

Request samples

Content type
application/json
{
  • "key": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "byok/v1",
  • "kind": "Key",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "key": {
    },
  • "provider": "AWS",
  • "state": "IN_USE"
}

Read a Key

General Availability

Make a request to read a key.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the key.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/byok/v1/keys/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "byok/v1",
  • "kind": "Key",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "key": {
    },
  • "provider": "AWS",
  • "state": "IN_USE"
}

Delete a Key

General Availability

Make a request to delete a key.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the key.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/byok/v1/keys/{id}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Costs (billing/v1)

General Availability

Cost objects represent the aggregated billing costs for an organization

Related guide: Retrieve costs for a range of dates.

The Costs Model

api_version
string
Value: "billing/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Cost"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

start_date
string <date>

Start date of time period (inclusive) to retrieve billing costs. It is represented in RFC3339 format and is in UTC.

end_date
string <date>

End date of time period (exclusive) to retrieve billing costs. It is represented in RFC3339 format and is in UTC.

granularity
string
Default: "DAILY"
extensible-enum: ["DAILY"]

Granularity at which each line item is aggregated.

network_access_type
string
extensible-enum: ["INTERNET","TRANSIT_GATEWAY","PRIVATE_LINK","PEERED_VPC"]

Network access type for the cluster.

product
string
extensible-enum: ["KAFKA","CONNECT","KSQL","AUDIT_LOG","STREAM_GOVERNANCE","CLUSTER_LINK","CUSTOM_CONNECT","SUPPORT_CLOUD_BASIC","SUPPORT_CLOUD_DEVELOPER","SUPPORT_CLOUD_BUSINESS","SUPPORT_CLOUD_PREMIER"]

Product name.

line_type
string
extensible-enum: ["KAFKA_STORAGE","KAFKA_PARTITION","KAFKA_NETWORK_READ","KAFKA_NETWORK_WRITE","KAFKA_BASE","KAFKA_NUM_CKUS","KAFKA_REST_PRODUCE","KSQL_NUM_CSUS","CONNECT_CAPACITY","CONNECT_NUM_TASKS","CONNECT_THROUGHPUT","CONNECT_NUM_RECORDS","SUPPORT","CLUSTER_LINKING_PER_LINK","CLUSTER_LINKING_WRITE","CLUSTER_LINKING_READ","AUDIT_LOG_READ","GOVERNANCE_BASE","SCHEMA_REGISTRY","PROMO_CREDIT","CUSTOM_CONNECT_NUM_TASKS","CUSTOM_CONNECT_THROUGHPUT"]

Type of the line item.

price
number <double>

Price for the line item in dollars.

unit
string

Unit of the line item.

quantity
number <double>

Quantity of the line item.

original_amount
number <double>

Original amount accrued for this line item.

discount_amount
number <double>

Amount discounted from the original amount in dollars.

amount
number <double>

Final amount after deducting discounts.

object

The resource for a given object

{
  • "api_version": "billing/v1",
  • "kind": "Cost",
  • "id": "dlz-f3a90de",
  • "start_date": "2022-10-12",
  • "end_date": "2022-10-15",
  • "granularity": "DAILY",
  • "network_access_type": "INTERNET",
  • "product": "KAFKA",
  • "line_type": "KAFKA_NUM_CKUS",
  • "price": 1.5,
  • "unit": "GB",
  • "quantity": 99.9,
  • "original_amount": 149.85,
  • "discount_amount": 20.85,
  • "amount": 129,
  • "resource": {
    }
}

List of Costs

General Availability

Retrieve a sorted, filtered, paginated list of all costs.

Authorizations:
cloud-api-key
query Parameters
start_date
required
string (SearchFilter)
Example: start_date=2022-10-12

Filter the results by exact match for start_date.

end_date
required
string (SearchFilter)
Example: end_date=2022-10-15

Filter the results by exact match for end_date.

page_size
integer <= 10000
Default: 5000

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/billing/v1/costs?start_date=2022-10-12&end_date=2022-10-15' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Compute Pools (fcpm/v2)

General Availability

A Compute Pool represents a set of compute resources that is used to run your Queries. The resources (CPUs, memory,…) provided by a Compute Pool are shared between all Queries that use it.

The Compute Pools Model

api_version
string
Value: "fcpm/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "ComputePool"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

object (fcpm.v2.ComputePoolSpec)

The desired state of the Compute Pool

object (fcpm.v2.ComputePoolStatus)

The status of the Compute Pool

{
  • "api_version": "fcpm/v2",
  • "kind": "ComputePool",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "spec": {},
  • "status": {
    }
}

List of Compute Pools

General Availability

Retrieve a sorted, filtered, paginated list of all compute pools.

Authorizations:
cloud-api-key
query Parameters
spec.region
string (SearchFilter)
Example: spec.region=us-west-1

Filter the results by exact match for spec.region.

environment
required
string (SearchFilter)
Example: environment=env-00000

Filter the results by exact match for environment.

spec.network
string (SearchFilter)
Example: spec.network=n-00000

Filter the results by exact match for spec.network.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/fcpm/v2/compute-pools?spec.region=us-west-1&environment=env-00000&spec.network=n-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Compute Pool

General Availability

Make a request to create a compute pool.

Authorizations:
cloud-api-key
Request Body schema: application/json
required
object

The desired state of the Compute Pool

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Read a Compute Pool

General Availability

Make a request to read a compute pool.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the compute pool.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/fcpm/v2/compute-pools/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Compute Pool

General Availability

Make a request to update a compute pool.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the compute pool.

Request Body schema: application/json
required
object

The desired state of the Compute Pool

Responses

Request samples

Content type
application/json
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{}

Delete a Compute Pool

General Availability

Make a request to delete a compute pool.

Authorizations:
cloud-api-key
path Parameters
id
required
string

The unique identifier for the compute pool.

query Parameters
environment
required
string (SearchFilter)
Example: environment=env-00000

Scope the operation to the given environment.

Responses

Request samples

curl --request DELETE \
  --url 'https://api.confluent.cloud/fcpm/v2/compute-pools/{id}?environment=env-00000' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Regions (fcpm/v2)

General Availability

Region objects represent cloud provider regions available when placing Flink compute pools. The API allows you to list Flink regions.

The Regions Model

api_version
string
Value: "fcpm/v2"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Region"

Kind defines the object this REST resource represents.

id
string <= 255 characters

ID is the "natural identifier" for an object within its scope/namespace; it is normally unique across time but not space. That is, you can assume that the ID will not be reclaimed and reused after an object is deleted ("time"); however, it may collide with IDs for other object kinds or objects of the same kind within a different scope/namespace ("space").

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

display_name
string

The display name.

cloud
string
extensible-enum: ["AWS","GCP","AZURE"]

The cloud service provider that hosts the region.

region_name
string

The region name.

http_endpoint
string <uri>

The regional API endpoint for flink compute pools.

{
  • "api_version": "fcpm/v2",
  • "kind": "Region",
  • "id": "dlz-f3a90de",
  • "metadata": {
    },
  • "display_name": "Ohio (us-east-2)",
  • "cloud": "AWS",
  • "region_name": "us-east-2",
  • "http_endpoint": "http://example.com"
}

List of Regions

General Availability

Retrieve a sorted, filtered, paginated list of all regions.

Authorizations:
cloud-api-key
query Parameters
cloud
string (SearchFilter)
Example: cloud=AWS

Filter the results by exact match for cloud.

region_name
string (SearchFilter)
Example: region_name=us-east-2

Filter the results by exact match for region_name.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://api.confluent.cloud/fcpm/v2/regions?cloud=AWS&region_name=us-east-2' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Statements (sql/v1)

General Availability

Statement represents a core resource used to model SQL statements for execution. A statement generalizes DDL, DML, DQL, etc., but doesn’t attempt to handle session management or any higher-level functionality. The API allows you to list, create, read, and delete your statements.

The Statements Model

api_version
string
Value: "sql/v1"

APIVersion defines the schema version of this representation of a resource.

kind
string
Value: "Statement"

Kind defines the object this REST resource represents.

object

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

name
string <= 100 characters [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-...

The user provided name of the resource, unique within this environment.

organization_id
string <uuid>

The unique identifier for the organization.

environment_id
string

The unique identifier for the environment.

object (sql.v1.StatementSpec)

The specs of the Statement

object (sql.v1.StatementStatus)

The status of the Statement

{
  • "api_version": "sql/v1",
  • "kind": "Statement",
  • "metadata": {},
  • "name": "sql123",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "environment_id": "string",
  • "spec": {
    },
  • "status": {
    }
}

List of Statements

General Availability

Retrieve a sorted, filtered, paginated list of all statements.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

query Parameters
spec.compute_pool_id
string
Example: spec.compute_pool_id=lfcp-00000

Filter the results by exact match for spec.compute_pool.

page_size
integer <= 100
Default: 10

A pagination size for collection requests.

page_token
string <= 255 characters

An opaque pagination token for collection requests.

Responses

Request samples

curl --request GET \
  --url 'https://flink.region.provider.confluent.cloud/sql/v1/organizations/{organization_id}/environments/{environment_id}/statements' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Statement

General Availability

Make a request to create a statement.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

Request Body schema: application/json
name
required
string <= 100 characters [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-...

The user provided name of the resource, unique within this environment.

organization_id
string <uuid>

The unique identifier for the organization.

environment_id
string

The unique identifier for the environment.

required
object

The specs of the Statement

Responses

Request samples

Content type
application/json
{
  • "name": "sql123",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "environment_id": "string",
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "api_version": "sql/v1",
  • "kind": "Statement",
  • "metadata": {},
  • "name": "sql123",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "environment_id": "string",
  • "spec": {
    },
  • "status": {
    }
}

Read a Statement

General Availability

Make a request to read a statement.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

statement_name
required
string

The unique identifier for the statement.

Responses

Request samples

curl --request GET \
  --url 'https://flink.region.provider.confluent.cloud/sql/v1/organizations/{organization_id}/environments/{environment_id}/statements/{statement_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "api_version": "sql/v1",
  • "kind": "Statement",
  • "metadata": {},
  • "name": "sql123",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "environment_id": "string",
  • "spec": {
    },
  • "status": {
    }
}

Delete a Statement

General Availability

Make a request to delete a statement.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

statement_name
required
string

The unique identifier for the statement.

Responses

Request samples

curl --request DELETE \
  --url 'https://flink.region.provider.confluent.cloud/sql/v1/organizations/{organization_id}/environments/{environment_id}/statements/{statement_name}' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Update a Statement

General Availability

Make a request to update a statement.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

statement_name
required
string

The unique identifier for the statement.

Request Body schema: application/json
name
required
string <= 100 characters [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-...

The user provided name of the resource, unique within this environment.

organization_id
string <uuid>

The unique identifier for the organization.

environment_id
string

The unique identifier for the environment.

required
object

The specs of the Statement

Responses

Request samples

Content type
application/json
{
  • "name": "sql123",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "environment_id": "string",
  • "spec": {
    },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Statement Results (sql/v1)

General Availability

StatementResult represents a result of a Statement resource. The API allows you to read your statement's results.

The Statement Results Model

api_version
required
string
Value: "sql/v1"

APIVersion defines the schema version of this representation of a resource.

kind
required
string
Value: "StatementResult"

Kind defines the object this REST resource represents.

required
object

ListMeta describes metadata that resource collections may have

object

A results property that contains a data property that contains an array of results.

{}

Read Statement Result

General Availability

Read Statement Result.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

name
required
string

The unique identifier for the statement.

query Parameters
page_token
string <= 255 characters

It contains the field offset in the CollectSinkFunction protocol. On the first request, it should be unset. The offset is assumed to start at 0.

Responses

Request samples

curl --request GET \
  --url 'https://flink.region.provider.confluent.cloud/sql/v1/organizations/{organization_id}/environments/{environment_id}/statements/{name}/results' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Statement Exceptions (sql/v1)

General Availability

StatementException represents an exception of a Statement resource. The API allows you to read your statement's exceptions.

The Statement Exceptions Model

kind
string
Value: "StatementException"

Kind defines the object this REST resource represents.

name
string

Name of the SQL statement exception.

message
string

Error message of the statement exception.

timestamp
string <date-time>

The date and time at which the exception occurred. It is represented in RFC3339 format and is in UTC.

{
  • "kind": "StatementException",
  • "name": "java.lang.RuntimeException",
  • "message": "java.lang.RuntimeException: An error occurred",
  • "timestamp": "2023-03-31T00:00:00-00:00"
}

List of Statement Exceptions

General Availability

Retrieve a list of the 10 most recent statement exceptions.

Authorizations:
resource-api-key
path Parameters
organization_id
required
string <uuid>

The unique identifier for the organization.

environment_id
required
string

The unique identifier for the environment.

statement_name
required
string

The unique identifier for the statement.

Responses

Request samples

curl --request GET \
  --url 'https://flink.region.provider.confluent.cloud/sql/v1/organizations/{organization_id}/environments/{environment_id}/statements/{statement_name}/exceptions' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}