How folders and files work in Skyfish

Folders are the primary way to organize files in Skyfish.

When you upload a file to a folder in Skyfish, the following is what actually happens. The file is first uploaded and saved to Skyfish’s cloud storage. Information about the file is then saved in the Skyfish database, and indexed by Skyfish’s search engine. Lastly, a ‘pointer’ to the uploaded file is added to the chosen folder. This pointer represents the file as being ‘stored in’ the folder.

When you ‘copy a file’ from one folder to another, Skyfish simply creates a new pointer to the file in the latter folder. Similarly, when you ‘move a file’ between folders, Skyfish simply moves the pointer from the old folder to the new one.

When you ‘remove a file’ from a folder, Skyfish deletes the pointer in the folder. When all pointers to a file are deleted from the folder structure, Skyfish automatically deletes the file.

Folders can easily be handled and modified using the Skyfish API.

How to fetch folders via the API

To list all the Skyfish folders that exist in your company, execute:

GET https://api.colourbox.com/folder

The output will resemble something like the following:

[
  {
    "id": 1891723,
    "name": "Picture of cats",
    "parent": null,
    "cover_photo_id": null,
    "company_id": 445605,
    "created": "2021-03-09 13:37:42",
    "permissions": {
      "groups": [
        "READ"
      ]
    }
  },
  {
    "id": 2020441,
    "name": "More pictures of cats",
    "parent": null,
    "cover_photo_id": null,
    "company_id": 445605,
    "created": "2022-01-25 08:34:57",
    "permissions": {
      "groups": [
        "READ",
        "ADMIN",
        "WRITE"
      ]
    }
  }
]  

The permissions key specifies the access rights that your users have:

This endpoint supports the following filtering options (all optional):

Creating a folder

To create a folder, make a POST request to https://api.colourbox.com/folder/

In the request’s body, you must specify the following:

Similar, to update a folder, make a POST request to https://api.colourbox.com/folder/:id/. The structure of the request’s body is the same as when creating a folder.

Some examples follow. Assume for all of them that the folder ID is 110917 and the parent folder ID is 110220.

To rename the folder to Testing, execute:

POST https://api.colourbox.com/folder/110917
{"name": "Testing", "parent": 110220}

To move the folder, so that it becomes a root folder:

POST https://api.colourbox.com/folder/110917
{"name": "Testing", "parent": null}

Deleting a folder

To delete a folder, execute the following:

DELETE https://api.colourbox.com/folder/:id

To empty a folder, i.e. to delete all contained files and subfolders but keep the folder itself:

POST  https://api.colourbox.com/folder/:id/purge

When users delete a folder via the Skyfish web UI, the folder is not deleted permanently. It is instead moved to the trashcan. If the folder is then left in the trashcan for more than 30 days, it is permanently deleted.

To move a folder to the trashcan via the API:

POST https://api.colourbox.com/folder/:id/move_to_trash

Adding tags to folders

Folders may have multiple tags added to them. When a tag is added to a folder, the tag is automatically inherited by all the files that are located in the folder, and in any subfolder therein. When a file is moved into a folder that already has a tag added to it, that file automatically inherits the tag, too. Similarly, if the file is moved out of the folder, the inherited tag will be removed from the file.

Modify these ‘Folder Tags’ in the following way:

List all Folder Tags:

GET https://api.colourbox.com/folder/:id/tags

Add tags tag1 and tag2 to a folder:

PUT https://api.colourbox.com/folder/:id/tags
["tag1", "tag2"]

Delete the Folder Tags tag1 and tag2:

DELETE https://api.colourbox.com/folder/:id/tags
["tag1", "tag2"]

Delete all Folder Tags:

DELETE https://api.colourbox.com/folder/:id/tags/purge

Downloading an entire folder as a .zip file

You can download a folder via the API. First, make a request to queue the folder for zipping. The API will return a job ID that can be queried for a job status report. Once the folder is zipped, you will receive a signed URL to download the .zip from. The user requesting the download will also get an email that contains the download URL.

To queue a folder for zipping:

POST https://api.colourbox.com/folder/:id/zip-file

You will receive something resembling the following:

{
  "job_id":"9xahozLZnDp3JFcqBmbYQysIVrj6Ni",
  "state":"PENDING",
  "url":null,
  "valid_until":null
}

To query the status of the zip job:

GET https://api.colourbox.com/zip-file/:job_id

The output is the same format as: https://api.colourbox.com/folder/:id/zip-file

When the job is done, you will receive output that resembles:

{
  "job_id":"9xahozLZnDp3JFcqBmbYQysIVrj6Ni",
  "state":"DONE",
  "url":"https:\/\/colourbox-zipfiles-prod.s3.eu-west-1.amazonaws.com\/tmp6yjgtuus.zip?.....",
  "valid_until":1678233600
}

Please note: We cache zip creation. Therefore, if you request a .zip file for a folder, but there already exists a non-expired/non-invalidated .zip file, we will return the existing .zip file. This means that your call to https://api.colourbox.com/folder/:id/zip-file may return a download URL immediately.