---
title: "Update document"
method: PATCH
path: "/_fabric/{fabric}/_api/document/{collection}/{key}"
tags: ["Documents"]
---

# Update document

`PATCH /_fabric/{fabric}/_api/document/{collection}/{key}`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/macrometa/apis/macrometa-api-reference/docs/_fabric/:fabric/_api/document/:collection/:key/patch.ts> (a function with typed inputs; its response is checked against the schema)

Partially updates the document identified by *key*. The body of the request must contain a JSON document with the attributes to patch (the patch document). All attributes from the patch document are added to the existing document if they do not yet exist, and overwritten in the existing document if they do exist there.

Setting an attribute value to *null* in the patch document causes a value of *null* to be saved for the attribute by default.

If the *If-Match* header is specified and the revision of the document in the database is unequal to the given revision, the precondition is violated.

If *If-Match* is not given and *ignoreRevs* is *false*, a *_rev* attribute in each document bodymust match the revision of the corresponding document in the database. Otherwise, the call fails.

If a precondition is violated, a *HTTP 412* is returned.

If the document exists and can be updated, a *HTTP 201* or a *HTTP 202* is returned, the *ETag* header field contains the new revision of the document (in double quotes) and the *Location* header contains a URL under which the document can be queried.

If *silent* is set to *false*, the body of the response contains a JSON object with the information about the handle and the revision.
 - *_id* contains the known *document-handle* of the updated document.
 - *_key* contains the key that uniquely identifies a document.
 - *_rev* contains the new document revision.

If the query parameter *returnOld* is *true*, the previous revision of the document is returned under the *old* attribute in the result.

If the query parameter *returnNew* is *true*, the new document is returned under the *new* attribute in the result.

If the document does not exist, a *HTTP 404* is returned and the body of the response contains an error document.

## Path parameters

- `fabric` string, string, required
- `collection` string, string, required
- `key` string, string, required

## Query parameters

- `keepNull` boolean
- `mergeObjects` boolean
- `ignoreRevs` boolean
- `returnOld` boolean
- `returnNew` boolean
- `silent` boolean
- `waitForSync` boolean

## Headers

- `If-Match` string

## Request body

- object

## Response `201`

Successfully updated document when *waitForSync* is enabled.

- ExamplesIdKeyRevOldrev
  - `_id` string: ID of the collection.
  - `_key` string: _key details of collection.
  - `_rev` string: _rev details of collection.
  - `_oldRev` string: previous revision of collection.

## Other responses

- `202`: Successfully updated document when *waitForSync* is disabled.
- `400`: Failed due to missing or malformed data. Verify that all parameters are complete.
- `404`: Failed to find specified collection or document.
- `412`: Failed due to the precondition being violated. The response contains the found documents' current revisions in the *_rev* attributes. Additionally, the attributes *_id* and *_key* are returned.

---

[API](https://skmtc.dev/macrometa/apis/macrometa-api-reference.md) - [All operations](https://skmtc.dev/macrometa/apis/macrometa-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/macrometa/apis/macrometa-api-reference/revisions/2006b6d7f31d?raw)