Skip to Content
IntroductionWorking with Files

Working with Files

Learn how to manage, search, delete, and organize your files using FileZen’s comprehensive file management API.

đź’ˇ SDK Available: While this documentation shows direct API usage with cURL examples, most of these methods are also available in our SDKs for faster integration. Check out our frameworks section for available integrations and a more streamlined development experience.

Authentication

All file management operations use the same authentication methods as file uploads:

API Key Authentication

curl -H "ApiKey: your-api-key-here"

Bearer Token Authentication

curl -H "Authorization: Bearer your-jwt-token" \
     -H "X-Project-Id: your-project-id"

Listing Files

Get All Files

Retrieve all files in your project:

curl -X GET "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here"

Get Files with Pagination

curl -X GET "https://api.filezen.dev/files?limit=20&offset=0" \
  -H "ApiKey: your-api-key-here"

Get Files with Parent Information

Include parent folder details in the response:

curl -X GET "https://api.filezen.dev/files?join=parent" \
  -H "ApiKey: your-api-key-here"

Response:

{
  "data": [
    {
      "id": "file-uuid",
      "createdAt": "2024-01-01T12:00:00Z",
      "updatedAt": "2024-01-01T12:00:00Z",
      "type": "file",
      "state": "completed",
      "name": "document.pdf",
      "mimeType": "application/pdf",
      "size": 1024000,
      "region": "us",
      "projectId": "project-uuid",
      "parentId": "folder-uuid",
      "parent": {
        "id": "folder-uuid",
        "name": "Documents",
        "type": "folder"
      },
      "url": "https://cdn.filezen.dev/files/file-uuid"
    }
  ],
  "count": 1,
  "total": 1,
  "page": 1,
  "pageCount": 1
}

Searching and Filtering Files

Filter by File Type

# Get only files (exclude folders)
curl -X GET "https://api.filezen.dev/files?filter=type||eq||file" \
  -H "ApiKey: your-api-key-here"
 
# Get only folders
curl -X GET "https://api.filezen.dev/files?filter=type||eq||folder" \
  -H "ApiKey: your-api-key-here"

Filter by Parent Folder

# Get files in a specific folder
curl -X GET "https://api.filezen.dev/files?filter=parentId||eq||folder-uuid" \
  -H "ApiKey: your-api-key-here"
 
# Get files in root directory (no parent)
curl -X GET "https://api.filezen.dev/files?filter=parentId||isnull" \
  -H "ApiKey: your-api-key-here"

Search by Name

# Search files containing "report" in name
curl -X GET "https://api.filezen.dev/files?filter=name||cont||report" \
  -H "ApiKey: your-api-key-here"
 
# Search files starting with "image"
curl -X GET "https://api.filezen.dev/files?filter=name||starts||image" \
  -H "ApiKey: your-api-key-here"

Filter by MIME Type

# Get all images
curl -X GET "https://api.filezen.dev/files?filter=mimeType||starts||image/" \
  -H "ApiKey: your-api-key-here"
 
# Get all videos
curl -X GET "https://api.filezen.dev/files?filter=mimeType||starts||video/" \
  -H "ApiKey: your-api-key-here"
 
# Get specific file type
curl -X GET "https://api.filezen.dev/files?filter=mimeType||eq||application/pdf" \
  -H "ApiKey: your-api-key-here"

Filter by Size

# Get files larger than 1MB
curl -X GET "https://api.filezen.dev/files?filter=size||gt||1048576" \
  -H "ApiKey: your-api-key-here"
 
# Get files smaller than 100KB
curl -X GET "https://api.filezen.dev/files?filter=size||lt||102400" \
  -H "ApiKey: your-api-key-here"

Filter by Date

# Get files created after a specific date
curl -X GET "https://api.filezen.dev/files?filter=createdAt||gt||2024-01-01T00:00:00Z" \
  -H "ApiKey: your-api-key-here"
 
# Get files created in the last 7 days
curl -X GET "https://api.filezen.dev/files?filter=createdAt||gt||$(date -d '7 days ago' -Iseconds)" \
  -H "ApiKey: your-api-key-here"

Filter by Metadata

Search and filter files based on metadata fields:

# Filter by metadata string field
curl -X GET "https://api.filezen.dev/files?filter=metadata.category||eq||documents" \
  -H "ApiKey: your-api-key-here"
 
# Filter by metadata containing specific text
curl -X GET "https://api.filezen.dev/files?filter=metadata.description||cont||report" \
  -H "ApiKey: your-api-key-here"
 
# Filter by metadata array field (files with specific tag)
curl -X GET "https://api.filezen.dev/files?filter=metadata.tags||cont||important" \
  -H "ApiKey: your-api-key-here"
 
# Filter by metadata boolean field
curl -X GET "https://api.filezen.dev/files?filter=metadata.isPublic||eq||true" \
  -H "ApiKey: your-api-key-here"
 
# Filter by metadata number field
curl -X GET "https://api.filezen.dev/files?filter=metadata.version||gt||1" \
  -H "ApiKey: your-api-key-here"
 
# Filter by nested metadata field
curl -X GET "https://api.filezen.dev/files?filter=metadata.author.name||eq||John Doe" \
  -H "ApiKey: your-api-key-here"
 
# Check if metadata field exists
curl -X GET "https://api.filezen.dev/files?filter=metadata.processed||notnull" \
  -H "ApiKey: your-api-key-here"
 
# Check if metadata field doesn't exist
curl -X GET "https://api.filezen.dev/files?filter=metadata.archived||isnull" \
  -H "ApiKey: your-api-key-here"

Complex Filtering

Combine multiple filters:

# Get PDF files larger than 1MB in a specific folder
curl -X GET "https://api.filezen.dev/files?filter=mimeType||eq||application/pdf&filter=size||gt||1048576&filter=parentId||eq||folder-uuid" \
  -H "ApiKey: your-api-key-here"
 
# Get images with specific metadata category and tags
curl -X GET "https://api.filezen.dev/files?filter=mimeType||starts||image/&filter=metadata.category||eq||photos&filter=metadata.tags||cont||vacation" \
  -H "ApiKey: your-api-key-here"
 
# Get recent documents that are marked as processed
curl -X GET "https://api.filezen.dev/files?filter=createdAt||gt||2024-01-01T00:00:00Z&filter=metadata.category||eq||documents&filter=metadata.processed||eq||true" \
  -H "ApiKey: your-api-key-here"
 
# Get files by specific author that are not archived
curl -X GET "https://api.filezen.dev/files?filter=metadata.author.name||eq||John Doe&filter=metadata.archived||ne||true" \
  -H "ApiKey: your-api-key-here"

Sorting Files

Sort by Name

# Sort by name ascending
curl -X GET "https://api.filezen.dev/files?sort=name,ASC" \
  -H "ApiKey: your-api-key-here"
 
# Sort by name descending
curl -X GET "https://api.filezen.dev/files?sort=name,DESC" \
  -H "ApiKey: your-api-key-here"

Sort by Date

# Sort by creation date (newest first)
curl -X GET "https://api.filezen.dev/files?sort=createdAt,DESC" \
  -H "ApiKey: your-api-key-here"
 
# Sort by update date (oldest first)
curl -X GET "https://api.filezen.dev/files?sort=updatedAt,ASC" \
  -H "ApiKey: your-api-key-here"

Sort by Size

# Sort by size (largest first)
curl -X GET "https://api.filezen.dev/files?sort=size,DESC" \
  -H "ApiKey: your-api-key-here"

Getting Individual Files

Get File by ID

curl -X GET "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here"

Get File with Relations

# Include parent folder information
curl -X GET "https://api.filezen.dev/files/file-uuid?join=parent" \
  -H "ApiKey: your-api-key-here"

Updating Files

Update File Metadata

curl -X PATCH "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "description": "Updated description",
      "tags": ["updated", "metadata"],
      "category": "documents"
    }
  }'

Rename File

curl -X PATCH "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-filename.pdf"
  }'

Move File to Different Folder

curl -X PATCH "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": "new-folder-uuid"
  }'

Move File to Root Directory

curl -X PATCH "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": null
  }'

Creating Folders

Create New Folder

curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "folder",
    "name": "My Documents",
    "parentId": null
  }'

Create Nested Folder

curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "folder",
    "name": "Subfolder",
    "parentId": "parent-folder-uuid"
  }'

Deleting Files

Delete Single File

curl -X DELETE "https://api.filezen.dev/files/file-uuid" \
  -H "ApiKey: your-api-key-here"

Response:

{
  "id": "file-uuid",
  "name": "deleted-file.pdf",
  "type": "file",
  "state": "completed"
}

Delete File by URL

Useful when you only have the file URL:

curl -X DELETE "https://api.filezen.dev/files/delete-by-url" \
  -H "ApiKey: your-api-key-here" \
  -G -d "url=https://cdn.filezen.dev/files/file-uuid"

Bulk Delete Files

Delete multiple files at once:

curl -X POST "https://api.filezen.dev/files/delete-bulk" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"id": "file-uuid-1"},
      {"id": "file-uuid-2"},
      {"id": "file-uuid-3"}
    ]
  }'

File Organization

Folder Structure Best Practices

Organizing files into a logical folder structure is essential for efficient file management. This section covers best practices for creating and maintaining folder hierarchies that scale with your application’s needs.

Hierarchical Organization

# Create main categories
curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "folder", "name": "Documents"}'
 
curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "folder", "name": "Images"}'
 
curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "folder", "name": "Videos"}'

Date-based Organization

# Create year/month structure
curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "folder", "name": "2024"}'
 
# Get the folder ID, then create month folders
curl -X POST "https://api.filezen.dev/files" \
  -H "ApiKey: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"type": "folder", "name": "January", "parentId": "2024-folder-uuid"}'

Advanced Queries

Combining Multiple Operations

# Get recent large image files, sorted by size
curl -X GET "https://api.filezen.dev/files?filter=mimeType||starts||image/&filter=size||gt||1048576&filter=createdAt||gt||2024-01-01T00:00:00Z&sort=size,DESC&limit=10" \
  -H "ApiKey: your-api-key-here"

Folder Contents with Statistics

# Get all files in a folder with count
curl -X GET "https://api.filezen.dev/files?filter=parentId||eq||folder-uuid&limit=100" \
  -H "ApiKey: your-api-key-here"

Error Handling

Common Error Responses

File Not Found

{
  "statusCode": 404,
  "message": "File not found",
  "error": "Not Found"
}

Invalid Filter

{
  "statusCode": 400,
  "message": "Invalid filter format",
  "error": "Bad Request"
}

Access Denied

{
  "statusCode": 403,
  "message": "Access denied to this file",
  "error": "Forbidden"
}

Query Parameters Reference

Filtering

  • filter=field||operator||value
  • Operators: eq (equals), ne (not equals), gt (greater than), lt (less than), gte (greater than or equal), lte (less than or equal), starts (starts with), ends (ends with), cont (contains), excl (excludes), in (in array), notin (not in array), isnull (is null), notnull (is not null)

Sorting

  • sort=field,direction
  • Directions: ASC (ascending), DESC (descending)
  • Multiple sorts: sort=field1,ASC&sort=field2,DESC

Pagination

  • limit=number - Number of results per page (default: 20)
  • offset=number - Number of results to skip (default: 0)
  • page=number - Page number (alternative to offset)

Relations

  • join=relation - Include related data
  • Available joins: parent, project

Best Practices

Performance Tips

  • Use pagination for large result sets
  • Include only necessary relations to reduce response size
  • Use specific filters to reduce query complexity
  • Cache frequently accessed file metadata

Organization Strategies

  • Use consistent naming conventions
  • Implement logical folder hierarchies
  • Use metadata for additional categorization
  • Regular cleanup of unused files

Security Considerations

  • Always validate file IDs before operations
  • Use bulk operations for multiple file management
  • Implement proper access controls
  • Monitor file access patterns

Metadata Usage

  • Store searchable information in metadata
  • Use consistent metadata schemas
  • Include version information for documents
  • Track file processing status in metadata
Last updated on
Uploading FilesWeb & Image Optimization
© 2026 FileZen. All rights reserved.