Skip to content

File Storage & Management

Store, organize, and retrieve files in GFile Plus buckets.

Upload and organize files in buckets

Store any type of file — images, videos, documents, archives — organized into buckets and folders.

Method 1: Direct upload

Upload a file directly using multipart form data.

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/upload?apiKey=<your-api-key>" \
  -F "file=@./my-photo.jpg" \
  -F 'body={"name":"my-photo.jpg","path":"/photos/"}'

Method 2: Create record then upload binary

First create a file record in the bucket, then upload the binary content separately. This approach reserves the file entry first, allowing users to upload the content later (e.g., via a form).

Step 1 — Create the file record:

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files?apiKey=<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-photo.jpg", "path": "/photos/"}'

The response includes the file id:

{
  "id": "<file-id>",
  "name": "my-photo.jpg",
  "path": "/photos/"
}

Step 2 — Upload the binary content:

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/<file-id>/reupload?apiKey=<your-api-key>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./my-photo.jpg

Use the id from Step 1 response as the :fileId in the reupload URL.

Supported file types:

Category Extensions
Images jpg, png, gif, webp, svg, bmp, ico, tiff
Videos mp4, avi, mov, mkv, webm, flv, wmv
Audio mp3, wav, ogg, flac, aac
Documents pdf, doc, docx
Spreadsheets xls, xlsx, csv
Presentations ppt, pptx
Archives zip, tar, gz, rar, 7z
Fonts ttf, otf, woff, woff2
Text files txt, md, json, xml, yaml, html, css, js

Download and view files

Retrieve file content for viewing inline or as a download.

# View file inline (browser display)
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?apiKey=<your-api-key>"

# Download file as attachment
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/download?apiKey=<your-api-key>" \
  -o output-file.jpg

Partial downloads with range requests

Download specific byte ranges for large files — useful for resumable downloads or media seeking.

# Download bytes 0-1023 (first 1KB)
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?apiKey=<your-api-key>" \
  -H "Range: bytes=0-1023"

The response includes Content-Range and Accept-Ranges: bytes headers.

Replace file content without changing metadata

Re-upload a file's binary content while preserving its ID, headers, alias, and metadata.

# Re-upload file content
curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/reupload?apiKey=<your-api-key>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./updated-file.jpg

Get file size and type information

Expand file metadata to include calculated size (human-readable) and detected file type.

# Get file with size and type info
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId?expands=SIZE&expands=TYPE&apiKey=<your-api-key>"

Response includes:

{
  "expands": {
    "size": { "bytes": 2048576, "human": "2 MB" },
    "type": { "type": "IMAGE" }
  }
}