File Uploads & Storage
File Uploads & Storage
NodeStack handles binary attachments with integrated disk storage, MIME detection, and token-protected access.
File Upload Endpoint
Files are uploaded directly alongside standard JSON record fields via multipart/form-data:
curl -X POST http://localhost:8090/api/collections/documents/records \
-H "Authorization: Bearer <TOKEN>" \
-F "title=Q3 Financial Report" \
-F "attachment=@/path/to/report.pdf"
The server:
- Validates the file extension and detected magic-number MIME type against schema constraints.
- Generates an obfuscated unique filename on disk inside
./nodestack_data/storage/. - Stores the filename string in the record's
attachmentfield.
Accessing Files
Files are served via the file endpoint:
GET /api/files/:collection/:recordId/:filename
Example URL
http://localhost:8090/api/files/documents/rec_98765/report_x8192a.pdf
Protected File Access
If a collection's View Rule restricts access to authenticated users or owners, file downloads require authentication:
1. Authorization Header
Pass standard Authorization: Bearer <TOKEN> header.
2. URL Token Parameter
For browser <img>, <video>, or <a> download links where custom headers cannot be set:
http://localhost:8090/api/files/documents/rec_98765/report.pdf?token=<TOKEN>
Using via nodestack-client
Generating authenticated file URLs with the client SDK:
const record = await client.collection('documents').getOne('rec_98765');
// Get direct URL with token automatically appended if needed
const fileUrl = client.getFileUrl(record, record.attachment);
console.log('Download URL:', fileUrl);