Media Management

Notty CMS includes a built-in media library for uploading, organizing, and serving files.

Upload Files

Single File Upload

curl -X POST http://localhost:2102/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@photo.jpg"

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "filename": "photo.jpg",
    "originalName": "photo.jpg",
    "mimeType": "image/jpeg",
    "size": 245760,
    "url": "/api/uploads/photo.jpg",
    "width": 1920,
    "height": 1080,
    "formats": {
      "small": { "url": "/api/uploads/small_photo.jpg", "width": 500 },
      "medium": { "url": "/api/uploads/medium_photo.jpg", "width": 750 },
      "large": { "url": "/api/uploads/large_photo.jpg", "width": 1000 }
    }
  }
}

Upload to a Folder

curl -X POST http://localhost:2102/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@photo.jpg" \
  -F "folderId=3"

Multiple File Upload

curl -X POST http://localhost:2102/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "files=@document.pdf"

Media Library API

List Files

curl "http://localhost:2102/api/media?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Parameter	Type	Example	Description
limit	number	20	Items per page
offset	number	0	Pagination offset
sort	string	created_at	Sort field
sortOrder	string	desc	Sort direction
folder	string	root or 5	Filter by folder ID
type	string	images	Filter: images, videos, audio, files
mimeType	string	image/jpeg	Exact MIME type filter
search	string	logo	Search by filename

Get File Details

curl http://localhost:2102/api/media/1 \
  -H "Authorization: Bearer $TOKEN"

Update File Metadata

curl -X PUT http://localhost:2102/api/media/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alt": "Team photo at the office",
    "caption": "Our team in 2024",
    "folder": 3
  }'

Replace File Content

curl -X PUT http://localhost:2102/api/media/1/file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@new-photo.jpg"

Delete a File

curl -X DELETE http://localhost:2102/api/media/1 \
  -H "Authorization: Bearer $TOKEN"

Check Where a File Is Used

curl http://localhost:2102/api/media/1/usage \
  -H "Authorization: Bearer $TOKEN"

Returns a list of content entries that reference this media file.

Folders

Organize media files into a hierarchical folder structure.

Create a Folder

curl -X POST http://localhost:2102/api/media-folders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Blog Images" }'

Create a Nested Folder

curl -X POST http://localhost:2102/api/media-folders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "2024", "parent": 1 }'

Get Folder Tree

curl http://localhost:2102/api/media-folders/tree \
  -H "Authorization: Bearer $TOKEN"

Returns the complete folder hierarchy.

Move Files Between Folders

curl -X PUT http://localhost:2102/api/media/bulk-move \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1, 2, 3],
    "folderId": 5
  }'

Delete Files in Bulk

curl -X DELETE http://localhost:2102/api/media/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 5, 6] }'

Thumbnails

Notty auto-generates image thumbnails in three sizes when you upload an image:

Size	Max Width	Purpose
small	500px	Thumbnails, lists
medium	750px	Cards, previews
large	1000px	Content images

Thumbnail sizes are configurable via settings.

Get Image Variants

curl http://localhost:2102/api/media/1/variants \
  -H "Authorization: Bearer $TOKEN"

Using Media in Content Schemas

Single Image Field

{
  "cover": {
    "type": "media",
    "allowedTypes": ["images"]
  }
}

Create content with media:

# Step 1: Upload the image
curl -X POST http://localhost:2102/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cover.jpg"
# Response: { "data": { "id": 42, ... } }

# Step 2: Reference the media ID in content
curl -X POST http://localhost:2102/api/content/article \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Article",
    "cover": 42
  }'

Gallery Field (Multiple Files)

{
  "gallery": {
    "type": "media",
    "allowedTypes": ["images"],
    "multiple": true
  }
}

Create content with gallery:

{
  "title": "Photo Album",
  "gallery": [42, 43, 44]
}

Populate Media in Queries

curl "http://localhost:2102/api/content/article?populate=cover" \
  -H "Authorization: Bearer $TOKEN"

Returns the full media object (url, alt, dimensions, formats) instead of just the ID.

Storage Configuration

Local Storage (Default)

// notty.config.ts
export default defineConfig({
  storage: {
    type: 'local',
    uploadDir: 'uploads',
    baseUrl: '/api/uploads',
  },
});

Setting	Env Variable	Default	Description
Storage type	STORAGE_TYPE	local	Storage provider
Upload directory	STORAGE_UPLOAD_DIR	uploads	File storage path
Base URL	STORAGE_BASE_URL	/api/uploads	Public URL prefix

Files are served from the upload directory via the built-in static file handler.