Documents

Documents are files placed in folders.

Documents do not have individual permissions, but inherit them from the folder, they are in. Hence, everyone, who can see a folder, can see all documents therein, and everyone, who can edit a folder, can edit documents in it.

Get Folders

curl "https://example.ziik.io/api/folders"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
    "hits":
    [
      {
        "id": 122,
        "content_type": "folder",
        "parent": 121,
        "name": "Example Folder",
        "owner": {},
        "userTypes": [
            {
                "id": 345,
                "name": "Example User Type",
                "rights": "access"
            },
            {
                "id": 456,
                "name": "Other User Type",
                "rights": "manage"
            }
        ],
        "units": [
            {
                "content_type": "unit",
                "id": 567,
                "name": "Example unit",
                "url": "api/units/567"
            }
        ],
        "shared": false,
        "inheritedShares": [
            {
                "id": 123,
                "name": "Frank Castle",
                "rights": "manage"
            }
        ],
        "url": "api/folders/122"
      },
      {
        "id": 123,
        "content_type": "folder",
        "parent": 121,
        "name": "Another Folder",
        "userTypes": [
            {
                "id": 345,
                "name": "Example User Type",
                "rights": "access"
            },
            {
                "id": 456,
                "name": "Other User Type",
                "rights": "manage"
            }
        ],
        "units": [
            {
                "content_type": "unit",
                "id": 567,
                "name": "Example unit",
                "url": "api/units/567"
            }
        ],
        "shared": false,
        "inheritedShares": [
            {
                "id": 123,
                "name": "Frank Castle",
                "rights": "manage"
            }
        ],
        "url": "api/folders/123"
      }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 50,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

This endpoint retrieves a list of folders.

If a parent ID is supplied, sub-folders to that folder are returned.

If no parent ID is supplied, root folders are returned.

Folders are restricted by user types and units.

The "owner" attribute is a User object.

HTTP Request

GET https://example.ziik.io/api/folders

Query Parameters

ParameterTypeDefaultDescription
parentInteger0ID of the parent folder to fetch folders for
pageInteger1Page number for pagination.
limitInteger500Number of records to return per page.

Get Folder Hierarchy

curl "https://example.ziik.io/api/folders/tree"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
    "hits":
    [
        {
            "id": 121,
            "content_type": "folder",
            "parent": 0,
            "name": "Parent Folder",
            "owner": {},
            "userTypes": [
                {
                    "id": 345,
                    "name": "Example User Type",
                    "rights": "access"
                },
                {
                    "id": 456,
                    "name": "Other User Type",
                    "rights": "manage"
                }
            ],
            "units": [
                {
                    "content_type": "unit",
                    "id": 567,
                    "name": "Example unit",
                    "url": "api/units/567"
                }
            ],
            "url": "api/folders/121",
            "children": [
              {
                "id": 122,
                "content_type": "folder",
                "parent": 121,
                "name": "Example Folder",
                "owner": {},
                "userTypes": [
                    {
                        "id": 345,
                        "name": "Example User Type",
                        "rights": "access"
                    },
                    {
                        "id": 456,
                        "name": "Other User Type",
                        "rights": "manage"
                    }
                ],
                "units": [
                    {
                        "content_type": "unit",
                        "id": 567,
                        "name": "Example unit",
                        "url": "api/units/567"
                    }
                ],
                "url": "api/folders/122"
              },
              {
                "id": 123,
                "content_type": "folder",
                "parent": 121,
                "name": "Another Folder",
                "owner": {},
                "userTypes": [
                    {
                        "id": 345,
                        "name": "Example User Type",
                        "rights": "access"
                    },
                    {
                        "id": 456,
                        "name": "Other User Type",
                        "rights": "manage"
                    }
                ],
                "units": [
                    {
                        "content_type": "unit",
                        "id": 567,
                        "name": "Example unit",
                        "url": "api/units/567"
                    }
                ],
                "url": "api/folders/123"
              }
            ]
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 50,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

This endpoint retrieves a list of folders with their children (sub-folders).

If a folder ID is supplied in the root parameter, only that folder and its sub-folders are returned.

If a folder ID is supplied in the exclude parameter, that folder and its sub-folders are NOT returned.

The "owner" attribute is a User object.

HTTP Request

GET https://example.ziik.io/api/folders/tree

Query Parameters

ParameterTypeDefaultDescription
rootInteger0ID of the folder to set as root of the returned hierarchy.
excludeInteger0ID of a folder to exclude from the result along with its children.

Get Single Folder

curl "https://example.ziik.io/api/folders/121"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
    "id": 122,
    "content_type": "folder",
    "parent": 121,
    "name": "Example Folder",
    "owner": {},
    "userTypes": [
        {
            "id": 345,
            "name": "Example User Type",
            "rights": "access"
        },
        {
            "id": 456,
            "name": "Other User Type",
            "rights": "manage"
        }
    ],
    "units": [
        {
            "content_type": "unit",
            "id": 567,
            "name": "Example unit",
            "url": "api/units/567"
        }
    ],
    "shared": false,
    "inheritedShares": [
        {
            "id": 123,
            "name": "Frank Castle",
            "rights": "manage"
        }
    ],
    "url": "api/folders/122"
}

This endpoint returns a single folder by its ID.

The "owner" attribute is a User object.

HTTP Request

GET https://example.ziik.io/api/folders/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the folder to retrieve`

Permissions Required

  • Access to folder - User's user type must be in folder's user types for non-personal folders. User's unit must be in folder's units for shared folders.

Create New Folder

curl -i -X POST "https://example.ziik.io/api/folders"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"name\": \"A New Folder\", \"parent\": 121, \"units\": [567], \"userTypes\": {"access": [345, 456], "manage": [567]}"

The above command returns 201 Created with a location header for where to find the new message

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/folders/1234
{
    "message": "Folder created"
}

This endpoint creates a new folder.

HTTP Request

POST https://example.ziik.io/api/folders

Request Parameters

ParameterTypeRequiredDescription
nameStringYesName of the new folder.
parentIntegerYesParent folder of the new folder.
unitsArrayNoArray of unit IDs to assign to the new folder if it is to be shared as a chain folder
userTypesArrayNoNot used for personal folders. Array with the following parameters
- readArrayNouser type IDs to allow read access to the new folder
- writeArrayNouser type IDs to allow write access to the new folder
- manageArrayNouser type IDs to allow manage access of the new folder
sharesArrayNoShares with users
- readArrayNouser IDs to allow shared read access
- writeArrayNouser IDs to allow shared access with write permissions
- manageArrayNouser IDs to allow shared access with manage permissions

Permissions Required

  • Access to parent folder

Edit Existing Folder

curl -i -X PATCH "https://example.ziik.io/api/folders/121"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"name\": \"A New Name\"}"

The above command returns 204 No Content on successful folder update.

HTTP/1.0 204 No Content

This endpoint updates an existing folder.

HTTP Request

PATCH https://example.ziik.io/api/folders/ID

Request Parameters

ParameterTypeRequiredDescription
nameStringNoNew name of the folder.
parentIntegerNoNew parent folder.
unitsArrayNoArray of unit IDs to replace for the folder. Only used for shared folders.
userTypesArrayNoNot used for personal folders. Array with the following parameters
- readArrayNouser type IDs to allow read access to the new folder
- writeArrayNouser type IDs to allow write access to the new folder
- manageArrayNouser type IDs to allow manage of the new folder
sharesArrayNoShares with users
- readArrayNouser IDs to allow shared read access
- writeArrayNouser IDs to allow shared access with write permissions
- manageArrayNouser IDs to allow shared access with manage permissions

Permissions Required

  • Manage permission to folder

Delete a Folder

curl -i -X DELETE "https://example.ziik.io/api/folders/122"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a folder.

HTTP Request

DELETE https://example.ziik.io/api/folders/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the folder to delete

Permissions Required

  • Manage access to folder
  • OR creator of folder

Upload File

curl -i -X POST "https://example.ziik.io/api/folders/121"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"file\": {\"type\": \"upload\", \"filename\": \"filename.ext\", \"data\": \"a7ab7a7b7c232cdefadef\"} }"

The above command returns 201 Created with a location header for where to find the new message

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/documents/1234
{
    "message": "Document created"
}

This endpoint uploads a file to a folder.

HTTP Request

POST https://example.ziik.io/api/folders/ID

Request Parameters

ParameterTypeRequiredDescription
fileArrayYesFile data with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Access to folder

Get Documents in a Folder

curl "https://example.ziik.io/api/folders/121/documents"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
  "hits":
  [
      {
        "id": 1221,
        "content_type": "document",
        "title": "filename.ext",
        "folder": 122,
        "date": 12345678,
        "author": {
            "See User Service ..."
        },
        "files": [
          {
             "id": 101,
             "name": "Filename.ext",
             "mime": "application/mime",
             "size": 123456,
             "type": "document",
             "source": "https://example.ziik.io/api/path/to/filename.ext"
          }
        ],
        "url": "api/documents/1221"
      },
      {
        "id": 1222,
        "content_type": "document",
        "title": "filename.ext",
        "folder": 122,
        "date": 12345678,
        "author": {
          "See User Service ..."
        },
        "files": [
          {
             "id": 102,
             "name": "Filename.ext",
             "mime": "application/mime",
             "size": 1234567,
             "type": "document",
             "source": "https://example.ziik.io/api/path/to/filename.ext"
          }
        ],
        "url": "api/documents/1222"
      }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 50,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

This endpoint returns documents in a folder

HTTP Request

GET https://example.ziik.io/api/folders/ID/documents

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the folder to retrieve documents from

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger500Number of records to return per page.

Permissions Required

  • Access to folder

Get Single Document

curl "https://example.ziik.io/api/documents/1221"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
    "id": 1221,
    "content_type": "document",
    "title": "filename.ext",
    "folder": 122,
    "date": 12345678,
    "author": {
        "See User Service ..."
    },
    "files": [
      {
         "id": 101,
         "name": "Filename.ext",
         "mime": "application/mime",
         "size": 123456,
         "type": "document",
         "source": "https://example.ziik.io/api/path/to/filename.ext"
      }
    ],
    "url": "api/documents/1221"
  }

This endpoint returns a single document.

HTTP Request

GET https://example.ziik.io/api/documents/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the document

Permissions Required

  • Access to document folder

Edit Existing Document

curl -i -X PATCH "https://example.ziik.io/api/documents/1221"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"name\": \"A New Document Name\", \"file\": {\"type\": \"upload\", \"filename\": \"filename.ext\", \"data\": \"a7ab7a7b7c232cdefadef\"}, \"folder\": 123}"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing document.

HTTP Request

PATCH https://example.ziik.io/api/documents/ID

Request Parameters

ParameterTypeRequiredDescription
nameStringNoNew name of the document.
folderIntegerNoNew folder.

Permissions Required

  • Manage access to folder
  • OR uploader of file

Delete a Document

curl -i -X DELETE "https://example.ziik.io/api/documents/1221"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a document.

HTTP Request

DELETE https://example.ziik.io/api/documents/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the document to delete

Permissions Required

  • Manage access to folder

Get Folder Parents

curl "https://example.ziik.io/api/folders/123/parents"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "content_type": "folder",
    "parent": null,
    "root": 1,
    "type": "chain",
    "name": "Chain",
    "date": 1492000417,
    "permissions": {
      "edit": false,
      "delete": false,
      "add": true
    },
    "url": "api\/folders\/1",
    "units": [
      {
        "content_type": "unit",
        "id": "1",
        "name": "International",
        "url": "api\/units\/1",
      },
      {
        "content_type": "unit",
        "id": "2",
        "name": "Denmark",
        "url": "api\/units\/2",
      }
    ],
    "userTypes": [
      {
        "id": 1,
        "name": "Manager",
        "rights": "manage"
      },
      {
        "id": 3,
        "name": "Employee",
        "rights": "access
      }
    ]
  },
  {
    "id": 38,
    "content_type": "folder",
    "parent": 1,
    "root": 1,
    "type": "chain",
    "name": "Marketing",
    "date": 1492000417,
    "permissions": {
      "edit": true,
      "delete": true,
      "add": true
    },
    "url": "api\/folders\/38",
    "units": [
      {
        "content_type": "unit",
        "id": "1",
        "name": "International",
        "url": "api\/units\/1",
      },
      {
        "content_type": "unit",
        "id": "2",
        "name": "Denmark",
        "url": "api\/units\/2",
      }
    ],
    "userTypes": [
      {
        "id": 1,
        "name": "Manager",
        "rights": "manage"
      },
      {
        "id": 3,
        "name": "Employee",
        "rights": "access
      }
    ]
  }
]

This endpoint retrieves a list of folders that are parent or parent's parent to the chosen folder.

HTTP Request

GET https://example.ziik.io/api/folders/ID/parents

URL Parameters

ParameterTypeDescription
idIntegerID of the folder to get parents for