Argus API Documentation
Space shortcuts
Page tree

Versions Compared

Old Version 5

changes.mady.by.user Joakim von Brandis

Saved on

compared with

New Version Current

changes.mady.by.user Joakim von Brandis

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

    666

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

    No Format
    #list#fetch the documents/subfolders contained incontents of 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 document in folder 666 with name "my document", mimetype "text/plain" and a plaintext content
curl -XPOST -#fetch the metadata of the document /Parent Folder/Folder/Document.pdf (in the space of the default customer for the current user)
curl -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 folder 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" }'and 
#update document 1027 with new binarya 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 accessRead accessWrite access
    Fetch folder metadataXXX
    Fetch document metadataXXX
    List folder contents
    		XX
    Download document contents
    		XX
    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 AccessModeDOCUMENT-VIEWERDOCUMENT-EDITORDOCUMENT-MANAGERDOCUMENT-ADMIN
    roleBasedRead accessWrite accessWrite accessWrite access
    writeRestrictedRead accessRead accessWrite accessWrite access
    readRestrictedNoneNoneWrite accessWrite access
    explicitNoneNoneNoneWrite 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 "Argus-API-Key: "contents",
  "mimeType": "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