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

# Replace document

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

Replaces the document with key <key> with the one in the body, provided there is such a document and no precondition is violated.

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 body must 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 (depending on *waitForSync*, see below), the *ETag* header field contains the new revision of the document 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 each 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

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

## Headers

- `If-Match` string

## Request body

- object

## Response `201`

Successfully replaced documents 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 replaced documents when *waitForSync* is disbled.
- `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)