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

# Update documents

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

## 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/patch.ts> (a function with typed inputs; its response is checked against the schema)

Partially update documents. The *_key* attributes in the body specify which documents should be updated. The body of the request must contain a JSON array of document updates with the attributes to patch (the patch documents). All attributes from the patch documents are added to the existing documents if they do not yet exist and overwritten in the existing documents if they do exist.

Setting an attribute value to *null* in the patch documents causees a value of *null* to be saved for the attribute.

If *ignoreRevs* is *false* and there is a *_rev* attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

If the document exists and can be updated, a *HTTP 201* or a *HTTP 202* is returned (depending on *waitForSync*, see below).

The body of the response contains a JSON array of the same length as the input array with the information about the handle and the revision of the updated documents. In each entry:
 - *_id* contains the known *document-handle* of each updated document.
 - *_key* contains the key that uniquely identifies a document.
 - *_rev* contains the new document revision.

In case of an error or violated precondition, an error object with the attribute *error* set to *true* and the attribute *errorCode* set to the error code is built.

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

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

Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the additional HTTP header *X-C8-Error-Codes* is set, which contains a map of the error codes that occurred together with their multiplicities, as in: *1200:17,1205:10* which means that in 17 cases the error 1200 "revision conflict" and in 10 cases the error 1205 "illegal document handle" has happened.

## Path parameters

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

## Query parameters

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

## Request body

- object

## Response `201`

Successfully updated documents when *waitForSync* is enabled.

- ExamplesIdKeyRev[]
  - `_id` string: ID of the collection.
  - `_key` string: _key details of collection.
  - `_rev` string: _rev details of collection.

## Other responses

- `202`: Successfully updated documents when *waitForSync* is disabled.
- `400`: Failed due to missing or malformed data. Verify that all parameters are complete.
- `404`: Failed to find specified collection.

---

[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)