Put a Document

• Use this endpoint with the PUT method to upload a new document to the database, or update an existing one:
  <server URL>/databases/<database name>/docs

• In this page:

  • Examples
  • Request Format
    • Request Body
  • Response Format

Examples

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\"
  }
}"

Linebreaks are added for clarity.

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"
}

Request Format

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

Parameter	Description	Required
id	Unique ID under which the new document will be stored, or the ID of an existing document to be updated	Yes

Headers

Header	Description	Required
If-Match	When updating an existing document, this header passes the document's expected change vector. If this change vector doesn't match the document's server-side change vector, a concurrency exception is thrown.	No

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>\",
      ...
  }
}

Depending on the shell you're using to run cURL, you will probably need to escape all double quotes within the request body using a backslash: " -> \".

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>"

Response Format

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

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

Header	Description
Content-Type	MIME media type and character encoding. This should always be: application/json; charset=utf-8.
Raven-Server-Version	Version of RavenDB the responding server is running

HTTP Status Code	Description
201	The document was successfully stored / updated
409	The change vector submitted did not match the server-side change vector. A concurrency exception is thrown.
500	Server error, e.g. when the submitted document's collection tag did not match the specified document's collection tag.