API Documentation

Everything you need to integrate MediaLabs into your app.

Getting Started

1

Get your API key

Create an API key to authenticate your requests.

2

Upload your first file

curl
curl -X POST https://api.medialabs.app/v1/files/upload \
  -H "Authorization: Bearer ml_your_api_key" \
  -F "file=@photo.jpg"
3

Use your CDN URL

Every uploaded file gets a CDN URL. You can transform images on the fly:

https://cdn.medialabs.app/{accountId}/{fileId}/original.jpg

<!-- Resize to 300px wide, convert to WebP -->
https://cdn.medialabs.app/.../original.jpg?w=300&f=webp

<!-- Crop to 200x200, 80% quality -->
https://cdn.medialabs.app/.../original.jpg?w=200&h=200&fit=cover&q=80
Base URLhttps://api.medialabs.app

Upload, list, get, update, delete, and serve files. Images get AI-generated names automatically.

POST/v1/files/uploadUpload a file (multipart, max 50 MB)

Images get an AI-generated descriptive name unless you provide a custom name. Send folderId before the file field in the multipart body.

Request Body
# multipart/form-data
folderId: "uuid" (optional, must come before file)
name: "custom-name.jpg" (optional)
file: <binary>
Response
{
  "id": "ml_img_VKM114Seg31uCERW",
  "name": "sunset-over-mountains.jpg",
  "fileType": "image",
  "mimeType": "image/jpeg",
  "fileSize": 245760,
  "url": "https://api.medialabs.app/v1/files/ml_img_.../serve",
  "cdnUrl": "https://cdn.medialabs.app/.../original.jpg",
  "createdAt": "2024-01-15T10:30:00.000Z"
}
Example
curl -X POST https://api.medialabs.app/v1/files/upload \
  -H "Authorization: Bearer ml_your_api_key"
POST/v1/files/upload/presignGet presigned URL for large files

For files >50 MB. Returns a URL to PUT the file to, then call /complete.

Request Body
{
  "fileName": "large-video.mp4",
  "mimeType": "video/mp4",
  "fileSize": 104857600,
  "folderId": "uuid" // optional
}
Response
{
  "fileId": "ml_vid_...",
  "uploadUrl": "https://r2.cloudflarestorage.com/...",
  "expiresAt": "2024-01-15T11:30:00.000Z"
}
Example
curl -X POST https://api.medialabs.app/v1/files/upload/presign \
  -H "Authorization: Bearer ml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "large-video.mp4", "mimeType": "video/mp4", "fileSize": 104857600, "folderId": "uuid" // optional}'
POST/v1/files/upload/completeFinalize presigned upload
Request Body
{ "fileId": "ml_vid_..." }
Response
{ "id": "ml_vid_...", "name": "...", "fileType": "video", "status": "ready", ... }
Example
curl -X POST https://api.medialabs.app/v1/files/upload/complete \
  -H "Authorization: Bearer ml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "ml_vid_..." }'
GET/v1/filesList files (paginated)
Query Parameters
folderId, fileType, status, search, cursor, limit (1-100, default 50)
Response
{
  "data": [{ "id": "...", "name": "...", "fileType": "image", "url": "...", "cdnUrl": "...", ... }],
  "cursor": "2024-01-15T10:30:00.000Z",
  "hasMore": true
}
Example
curl https://api.medialabs.app/v1/files \
  -H "Authorization: Bearer ml_your_api_key"
GET/v1/files/:idGet file details
Response
{
  "id": "ml_img_...", "name": "...", "fileType": "image",
  "mimeType": "image/jpeg", "fileSize": 245760, "status": "ready",
  "folderId": null, "width": 1920, "height": 1080,
  "url": "...", "cdnUrl": "...",
  "createdAt": "...", "updatedAt": "..."
}
Example
curl https://api.medialabs.app/v1/files/:id \
  -H "Authorization: Bearer ml_your_api_key"
GET/v1/files/:id/serveServe file content (302 redirect)

Redirects to a presigned download URL. Use for displaying images or downloading files.

Example
curl https://api.medialabs.app/v1/files/:id/serve \
  -H "Authorization: Bearer ml_your_api_key"
PATCH/v1/files/:idRename or move a file
Request Body
{
  "name": "new-name.jpg",       // optional
  "folderId": "uuid" | null     // optional, null = root
}
Response
{ "id": "...", "name": "new-name.jpg", "folderId": "uuid", "updatedAt": "..." }
Example
curl -X PATCH https://api.medialabs.app/v1/files/:id \
  -H "Authorization: Bearer ml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "new-name.jpg", // optional "folderId": "uuid" | null // optional, null = root}'
DELETE/v1/files/:idDelete a file

Permanently deletes from storage and database.

Example
curl -X DELETE https://api.medialabs.app/v1/files/:id \
  -H "Authorization: Bearer ml_your_api_key"
POST/v1/files/bulk-deleteDelete multiple files (max 100)
Request Body
{ "ids": ["ml_img_...", "ml_img_..."] }
Response
{ "deleted": 2 }
Example
curl -X POST https://api.medialabs.app/v1/files/bulk-delete \
  -H "Authorization: Bearer ml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["ml_img_...", "ml_img_..."] }'
POST/v1/files/bulk-moveMove multiple files to a folder
Request Body
{
  "ids": ["ml_img_...", "ml_img_..."],
  "folderId": "uuid" | null  // null = root
}
Response
{ "moved": 2 }
Example
curl -X POST https://api.medialabs.app/v1/files/bulk-move \
  -H "Authorization: Bearer ml_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["ml_img_...", "ml_img_..."], "folderId": "uuid" | null // null = root}'