> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/api-reference/database/schemas/delete-database-schema.md).

# Delete Database Schema

Delete a database schema and drop its records (its collection) in the request's environment.

A **schema** defines a collection's fields, types, and validation. Schemas support drafts, versions, and publishing.

This endpoint deletes the schema **and its records** in the environment of the request (the `norbix-env` header; PROD when it is not sent). It drops the schema's MongoDB collection — every record and its indexes — in every active database integration of that environment, then removes that environment's copy of the schema. This action cannot be undone.

{% hint style="warning" %}
This action is destructive or irreversible. Make sure you target the right item and confirm before running it.
{% endhint %}

What the call does, in order:

1. **Checks.** A schema that is still in use cannot be deleted, and nothing is dropped when the call is refused:
   * a schema trigger on it → `CM-ERRORS-SCHEMA-017`, with the blocking triggers in `BlockerTriggerIds`; delete the triggers first.
   * it is the start collection of a saved aggregate, or a collection that a saved aggregate joins (`$lookup`, `$graphLookup`, `$unionWith`) → `CM-ERRORS-SCHEMA-018`, with the blocking aggregates in `BlockerAggregateIds` and `BlockerAggregateNames`; delete or change them first.
2. **Drops the records** in that environment. When the schema has AI **Embed** on, its records are also taken out of the project's AI knowledge.
3. **Removes the schema** (its list and embed settings go with it).

Good to know:

* **Only the request's environment.** The copies of the schema in other environments, and their records, are not touched. To clear TEST and PROD, delete the schema in each environment.
* **A new schema with the same name starts empty** — the old records do not come back.
* **Safe to retry.** If the drop fails (for example an integration cannot be reached), the schema stays and the call returns an error; calling it again is safe.
* A managed Atlas Flex database that is still being provisioned has no collection yet, so it is skipped.

## Notes for SDK and tool authors

* The request is `DELETE /{version}/database/schemas/{Id}` with an empty body; the success response is empty. Send `norbix-env` to choose the environment — the SDK method has no separate "keep records" or "all environments" option.
* Treat it as a **destructive** call: ask the user to confirm, and name the environment and the record count in the prompt (count first with [Count](/codemash/api-reference/database/collections/count.md) on the collection).
* Show `CM-ERRORS-SCHEMA-017` / `CM-ERRORS-SCHEMA-018` with the blocker ids from the error metadata, so the user knows what to remove first.

{% openapi src="/files/0gOkqzp7kyziG9XPpCBy" path="/{version}/database/schemas/{Id}" method="delete" %}
[norbix-hub-swagger.json](https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-7c7445e68689b62620e59cb01a3523deb46b865b%2Fnorbix-hub-swagger.json?alt=media)
{% endopenapi %}

## In Cloud

Manage this visually in Cloud — see [Database](/codemash/cloud/database/collections/create-schema.md).

## Use it from code

Every Norbix SDK exposes this endpoint as a method — see [Delete Database Schema](/codemash/sdks/database/schemas/delete-database-schema.md) in the SDK reference, with examples in every language.