Case Status Kiln
Log In

Wiki

Options

 
  • RSS Feed

Last modified on 8/08/2017 7:33 AM by User.

Tags:

API Documentation

 

THE PAGE BELOW IS OUT-DATED. PLEASE CLICK AND BOOKMARK THIS NEW LINK BELOW FOR THE LATEST API DOCUMENTATION:

https://intelligencebank.atlassian.net/wiki/display/APIDOC/

 

 

Overview

This service provides the ability to retrieve, add and modify digital assets that reside on an IntelligenceBank platform instance.

RFC2119 Words

The key words "MUST","MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in RFP2119.

Media Type Support

All server response bodies SHOULD be returned using the JSON Media Type. All client request bodies SHOULD be sent using the application/x-www-form-urlencoded Form Media Type, or the multipart/form Media Type as appropriate.

 

URLs and Operations

All URLs share a common base of

https://XXXXX.intelligencebank.com/webapp/1.0

where XXXXX is the subdomain assigned to a client.

Below is a list of the endpoint URLs and the operations they perform

/login

The /login URL supports the following HTTP methods

  1. POST using the Login Payload and returns the Login Response 

/reset

The /reset URL supports the following HTTP methods

  1. POST using the Reset Payload and returns the No Content Response

/resources

The /resources URL supports the following HTTP methods

  1.  GET using the Root Folder Request and returns the Folder Response
  2.  GET using the Folder Request and returns the Folder Response
  3.  GET using the Resource Request and returns the resource file or file size estimate
  4.  POST using the Create Folder Payload and returns the FolderResponse  
  5.  POST using the Create Resource Payload and returns the Resource Response
  6.  PUT using the Update Folder Payload and returns the FolderResponse
  7.  PUT using the Update Resource Payload and returns the Resource Response
  8.  DELETE using the Delete Folder Request and returns a No Content Response
  9.  DELETE using the Delete Resource Request and returns a No Content Response

/icon

The /icon URL supports the following HTTP methods

  1.  GET using the Icon Request and returns the icon file 

/comments

The /comments URL supports the following HTTP methods

  1. GET with the Comment Request and returns the Comment Response
  2. POST with the Comment Payload and returns the No Content Response

/sync

The /sync URL supports the following HTTP methods

  1. POST with the Sync Payload and returns the Sync Response

/search

The /search URL supports the following HTTP methods

  1. GET with the Search Request and returns the Search Response

/downloadpresets

The /downloadpresets URL supports the following HTTP methods

  1.  GET using the Download Preset Request and returns the Download Preset Response

/database

The /database URL supports the following HTTP methods

  1.  GET using the Databases Request and returns the Databases Response
  2.  GET using the Database Form Request and returns the Database Form Response
  3.  GET using the Database Request and returns the Database Response

Requests and Payloads

Below is a list of query strings and payloads that can be sent from the client to the server along with a list of common server responses

Login Payload

Example

   p70=joe.blow@test.com&p80=mypassword&p90=test.intelligencebank.com

would request a login to the test.intelligencebank.com site with the user joe.blow@test.com.

Note this payload is simple key/value pairs. The client MUST use POST to send this payload to the Login URL. You SHOULD use the following header

    Content-Type: application/x-www-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Login Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Reset Payload

Example

   p70=joe.blow@test.com&p90=test.intelligencebank.com

would request the server to send a password reset email to be sent to joe.blow@test.com. If the user is valid then an email will be sent to that address.

Note this payload is simple key/value pairs. The client MUST use POST to send this payload to the Reset URL. You SHOULD use the following header

    Content-Type: application/x-ww-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the No Content Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Root Folder Request

?p10={apikey}&p20={useruuid}

Example

   p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef

would request the contents of the root folder. This will contain metadata for all the folders with the root folder and will allow the client to navigate the underlying folder structure.

Note this is a query string and not a payload. The client MUST append this string to the Resources URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Folder Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Folder Request

?p10={apikey}&p20={useruuid}&folderuuid={folder uuid}&skip={starting position}&limit={number of resources to return}

Example

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef&folderuuid=hg3v23ghj4hb34hhjhjg34

would request the contents of the folder with that folderuuid. The response will contain metadata for all the folders and resources within  the folder.

If the limit parameter is included in the request then the number of resources returned will be the value of the limit parameter, starting from the first resource if their is no skip value present, or from the value of the skip parameter if it is present.

If the skip parameter is included in the request and the limit parameter is not then the resources returned will be those starting from the skip value and ending at the last resource.

The skip value is zero indexed based i.e. the first resource resides at skip=0. If the skip parameter is not included in the request then the starting point will be as if a skip value of 0 was included. If the skip value is larger than the number of resources in the folder then no resource element will be returned. 

Note this is a query string and not a payload. The client MUST append this string to the Resources URL. The client MUST include the p10, p20 and folderuuid parameters. The client MAY include the skip and/or the limit parameters. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Folder Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Resource Request

?p10={apikey}&p20={useruuid}&fileuuid={resource uuid}&version={ version number }&ext={ file extension }&preview=true&size={ percentage of original file size }&cropwidth={ cropped output width }&cropheight={ cropped output height }&cropx={ x coordinate to start the crop }&cropy={ y coordinate to start the crop }&compression={ compression quality }&compressiontype={ type of compression }

Examples

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34

would request to download the file with that fileuuid.

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34&size=25&ext=gif    

would request to download the file with that fileuuid at 25% of its original size, converted to a gif format


        p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34&compression=80&compressiontype=10 

would request to download the file with that fileuuid compressed at 80% using JPEG lossless compression

        p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34&cropwidth=200&cropheight=200&cropx=0&cropy=0    

would request to download the file with that fileuuid cropped to 200x200px starting from the top left 
corner of the image


        p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34&cropwidth=200&cropheight=200&compression=50
            &compressiontype=10&fileinfo=true    

would request the estimated file size of the file with that fileuuid if it was to be cropped to 200x200px,  
compressed at 50% using JPEG losslesscompression

Mandatory parameters: p10, p20, fileuuid

Note this is a query string and not a payload. The client MUST append this string to the Resources URL. The client MUST use GET when executing this request.

Notes:

  1. If the version number is provided then that version's file will be downloaded. If the provided version number is not found then a  'not found' response will be provided
  2. If no version parameter is provided then the latest or current file version is downloaded.
  3. If the preview=true parameter is set then the returned image will be a png version of the original.
  4. If cropping an image, the following 4 parameters must be specified: cropwidth, cropheight, cropx and cropy
  5. If size parameter is included in a URL which also contains cropping parameters, the cropping parameters (cropwidth, cropheight, cropx and cropy) need to be specified at the same percentage as the size parameters.
    e.g. The following two snippets would produce the same target part of the image just at different dimensions -Without the size parameter: &cropwidth=960&cropheight=600&cropx=800&cropy=500                                       With the size parameter set to 50%: &cropwidth=480&cropheight=300&cropx=400&cropy=250&size=50
  6. Types  of compression:
    • 1 = No compression
    • 2 = BZIP2 (Lossless Compression)
    • 8 = JPEG (Lossy Compression)
    • 10 = JPEG (Lossless Compression)
    • 11 = LZW (Lemple-Zif-Welch) (Lossless Compression)
    • 12 = Run-Length Encoding (Lossless Compression)
    • 13 = ZIP (Lossless Compression)

Upon successful completion of this operation, the server SHOULD return the requested file. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Delete Folder Request

?p10={apikey}&p20={useruuid}&folderuuid={folder uuid}

Example

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &folderuuid=hg3v23ghj4hb34hhjhjg34

would request to delete the folder with that folderuuid.

Note this is a query string and not a payload. The client MUST append this string to the Resources URL. The client MUST use DELETE when executing this request.

Upon successful completion of this operation, the server SHOULD return the No Content Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Delete Resource Request

?p10={apikey}&p20={useruuid}&fileuuid={folder uuid}

Example

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34

would request to delete the file with that fileuuid.

Note this is a query string and not a payload. The client MUST append this string to the Resources URL. The client MUST use DELETE when executing this request.

Upon successful completion of this operation, the server SHOULD return the No Content Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Create Folder Payload

?p10={apikey}&p20={user id}

Example

   name=Images&parent=hjsdhsd5sddsjhd675ddfsfddsf

would request to create the folder called Images within the parent folder with that uuid.

Note this payload is simple key/value pairs. The client MUST use POST to send this payload to the Resources URL. You SHOULD use the following header

    Content-Type: application/x-ww-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Folder Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Update Folder Payload

?p10={apikey}&p20={user id}&folderuuid=hg3v23ghj4hb34hhjhjg34dssf

Example

   name=Archived%20Images

would request to update the name of the folder with that uuid to the new value "Archived Images"

Note this payload is simple key/value pairs. The client MUST use PUT to send this payload to the Resources URL. You SHOULD use the following header

    Content-Type: application/x-ww-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Folder Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Create Resource Payload

?p10={apikey}&p20={user uuid}&folderuuid={folder uuid}

Note this payload is a mulitpart/form-data. The client MUST use POST to send this payload to the Resources URL.

The name parameter in the header of the file component of the form MUST be called file1 i.e. name=file1.

The filename parameter in the header of the file component of the form MUST be the path to the file to be uploaded i.e. filename=<name of file to upload>

Example

 -------NEXT_PART_1431579477.49877
Content-Disposition: form-data; name="options"

{
    "folder"      : "06da9efd9e96a973015a5571b65d4b6c",
    "filename"    : "/opt/test.txt",
    "name"        : "Test file",
    "description" : "this is a test file"
}
-------NEXT_PART_1431579477.49877
Content-Disposition: form-data; name=file1; filename=/opt/test.txt
Content-Type: plain/text

one
two
three
four

-------NEXT_PART_1431579477.49877--

would request to upload the file called test.txt, save it within the folder with that uuid, give it the name "Test file" and a description of "this is a test file".

You SHOULD use the following header

    Content-Type: multipart/form-data

Upon successful completion of this operation, the server SHOULD return the No Content Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Update Resource Payload

There are two options for the update a resource. The first option is for updating the metadata of the resource only, not the actual file.  The second is for updating the resource file, and optionally the metadata too.

              Option 1 - Update metadata only

The URL would contain the following parameters

?p10={apikey}&p20={user id}&fileuuid={resource uuid}

And the body of the request would contain the metadata to be updated. This will overwrite the existing data so any existing tags must also be sent back when updating this field.

Example

   name=Archived%20Images&description=Old%20images&tags=California%2c%20trip%2c%20San%20Diego

would request to update the name of the folder with that uuid to the new value "Archived Images", set the description to "Old images" and set the keywords to "California, trip, San Diego"

Supported fields for metadata updates are Title, Description and Tags (referred to as Keywords in the platform).

Note this payload is simple key/value pairs. The client MUST use PUT to send this payload to the Resources URL. You SHOULD use the following header

    Content-Type: application/x-ww-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Resource Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response

Option 2 - Update Resource File

?p10={apikey}&p20={user id}&fileuuid={resource uuid}

Example

 -------NEXT_PART_1431579477.49877
Content-Disposition: form-data; name="options"

{
    "folder"      : "06da9efd9e96a973015a5571b65d4b6c",
    "filename"    : "/opt/test2.txt",
    "name"        : "Test 2 file",
    "description" : "this is the new version"
}
-------NEXT_PART_1431579477.49877
Content-Disposition: form-data; name=file1; filename=/opt/test.txt
Content-Type: plain/text

one
two
three
five

-------NEXT_PART_1431579477.49877--

would request to upload the file called test2.txt, replace the existing file that is linked to that uuid, change the name to "Test 2 file" and the description to  "this is the new version".

Note this payload is a mulitpart/form-data. The client MUST use PUT to send this payload to the Resources URL. You SHOULD use the following header

    Content-Type: multipart/form-data

Upon successful completion of this operation, the server SHOULD return the Resource Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Thumbnail / Icon Request

?p10={apikey}&p20={useruuid}&type={ folder | people | file }&name={ folderuuid | fileuuid | useruuid | 'folder' | 'people }&ext={ file extension desired }

Example

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &type=file&name=hg3v23ghj4hb34hhjhjg34&ext=PDF

would request to get the Thumbnail / Icon for the PDF version of the file with that fileuuid. If there was also. a DOCX version of the file then the 'ext' part of the request would change to DOCX

Note this is a query string and not a payload. The client MUST append this string to the Thumbnail / Icon URL. The client MUST use GET when executing this request.

Notes

  1. If a name is provided but a custom icon cannot be found, and a client default Thumbnail / Icon cannot be found then the default icon for the type is returned.
  2. If the name and type and ext parameters are missing it will return the default resource Thumbnail / Icon
  3. If a name is provided and the type is set to file and a valid ext is provided, then the ext Thumbnail / Icon is returned, otherwise the default resource icon is returned.

Upon successful completion of this operation, the server SHOULD return the requested file. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Comment Request

?p10={apikey}&p20={useruuid}&fileuuid={  fileuuid  }

Example

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
            &fileuuid=hg3v23ghj4hb34hhjhjg34

would request to get any comments for the file with that fileuuid.

Note this is a query string and not a payload. The client MUST append this string to the Comment URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Comment Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Comment Payload

?p10={apikey}&p20={user id}&fileuuid={ fileuuid }&version={version number}

Example

 p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef
        &type=file&fileuuid=hg3v23ghj4hb34hhjhjg34
   comment=some%20text%20goes%20for%20a%20comment

would create the comment and attach it to the file with that fileuuid. If there is a version number as part of the request then the comment will be attached to that version of the file, otherwise it will be attached to the latest version.

Note this payload is simple key/value pairs. The client MUST use POST to send this payload to the Comment URL. You SHOULD use the following header

    Content-Type: application/x-ww-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Comment Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Sync Payload

?p10={apikey}&p20={user id}

POST data

apikey={apikey}&useruuid={user id}
&sync=[{"folders":[<one or more folderuuids>]},{"files":[{<fileuuid>,<updatedat>,<optional annotations>]}]

Example

 apikey=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&useruuid=3nj34hvdsjds8dnfnfd87bhbvuef
    &sync=[{"folders":["06da9efd9e96a973015a5571b65d4b6c","334j3jkh3dsf76dsf7sdf7sdb6c"]}, 
            {"files":{"fileuuid":"hg3v23ghj4hb34hhjhjg34dfsf","updatedat":"2015-01-01 11:00:00", 
                "annotation":[{"annotation data"}]}]}]

        would ask for the sync data for the two folders with uuids listed and for the file with that fileuuid, which has been updated with a new annotation.

Note this payload is a key/value pair with the value of the sync key being a JSON format document. The client MUST use POST to send this payload to the Sync URL. You SHOULD use the following header

    Content-Type: application/x-www-form-urlencoded 

Upon successful completion of this operation, the server SHOULD return the Sync Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Search Request

?p10={apikey}&p20={useruuid}&searchterm={  word or words to search for  }&folderuuid= {folder uuid to start search from }&fromdate={ date to search from in format YYYY-MM-DD}

The folderuuid and fromDate fields are optional.

Examples

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef&searchterm=supercalifraj

would request to get any documents that contain the term 'supercalifraj'

       p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef&searchterm=*&fromDate=2017-01-01

would request to get all documents updated or created since Jan 1 2017

Note this is a query string and not a payload. The client MUST append this string to the Search URL. The client MUST use GET when executing this request.

Notes:

  1. If folderuuid is not present in the URL then the search will start from the root folder.

Upon successful completion of this operation, the server SHOULD return the Search Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Download Preset Request

?p10={apikey}&p20={useruuid}

Example

   p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef

would request all the saved download presets.

Note this is a query string and not a payload. The client MUST append this string to the Download Presets URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Download Preset Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Databases Request

?p10={apikey}&p20={useruuid}

Example

   p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef

would request all the databases.

Note this is a query string and not a payload. The client MUST append this string to the Databases URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Databases Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Database Form Request

?p10={apikey}&p20={useruuid}&databaseuuid={databaseuuid}&form=true

Example

   p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef \ 
       &databaseuuid=gryfhgutjgiyhkgjhutyrgdnbvjhj&form=true

would request the form structure for the database with that databaseuuid.

Note this is a query string and not a payload. The client MUST append this string to the Databases URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Database Form Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Database Request

?p10={apikey}&p20={useruuid}&databaseuuid={databaseuuid}

Example

   p10=adsferdftfgryfhgutjgiyhkgjhutyrgdnbvjhj&p20=3nj34hvdsjds8dnfnfd87bhbvuef \ 
       &databaseuuid=gryfhgutjgiyhkgjhutyrgdnbvjhj

would request the records for the database with that databaseuuid.

Note this is a query string and not a payload. The client MUST append this string to the Databases URL. The client MUST use GET when executing this request.

Upon successful completion of this operation, the server SHOULD return the Database Form Response. If the operation is not successful, the server MUST return the appropriate HTTP status code and the Error Response.

Responses

Below is a list of the common responses from the server

Login Response

The HTTP status code is returned with the following cookie

_aid: <aid cookie>

and the following body:

{
    "clientid":<clientid>,
    "clientname":"<clientname>",
    "clientuuid":"clientuuid",
    "apikey":"<apikey>",
    "logintimeoutperiod":<login timeout in hours>,
    "adminemail":"conatct email for site",
    "passwordexpiryperiod":<password expiry days | null>,
    "userverificationperiod":<user verify in days | null>,
    "offlineexpiryperiod":<days offline till expiry>,
    "annotations":"<basic | advanced | null>",
    "comments":"< 1 | null",
    "passwordexpired":< 1 | null>,
    "emailexpired":< 1 | null>,
    "versions":"< 1 | null>",
    "firstname":"<users firstname>",
    "lastname":"<users lastname>",
    "useruuid":"<user uuid>",
    "thumbnail":"<rel url for user thumbnail>",
    "foldericon":"<icon type for folder>",
    "rowsOnPage":"<number of rows per page>",
    "defaultFolderSortOrder":"<sort order for folders>"
}


The server SHOULD return this response when the POST /login operation is successful.

The _aid value returned in the cookie of the header is required in the header for all subsequent operations.

Folder Response

The HTTP status code is returned with the following body:

{
    "response":
        {
            "hasversions":"< 1 if versions is enabled | 0 >",
                "folder":[
                    {
                        "folderuuid":"<folderuuid>",
                        "name":"<folder name>",
                        "description":"<folder description>",
                        "createdtime":"<UTC datetime created>",
                        "comments":"<has comments>",
                        "perm":"<permission level for this user for this folder",
                        "children":
                            {
                                "folders":"<number of subfolders>",
                                "resources":"<number of resource files>"
                            },
                        "defaultorder":"<default order for resources>",
                        "sortorder":"<sequence number for ordering within parent folder>"
                    },
                    {
                        ... another folder 
                    }
                ],
                "resource":[
                    {
                        "resourceuuid":"<resource uuid>",
                        "resourcetype":"<resource type - file>",
                        "seen":"< 1 if user has opened this resource>",
                        "title":"<name of resource>",
                        "description":"<description of resource>",
                        "sortorder":"<sequence number for ordering within folder for viewing>",
                        "updatedat":"<UTC datetime updated>",
                        "processedat":"<UTC datetime file was processed>",
                        "updatedby":"<firstname lastname of user who last updated or created file>",
                        "ownershiptype":"<ownership type>",
                        "tags":[<any keywords for this file>],
                        "fileuuid":"<file uuid>",
                        "filetype":"<file type extension>",
                        "filesize":"<size of file in bytes>",
                        "prevfiletype":"<type of preview file>",
                        "prevfilesize":"<file size in bytes of preview file>",
                        "origfilename":"<original filename including extension>",
                        "resourcedate":"<UTC date file created or date set by user>",
                        "uploadedtime":"<UTC datetime file was uploaded>",
                        "reviewdate":"<UTC datetime for review of ile if set>",
                        "printing":"< 1 if printing allowed>",
                        "version":"<version number>",
                        "annotations":"<whether file has annotations>",
                        "versions":[
                            {
                                "versionnumber":"<version number>",
                                "origfilename":"<original filename including extension>",
                                "filetype":"<file type extension>",
                                "filesize":"<file siz ein bytes>",
                                "datecreated":"<UTC datetime when file created>",
                                "comment":"<any comments on file>",
                                "createdby":"<firstname lastname of user who created file>",
                                "ownershiptype":"<ownership type>"
                            }
                        ]
                    }
                ]
        }
}

The server SHOULD return this response when the GET Root Folder Request, Folder Request, Create Folder, Update Folder  operations are successful.

Resource Response

The HTTP status code is returned with the following body:

{
    "response":
        {
            "resource":[
                    {
                        "resourceuuid":"<resource uuid>",
                        "resourcetype":"<resource type - file>",
                        "seen":"< 1 if user has opened this resource>",
                        "title":"<name of resource>",
                        "description":"<description of resource>",
                        "sortorder":"<sequence number for ordering within folder for viewing>",
                        "updatedat":"<UTC datetime updated>",
                        "processedat":"<UTC datetime file was processed>",
                        "updatedby":"<firstname lastname of user who last updated or created file>",
                        "ownershiptype":"<ownership type>",
                        "tags":[<any keywords for this file>],
                        "fileuuid":"<file uuid>",
                        "filetype":"<file type extension>",
                        "filesize":"<size of file in bytes>",
                        "prevfiletype":"<type of preview file>",
                        "prevfilesize":"<file size in bytes of preview file>",
                        "origfilename":"<original filename including extension>",
                        "resourcedate":"<UTC date file created or date set by user>",
                        "uploadedtime":"<UTC datetime file was uploaded>",
                        "reviewdate":"<UTC datetime for review of ile if set>",
                        "printing":"< 1 if printing allowed>",
                        "version":"<version number>",
                        "annotations":"<whether file has annotations>",
                        "versions":[
                            {
                                "versionnumber":"<version number>",
                                "origfilename":"<original filename including extension>",
                                "filetype":"<file type extension>",
                                "filesize":"<file siz ein bytes>",
                                "datecreated":"<UTC datetime when file created>",
                                "comment":"<any comments on file>",
                                "createdby":"<firstname lastname of user who created file>",
                                "ownershiptype":"<ownership type>"
                            }
                        ]
                    }
                ]
        }
}

The server SHOULD return this response when the Create Resource Request and Update Resource Request  operations are successful.

 

The HTTP status code is returned with the following body:

{
    "estimatedFileSize": "<estimated size of the file after parameters have been applied in bytes>"
}

The server SHOULD return this response when the GET Resource Request with { fileinfo=true } has  been  successful.

 

Comment Response

The HTTP status code is returned with the following body:

{
    "response":
        {
            "comment":{
                        "commentid":"<comment id> ",
                        "comment":"<comment text>",
                        "createdat":"<UTC datetime created>",
                        "createdby":"<firstname lastname of user who created file>",
                        "updatedat":"<UTC datetime updated>",
                        "updatedby":"<firstname lastname of user who last updated or created file>",
                        "version":"<version number>",
                        "iconuuid":"<uuid of icon of creator>",
                       }
        }
}

The server SHOULD return this response when the GET Comment Request operation is successful.

 

Sync Response

The HTTP status code is returned with the following body:

{
    "folders":
        {
            "folder":[
                {
                    "folderuuid":"<folder uuid>",
                    "hasversions":"< 1 if versions enabled, 0 if not >",
                    "perm":"< permission level >",
                    "resource":[
                        {
                            "resourceuuid":"<resource uuid>",
                            "resourcetype":"<resource type>",
                            "seen":"< 1 if previosly accessed, 0 if not >",
                            "title":"<name of resource>",
                            "description":"<description>",
                            "sortorder":<sequence order in folder listing | null>,
                            "processedat":"<UTC datetime processed>",
                            "updatedat":"<UTC datetime updated>",
                            "updatedby":"<firstname lastname of user who last updated>",
                            "tags":[<keywords to be linked to resource>],
                            "uploadedtime":"<UTC datetime file uploaded>",
                            "fileuuid":"<file uuid>",
                            "filetype":"<file type extension>",
                            "filesize":"<file size in bytes>",
                            "prevfiletype":"<type of preview file>",
                            "prevfilesize":"<file size in bytes of preview file>",
                            "origfilename":"<original filename>",
                            "annotations":"<1 if annotations enabled or 0>",
                            "annotation":[{<annotation data>},{ .. another annotation .. }],
                            "resourcedate":"2015-05-14 05:12:47",
                            "printing":"<1 if printing allowed or 0>",
                            "version":"<version number>",
                            "tree":[<list of folder uuids as folder tree for this resource>]
                            "versions":[
                                {
                                    "versionnumber":"<version number>",
                                    "origfilename":"<original filename>",
                                    "filetype":"<file type extension>",
                                    "filesize":"<file size in bytes>",
                                    "datecreated":"UTC datetime file uploaded",
                                    "comment":<comments>,
                                    "createdby":"<firstname lastname of creator>"
                                }] 
                        },{
                             ..... next resource
                        }
                    ]
                },{
                    ... next folder
                  }
              ]
          },
        {
            "files": 
                [
                   file: {
                            "status":"<deleted | updated | newfile | access denied>",
                            "resourceuuid":"<resource uuid>",
                            "resourcetype":"<resource type>",
                            "seen":"< 1 if previosly accessed, 0 if not >",
                            "title":"<name of resource>",
                            "description":"<description>",
                            "sortorder":<sequence order in folder listing | null>,
                            "processedat":"<UTC datetime processed>",
                            "updatedat":"<UTC datetime updated>",
                            "updatedby":"<firstname lastname of user who last updated>",
                            "tags":[<keywords to be linked to resource>],
                            "uploadedtime":"<UTC datetime file uploaded>",
                            "fileuuid":"<file uuid>",
                            "filetype":"<file type extension>",
                            "filesize":"<file size in bytes>",
                            "prevfiletype":"<type of preview file>",
                            "prevfilesize":"<file size in bytes of preview file>", 
                            "origfilename":"<original filename>",
                            "annotations":"<1 if annotations enabled or 0>",
                            "annotation":[{<annotation data>},{ .. another annotation .. }],
                            "resourcedate":"<UTC datetime created>",
                            "resourcedate":"<UTC datetime review due>",
                            "printing":"<1 if printing allowed or 0>",
                            "version":"<version number>",
                            "tree":[<list of folder uuids as folder tree for this resource>]
                            "versions":[
                                {
                                    "versionnumber":"<version number>",
                                    "origfilename":"<original filename>",
                                    "filetype":"<file type extension>",
                                    "filesize":"<file size in bytes>",
                                    "datecreated":"UTC datetime file uploaded",
                                    "comment":<comments>,
                                    "createdby":"<firstname lastname of creator>"
                                    "prevfiletype":"<type of preview file>",
                                    "prevfilesize":"<file size in bytes of preview file>", 
                                }], 
                        }
            ]
      }
}

The server SHOULD return this response when the Sync Payload operation is successful.

Search Response

The HTTP status code is returned with the following body:

{
    "numFound":"7",
    "doc":[
        {
            "uuid":"15e617346a2cc44edd72e59d86559b90",
            "title":"Version Test",
            "description":"",
            "id":"250597",
            "ext":"PDF",
            "data":{
                "location":"content",
                "snippet":{
                    "ib_title":"Version <em>Test</em>"
                }
            },
            "file":            
                  {
                    "resourceuuid":"<resource uuid>",
                            "resourcetype":"<resource type>",
                            "seen":"< 1 if previosly accessed, 0 if not >",
                            "title":"<name of resource>",
                            "description":"<description>",
                            "sortorder":<sequence order in folder listing | null>,
                            "processedat":"<UTC datetime processed>",
                            "updatedat":"<UTC datetime updated>",
                            "updatedby":"<firstname lastname of user who last updated>",
                            "tags":[<keywords to be linked to resource>],
                            "uploadedtime":"<UTC datetime file uploaded>",
                            "fileuuid":"<file uuid>",
                            "filetype":"<file type extension>",
                            "filesize":"<file size in bytes>",
                            "prevfiletype":"<type of preview file>",
                            "prevfilesize":"<file size in bytes of preview file>", 
                            "origfilename":"<original filename>",
                            "annotations":"<1 if annotations enabled or 0>",
                            "annotation":[{<annotation data>},{ .. another annotation .. }],
                            "resourcedate":"<UTC datetime created>",
                            "resourcedate":"<UTC datetime review due>",
                            "printing":"<1 if printing allowed or 0>",
                            "version":"<version number>",
                            "tree":[<list of folder uuids as folder tree for this resource>]                                       "versions":[
                                {
                                    "versionnumber":"2",
                                    "origfilename":"<original filename>",
                                    "filetype":"<file type extension>",
                                    "filesize":"<file size in bytes>",
                                    "datecreated":"<UTC datetime file uploaded>",
                                    "comment":<comments>,
                                    "createdby":"<firstname lastname of creator>"                                                            "prevfiletype":"<type of preview file>",
                                    "prevfilesize":"<file size in bytes of preview file>",                                             },{
                                    "versionnumber":"1",
                                    "origfilename":"<original filename>",
                                    "filetype":"<file type extension>",
                                    "filesize":"<file size in bytes>",
                                    "datecreated":"<UTC datetime file uploaded>",
                                    "comment":"<comments>",
                                    "createdby":"<firstname lastname of creator>"                                                            "prevfiletype":"<type of preview file>",
                                    "prevfilesize":"<file size in bytes of preview file>",                                             }
                            ]
                    }}
        ]

}

The server SHOULD return this response when the Search Request operation is successful.

Download Preset Response

The HTTP status code is returned with the following body:

{
    "presets":[
        {
            "uuid":"15e617346a2cc44edd72e59d86559b90",
            "name":"Preset Test",
            "fileType":"png",
            "compressionQuality":"60",
            "compressionType":"1",
            "fileSize":"custom",
            "customWidth":200            
            "customHeight":200,
            "cropWidth":null,
            "cropHeight":null,
            "id":3322362,
        },
        {
            ... next download preset
        }
    ]
}

The server SHOULD return this response when the Download Preset Request operation is successful.

Databases Response

The HTTP status code is returned with the following body:

{
    "response":{
           "databases":[
               {
                   "name":"<name>",
                   "description":"<desciption>",
                   "submissionType":"single",
                   "sortorder":0,
                   "allowComment":false,
                   "samePageDatabaseSettings":"no",
                   "autoCreateResourceFolders":"off",
                   "related":null,
                   "autoCreateDestinationFolder":null,
                   "autoCreateCloneStructureDestinationFolder":null,
                   "customItemNameSingle":null,
                   "customItemNamePlural":null,
                   "uuid":"130441211b4da09128b62308bdbe9098",
                   "createTime":"2017-03-24T14:31:07+11:00",
                   "lastUpdateTime":"2017-04-21T13:52:22+10:00",
                   "_id":"130441211b4da09128b62308bdbe9098",
                   "thumbnail":"/uploads/8ec3b01d58fe6c616e602cf8c388273f/logo/a68304b192a27f34eb1b4726e625f9ef.png"
               },
           ... another database    
           ]
    }
}

The server SHOULD return this response when the GET Databases Request operation is successful.

Database Form

The HTTP status code is returned with the following body:

"response":{
    "tab":{
        "label":"",
        "uuid":"<tabuuid>",
        "sections":[
            {
                "uuid":"<section uuid>",
                "label":"<label>",
                "fields":[
                    [
                        {
                            "id":"<field uuid",
                            "label":"<field label>",
                            "type":"<field type>"
                        },
                        {
                            "id":"<field uuid",
                            "label":"<field label>",
                            "type":"<field type>"
                        },
                        {
                            "id":"<field uuid>",
                            "label":"<field label>",
                            "type":"<checkbox|radio|select>",
                            "options":{
                                "<option uuid>":
                                    {
                                        "uuid":"<option uuid>",
                                        "value":"<option value"
                                    },
                                "<option uuid>":
                                    {
                                        "uuid":"<option uuid>",
                                        "value":"<option value"
                                    },
                                ... other options
                        },
                        ... other fields
                    ]
                ]
            },
            {
              ... another section
            }
        ]
    }
}

The server SHOULD return this response when the GET Database Form Request operation is successful.

Database

The HTTP status code is returned with the following body:

"response": {
    "records": [
      {
        "meta": {
          "uuid": "<record uuid",
          "createTime": "2017-04-11T16:24:25+10:00",
          "lastUpdateTime": "2017-04-21T13:51:34+10:00",
          "title": "<record title>",
          "verbosetitle": "<verbose title>",
          "currentstage": "<current stage uuid>",
          "isSubmissionCompleted": <true|false>
        },
        "fields": [
          {
            "id": "<field uuid>",
            "label": "<field label>",
            "type": "<field type>",
            "value": "<field value>"
          },
          {
            "id": "<field uuid>",
            "label": "<field label>",
            "type": "<type = select|radio|checkbox>",
            "value": [
              "<option value>"
              ... <other values for multiple value field>
            ]
          },
          ... other fields
        ]
     },
     {
         ... another record
     }
    ]
  }

The server SHOULD return this response when the GET Database Request operation is successful.

No Content Response

The HTTP status code is returned with no body.


The server SHOULD return this response when the Delete Folder Request, Delete Resource Request, Rest Request and Comment Payload  operations are successful

Error Response

The HTTP status code returned is in the 4xx or 5xx family and an appropriate error message is included in the body. For example:

    Error Response
    404 Not Found HTTP/1.1
    Content-Type: application/json

    {message:"<Reason for error>"}

The server MUST return this response when any requested operation fails.

Note

It is possible that future forward-compatible modifications to this specification will include new URLs, objects, arrays, properties etc. Al care will be taken to ensure these do not effect the existing calls.

 

Learn more about each call

Authentication

  1. Login
  2. Reset password
  3. Verify email

Resources Library

  1. Retrieve folder contents
  2. Retrieve folder info
  3. Download a file
  4. Retrieve estimated file size
  5. Retrieve a thumbnail
  6. Retrieve an annotation
  7. Save an annotation
  8. Retrieve comments
  9. Save a comment
  10. Synchronize external application and web
  11. Search in cloud
  12. Retrieve download presets

Databases

  1. Retrieve database list
  2. Retrieve database form
  3. Retrieve database records