Create a new document with a server-generated database URI.
|extension||Specifies a URI extension to use when the document URI is generated by MarkLogic Server. The generated URI will end with "." plus this extension. This parameter is required.|
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: |
Specifies a directory prefix to use when the document URI is generated
by MarkLogic Server. If an |
|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. Specifying a format overrides the Content-Type request header value when inserting only metadata. For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide. This parameter only affects metadata, not document content.|
|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.|
Assign the document to the listed role, with the permission given in
the parameter value. For example, |
Attach the named property to the document, with the given property value.
For example, |
Attach the specified values metadata to the document, where the
key is as given after the |
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: |
The type of XML repair to perform on the input content. Accepted values:
Names a content transformation previously installed via the
A transform parameter name and value. For example,
|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.|
The transaction identifier of the multi-statement transaction in
which to service this request. Use the |
This parameter is deprecated and will be ignored if present.
When ingesting JSON content, this parameter specifies the JSON
content language. Accepted values:
Any value accepted in the |
|Content-Type?||The MIME type of the data in the request body. See the usage notes for details.|
If the request successfully creates a new document with a server
assigned URI, then the |
Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Updated or Unchanged).
rest-writerrole, or the following privileges:
Use this form of
POST /v1/documents to create a new
document with a server-generated URI. The request can optionally
include metadata. For all other document and metadata creation or
update operations, see
PUT /v1/documents or the other
To create a new document with a server-assigned URI:
contentas one of the
The request body must be either the document content or a multi-part
message that includes both metadata and content, as described below.
The server-generated URI is returned in the
You can create content and metadata in a single request in two ways:
multipart/mixedrequest with the metadata and content in the request body parts.
You cannot combine these methods: Metadata request parameters are ignored when the request body includes metadata. You cannot insert metadata without also inserting content.
When using a
multipart/mixed request to insert content
and metadata in the body of a single request, put the metadata in the
first part and specify its content type (XML or JSON) using the
Content-type header of the part or the
parameter. Put the content in the second part and set the Content-type
header the appropriate MIME type for the content.
When including metadata in the request body, supply metadata specified
category parameters in a single XML or JSON container.
For details, see
Loading Content into the Database in the REST Application Developer's Guide.
For a binary document, 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
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.
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the
role and an update permission for the
When you explicitly set permissions, they are combined with the default
permissions for the role of the current user.
When updating document permissions, the permissions must include at least one update permission.
metadata-values category represents "metadata fields"
document metadata. For more details, see
Metadata Fields in the Administrator's Guide.
curl --anyauth --user user:password -X POST -d@'./my-content' -i \ -H "Content-type: application/xml" \ 'http://localhost:8000/v1/documents?extension=xml&directory=/plays/' ==> Create a document from the XML in ./my-content, with a server generated URI. The URI is rooted at the directory "/plays/" and has an ".xml" suffix. The generated URI is returned in the Location response header. MarkLogic Server returns a response similar to the following: Content-type: application/xml Server: MarkLogic Content-Length: 211 Connection: Keep-Alive Keep-Alive: timeout=5 HTTP/1.1 201 Document Created Location: /plays/14993128029398656352.xml Server: MarkLogic Content-Length: 0 Connection: Keep-Alive Keep-Alive: timeout=5