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

# Replace documents

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

Replaces multiple documents in the specified collection with the ones in the body. The replaced documents are specified by the *_key* attributes in the body documents.

If *ignoreRevs* is *false*,, a *_rev* attribute in each document body must match the revision of the corresponding document in the database. Otherwise, the call fails

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 replaced documents. In each entry:
 - *_id* contains the known *document-handle* of each updated document.
 - *_key* contains the key which 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.

If the query parameter *returnOld* is *true*, 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*, 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, that 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

- `ignoreRevs` boolean
- `returnOld` boolean
- `returnNew` boolean
- `waitForSync` boolean

## Request body

- object

## Response `201`

Successfully replaced 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 replaced 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)