> ## 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.

# Delete Kafka Schemas

> Soft delete, hard delete, what blocks a deletion, and what you can't get back.

Deletion happens in two stages. A **soft delete** hides a schema from normal queries but keeps it
readable and keeps its version number reserved. A **hard delete** removes it permanently and requires
a prior soft delete.

<Warning title="There is no undelete">
  Nothing restores a soft-deleted schema. Re-registering the identical schema string creates a **new
  version**—it does not revive the old one. Hard-deleted data is gone.

  Treat the soft delete as your window to change your mind, not as a reversible operation.
</Warning>

## Soft delete

Delete a single version:

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

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

Or the whole subject:

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

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

After a soft delete the schema no longer appears in `GET /subjects` or
`GET /subjects/{subject}/versions`, and consumers can no longer resolve it by subject and version.

<Warning title="Consumers cannot resolve soft-deleted schemas by ID">
  A soft delete doesn't remove records already on the topic, but consumers **cannot** resolve a
  soft-deleted schema through `GET /schemas/ids/{id}`. This differs from the Confluent Schema Registry,
  where `GET /schemas/ids/{id}` continues to return soft-deleted schemas.

  Plan your deletion carefully: any consumer that encounters a record whose schema was soft-deleted
  will fail to deserialize it.
</Warning>

## Inspect deleted schemas

```shell theme={null}
# Include soft-deleted subjects
curl -u "any-user:$API_KEY" "$SR_URL/subjects?deleted=true"

# Only soft-deleted subjects
curl -u "any-user:$API_KEY" "$SR_URL/subjects?deletedOnly=true"

# A soft-deleted version
curl -u "any-user:$API_KEY" "$SR_URL/subjects/orders-value/versions/1?deleted=true"
```

`deleted` and `deletedOnly` also work on `GET /subjects/{subject}/versions`, and `deleted` works on
`GET /schemas/ids/{id}/versions` and `GET /schemas/ids/{id}/subjects`.

## Hard delete

Add `?permanent=true` after the soft delete:

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

Calling a hard delete on something that hasn't been soft-deleted returns:

| Code  | Meaning                        |
| ----- | ------------------------------ |
| 40405 | The subject isn't soft-deleted |
| 40407 | The version isn't soft-deleted |

Soft-deleting something twice returns 40404 for a subject or 40406 for a version.

## References block deletion

You can't delete a schema another schema references. The attempt returns error code **42206**, for
soft and hard deletes alike.

Find what's holding it:

```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. Resolve each with `GET /schemas/ids/{id}/subjects` to find
the subjects, and delete those first. See
[Schema references](/kafka/governance/sr/fundamentals/schema-references).

## Version numbering after deletion

Version numbers aren't necessarily reused after a deletion, and the exact behavior depends on how
the registry is deployed for your cluster.

Don't build anything that assumes the next version will be `max(version) + 1`, and don't treat a gap
in version numbers as a problem. Read the version back from the registration response instead of
computing it.

## Storage

There's no maximum number of subjects, no maximum number of versions per subject, and no storage
quota, so you won't need to delete schemas to make room. Delete them because they're obsolete, not
because you're running out of space.

The one hard limit is the **5 MB request body**, which caps the size of a single schema.

## Next steps

<CardGroup cols={2}>
  <Card title="Manage schemas" icon="sliders" href="/kafka/governance/sr/manage/manage-schemas">
    Register schemas and set compatibility modes.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/kafka/governance/sr/reference/troubleshooting">
    Error codes and what to do about them.
  </Card>
</CardGroup>