Schema Registry Clusters API Quick Start for Confluent Cloud

This page provides links to the Confluent Cloud Schema Registry API reference, a concept introduction to the model, an explanation of how to test the API calls, and detailed usage examples for all available actions.

APIs

Take me directly to the API reference:

• Regions (srcm/v2)
• Clusters (srcm/v2)

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:

• List regions
• Read a region

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

• List clusters
• Create a cluster
• Read a cluster
• Update a cluster
• Delete a cluster

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

Related content

• Regions (srcm/v2)
• Clusters (srcm/v2)
• Schema Registry Regions