Base URL

/api/assets

Authentication

All endpoints require a valid JWT token in the Authorization header.

Endpoints

Upload Assets

Get Presigned URL

Generates a URL for client-side upload to S3.

POST /presigned-url

Body:

{
  "filename": "image.jpg",
  "contentType": "image/jpeg",
  "fileSize": 102400,
  "folderId": "uuid-optional",
  "tags": ["tag1", "tag2"]
}

Response:

{
  "uploadUrl": "https://s3...",
  "key": "company/assets/...",
  "cdnUrl": "https://cdn...",
  "assetId": "uuid"
}

Direct Upload

Upload file directly to server (multipart/form-data).

POST /direct

Form Data:

• file: File content

Response:

{
  "asset": { ... },
  "cdnUrl": "https://cdn..."
}

Manage Assets

List Assets

GET /

Query Parameters:

• limit: Number of items (default 50)
• offset: Pagination offset
• folderId: Filter by folder UUID
• type: Filter by type (IMAGE, VIDEO, etc.)
• tags: Filter by tag names (array)
• search: Search filename or prompt
• isArchived: Boolean

Get Asset Details

GET /:id

Update Asset

PATCH /:id

Body:

{
  "folderId": "uuid",
  "tags": ["new-tag-list"],
  "isArchived": false
}

Delete Asset

DELETE /:id

Query Parameters:

• hard: true to permanently delete from DB and S3. Default is soft delete (archive).

Record Usage

POST /:id/usage

Body:

{
  "contentType": "SOCIAL_POST", // BLOG_POST, VIDEO_SCRIPT
  "contentId": "uuid",
  "usageContext": "cover_image"
}

Manage Folders

Create Folder

POST /folders

Body:

{
  "name": "Marketing",
  "parentId": "uuid-optional"
}

List Folders

GET /folders

Query Parameters:

• parentId: Filter by parent folder UUID

Delete Folder

DELETE /folders/:id