Versions Compared
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
pathThe 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:
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/ |
Reports/ |
Weekly%20Reports?customer=mycustomer |
GET https://api.mnemonic.no/documents/v1/folder/path/content/Folder/Subfolder?customer=mycustomer&limit=10&offset=20
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/ |
Reports/ |
POST https://api.mnemonic.no/documents/v1/folder/path/access/Folder/Subfolder?customer=mycustomer
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/ |
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 |
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 |
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.
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/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 endpointOr 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 |
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 |
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 |
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
-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 | ||
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 |
---|