> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Entity Update Behavior (PUT vs PATCH)
> Understand how PUT and PATCH differ when updating existing entities, including the field-level preserve and merge rules applied to bot-driven requests.
# Entity Update Behavior (PUT vs PATCH)
`PUT` and `PATCH` behave differently when you update an entity that already exists. This page covers three things: which fields `PUT` keeps versus overwrites, why `PATCH` is the right tool for intentionally replacing a value, and a common mistake to avoid with placeholder text.
`PUT` is not always a full overwrite, but the protection is caller- and field-specific, not universal. For a defined set of fields, if a value is already set, `PUT` keeps it instead of replacing it with an empty or missing one — but which fields are protected, and whether a caller can override them, depends on who's calling and which field it is. See [PUT Preserve Logic](#put-preserve-logic-bot-driven-updates) below for the exact rules. To intentionally replace a protected value, use `PATCH`.
## PUT Preserve Logic (Bot-Driven Updates)
When a bot — for example, the `ingestion-bot` running a metadata ingestion workflow — updates an entity with `PUT`, the backend keeps several fields as they are instead of overwriting them. This stops metadata that someone curated by hand from being wiped out by a routine ingestion run.
Protection works a little differently depending on the field:
**Preserved for bot-driven PUT — PATCH only:**
If any of these fields already have a value, a bot's `PUT` request won't change them. There's no way around this except `PATCH`.
* `extension` and custom properties
* `domain` and `dataProducts`
* Certifications
* Nested metadata, such as a column's `description` and `displayName` on a table
**Preserved for bot-driven PUT — override available:**
Same as above: if these fields already have a value, a bot's `PUT` request won't change them. The one exception is a bulk create-or-update request with `overrideMetadata=true`, which forces the overwrite without needing `PATCH`.
* Top-level `description`
* `owners` — no `PUT` request, from a bot or a person, can ever remove owners by leaving the field blank or sending an empty list. Separately, a bot can't replace the owners with a different value either, but only if that bot's role doesn't have `EditOwners` permission.
**Applies to every PUT request, not just bots:**
* `tags` — `PUT` adds the tags in the request to the entity's existing tags. This happens for every caller, not just bots. `PUT` never removes an existing tag; only `PATCH` can do that.
`overrideMetadata=true` only works on the bulk create-or-update endpoint (the same setting shown as the "Override Metadata" toggle in connector ingestion configs). The regular single-entity `PUT` endpoints used throughout this API reference don't support it.
## The PATCH Requirement
`PATCH` preserves any field you don't include in the request — it only changes the fields you explicitly target. Replacing one of the fields above with `PATCH` still requires the caller to have permission to modify that specific field; it isn't a way around field-level authorization, only around the `PUT` preserve rules.
Use [JSON Patch (RFC 6902)](/api-reference/data-assets/tables/update) to set exactly the fields you want to change. Unlike `PUT`, `PATCH` applies the values you send instead of preserving what's already there — so it's the right tool whenever you need to correct or replace curated metadata, not just fill in a gap.
```bash PATCH to overwrite a description theme={null}
curl -X PATCH "{base_url}/api/v1/tables/{id}" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json-patch+json" \
-d '[
{"op": "replace", "path": "/description", "value": "Corrected description."}
]'
```
## Best Practice: Avoid Placeholder Values
Don't send placeholder strings such as `"No description provided"` when you create an entity. The backend can't tell a placeholder from a real description — it treats both as a value that's already set.
That matters because of the preserve logic above: once a description has any value, a bot-driven `PUT` won't touch it. So a placeholder set at creation time permanently blocks a later ingestion run from ever filling in the real description. Leave the field empty instead — only an empty field can be filled in later by `PUT`.
Already created entities with placeholder descriptions? A `PUT` request won't clear them. Use `PATCH` to replace the placeholder with the real value, or with an empty string.
## Scope
This applies to the create-or-update (`PUT`) APIs for entities such as Tables, Dashboards, Pipelines, Domains, Glossaries, and Services — as well as other data assets, governance entities, data quality entities, and users.
It doesn't apply to action or configuration endpoints, such as [Lineage](/api-reference/lineage) operations or system settings. Those follow different rules.
See a full PATCH example for updating a table
Learn how to set up the ingestion-bot that drives PUT updates