Files API

This documentation is verified against the actual API test suite (test/file.test.js).

Overview

The Files API provides file upload, storage, retrieval, and management capabilities. Files can be uploaded directly from your device or from a remote URL.

Key Features:

Upload files via multipart/form-data
Upload files from URL
File metadata management
Secure file storage
File deletion

Upload File

Upload a file to the system.

Endpoint: POST /files

Authentication: Required (Bearer token)

Content-Type: multipart/form-data

Request

Send file as form-data with field name file:

curl -X POST "http://localhost:3000/files" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/your/file.jpg"

Response

Success (200 OK):

{
  "data": "file-id-here"
}

The response contains the file ID which can be used to reference the file in other API calls.

Example with Node.js

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/file.jpg'));

const response = await fetch('http://localhost:3000/files', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log('File ID:', data.data);

Get File Details

Retrieve metadata about a file.

Endpoint: GET /files/:id

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
id	string	File ID returned from upload

Response

Success (200 OK):

{
  "data": {
    "id": "file-id",
    "filename": "test-image.jpg",
    "type": "image/jpeg",
    "size": 15234
  }
}

Field	Type	Description
id	string	Unique file identifier
filename	string	Original filename
type	string	MIME type of the file
size	number	File size in bytes

Error (403 Forbidden):**

When file doesn't exist or has been deleted:

{
  "error": {
    "message": "File not found or access denied"
  }
}

Example

curl "http://localhost:3000/files/file-id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update File Metadata

Update file information like title and description.

Endpoint: PATCH /files/:id

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
id	string	File ID to update

Request Body

{
  "title": "Updated Test Image",
  "description": "This is an updated test image"
}

Field	Type	Required	Description
title	string	No	File title
description	string	No	File description

Response

Success (200 OK):

{
  "data": "file-id"
}

Example

curl -X PATCH "http://localhost:3000/files/file-id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Photo",
    "description": "Vacation photo from 2024"
  }'

Upload File from URL

Upload a file from a remote URL.

Endpoint: POST /files/upload-from-url

Authentication: Required (Bearer token)

Request Body

{
  "url": "https://www.example.com/image.png"
}

Field	Type	Required	Description
url	string	Yes	Public URL of the file to upload

Response

Success (200 OK):

{
  "data": "file-id"
}

Example

curl -X POST "http://localhost:3000/files/upload-from-url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.gstatic.com/webp/gallery3/1.png"
  }'

Use Cases

Import files from external sources
Copy files from public URLs
Batch import from web services
Migrate files from other systems

Delete File

Delete a file from the system.

Endpoint: DELETE /files/:id

Authentication: Required (Bearer token)

URL Parameters

Parameter	Type	Description
id	string	File ID to delete

Response

Success (200 OK):

{
  "message": "File deleted successfully"
}

Post-Deletion Behavior

After deletion:

The file is permanently removed from storage
File metadata is removed from the database
Attempts to access the file will return 403 Forbidden
The file ID becomes invalid

Example

curl -X DELETE "http://localhost:3000/files/file-id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Complete Workflow Example

1. Upload a File

FILE_ID=$(curl -X POST "http://localhost:3000/files" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg" | jq -r '.data')

echo "Uploaded file ID: $FILE_ID"

2. Get File Details

curl "http://localhost:3000/files/$FILE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Update File Metadata

curl -X PATCH "http://localhost:3000/files/$FILE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vacation Photo",
    "description": "Summer 2024"
  }'

4. Use File in Other Collections

curl -X POST "http://localhost:3000/items/posts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Post",
    "content": "Check out this photo!",
    "featuredImage": "'"$FILE_ID"'"
  }'

5. Delete File (When No Longer Needed)

curl -X DELETE "http://localhost:3000/files/$FILE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

File Storage

Files are stored using the configured storage provider (local filesystem or cloud storage like AWS S3). The storage location is determined by environment variables:

STORAGE_TYPE=local
STORAGE_LOCAL_ROOT=/path/to/storage

Or for S3:

STORAGE_TYPE=s3
STORAGE_S3_BUCKET=my-bucket
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ACCESS_KEY=your-access-key
STORAGE_S3_SECRET_KEY=your-secret-key

Supported File Types

The system supports all file types. Common examples:

Images:

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)
SVG (.svg)

Documents:

PDF (.pdf)
Word (.doc, .docx)
Excel (.xls, .xlsx)
PowerPoint (.ppt, .pptx)

Media:

Video (.mp4, .mov, .avi)
Audio (.mp3, .wav, .ogg)

Archives:

ZIP (.zip)
RAR (.rar)
TAR (.tar, .gz)

Best Practices

File Organization

Use Meaningful Titles: Set descriptive titles when uploading
Add Descriptions: Document what each file contains
Clean Up: Delete unused files to save storage space
Reference Files: Store file IDs in your collection items

Security

All file operations require authentication
File access is controlled by permissions
Deleted files are permanently removed
Use secure HTTPS for file uploads

Performance

Upload files directly when possible (faster than URL upload)
Consider file size limits based on your infrastructure
Use appropriate file formats (WebP for images, compressed videos, etc.)

Data Integration

Item Routes - Reference files in your data collections
Schema Reference Guide - UUID fields for file references

Access Control

Authentication Routes - File upload authentication
Permission Routes - File access control

Storage Configuration

Additional Features - Storage services (local, S3) configuration
Settings Routes - Storage settings management
Deployment Guide - Production storage setup

Integration

Integration Guide - Client-side file uploads
API Routes Reference - Complete endpoint listing

On this page