Kafka Schema Registry REST API Examples

Worked examples for each supported endpoint. For the complete endpoint list, unsupported endpoints, and behavior differences, see Confluent API compatibility.

Setup

Set your endpoint and credentials once:

export SR_URL="https://<schema-registry-url>"
export API_KEY="<your-api-key>"

Every example uses Basic authentication, where the API key is the password and the username is an ignored placeholder. Bearer token authentication is also supported:

curl -H "Authorization: Bearer $TOKEN" "$SR_URL/schemas/types"

See Connect for how to find the URL and for the OAuth2 and mTLS alternatives.

Quote any URL containing ? or & so your shell doesn’t interpret it: curl -u "any-user:$API_KEY" "$SR_URL/subjects?deleted=true".

The registry accepts application/vnd.schemaregistry.v1+json as the content type for writes. Any Accept value outside the supported set returns 412.

Schemas

List supported schema types

curl -u "any-user:$API_KEY" "$SR_URL/schemas/types"

["AVRO","JSON","PROTOBUF"]

Get a schema by ID

curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1"

{"schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"}

Get only the schema string

curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/schema"

List the subjects a schema ID appears in

curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/subjects"

["orders-value"]

The same schema ID can appear under several subjects. Add ?deleted=true to include soft-deleted ones.

List subject-versions for a schema ID

curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/versions"

[{"subject":"orders-value","version":1}]

Subjects

List all subjects

curl -u "any-user:$API_KEY" "$SR_URL/subjects"

["orders-value","customers-value"]

Use ?deleted=true to include soft-deleted subjects, or ?deletedOnly=true for only those.

This returns only the subjects your credentials can read, rather than failing. An empty array can mean the registry is empty or that your role covers no existing subject.

Register a schema

curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schemaType":"AVRO","schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"}' \
  "$SR_URL/subjects/orders-value/versions"

{"id":1}

Add ?normalize=true to canonicalize before storing—effective for Avro and Protobuf, a no-op for JSON Schema. To register a schema that references another, include a references array. See Schema references.

Look up a schema under a subject

Find whether a schema is already registered, without registering it:

curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"}' \
  "$SR_URL/subjects/orders-value"

{"subject":"orders-value","id":1,"version":1,"schema":"..."}

Returns 404 if the schema isn’t registered under that subject.

List versions under a subject

curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions"

[1,2,3]

Get a specific version

curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/1"

{"subject":"orders-value","id":1,"version":1,"schema":"..."}

Use latest in place of a version number to get the newest. Add ?deleted=true to read a soft-deleted version.

Get only the schema string for a version

curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/latest/schema"

List schemas that reference a version

curl -u "any-user:$API_KEY" "$SR_URL/subjects/com.acme.Address/versions/1/referencedby"

[2,3]

The response is an array of schema IDs. A non-empty result means deleting this version returns error 42206.

Delete a version

Soft delete first:

curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value/versions/1"

Then hard delete, if you want the data gone:

curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value/versions/1?permanent=true"

Hard delete requires a prior soft delete—calling it first returns 40407 for a version or 40405 for a subject. There is no undelete: re-registering the same schema after a soft delete creates a new version. Hard-deleted data is unrecoverable.

Delete a subject

curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value"

[1,2,3]

The response lists the versions that were deleted. Add ?permanent=true for the hard delete, after the soft delete.

Compatibility

Test a schema against a version

curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"},{\"name\":\"total\",\"type\":[\"null\",\"double\"],\"default\":null}]}"}' \
  "$SR_URL/compatibility/subjects/orders-value/versions/latest"

{"is_compatible":true}

Test against every version

curl -u "any-user:$API_KEY" \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema":"..."}' \
  "$SR_URL/compatibility/subjects/orders-value/versions?verbose=true"

Add ?verbose=true to either endpoint to get the reason a check failed:

{"is_compatible":false,"messages":["READER_FIELD_MISSING_DEFAULT_VALUE: total"]}

Both compatibility endpoints are POST, not GET.

Config

Get a subject’s compatibility level

curl -u "any-user:$API_KEY" "$SR_URL/config/orders-value"

{"compatibilityLevel":"BACKWARD"}

Set a subject’s compatibility level

curl -u "any-user:$API_KEY" \
  -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"compatibility":"BACKWARD_TRANSITIVE"}' \
  "$SR_URL/config/orders-value"

{"compatibilityLevel":"BACKWARD_TRANSITIVE"}

GET /config always returns {"compatibilityLevel":"NONE"} regardless of what’s in force. The real default is BACKWARD. There is no PUT /config—set the level per subject.

Mode

curl -u "any-user:$API_KEY" "$SR_URL/mode"

{"mode":"READWRITE"}

Only the global /mode exists; per-subject mode returns 404. Whether PUT /mode works depends on your cluster—see Confluent API compatibility.

Introduction

Get Started

Kafka Clusters

Process

Lakehouse

Governance

Migrate

Kafka Clients

Setup

Schemas

List supported schema types

Get a schema by ID

Get only the schema string

List the subjects a schema ID appears in

List subject-versions for a schema ID

Subjects

List all subjects

Register a schema

Look up a schema under a subject

List versions under a subject

Get a specific version

Get only the schema string for a version

List schemas that reference a version

Delete a version

Delete a subject

Compatibility

Test a schema against a version

Test against every version

Config

Get a subject’s compatibility level

Set a subject’s compatibility level

Mode

Next steps

Confluent compatibility

Evolution and compatibility

​Setup

​Schemas

​List supported schema types

​Get a schema by ID

​Get only the schema string

​List the subjects a schema ID appears in

​List subject-versions for a schema ID

​Subjects

​List all subjects

​Register a schema

​Look up a schema under a subject

​List versions under a subject

​Get a specific version

​Get only the schema string for a version

​List schemas that reference a version

​Delete a version

​Delete a subject

​Compatibility

​Test a schema against a version

​Test against every version

​Config

​Get a subject’s compatibility level

​Set a subject’s compatibility level

​Mode

​Next steps

Confluent compatibility

Evolution and compatibility

Setup

Schemas

List supported schema types

Get a schema by ID

Get only the schema string

List the subjects a schema ID appears in

List subject-versions for a schema ID

Subjects

List all subjects

Register a schema

Look up a schema under a subject

List versions under a subject

Get a specific version

Get only the schema string for a version

List schemas that reference a version

Delete a version

Delete a subject

Compatibility

Test a schema against a version

Test against every version

Config

Get a subject’s compatibility level

Set a subject’s compatibility level

Mode

Next steps