1. Home
  2. Cloud
  3. Govern Streams and Schemas in Confluent Cloud
  4. Stream Governance in Confluent Cloud

Schema Registry Clusters API Quick Start

APIs

Take me directly to the API reference:

Overview

Stream Governance is available on several Confluent Cloud hosted regions into which you can provision per-environment Schema Registry Clusters with Essentials or Advanced packages.

In addition to managing these Schema Registry Clusters with the Confluent Cloud Console and Confluent CLI , you can use a collection of REST APIs to provision and enable Stream Governance packages for your Confluent Cloud environments.

Most actions described below relate to managing Schema Registry Clusters (list, create, read, update, and so on). Two read-only actions are available to get the Schema Registry region information you need to provide in order to create Schema Registry Clusters.

This document is meant to supplement the API reference documentation for Schema Registry regions and clusters, which is linked below.

You can perform the following operations on Schema Registry Regions with this API:

You can perform the following operations on Schema Registry Clusters with this API:

Base URL

The base URL for Schema Registry region and cluster management calls is:

https://api.confluent.cloud/

Object model

All Confluent objects share a set of common properties:

  • api_version: Indicates the API version for the object. The version for these APIs is srcm/v2.
  • kind: Indicates what kind of object it is.
  • id: An identifier for the object.

Authentication

Each request to the server must include an Authorization: Basic {key} header that contains a Confluent Cloud API key. For more details on creating or accessing your Confluent Cloud API keys, see Cloud API keys. API requests without a correct authentication header will fail. An API key grants access to a single Confluent cluster.

These keys grant API access to many resources, and should not be shared publicly to GitHub, in client-side code, and so forth.

HTTP Basic authorization requires the key to be colon-separated and base64-encoded.

For example, if your API Key is abcp7DEFGH123456789 and the corresponding Secret is XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO, generate a base64-encoded header with the following command on MacOS or Linux:

echo -n "abcp7DEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

The resulting authorization header will be:

Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=

Alternatively, if testing using Postman, specify Basic Auth and provide the API Key as the Username and the API Secret as the password and Postman will provide the encoding.

How to Test Using curl

The sections that follow describe how to format the API calls with GET and POST, as you would incorporate into your code. You can test the calls against Confluent Cloud from the command line using curl commands. You will need to log in to Confluent Cloud to do this. If you are new to the Confluent CLI, check out this handy commands reference.

For example:

  1. Log on to Confluent Cloud with the Confluent CLI. (Provide username and password at prompts.)

    confluent login --url https://confluent.cloud

  2. Create a Confluent Cloud API key and secret:

    confluent api-key create --resource cloud

  3. Store the key and secret in variables:

    export CCLOUD_KEY=<generated-API-key>

    export CCLOUD_SECRET=<generated-API-secret>

  4. Store the URL for Confluent Cloud in a variable:

    export CCLOUD_URL=https://api.confluent.cloud/

    Tip

    The URL https://confluent.cloud/api should also work here.

  5. Now, use curl to run the API call to list Schema Registry regions:

    curl -u $CCLOUD_KEY:$CCLOUD_SECRET "$CCLOUD_URL/srcm/v2/regions"

    Your output should be similar to that shown in the example response for List regions below.

Schema Registry regions

List regions

Request example

API reference link: List of Regions

The following example shows how to list all available regions.

GET /srcm/v2/regions

Your request can include the following query parameters:

Parameter Required or Optional Description
spec.cloud Optional Filter results by cloud provider name, such as AWS
spec.region.name Optional Filter results by cloud provider region name, such as us-east-2.
spec.packages Optional Filters for the specified package type. Valid values are ESSENTIALS or ADVANCED. Note that this parameter (spec.packages) can be repeated, and the API will return regions that match any of the provided values.
page_size Optional Specifies an integer page size for the returned payload. Max value is 100. Default: 10.
page_token Optional Contains the opaque pagination token string.

Example response

A successful call returns an HTTP 200 OK and a JSON payload that shows all available regions (if no filters are applied). The metadata for each region describes the Cloud, display name, the packages in which it is available, and the region name. A subset of the output is shown below as an example.

{
  "api_version": "srcm/v2",
  "kind": "RegionList",
  "metadata": {
    "first": "https://api.confluent.cloud/srcm/v2/regions",
    "last": "https://api.confluent.cloud/srcm/v2/regions?page_token=bcAOehAY8F16YD84Z1wT",
    "prev": "https://api.confluent.cloud/srcm/v2/regions?page_token=YIXRY97wWYmwzrax4dld",
    "next": "https://api.confluent.cloud/srcm/v2/regions?page_token=UvmDWOB1iwfAIBPj6EYb",
    "total_size": 123
  },
  "data": [
    {
      "api_version": "srcm/v2",
      "kind": "Region",
      "id": "sgreg-1",
      "metadata": {
        "self": "https://api.confluent.cloud/srcm/v2/regions/sgreg-1",
        "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-1",
        "created_at": "2006-01-02T15:04:05-07:00",
        "updated_at": "2006-01-02T15:04:05-07:00",
        "deleted_at": "2006-01-02T15:04:05-07:00"
      },
      "spec": {
        "display_name": "Ohio (us-east-2)",
        "cloud": "AWS",
        "region_name": "us-east-2",
        "packages": [
          "ESSENTIALS",
          "ADVANCED"
        ]
      }
    }
  ]
}

...

Read a region

API reference link: Read a Region

Request example

The following example shows how to read a specific region by providing the region ID (obtained from the previous call to list regions).

GET /srcm/v2/regions/{id}

Your request must include the following query parameter:

Parameter Required or Optional Description
id Required A string that is the unique identifier for the region.

Example response

{
  "api_version": "srcm/v2",
  "kind": "Region",
  "id": "sgreg-1",
  "metadata": {
    "self": "https://api.confluent.cloud/srcm/v2/regions/sgreg-1",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-1",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00",
    "deleted_at": "2006-01-02T15:04:05-07:00"
  },
  "spec": {
    "display_name": "Ohio (us-east-2)",
    "cloud": "AWS",
    "region_name": "us-east-2",
    "packages": [
      "ESSENTIALS",
      "ADVANCED"
    ]
  }
}

Schema Registry Cluster Management

List clusters

API reference link: List of Clusters

Request example

The following examples show how to retrieve a sorted, filtered, paginated list of all clusters.

GET /srcm/v2/clusters?environment={environment_id}

Your request can include the following query parameters:

Parameter Required or Optional Description
environment_id Required Filter results by exact match for this environment ID.
page_size Optional Specifies an integer page size for the returned payload. Max value is 100. Default: 10.
page_token Optional Contains the opaque pagination token string.

Example response

A successful call returns an HTTP 200 OK and a JSON payload that contains a list of Schema Registry Clusters for the environment. The response describes each cluster including the following information:

  • The associated Stream governance package.
  • The Schema Registry region for the cluster. See Cloud Providers and Region Support for a full list of Schema Registry regions.
  • The cluster status (PROVISIONED, PROVISIONING, FAILED).
  • Information about the environment that contains the cluster.
{
  "api_version": "srcm/v2",
  "kind": "ClusterList",
  "metadata": {
    "first": "https://api.confluent.cloud/srcm/v2/clusters",
    "last": "https://api.confluent.cloud/srcm/v2/clusters?page_token=bcAOehAY8F16YD84Z1wT",
    "prev": "https://api.confluent.cloud/srcm/v2/clusters?page_token=YIXRY97wWYmwzrax4dld",
    "next": "https://api.confluent.cloud/srcm/v2/clusters?page_token=UvmDWOB1iwfAIBPj6EYb",
    "total_size": 123
  },
  "data": [
    {
      "api_version": "srcm/v2",
      "kind": "Cluster",
      "id": "lsrc-12345",
      "metadata": {
        "self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
        "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
        "created_at": "2006-01-02T15:04:05-07:00",
        "updated_at": "2006-01-02T15:04:05-07:00",
        "deleted_at": "2006-01-02T15:04:05-07:00"
      },
      "spec": {
        "display_name": "Stream Governance package",
        "package": "ESSENTIALS",
        "http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
        "environment": {
          "id": "env-00000",
          "related": "https://api.confluent.cloud/v2/environments/env-00000",
          "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
        },
        "region": {
          "id": "sgreg-00000",
          "related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
          "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
        }
      },
      "status": {
        "phase": "PROVISIONED"
      }
    }
  ]
}

Create a cluster

API reference link: Create a Cluster

You can create a Schema Registry Cluster with a POST call to the cluster endpoint. Make sure you include the authorization header with your API key and API secret.

POST /srcm/v2/clusters

Request

When you make the request, include a JSON payload that contains a spec object showing the desired state of the cluster.

Request specification

Parameter Required or Optional Description
package Required Object that contains the Stream Governance package; either ESSENTIALS or ADVANCED.
environment Required Object that contains the environment identifier.
region Required Object that contains the Schema Registry region ID.

Request example

{
  "spec": {
    "package": "ESSENTIALS",
    "environment": {
      "id": "env-00000"
    },
    "region": {
      "id": "sgreg-00000"
    }
  }
}

Example response

Success returns an HTTP 202 ACCEPTED with a JSON payload that describes the cluster. The cluster description includes the following:

  • The associated Stream Governance package (ESSENTIALS or ADVANCED).
  • Information about the environment that contains the cluster.
  • The Schema Registry region ID.
  • The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
  "api_version": "srcm/v2",
  "kind": "Cluster",
  "id": "lsrc-12345",
  "metadata": {
    "self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00",
    "deleted_at": "2006-01-02T15:04:05-07:00"
  },
  "spec": {
    "display_name": "Stream Governance package",
    "package": "ESSENTIALS",
    "http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
    "environment": {
      "id": "env-00000",
      "related": "https://api.confluent.cloud/v2/environments/env-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
    },
    "region": {
      "id": "sgreg-00000",
      "related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
    }
  },
  "status": {
    "phase": "PROVISIONED"
  }
}

Read a cluster

API reference link: Read a Cluster

To read a Schema Registry Cluster, make a GET call to the cluster endpoint to retrieve details about a specified cluster. You must specify the environment and cluster identifiers in the request. This call does not require a payload. Make sure you include the authorization header with your API key and API secret.

Request example

GET /srcm/v2/clusters/{id}?environment={environment_id}

Your request must include the following parameters:

Parameter Required or Optional Description
id Required Path parameter specifying the identifier for the cluster to read.
environment Required Query parameter specifying the identifier for the environment that contains the cluster to read.

Example response

Success returns an HTTP 200 OK and the following JSON payload that describes the cluster, including the following:

  • The associated Stream Governance package (ESSENTIALS or ADVANCED).
  • Information about the environment that contains the cluster.
  • The Schema Registry region ID.
  • The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
  "api_version": "srcm/v2",
  "kind": "Cluster",
  "id": "lsrc-12345",
  "metadata": {
    "self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00",
    "deleted_at": "2006-01-02T15:04:05-07:00"
  },
  "spec": {
    "display_name": "Stream Governance package",
    "package": "ESSENTIALS",
    "http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
    "environment": {
      "id": "env-00000",
      "related": "https://api.confluent.cloud/v2/environments/env-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
    },
    "region": {
      "id": "sgreg-00000",
      "related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
    }
  },
  "status": {
    "phase": "PROVISIONED"
  }
}

Update a cluster

API reference link: Update a Cluster

You can update a cluster with an HTTP PATCH call to the cluster endpoint. You specify the environment and cluster identifiers in the request, and include a payload that contains details of the change. You can specify one change in the request:

  • Update the Stream Governance package type associated with the cluster: ESSENTIALS or ADVANCED. Note that clusters can be upgraded from ESSENTIALS to ADVANCED, but cannot be downgraded from ADVANCED to ESSENTIALS.

Make sure you include the authorization header with your API key and API secret.

Request example

PATCH /srcm/v2/clusters/{id}
Parameter Required or Optional Description
package Required String identifying the package to associate with the cluster.
environment Required Object specifying the identifier for the environment that contains the cluster to update.

The JSON payload contains a spec object with:

  • The ID for the environment that contains the Schema Registry Cluster.
  • The package type to associate with the Schema Registry Cluster.
{
  "spec": {
    "package": "ADVANCED",
    "environment": {
      "id": "env-00000"
    }
  }
}

Example response

Success returns a 200 OK and JSON payload that describes the updated cluster. Similiar to the other calls, the payload describes:

  • The associated Stream Governance package (ESSENTIALS or ADVANCED).
  • Information about the environment that contains the cluster.
  • The Schema Registry region ID.
  • The cluster status (PROVISIONED, PROVISIONING, FAILED).
{
  "api_version": "srcm/v2",
  "kind": "Cluster",
  "id": "dlz-f3a90de",
  "metadata": {
    "self": "https://api.confluent.cloud/srcm/v2/clusters/lsrc-12345",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-abc123/cloud-cluster=lsrc-12345",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00",
    "deleted_at": "2006-01-02T15:04:05-07:00"
  },
  "spec": {
    "display_name": "Stream Governance package",
    "package": "ESSENTIALS",
    "http_endpoint": "https://psrc-00000.us-central1.gcp.confluent.cloud",
    "environment": {
      "id": "env-00000",
      "related": "https://api.confluent.cloud/v2/environments/env-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
    },
    "region": {
      "id": "sgreg-00000",
      "related": "https://api.confluent.cloud/srcm/v2/regions/sgreg-00000",
      "resource_name": "https://api.confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/region=sgreg-00000"
    }
  },
  "status": {
    "phase": "PROVISIONED"
  }
}

Delete a cluster

API reference link: Delete a Cluster

You can delete a Schema Registry Cluster with a DELETE call to the cluster endpoint. You specify the environment and cluster identifiers in the request, and the call does not require a payload. Make sure you include the authorization header with your API key and API secret.

Note that once a cluster has been deleted, it cannot be restored.

Request example

DELETE /srcm/v2/clusters/{id}?environment={environment_id}
Parameter Required or Optional Description
id Required Path parameter specifying the identifier for the cluster to delete.
environment Required Query parameter specifying the identifier for the environment that contains the cluster to delete.

Example response

Success returns an HTTP 204 No Content.

For details on the types of responses you can expect when a call fails, see Failures.

Failures

When a failure occurs, you should receive one of the following statuses:

400 Bad Request
Typically a malformed or missing parameter or a parameter value that is not allowed.
401 Unauthorized
Typically invalid or missing authentication credentials.
403 Forbidden
Indicates the credentials provided are not valid for the resource. Make sure your cluster and environment identifiers are correct and match the credentials provided.
404 Not Found
Indicates the resource could not be found at the specified URL.
429 Rate Limit Exceeded
You have sent too many requests.
500 Oops something went wrong
An issue not covered by other errors.

The failure message body will provide more detail about the failure reason and an identifier to use with Confluent support if you need help solving the problem. The following example shows a 400 Bad Request error with details about why the call failed.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "errors": [
      {
           "id": "c9cb03c2878ca172bbd0072bd99a9aaa",
            "status": "400",
            "code": "parameter_missing",
            "detail": "Missing Parameter",
            "source": {
               "parameter": "environment"
             }
      }
   ]
 }