Put a Document

These are cURL requests to a database named "Example" on our playground server to store and then modify a document.

1) Store a new document "person/1-A" in the collection "People"

curl -X PUT "http://live-test.ravendb.net/databases/Example/docs?id=person/1-A"
-d "{ 
    \"FirstName\":\"Jane\", 
    \"LastName\":\"Doe\",
    \"Age\":42,
    \"@metadata\":{
        \"@collection\":\"People\"
    }
}"

Response:

HTTP/1.1 201
status: 201
Server: nginx
Date: Tue, 27 Aug 2019 10:58:28 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Vary: Accept-Encoding
Raven-Server-Version: 4.2.3.42

{
    "Id":"person/1-A",
    "ChangeVector":"A:1"
}

2) Update that same document

curl -X PUT "http://live-test.ravendb.net/databases/Example/docs?id=person/1-A"
--header "If-Match: A:1-L8hp6eYcA02dkVIEifGfKg"
-d "{ 
    \"FirstName\":\"John\", 
    \"LastName\":\"Smith\",
    \"Age\":24,
    \"@metadata\":{
        \"@collection\": \"People\"
    }
}"

The response is the same as the previous response except for the updated change vector:

HTTP/1.1 201
status: 201
Server: nginx
Date: Tue, 27 Aug 2019 10:59:54 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip
Vary: Accept-Encoding
Raven-Server-Version: 4.2.3.42

{
    "Id":"person/1-A",
    "ChangeVector":"A:3"
}

This is the general format of the cURL request:

curl -X PUT "<server URL>/databases/<database name>/docs?id=<document ID>"
--header "If-Match: <expected change vector>"
-d "<JSON document>"

Query String Parameters

Headers

Request Body

The body contains a JSON document. This will replace the existing document with the specified ID if one exists. Otherwise, it will become a new document with the specified ID.

{
    \"<field>\": \"<value>\",
    ...
    \"@metadata\": {
        \"@collection\": \"<collection name>\",
        ...
    }
}

When updating an existing document, you'll need to include its collection name in the metadata or an exception will be thrown. Exceptions to this rule are documents in the collection @empty - i.e. not in any collection. A document's collection cannot be modified.

Another way to make this request is to save your document as a file (such as a .txt), and pass the path to that file in the request body:

curl -X PUT "<server URL>/databases/<database name>/docs?id=<document ID>"
-d "<@path/to/yourDocument.txt>"

The response body is JSON and contains the document ID and current change vector:

{
    "Id": "<document ID>",
    "ChangeVector": "<current change vector>"
}