MarkLogic 9 Product Documentation
PUT /v1/documents

Summary

Insert or update document contents and/or metadata, at a caller-supplied document URI.

URL Parameters
uri	The URI of the document to be created or updated.
category*	The category of data to insert or update. Category may be specified multiple times to insert or replace any combination of content and metadata. Valid categories: `content` (default), `metadata`, `metadata-values`, `collections`, `permissions`, `properties`, and `quality`. Use `metadata` to update all metadata. See the Usage notes below.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format?	The content type of the metadata in the request body. The MIME type in the Content-type request or part header overrides the `format` parameter if the header is set to a MIME type compatible with the supported metadata formats (XML and JSON). For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide.
collection*	The URI of a collection to which to add the document. Use this parameter only when the request includes content; see the Usage notes for details.
quality?	The quality of this document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0. Use this parameter only when the request includes content; see the Usage notes for details.
perm:{role}*	Assign the document to the listed role, with the permission given in the parameter value. For example, `perm:editor=update`. Valid values: `read, update, execute`. Only the named role is changed. Unspecified roles retain their current permissions. Use this parameter only when the request includes content; see the Usage notes for details.
prop:{name}*	Attach the named property to the document, with the given property value. For example, `prop:decade=70`. The property name must be an `xs:NCName`. If the property already exists, its value is replaced. Only the named property is modified. Unspecified properties are unaffected. Use this parameter only when the request includes content; see the Usage notes for details.
value:{key}*	Attach the specified values metadata to the document, where the key is as given after the `value:` prefix and the value is the request parameter value. For example, `value:a=1`. Only the specified key's value is changed. Use this parameter only when the request includes content; see the Usage Notes for details. Setting the parameter is equivalent to calling xdmp:document-set-metadata.
extract?	For binary content, whether or not to extract metadata, and whether to store the extracted metadata as properties or in a separate XHTML document. Accepted values: `properties` or `document`. See note below.
repair?	The type of XML repair to perform on the input content. Accepted values: `none` (default) or `full`. Use `full` to request the server to repair malformed input XML. Use `none` to request the server to reject malformed input XML. If repair results in multiple root nodes, the update is rejected.
transform?	Names a content transformation previously installed via the `/transforms` service. The service applies the transformation to the content prior to updating or inserting the document or metadata.
trans:{name}*	A transform parameter name and value. For example, `trans:myparam=1`.
forest-name?	Specifies the name of a forest into which this document is inserted. If the document already exists in the database, it remains in its existing forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If the document already exists and the forest in which it is stored is set to delete-only, an error is raised.
txid?	The transaction identifier of the multi-statement transaction in which to service this request. Use the `/transactions` service to create and manage multi-statement transactions.
lang?	This parameter is deprecated and will be ignored. When ingesting JSON content, this parameter specifies the JSON content language. Accepted values: Any value accepted in the `xml:lang` attribute.
temporal-collection?	Specify the name of a temporal collection into which the documents are to be inserted. For details, see Managing Temporal Documents in the Temporal Developer's Guide.
temporal-document?	The "logical" document URI in the temporal collection specified using the `temporal-collection` request parameter. For details, see Managing Temporal Documents in the Temporal Developer's Guide. This parameter can only be used when the `temporal-collection` parameter is also present.
system-time?	Set the system start time for the insertion or update. This time will override the system time set by MarkLogic. Ignored if `temporal-collection` is not included in the request.

Request Headers
Content-Type?	The MIME type of the data in the request body. This header does not determine how the request body contents are interpreted in all cases. For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide.
If-Match?	Specifies a document version identifier that must match the current version of the target document for the update to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see Using Optimistic Locking to Update Documents in the REST Application Developer's Guide.

Request Headers

Content-Type?

The MIME type of the data in the request body. This header does not determine how the request body contents are interpreted in all cases. For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide.

If-Match?

Specifies a document version identifier that must match the current version of the target document for the update to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see Using Optimistic Locking to Update Documents in the REST Application Developer's Guide.

Response

Upon success, MarkLogic Server responds with 201 (Created) or 204 (Updated).

Required Privileges

This operation requires the rest-writer role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Using the system-time parameter also requires the following privilege:

http://marklogic.com/xdmp/privileges/temporal-statement-set-system-time

Usage Notes

If no permissions are explicitly set, documents you create with the MarkLogic REST API have a read permission for the rest-reader role and an update permission for the rest-writer role. When you explicitly set permissions, they are combined with the default permissions for the role of the current user. For details, see Controlling Access to Documents and Other Artifacts in the REST Application Developer's Guide.

You can add or update content and metadata in a single request in two ways: Construct a multipart/mixed request with the metadata and content in the request body parts, or place the content in the request body and specify metadata using the collection, quality, perm, and value:{key}, prop request parameters. You cannot combine these methods: Metadata request parameters are ignored when the request body includes metadata. The metadata request parameters are only usable when you also insert or update content. For details, see 'Loading Content and Metadata in the Same Request' in the REST Application Developer's Guide.

To add or replace just metadata, specify the metadata as a single XML or JSON container in the request body and specify its content type using the Content-type header or the format request parameter. You cannot use the metadata request parameters without content. For details, see Adding Metadata in the REST Application Developer's Guide.

Use category to completely replace a category of metadata. For example, category=properties replaces all existing properties of a document. Use the specific metadata parameters to selectively modify a metadata category. For example, use prop:decade=70 to add or modify just the "decade" property. Using category=metadata replaces all metadata for the document. Metadata request parameters are ignored when the request body includes metadata.

Extracting metadata as properties replaces any existing properties on the document. Extracting metadata to a document creates an XHTML document that differs from the input document only by having a xhtml file name extension. If CPF is installed in the database, the XHTML document includes a link to the binary document. For details, see Extracting Metadata and Text From Binary Documents in the Search Developer's Guide.

When updating document permissions, the permissions must include at least one update permission.

When working with temporal documents, the uri parameter always refers to a document URI. When the system manages the version URIs, the document URI and the temporal document collection URI have the same value. When the user manages the version URIs, this may not be the case. When they differ, the uri parameter indicates the document URI, and the temporal-document parameter indicates the temporal document collection URI.

Example

curl --anyauth --user user:password -T ./my-content -i \
  -H "Content-type: application/xml" \
  http://localhost:8000/v1/documents?uri=/shakespeare/plays/a_and_c.xml

==> If a document already exists with URI /shakespeare/plays.a_and_c.xml,
    the document contents are updated with the contents of the file
    ./my-content, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close

==> If a document does not already exist with URI 
    /shakespeare/plays/a_and_c.xml, a new document in created with
    that URI, and the following headers are returned:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 100 Continue

HTTP/1.1 201 Document Created
Location: /shakespeare/plays/a_and_c.xml
Server: MarkLogic
Content-Length: 0
Connection: close