Logo Help Center

Elvis 4 REST API - create

Elvis 4 REST API - create


    ?Filedata=<multipart/form-data encoded file>
    &metadata=<JSON encoded metadata>
    &<Elvis metadata field name>=<value>
    &metadataToReturn=<comma-delimited fields>
    &nextUrl=<next URL>

What does it do?

Upload and create an asset.

This call will create a new asset in Elvis. It can be used to upload files into Elvis. It can also be used to create 'virtual' assets like collections. In that case no file has to be uploaded and Elvis will create a 0 kb placeholder for the virtual asset.

When you want to create a new asset, certain metadata is required. The metadata is needed to determine where the file will be stored in Elvis.

Tip: The create service behaves almost identical to the update service. The update service has an additional 'id' parameter to specify the asset that should be updated.



The file to be created in Elvis.

If you do not specify a filename explicitly through the metadata, the filename of the uploaded file will be used.

The parameter is named "Filedata" because that is the standard name used by flash uploads. This makes it easy to use flash uploaders to upload batches of files to Elvis.

Optional. If omitted, a 0kb placeholder file will be created.


A JSON encoded object with properties that match Elvis metadata field names. This metadata will be set on the asset in Elvis.

Optional. You can also use parameters matching Elvis field names.


Info: Requires Elvis 4.6.17 or higher.

Comma-delimited list of metadata fields to return in hits. It is good practice to always specify just the metadata fields that you need.


Specify "all", or omit to return all available metadata.


Leave 'empty' to return only minimal fields


Optional. Default returns all fields.


Any parameter matching an Elvis metadata field name will be used as metadata. This metadata will be set on the asset in Elvis.

Optional. You also use the 'metadata' parameter.


When specified, the service will send a 301 redirect to this URL when it is completed successfully. If you place '${id}' in the URL, it will be replaced with the Elvis asset id of the created asset.

Optional. If omitted, a simple 200 OK status code will be returned.

Return value

Depending if a nextUrl is specified, this service will either send a 301 redirect, or return a JSON response with a hit containing all info and metadata about the created asset. The returned JSON has the same format as the hits returned in search results.

If the operation fails, an error page with a 500 error status will be returned.


Upload form

This simple HTML form uploads a file into Elvis, into the folder /Upload Zone:

<form action="http://demo.elvisdam.com/services/create"
   method="post" enctype="multipart/form-data">
  <input type="hidden" name="nextUrl" value="...mypage.html#${id}">
  <input type="hidden" name="folderPath" value="/Upload Zone">
  <label for="file">File </label>
  <input type="file" name="Filedata" id="file">
  <input type="submit" value="Create">

Tip: The auto-organize mechanism will put the file into /Upload Zone/Auto organized/(year)/(date) to keep the top-level folder organized.

Creating collections

The following call creates a new empty collection in /Demo Zone/Collections:


    ?folderPath=/Demo Zone/Collections
    &name=My Collection

As you can see the location of the asset is specified using several metadata fields. If you want to specify this with one field, use the assetPath field, which contains the complete path including the filename:


    ?assetPath=/Demo Zone/Collections/My Collection.collection

The JSON result returned by the service has the following format and information. If you upload a real file, like an image instead of creating a virtual asset like the collection above, the result will also have thumbnail and preview URLs:

  "permissions" : "VPUMECD",
  "id" : "0pBENZZH4ro9pRuHSAAlYr",
  "metadata" : {
    "assetPath" : "/Demo Zone/Collections/My Collection.collection",
    "assetCreator" : "admin",
    "folderPath" : "/Demo Zone/Collections",
    "assetModified" : {
      "value" : 1297422957338,
      "formatted" : "2011-02-11 12:15:57 +0100"
    "metadataComplete" : "true",
    "assetCreated" : {
      "value" : 1297422957338,
      "formatted" : "2011-02-11 12:15:57 +0100"
    "extension" : "collection",
    "assetModifier" : "admin",
    "assetType" : "collection",
    "name" : "My Collection",
    "assetRevision" : 1,
    "filename" : "My Collection.collection",
    "assetDomain" : "container"
  "thumbnailHits" : [ ],
  "originalUrl" : "http://localhost:8080/controller/file/Demo%20Zone/Collections/My%20Collection.collection"
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request


Please sign in to leave a comment.