CasaOS APIs for Batch Operations and File Management: Complete REST API Reference

CasaOS exposes RESTful HTTP endpoints under /api/v1/batch for bulk file operations and /api/v1/file for individual file management, implemented in Go using the Echo framework with support for chunked uploads, queue-based task management, and thumbnail generation.

CasaOS provides a comprehensive REST API for managing files and performing batch operations on Linux-based home servers. The API routes are defined in route/v1/file.go and route/v2/file.go, utilizing the Echo web framework to handle everything from single-file deletions to asynchronous batch copying and moving tasks. These endpoints enable developers to integrate CasaOS file management capabilities into third-party applications or automation scripts.

Batch Operations API

The batch operations API, mounted under /api/v1/batch in route/v1.go, handles bulk actions on multiple files or directories through a centralized task queue. According to the CasaOS source code, these endpoints leverage the global service.FileQueue to track long-running operations while providing real-time status updates via the notification service.

Delete Multiple Files

To delete several files or directories simultaneously, send a DELETE request to /api/v1/batch with a JSON array of absolute paths. The DeleteFile function in route/v1/file.go processes this request:

curl -X DELETE "http://<host>/api/v1/batch" \
     -H "Authorization: Bearer <api-key>" \
     -H "Content-Type: application/json" \
     -d '["/share/docs/report.pdf","/share/tmp/old.log"]'

Create Batch Tasks (Copy, Move, or Rename)

Long-running batch operations like copying or moving directories are created via POST /api/v1/batch/task. This endpoint accepts a JSON payload describing the source paths, destination, and operation type, handled by the PostOperateFileOrDir function:

curl -X POST "http://<host>/api/v1/batch/task" \
     -H "Authorization: Bearer <api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "src": ["/share/photos/2023/"],
           "dst": "/share/backup/photos/",
           "op": "copy"
         }'

Cancel Running Batch Tasks

To abort a queued or in-progress operation, send a DELETE request to /api/v1/batch/{id}/task. This calls DeleteOperateFileOrDir, removes the entry from service.FileQueue, and triggers a notification update:

curl -X DELETE "http://<host>/api/v1/batch/12345/task" \
     -H "Authorization: Bearer <api-key>"

Download Files and Archives

The batch endpoint also handles downloads via GET /api/v1/batch, supporting both single file downloads and ZIP archive generation for multiple files through the GetDownloadFile handler.

File Management API

Individual file operations are available under /api/v1/file and /api/v2/file, providing granular control over content updates, uploads, and metadata retrieval.

Delete Individual Files

The DeleteFile function in route/v1/file.go handles DELETE requests to /api/v1/file/delete, accepting a JSON array of paths similar to the batch endpoint but optimized for single operations.

Update File Content

Modify existing files in-place using PUT /api/v1/file/update, which calls PutFileContent and expects a JSON body with path and content fields:

{
  "path": "/a/b.txt",
  "content": "new file content here"
}

Image Retrieval and Thumbnails

Retrieve images or their thumbnails via GET /api/v1/file/image using the GetFileImage function. The type parameter accepts thumbnail for preview generation:

curl -X GET "http://<host>/api/v1/file/image?path=/share/pics/cat.jpg&type=thumbnail" \
     -H "Authorization: Bearer <api-key>" \
     --output cat_thumb.jpg

Chunked Upload API

Large file uploads are handled by the v2 API in route/v2/file.go. The process involves multipart form data posted to POST /api/v2/file/upload, managed by the PostUploadFile function:

# First chunk

curl -X POST "http://<host>/api/v2/file/upload" \
     -F "path=/share/uploads" \
     -F "chunkNumber=1" \
     -F "chunkSize=1048576" \
     -F "currentChunkSize=1048576" \
     -F "totalChunks=5" \
     -F "totalSize=5242880" \
     -F "identifier=abc123" \
     -F "filename=video.mp4" \
     -F "relativePath=video.mp4" \
     -F "file=@chunk1.bin"

Repeat with chunkNumber=2 through 5. The server assembles the file once all chunks are received.

Directory Operations

Directory management endpoints are grouped under /api/v1/folder in route/v1/file.go:

• GET /folder/dirpath - List contents via DirPath
• POST /folder - Create directories via MkdirAll
• PUT /folder/name - Rename via RenamePath
• GET /folder/size - Calculate size via GetSize
• GET /folder/count - Count entries via GetFileCount

Route Registration and Architecture

All v1 routes are registered in route/v1.go within dedicated Echo groups. The v1BatchGroup handles /batch paths while v1FileGroup and v1FolderGroup manage file operations:

v1BatchGroup := v1Group.Group("/batch")
{
    v1BatchGroup.DELETE("", v1.DeleteFile)
    v1BatchGroup.DELETE("/:id/task", v1.DeleteOperateFileOrDir)
    v1BatchGroup.POST("/task", v1.PostOperateFileOrDir)
    v1BatchGroup.GET("", v1.GetDownloadFile)
}

The v2 chunked upload resides in route/v2/file.go as a separate implementation. Supporting utilities for file size calculation and image processing are located in model/file.go, while service/notify.go handles UI notifications for batch operation status changes.

Summary

• Batch operations use /api/v1/batch endpoints for delete, copy, move, and download operations
• The service.FileQueue manages asynchronous task execution and cancellation via DeleteOperateFileOrDir
• File management spans /api/v1/file for content updates and /api/v1/folder for directory operations
• Chunked uploads are implemented in v2 API at /api/v2/file/upload using PostUploadFile
• Key implementation files include route/v1/file.go, route/v2/file.go, and service/file_upload.go

Frequently Asked Questions

What authentication method does CasaOS use for these APIs?

CasaOS API endpoints require authentication via the ApiKeyAuth security scheme. Include the API key in the Authorization header as a Bearer token: Authorization: Bearer <api-key>. All endpoints in route/v1/file.go and route/v2/file.go enforce this authentication.

Can I cancel a long-running batch operation?

Yes. Batch tasks can be cancelled by sending a DELETE request to /api/v1/batch/{id}/task. This endpoint calls DeleteOperateFileOrDir in route/v1/file.go, removes the task from the service.FileQueue, and notifies the UI of the cancellation status through the notification service.

How does CasaOS handle large file uploads?

Large files are uploaded via the v2 API using chunked multipart uploads to /api/v2/file/upload. The client sends file chunks sequentially with metadata including chunkNumber, totalChunks, and identifier, which the server reassembles upon completion according to the implementation in route/v2/file.go.

Where are the API route handlers defined in the source code?

Route handlers are defined in route/v1/file.go for batch and file operations, route/v2/file.go for chunked uploads, and registered in route/v1.go where the Echo router groups (v1BatchGroup, v1FileGroup, v1FolderGroup) are configured. The batch queue implementation resides in service/file_upload.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}