> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kafka Schema Registry REST API Examples

> Worked curl examples for every supported Schema Registry endpoint, with request and response.

Worked examples for each supported endpoint. For the complete endpoint list, unsupported endpoints,
and behavior differences, see
[Confluent API compatibility](/kafka/governance/sr/reference/confluent-compatibility).

## Setup

Set your endpoint and credentials once:

```shell theme={null}
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:

```shell theme={null}
curl -H "Authorization: Bearer $TOKEN" "$SR_URL/schemas/types"
```

See [Connect](/kafka/governance/sr/connect) for how to find the URL and for the
OAuth2 and mTLS alternatives.

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

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

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/types"
```

```json theme={null}
["AVRO","JSON","PROTOBUF"]
```

### Get a schema by ID

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1"
```

```json theme={null}
{"schema":"{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"}
```

### Get only the schema string

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/schema"
```

### List the subjects a schema ID appears in

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/subjects"
```

```json theme={null}
["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

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/schemas/ids/1/versions"
```

```json theme={null}
[{"subject":"orders-value","version":1}]
```

## Subjects

### List all subjects

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects"
```

```json theme={null}
["orders-value","customers-value"]
```

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

<Note title="Note">
  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.
</Note>

### Register a schema

```shell theme={null}
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"
```

```json theme={null}
{"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](/kafka/governance/sr/fundamentals/schema-references).

### Look up a schema under a subject

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

```shell theme={null}
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"
```

```json theme={null}
{"subject":"orders-value","id":1,"version":1,"schema":"..."}
```

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

### List versions under a subject

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions"
```

```json theme={null}
[1,2,3]
```

### Get a specific version

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/1"
```

```json theme={null}
{"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

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/latest/schema"
```

### List schemas that reference a version

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/subjects/com.acme.Address/versions/1/referencedby"
```

```json theme={null}
[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:

```shell theme={null}
curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value/versions/1"
```

```json theme={null}
1
```

Then hard delete, if you want the data gone:

```shell theme={null}
curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value/versions/1?permanent=true"
```

<Warning>
  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.
</Warning>

### Delete a subject

```shell theme={null}
curl -u "any-user:$API_KEY" -X DELETE "$SR_URL/subjects/orders-value"
```

```json theme={null}
[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

```shell theme={null}
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"
```

```json theme={null}
{"is_compatible":true}
```

### Test against every version

```shell theme={null}
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:

```json theme={null}
{"is_compatible":false,"messages":["READER_FIELD_MISSING_DEFAULT_VALUE: total"]}
```

<Warning>
  Both compatibility endpoints are **POST**, not GET.
</Warning>

## Config

### Get a subject's compatibility level

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/config/orders-value"
```

```json theme={null}
{"compatibilityLevel":"BACKWARD"}
```

### Set a subject's compatibility level

```shell theme={null}
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"
```

```json theme={null}
{"compatibilityLevel":"BACKWARD_TRANSITIVE"}
```

<Warning title="The global GET /config is not meaningful">
  `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.
</Warning>

## Mode

```shell theme={null}
curl -u "any-user:$API_KEY" "$SR_URL/mode"
```

```json theme={null}
{"mode":"READWRITE"}
```

Only the global `/mode` exists; per-subject mode returns 404. Whether `PUT /mode` works depends on
your cluster—see
[Confluent API compatibility](/kafka/governance/sr/reference/confluent-compatibility#put-mode-availability-varies).

## Next steps

<CardGroup cols={2}>
  <Card title="Confluent compatibility" icon="list-check" href="/kafka/governance/sr/reference/confluent-compatibility">
    The full endpoint list and behavior differences.
  </Card>

  <Card title="Evolution and compatibility" icon="code-compare" href="/kafka/governance/sr/fundamentals/schema-evolution">
    What each compatibility mode permits.
  </Card>
</CardGroup>