Folders

Organize files with hierarchical folders.

Folders provide hierarchical organization for files within a space. They support nesting, inherited access control, and path-based references.

Creating a Folder

curl -X POST https://api.tzzl.io/api/v1/folders \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "photos",
    "space_id": "01HQ..."
  }'

With a Parent Folder

curl -X POST https://api.tzzl.io/api/v1/folders \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vacation",
    "space_id": "01HQ...",
    "parent_id": "01HQ..."
  }'

This creates a folder at the path photos/vacation/.

Folder Properties

Field	Description
`id`	ULID primary key
`name`	Folder name
`path`	Full folder path (e.g., `photos/vacation/`)
`space_id`	Parent space ID
`parent_id`	Parent folder ID (null for root folders)
`has_children`	Boolean indicating if the folder has subfolders
`access_control`	JSON access control settings
`security`	JSON security settings

Listing Folders

curl "https://api.tzzl.io/api/v1/folders?space_id=SPACE_ID" \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Get a Folder

curl https://api.tzzl.io/api/v1/folders/FOLDER_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Update a Folder

curl -X PUT https://api.tzzl.io/api/v1/folders/FOLDER_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "new-name" }'

Delete a Folder

curl -X DELETE https://api.tzzl.io/api/v1/folders/FOLDER_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

A folder must be empty (no files and no subfolders) before it can be deleted.

Folder Access Control

Set access control for a folder and its contents:

curl -X PUT https://api.tzzl.io/api/v1/folders/FOLDER_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": true
    }
  }'

Reset to space defaults:

curl -X DELETE https://api.tzzl.io/api/v1/folders/FOLDER_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Folder Security

Configure security settings for a folder:

curl -X PUT https://api.tzzl.io/api/v1/folders/FOLDER_ID/security \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "security": { ... }
  }'

Reset to defaults:

curl -X DELETE https://api.tzzl.io/api/v1/folders/FOLDER_ID/security \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Uploading to a Folder

Specify a folder when uploading files:

curl -X POST https://api.tzzl.io/api/v1/upload \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -F "[email protected]" \
  -F "space=a1b2c3" \
  -F "folder_id=01HQ..." \
  -F "folder_path=photos/vacation/"

You can also configure a default folder in an upload config's storage settings:

{
  "config": {
    "storage": {
      "folder": "user-uploads"
    }
  }
}

PreviousFiles NextSpaces