---
title: "Create document"
method: POST
path: "/_fabric/{fabric}/_api/document/{collection}"
tags: ["Documents"]
---

# Create document

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

Create a new document from the document given in the body, unless there is already a document with the *_key* given. If no *_key* is given, a new unique *_key* is generated automatically.

The body can be an array of documents, in which case all documents in the array are inserted with the same semantics as for a single document. The result body contains a JSON array of the same length as the input array, and each entry contains the result of the operation for the corresponding input. In case of an error the entry is a document with attributes *error* set to *true* and errorCode set to the error code that has happened.

Possibly given *_id* and *_rev* attributes in the body are always ignored, the URL part or the query parameter collection respectively counts.

If the document is created successfully, the *Location* header contains the path to the newly created document. The *Etag* header field contains the revision of the document. Both are only set in the single document case.

If *silent* is not set to *true*, the body of the response contains a JSON object (single document case) with the following attributes:

 - *_id* contains the document handle of the newly created document.
 - *_key* contains the document key.
 - *_rev* contains the document revision.

In the multi case the body is an array of such objects. If the query parameter *returnNew* is *true*, then, for each generated document, the new document is returned under the *new* attribute in the result.

## Path parameters

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

## Query parameters

- `collection` string
- `returnNew` boolean
- `returnOld` boolean
- `silent` boolean
- `overwrite` boolean
- `waitForSync` boolean

## Request body

- object[]

## Response `201`

Successfully created documents when *waitForSync* is enabled. If more than one document is specified in the JSON body, check the response body to verify the creations succeeded.

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

## Other responses

- `202`: Successfully created 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.
- `409`: Failed to create document, in the single document case. If a document with the same qualifiers in an indexed attribute conflicts with an already existing document and thus violates that unique constraint, the response body contains an error document. In the array case only 201 or 202 is returned, but if an error occurred, 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: *1205:10,1210:17* which means that in 10 cases the error 1205 "illegal document handle" and in 17 cases the error 1210 "unique constraint violated" has happened.

---

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