About Documents API

The Argus document system provides a hierarchical folder structure per customer, with named folders which can contain subfolders or documents.

The Document system uses role based access to control read- and write access to the documents per customer. In addition, each folder or document can be restricted and granularly access controlled using explicit access control.
Permission checking is transitive, meaning that to read a folder or document element, a user needs folder access to the elements parent folder (recursively, up to the root folder).

The Document system is versioned, so each document update will generate a new revision of a document, and the system retains the revision history.
It allows a user to lock a document for a period of time, to avoid conflicting updates.

Tip
Please read the General Integration Guide to learn the general concepts and common data structures used throughout the Argus API.

Detailed API documentation

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Integration guide

Documents and Folders by

path

The Document API supports fetching folders by path, i.e. the path of the folder is specified in the URI, relative to the customer root. The path elements must use valid URL Encoding.
The customer root for path endpoints will always be the customer of the current user, unless otherwise specified in the "customer" query parameter:

No Format#fetch the folder "Reports/Weekly Reports" under the root folder of my users customer

ID

Every document and folder has a unique ID, unique across all document spaces. Operations on document/folder ID is unambiguous, and therefore recommended for most API usage.

No Format

#fetch the metadata of the folder with ID 99
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/99

#fetch the metadata of the document with ID 101
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folderdocument/path/meta/Reports/Weekly%20Reports

#fetch the folder "Reports/Weekly Reports" under the root folder of customer "mycustomer"101

Folders by path

The Document API also supports fetching folders and documents by path, i.e. the path of each folder (+ document name for a document) is specified in the URI, relative to the document space root root. The path elements must use valid URL Encoding.
The space root for path endpoints will always be the space of the default customer for the current user , unless otherwise specified in the "customer" query parameter:

No Format

#fetch the metadata of the folder folder "Reports/Weekly Reports" in the space of the default customer for the current user
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/meta/Reports/Weekly%20Reports?customer=mycustomer

The following endpoints are usable for folders by path:

Fetching the metadata of a folder by path:
GET



#fetch the metadata of the folder "Reports/Weekly Reports" in the space of customer "mycustomer"
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/meta/

Folder

Reports/

Subfolder

Weekly%20Reports?customer=mycustomer

Listing the contents of a folder by path:
GET https://api.mnemonic.no/documents/v1/folder/path/content/Folder/Subfolder?customer=mycustomer&limit=10&offset=20

Listing the explicit access settings of a folder by path:
GET



#fetch the metadata of the document "Reports/Weekly Reports/Report.pdf" in the space of the default customer for the current user
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/meta/

access

Reports/

Folder/Subfolder?customer=mycustomer&limit=10&offset=20

Granting explicit access for a folder by path:
POST https://api.mnemonic.no/documents/v1/folder/path/access/Folder/Subfolder?customer=mycustomer

Setting the access mode for a folder by path:
PUT https

Weekly%20Reports/Report.pdf

See the Swagger API documentation for details.

Fetch root folder for customer

To fetch the root folder of a particular customer, use the customer root folder endpoint:

No Format
#fetch the document space root folder of customer 1 curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/

folder/path/access/Folder/Subfolder?customer=mycustomer

Creating a new subfolder by path
POST https://api.mnemonic.no/documents/v1/folder/path/Folder?customer=mycustomer

See the Swagger API documentation for details.

Fetch root folder for customer

To fetch the root folder of a particular customer, use the customer root folder endpoint:

No Format
#fetch thecustomer/1

Or by path

No Format
#fetch the document space root folder of customer 1"customer" curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/customerfolder/1

Or by

path

No Format
#fetch the root folder of customer "customer" curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/meta/?customer=customer

This returns a folder descriptor object:

No Format

{	
  "data": {
    "id": 666,
    "parentElements": [],
    "name": "Root folder for mnemonic (mnemonic)",
    "customer": {...},
	...
    "accessMode": "roleBased",
    "effectiveAccessMode": "roleBased",
    "currentUserAccessLevel": "write",
    "elementType": "folder",
    "flags": [
      "ROOT_FOLDER"
    ]
  },...
}

Tip

The folderelement structure returned is the same used for all document and folder endpoints.

The currentUserAccessLevel allows the user to quickly determine which permissions the user has for this particular element.

See the Swagger API documentation for details.

Listing the contents of a folder

To list the folders and documents contained in a folder, use the folder content endpoint:

No Format
#list the documents/subfolders contained in the folder 666 curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/666/content

Or by path:

No Format

#list the documents/subfolders contained in the folder Parent Folder
curl -H "Argus- (in the space of the default customer for the current user)
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/content/Parent%20Folder

The response from this endpoint returns a list of folders and documents contained in this folder:

No Format

{
	"data": [
		{
			"id": 1087,
			"parentElements": [{"id": 666,"name": "Parent folder"}],
			"name": "Folder name",
 			...
			"accessMode": "explicit",
			"effectiveAccessMode": "explicit",
			"currentUserAccessLevel": "write",
			"elementType": "folder",
			"flags": []
		}],
		"size": 1
	],...
}

The parentElements field of a document/folder element lists the string of parent folders from this elements immediate parent up to the document root.

See the Swagger API documentation for details.

Listing the root folder

The root folder endpoint provides the contents of the users absolute root, which is a customer root folder if the user has access to only one customer.

However, if the user has access to multiple customers, the root folder endpoint will list all the available customer root folders.

This is a natural starting point if traversing the document tree manually.

No Format

Fetching a document

To the metadata of a document, use the document endpoint:

No Format
#fetch the metadata of the document 666 curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folderdocument/root

See the Swagger API documentation for details.

Fetching a document

To fetch the actual contents of a the document, use the document content endpoint

No Format
#list#fetch the documents/subfolderscontents containedof in the folderdocument 666 curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/666/content

See the Swagger API documentation for details.

Creating a document

To create a document, post a new document to the folder documents endpoint

Or by path:

No Format

#create a new#fetch the metadata of the document in folder 666 with name "my document", mimetype "text/plain" and a plaintext content/Parent Folder/Folder/Document.pdf (in the space of the default customer for the current user)
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/document/666/documents -d '{
  "name": "my document",
  "text": "contents",
  "mimeType": "text/plain"
}'



#create a new document in path/meta/Parent%20Folder/Folder/Document.pdf

#fetch the contents of the same document
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/path/content/Parent%20Folder/Folder/Document.pdf

See the Swagger API documentation for details.

Creating a document

To create a document, post a new document to the folder documents endpoint:

No Format

#create a new document in folder 666 with name "my imagedocument", mimetype "imagetext/pngplain" and a base64-encodedplaintext binary content
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/documentfolder/666/documents -d '{
  "name": "my imagedocument",
  "datatext": "MmZkZWFlZTUwYWMyMmRmNzhlOWNjN2MxOWViYjU2NDAKcontents",
  "mimeType": "imagetext/pngplain"
}'

See the Swagger API documentation for details.

Updating a document

To update an existing document, perform a PUT to the document endpoint.

No Format

#update document 1027 with new


#create a new document in folder 666 with name "newmy documentnameimage", mimetype "textimage/csvpng" and a base64-encoded plaintextbinary content
curl -XPUTXPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/666/documents -d '{
  "name": "my image",
  "data": "MmZkZWFlZTUwYWMyMmRmNzhlOWNjN2MxOWViYjU2NDAK",
  "mimeType": "image/document/1027 -d '{
  "name":png"
}'

To upload by path, use the streaming upload by path endpoint, below.

Upload document as stream

For larger documents, the document API now supports uploading by stream:

No Format

#create a new document "Document.pdf" in the folder 202 from the local file /path/to/Document.pdf
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/pdf" https://api.mnemonic.no/documents/v1/folder/202/documents --data-binary @/path/to/Document.pdf

Or by path

No Format

#create a new document "/Folder/Subfolder/Document.pdf" (in the space of the default customer for the current user)
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/pdf" https://api.mnemonic.no/documents/v1/document/path/Folder/Subfolder/Document.pdf --data-binary @/path/to/Document.pdf

#create a new document "/Folder/Subfolder/Document.pdf" (in the space of the customer "mycustomer")
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/pdf" https://api.mnemonic.no/documents/v1/document/path/Folder/Subfolder/Document.pdf?customer=mycustomer --data-binary @/path/to/Document.pdf

Tip
When uploading by path, the endpoint will reject the request if any of the parent folder elements are missing. Use option `createMissing=true` to create missing parent elements.

Tip
When posting a document, the endpoint will reject the request if an element with the same name exists in the parent folder. Use option `overwriteExisting=true` to overwrite existing document. This will fail if the existing element is a subfolder, or if the current user does not have write permissions to the existing element.

See the Swagger API documentation for details.

Updating a document

To update an existing document, perform a PUT to the document endpoint.

No Format

#update document 1027 with new name "new documentname",
  "text": "a,b,c",
  "mimeType": mimetype "text/csv"
}'

#update document 1027 with new binary and a plaintext content
curl -XPUT -H "Argus-API-Key: my/api/key-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/document/1027 -d '{
  "name": "new documentname",
  "text": "a,b,c",
  "datamimeType": "MmZkZWFlZTUwYWMyMmRmNzhlOWNjN2MxOWViYjU2NDAKtext/csv"
}'

In both examples, this will create a new revision of document 1027.a new revision of document 1027.

Tip
To update an existing document with streaming upload, use the streaming upload endpoint above, with option `overwriteExisting=true`

See the Swagger API documentation for details.

Creating a new folder

To create a new folder, use the POST endpoint on the folder element:

No Format

#create a new subfolder in folder 666 with name "my folder"
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/666 -d '{
  "name": "my folder"
}'

Or by path

No Format

#create a new subfolder in folder "MyRootFolder" with name "my folder"
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/path/MyRootFolder -d '{
  "name": "my folder"
}'

See the Swagger API documentation for details.

Deleting a document

No Format

#delete document 1027
curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/1027
#delete document 1027/Folder/Subfolder/Document.pdf
curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/1027path/Folder/Subfolder/Document.pdf

See the Swagger API documentation for details.

Deleting a folder

To delete a folder, the default mode is DELETE_IF_EMPTY, meaning that the folder must not contain any non-deleted entries, else the request will fail

No Format#delete folder 666

-deleted entries, else the request will fail

No Format

#delete folder 666
curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/666
#delete folder /Folder/Subfolder (in the space of the customer "mycustomer")
curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/666path/Folder/Subfolder?customer=mycustomer

To delete a folder recursively, use mode DELETE_CASCADE

No Format
#delete folder 666 curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/666?mode=DELETE_CASCADE

See the Swagger API documentation for details.

Managing document access

Managing access to documents can be done per document, or on a folder level.

Note
Folder access management can be done by the document owner, or users with the document manager role.

A users effective access permissions to an element can be folder access, read access or write access.

Write access is required to update a document, or add a document or subfolder to a folder.
Read access is required to read the contents of a document (data) or folder (subfolders/documents)
Folder access is required to traverse a folder or fetch folder/document metadata.

Tip
When listing the contents of a folder which the current user has folder level access to, it will only list subfolders or documents which the user also has access to.

	Folder access	Read access	Write access
Fetch folder metadata	X	X	X
Fetch document metadata	X	X	X
List folder contents		X	X
Download document contents		X	X
Add subfolder			X (on parent folder)
Add document to folder			X (on parent folder)
Update document			X (on document)

Role based access to documents provides different access levels for documents/folders depending on their access mode:

Role vs AccessMode	DOCUMENT-VIEWER	DOCUMENT-EDITOR	DOCUMENT-MANAGER	DOCUMENT-ADMIN
roleBased	Read access	Write access	Write access	Write access
writeRestricted	Read access	Read access	Write access	Write access
readRestricted	None	None	Write access	Write access
explicit	None	None	None	Write access

Explicit access control on documents/folders grants the affected user/group an explicit access level (read/write/folder access).

Tip
Granting explicit access for a subject to a folder/document will automatically grant folder access to the parent folder (recursively to the root folder), unless explicit access is granted to the same subject.

Creating element with restricted access

To create a folder with restricted access

No Format

#create a new subfolder with explicit access mode
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/666 -d '{
  "name": "my folder",
  "accessMode": "explicit"
}'

To create a document with restricted access:

No Format

#create a new document with access mode "explicit"
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/document/666/documents -d '{
  "name": "my document",
  "text": "contents",
  "mimeType": "text/plain",
  "accessMode": "explicit"
}'
#same operation for streaming upload by path
curl -XPOST -H ": "contents",
  "mimeType": "Argus-API-Key: my/api/key" -H "Content-Type: text/plain",
  "accessMode": "explicit"
}' https://api.mnemonic.no/documents/v1/document/path/Folder/Subfolder/my%20document?accessMode=explicit --data-binary @/path/to/document.txt

Setting new access mode on an element

No Format

#set access mode explicit on document 1027
curl -XPUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/document/1027/access -d '{
  "accessMode": "explicit"
}'
#set access mode explicit on folder 666
curl -XPUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/666/access -d '{
  "accessMode": "explicit"
}'
#set access mode explicit on /MyFolder by path
curl -XPUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/path/access/MyFolder -d '{
  "accessMode": "explicit"
}'

Granting explicit access to an element

No Format

#grant write access for subject 130 to document 1027
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/document/1027/access -d '{
  "subjectID": 130,
  "level": "write"
}'
#grant folder access for subject 130 to folder 666
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/666/access -d '{
  "subjectID": 130,
  "level": "folder"
}'
#grant folder access for subject 130 to folder /MyFolder
curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/documents/v1/folder/path/access/MyFolder -d '{
  "subjectID": 130,
  "level": "folder"
}'

Listing explicit access granted to an element

No Format

#list explicit access granted for document
curl -XGET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/1027/access
#list explicit access granted for folder 666
curl -XGET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/666/access
#list explicit access granted for folder /MyFolder
curl -XGET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/folder/path/access/MyFolder

Revoking explicit access from an element

Use the ID of the access element listed from the access endpoint:

No Format
#revoke explicit access granted to document 1027 curl -XDELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/documents/v1/document/1027/access/623

Table of Contents

Space shortcuts

Page tree

Versions Compared

Old Version 5

New Version Current

Key

About Documents API

Detailed API documentation

Integration guide

Documents and Folders by

ID

Folders by path

Fetch root folder for customer

Listing the contents of a folder

Listing the root folder

Fetching a document

Fetching a document

Creating a document

Creating a document

Updating a document

Updating a document

Creating a new folder

Deleting a document

Managing document access

Creating element with restricted access

Setting new access mode on an element

Granting explicit access to an element

Listing explicit access granted to an element

Revoking explicit access from an element

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 5

New Version Current

Key

About Documents API

Detailed API documentation

Integration guide

Documents and Folders by

ID

Folders by path

Fetch root folder for customer

Listing the contents of a folder

Listing the root folder

Fetching a document

Fetching a document

Creating a document

Creating a document

Updating a document

Updating a document

Creating a new folder

Deleting a document

Managing document access

Creating element with restricted access

Setting new access mode on an element

Granting explicit access to an element

Listing explicit access granted to an element

Revoking explicit access from an element