Media
Overview
The Media API gives you full programmatic access to your media library — the same files that appear under Media in the SkyLight Chat dashboard. You can list, upload, rename, and delete images and videos.
Files are stored on the configured storage backend (local, S3, Wasabi, or DigitalOcean Spaces) and served via a public URL.
AI agents and chat
The media library is the catalog of assets your AI agent can deliver in conversation on supported channels—alongside text—when instructions or product catalog entries point at specific files. Upload and organize files here so automated replies can share the correct image, video, or downloadable document in context.
The MediaFile object
{
"id": 15,
"name": "Product Hero Image",
"original_name": "hero-product-v2.jpg",
"url": "https://dashboard.skylightchat.com/storage/media/9/images/1741430012_abc123.jpg",
"file_type": "image",
"mime_type": "image/jpeg",
"extension": "jpg",
"file_size": 204800,
"formatted_size": "200 KB",
"metadata": { "width": 1920, "height": 1080 },
"uploaded_by": "client",
"is_active": true,
"created_at": "2026-03-08T10:00:00.000000Z",
"updated_at": "2026-03-08T10:00:00.000000Z"
}
| Field | Type | Description |
|---|---|---|
id | integer | Unique file identifier |
name | string | Display name (editable via PUT) |
original_name | string | Original filename from the upload |
url | string | Publicly accessible URL to the file |
file_type | string | image or video |
mime_type | string | Full MIME type (e.g. image/jpeg) |
extension | string | File extension |
file_size | integer | Size in bytes |
formatted_size | string | Human-readable size (e.g. 200 KB) |
metadata | object|null | For images: width and height in pixels |
uploaded_by | string | client or admin |
is_active | boolean | Whether the file is active |
List media files
GET /api/v1/media
Returns a paginated list of your media files, ordered newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
type | string | Filter by type: image or video |
search | string | Search by display name or original filename |
per_page | integer | Results per page (default: 25, max: 100) |
curl "https://dashboard.skylightchat.com/api/v1/media?type=image&per_page=10" \
-H "X-Api-Key: ••••••••••••"
Upload a file
POST /api/v1/media
Upload a new image or video. This is a multipart/form-data request.
| Field | Type | Required | Notes |
|---|---|---|---|
file | file | ✓ | jpg, jpeg, png, gif, mp4, avi, mov, wmv, flv, webm — max 50 MB |
name | string | No | Display name. Defaults to the original filename if omitted. |
curl -X POST https://dashboard.skylightchat.com/api/v1/media \
-H "X-Api-Key: ••••••••••••" \
-F "file=@/path/to/product-hero.jpg" \
-F "name=Product Hero Image"
Returns 201 Created with the full media object including the public url.
Get a file
GET /api/v1/media/{id}
Returns a single media file. Returns 404 if the file does not exist or belongs to a different account.
curl https://dashboard.skylightchat.com/api/v1/media/15 \
-H "X-Api-Key: ••••••••••••"
Rename a file
PUT /api/v1/media/{id}
Update the display name of a media file. The physical file is not changed.
| Field | Type | Required |
|---|---|---|
name | string | ✓ |
curl -X PUT https://dashboard.skylightchat.com/api/v1/media/15 \
-H "X-Api-Key: ••••••••••••" \
-H "Content-Type: application/json" \
-d '{ "name": "Product Hero — March 2026" }'
Delete a file
DELETE /api/v1/media/{id}
Permanently deletes the media file and its physical storage object. Returns 204 No Content.
curl -X DELETE https://dashboard.skylightchat.com/api/v1/media/15 \
-H "X-Api-Key: ••••••••••••"
Supported file types
| Category | Extensions |
|---|---|
| Images | jpg, jpeg, png, gif |
| Videos | mp4, avi, mov, wmv, flv, webm |
Maximum file size: 50 MB per upload.