Table of Contents

File Operations Quick Reference

Basic File Operations

Upload a File
Download a File
Delete a File

Advanced File Operations

Move/Rename Files
Copy Files ⭐ New Feature
List Directory Contents
Create Directory

File Metadata Operations

Get File Information
File Attributes and Tagging

Response Codes
Operation Comparison
Best Practices

When to Use Copy vs Move
Performance Tips
Error Handling

Related Documentation
Examples Repository

File Operations Quick Reference

This page provides a quick reference for common file operations in SeaweedFS using the HTTP API.

Basic File Operations

Upload a File

Small files (direct upload):

# Upload with PUT
curl -X PUT "http://localhost:8888/path/to/file.txt" -d "file content"

# Upload with POST (multipart)
curl -X POST "http://localhost:8888/path/to/file.txt" -F "file=@localfile.txt"

Download a File

# Get file content
curl "http://localhost:8888/path/to/file.txt"

# Download to local file
curl "http://localhost:8888/path/to/file.txt" -o localfile.txt

Delete a File

# Delete single file
curl -X DELETE "http://localhost:8888/path/to/file.txt"

# Delete directory (recursive)
curl -X DELETE "http://localhost:8888/path/to/directory/?recursive=true"

Advanced File Operations

Move/Rename Files

# Move file to new location
curl -X POST "http://localhost:8888/new/path/file.txt?mv.from=/old/path/file.txt"

# Rename file in same directory
curl -X POST "http://localhost:8888/path/to/newname.txt?mv.from=/path/to/oldname.txt"

Copy Files ⭐ New Feature

# Copy file (preserves original)
curl -X POST "http://localhost:8888/backup/file.txt?cp.from=/original/file.txt"

# Copy with automatic name resolution
curl -X POST "http://localhost:8888/backup/?cp.from=/original/file.txt"
# Result: /backup/file.txt

List Directory Contents

# List directory
curl -H "Accept: application/json" "http://localhost:8888/path/to/directory/?pretty=y"

# List with pagination
curl -H "Accept: application/json" "http://localhost:8888/path/?limit=10&lastFileName=somefile.txt"

Create Directory

# Create empty directory
curl -X POST "http://localhost:8888/path/to/new/directory/"

File Metadata Operations

Get File Information

# Get file metadata
curl -I "http://localhost:8888/path/to/file.txt"

File Attributes and Tagging

# Set custom attributes
curl -X PUT "http://localhost:8888/path/to/file.txt" \
  -H "Seaweed-Custom-Attribute: value" \
  -F "file=@localfile.txt"

# Set TTL (time to live)
curl -X POST "http://localhost:8888/path/to/file.txt?ttl=3600" \
  -F "file=@localfile.txt"

Response Codes

HTTP Code	Operation	Meaning
200 OK	GET	File retrieved successfully
201 Created	POST/PUT	File uploaded successfully
204 No Content	DELETE, COPY, MOVE	Operation completed successfully
400 Bad Request	Any	Invalid parameters or unsupported operation
404 Not Found	GET, DELETE	File or directory not found
409 Conflict	POST/PUT	File already exists (when using exclusive creation)

Operation Comparison

Operation	Source File	Use Case	Performance
Upload	External → SeaweedFS	Add new files	Network dependent
Download	SeaweedFS → External	Retrieve files	Network dependent
Move (`mv.from`)	Deleted	Rename/relocate	Very fast (metadata only)
Copy (`cp.from`)	Preserved	Backup/duplicate	Depends on file size
Delete	Deleted	Remove files	Fast

Best Practices

When to Use Copy vs Move

Use Copy (cp.from) when:

Creating backups before modifications
Duplicating configuration templates
Staging files for testing
Need to preserve original file

Use Move (mv.from) when:

Renaming files
Reorganizing file structure
Moving files between directories
Don't need original file

Performance Tips

Batch operations: Group multiple operations when possible
Small files: Use direct PUT for files < 1MB
Large files: POST with multipart automatically chunks files
Copy operations: Server-side copy is much faster than download + upload
Directory operations: Plan directory structure to minimize reorganization

Error Handling

# Check operation status
if curl -X POST "http://localhost:8888/dest?cp.from=/src" -w "%{http_code}" -o /dev/null -s | grep -q "204"; then
    echo "Copy successful"
else
    echo "Copy failed"
fi

Filer Server API - Complete API reference
Filer Commands and Operations - Command-line tools
Getting Started - Installation and setup
FAQ - Common questions and answers

Examples Repository

For more complex examples and use cases, see:

SeaweedFS Examples (if available)
Community-contributed scripts and tools
Language-specific client libraries

💡 Tip: Use the ?pretty=y parameter with JSON responses to get formatted output for easier reading during development and testing.

Introduction

API

Configuration

Filer

Filer Stores

Management

Advanced Filer Configurations

FUSE Mount

WebDAV

SFTP Server

Cloud Drive

AWS S3 API

S3 Table Bucket

Iceberg Integrations

S3 Authentication & IAM

S3 Configuration - Start Here
S3 Credentials (-s3.config)
OIDC Integration (-s3.iam.config)
Kubernetes ServiceAccount Authentication (IRSA-style)
S3 Policy Variables
S3 Policy Conditions
S3 Bucket Policies
Amazon IAM API
AWS IAM CLI
weed shell - Shell IAM Commands

Server-Side Encryption

S3 Client Tools

Machine Learning

HDFS

Replication and Backup

Async Replication to another Filer [Deprecated]
Async Backup
Async Filer Metadata Backup
Async Replication to Cloud [Deprecated]
Kubernetes Backups and Recovery with K8up