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

Confluent Cloud APIs

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.

Introduction

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. Please review the example request and response bodies in the Connect v1 API documentation below 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 (e.g., throughput or SLOs) and it will figure out how to make it happen (e.g., 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 for integrating with Confluent Cloud. Integrations must be authorized and authenticated before they can access or manage resources in Confluent Cloud. You can manage your API keys in the Confluent Cloud Dashboard or Confluent Cloud CLI. See the docs for details on creating and managing API keys.

Today, you can divide API keys into two classes:

  • Cloud API Keys – These grant access to the Confluent Cloud Control Plane APIs, such as for Provisioning and Metrics integrations.
  • Cluster API Keys – These grant access to a single Confluent cluster, such as a specific Kafka or Schema Registry cluster.

An API key is owned by a 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 Cluster API Key for neptune owned by Armageddon will have these ACLs.
  • Note 1: ACLs aren't currently enforced for users, only service accounts.
  • Note 2: API Keys are automatically deleted when the owning user or service account is deleted (e.g., an employee leaves the company, or moves to a new department and an SSO integration removes their user in Confluent Cloud as they no longer require access)
  • Confluent strongly recommend that you use service accounts for all production-critical access.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

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

To use your API key, send it as an Authorization: Basic {key} header. Remember that HTTP Basic authorization requires you to colon-separate and base64 encode your key. For example, if your API Key ID is ABCDEFGH123456789 and the corresponding API Key Secret is XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO, then the authorization header will be

Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=

This example header can be generated from the API key (on Mac OS X) with

$ echo -n "ABCDEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

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

oauth

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

Security Scheme Type OAuth2
clientCredentials OAuth Flow
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.

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
Environment crn://confluent.cloud/environment=e-xyz1234
User crn://confluent.cloud/user=u-rst9876
API Key crn://confluent.cloud/api-key=ABCDEFG9876543210
Service Account crn://confluent.cloud/service-account=sa-lmn2468
Service Account Key crn://confluent.cloud/service-account-key=HIJKLMN0123456789
Kafka Cluster crn://confluent.cloud/kafka=lkc-abc123

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.

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. For Closed Previews, users must be granted explicit access to the API by Confluent.
  • Generally Available (GA) – Will not change at short notice. Recommended for production usage. Officially supported by Confluent for non-production and production usage.
  • Deprecated – No longer supported. Will be removed in the future at the announced date. Use is discouraged and migration following the upgrade guide is recommended.
  • Sunset – Removed, and no longer supported or available.

Resources, operations, and individual fields in the OpenAPI spec will be annotated with x-lifecycle-stage, x-deprecated-at, and x-sunset-at. These annotations will appear in the corresponding API Reference Documentation. 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.

Api Keys (iam/v2)

Early Access Request Access To API Keys Management API v2

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 or Schema Registry. 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.

secret
string

The API key secret. Only provided in create responses, not in get or list.

display_name
string

A human readable name for the API key

description
string

A human readable description for the API key

object

The owner to which this belongs. The owner can be one of iam.v2.User, iam.v2.ServiceAccount.

object

The resource associated with this object. The resource can be one of cmk.v2.KafkaCluster.

{
  • "api_version": "iam/v2",
  • "kind": "ApiKey",
  • "id": "dlz-f3a90de",
  • "metadata":
    {
    },
  • "secret": "R15hoiDIq8Nxu/lY4mPO3DwAVIfU5W7OI+efsB607mLgHTnVW5XJGVqX2ysDx987",
  • "display_name": "CI kafka access key",
  • "description": "This API key provides kafka access to cluster x",
  • "owner":
    {},
  • "resource":
    {}
}

List of Api Keys

Early Access Request Access To API Keys Management API v2

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:
query Parameters
owner
string (SearchFilter)

Filter the results by exact match for owner.

resource
string (SearchFilter)

Filter the results by exact match for 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?owner=SOME_STRING_VALUE&resource=SOME_STRING_VALUE&page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Api Key

Early Access Request Access To API Keys Management API v2

Make a request to create an api key.

Authorizations:
Request Body schema: application/json
display_name
string

A human readable name for the API key

description
string

A human readable description for the API key

required
object

The owner to which this belongs. The owner can be one of iam.v2.User, iam.v2.ServiceAccount.

resource
object Recursive

The resource associated with this object. The resource can be one of cmk.v2.KafkaCluster.

Responses

Request samples

Content type
application/json
{
  • "display_name": "CI kafka access key",
  • "description": "This API key provides kafka access to cluster x",
  • "owner":
    {
    },
  • "resource":
    {
    }
}

Response samples

Content type
application/json
{}

Delete an Api Key

Early Access Request Access To API Keys Management API v2

Make a request to delete an api key.

Authorizations:
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":
    [
    ]
}

Update an Api Key

Early Access Request Access To API Keys Management API v2

Make a request to update an api key.

Authorizations:
path Parameters
id
required
string

The unique identifier for the api key.

Request Body schema: application/json
display_name
string

A human readable name for the API key

description
string

A human readable description for the API key

Responses

Request samples

Content type
application/json
{
  • "display_name": "CI kafka access key",
  • "description": "This API key provides kafka access to cluster x"
}

Response samples

Content type
application/json
{}

Read an Api Key

Early Access Request Access To API Keys Management API v2

Make a request to read an api key.

Authorizations:
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
{}

Users (iam/v2)

Generally Available

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

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

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

Generally Available

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

Authorizations:
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?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a User

Generally Available

Make a request to read a user.

Authorizations:
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"
}

Update a User

Generally Available

Make a request to update a user.

Authorizations:
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"
}

Delete a User

Generally Available

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

Generally Available

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

Generally Available

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

Authorizations:
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?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Service Account

Generally Available

Make a request to create a service account.

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

Generally Available

Make a request to read a service account.

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

Generally Available

Make a request to update a service account.

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

Generally Available

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:
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":
    [
    ]
}

Role Bindings (iam/v2)

Generally Available

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

Generally Available

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

Authorizations:
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 <= 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/role-bindings?principal=SOME_STRING_VALUE&role_name=SOME_STRING_VALUE&crn_pattern=SOME_STRING_VALUE&page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Role Binding

Generally Available

Make a request to create a role binding.

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

Generally Available

Make a request to read a role binding.

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

Generally Available

Make a request to delete a role binding.

Authorizations:
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
{
  • "errors":
    [
    ]
}

Environments (org/v2)

Generally Available

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

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

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

Generally Available

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

Authorizations:
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?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Environment

Generally Available

Make a request to create an environment.

Authorizations:
Request Body schema: application/json
display_name
required
string

A human-readable name for the Environment

Responses

Request samples

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

Response samples

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

Read an Environment

Generally Available

Make a request to read an environment.

Authorizations:
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"
}

Update an Environment

Generally Available

Make a request to update an environment.

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

Responses

Request samples

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

Response samples

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

Delete an Environment

Generally Available

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:
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":
    [
    ]
}

Subscriptions (notifications/v1)

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 retrieve, update, and delete subscriptions, as well as to view the list of all your subscriptions.

Related guide: Proactive Support for Confluent Platform in Confluent Cloud.

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.

display_name
string <= 64 characters

A human readable name for the particular subscription

description
string <= 128 characters

A human readable description for the particular subscription

object

The type of notification to subscribe to.

Array of objects (ObjectReference) non-empty

Integrations to which notifications are to be sent.

{
  • "api_version": "notifications/v1",
  • "kind": "Subscription",
  • "id": "dlz-f3a90de",
  • "metadata":
    {},
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "notification_type":
    {},
  • "integrations":
    []
}

List of Subscriptions

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

Authorizations:
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/notifications/v1/subscriptions?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Subscription

Make a request to create a subscription.

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

A human readable name for the particular subscription

description
string <= 128 characters

A human readable description for the particular subscription

required
object

The type of notification to subscribe to.

required
Array of objects (ObjectReference) non-empty

Integrations to which notifications are to be sent.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "notification_type":
    {
    },
  • "integrations":
    [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "Subscription",
  • "id": "dlz-f3a90de",
  • "metadata":
    {},
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "notification_type":
    {},
  • "integrations":
    []
}

Read a Subscription

Make a request to read a subscription.

Authorizations:
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
{
  • "api_version": "notifications/v1",
  • "kind": "Subscription",
  • "id": "dlz-f3a90de",
  • "metadata":
    {},
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "notification_type":
    {},
  • "integrations":
    []
}

Update a Subscription

Make a request to update a subscription.

Authorizations:
path Parameters
id
required
string

The unique identifier for the subscription.

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

A human readable name for the particular subscription

description
string <= 128 characters

A human readable description for the particular subscription

Array of objects (ObjectReference) non-empty

Integrations to which notifications are to be sent.

Responses

Request samples

Content type
application/json
{
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "integrations":
    [
    ]
}

Response samples

Content type
application/json
{
  • "api_version": "notifications/v1",
  • "kind": "Subscription",
  • "id": "dlz-f3a90de",
  • "metadata":
    {},
  • "display_name": "Slack Subscription",
  • "description": "Delivers alerts on the admin channel",
  • "notification_type":
    {},
  • "integrations":
    []
}

Delete a Subscription

Make a request to delete a subscription.

Authorizations:
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)

You can create an Integration to specify how we can notify you when we receive an alert/notification for a subscription.

Related guide: Proactive Support for Confluent Platform in Confluent Cloud.

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

A human readable name for the particular integration

description
string

A human readable description for the particular integration

any

Integration-specific details (integration targets)

{}

List of Integrations

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

Authorizations:
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/notifications/v1/integrations?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create an Integration

Make a request to create an integration.

Authorizations:
Request Body schema: application/json
display_name
required
string

A human readable name for the particular integration

description
string

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
{}

Read an Integration

Make a request to read an integration.

Authorizations:
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
{}

Update an Integration

Make a request to update an integration.

Authorizations:
path Parameters
id
required
string

The unique identifier for the integration.

Request Body schema: application/json
display_name
string

A human readable name for the particular integration

description
string

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
{}

Delete an Integration

Make a request to delete an integration.

Authorizations:
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 an integration

Sends a test notification to validate the integration.

Authorizations:
Request Body schema: application/json
display_name
required
string

A human readable name for the particular integration

description
string

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)

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

Related guide: Proactive Support for Confluent Platform in Confluent Cloud.

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

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

Authorizations:
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/notifications/v1/notification-types?page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Read a Notification Type

Make a request to read a notification type.

Authorizations:
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)

Generally Available

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

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

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

Generally Available

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

Authorizations:
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=SOME_STRING_VALUE&spec.network=SOME_ARRAY_VALUE&page_size=SOME_INTEGER_VALUE&page_token=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Create a Cluster

Generally Available

Make a request to create a cluster.

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

Generally Available

Make a request to read a cluster.

Authorizations:
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=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

Content type
application/json
{}

Update a Cluster

Generally Available

Make a request to update a cluster.

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

Generally Available

Make a request to delete a cluster.

Authorizations:
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=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

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

Connectors (v1)

General Availability

API for managing connectors.

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

Connect metrics are available through Metrics v2 API.

Related guide: Confluent Cloud API and Fully-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:
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"
]

Create a Connector

General Availability

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

Authorizations:
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"
}

Read a Connector Configuration

General Availability

Get the configuration for the connector.

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

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.

property name*
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:
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:
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 (v1)

General Availability

API for managing lifecycle of connectors. 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:
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:
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 (v1)

General Availability

API for requesting the status of a connector or the tasks of a connector.

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:
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:
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
[
  • {
    }
]

Plugins (v1)

General Availability

API for managing connector plugins.

List of Connector Plugins

General Availability

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

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