Media API
The media library stores files once so you can reuse them across posts. Upload a file, keep the returned id, and pass that ID in medias when you create a post. All paths are under /api/media.
Auth and workspace selection are described in the REST API overview. Media routes are gated by the plan's media library flag. In the shared tier table every plan includes it, and self-hosted installs skip plan checks.
Which media endpoints can I call?
| Method | Path | Purpose | Permission | Guarded API key |
|---|---|---|---|---|
POST | /media/upload | Upload one file | media.upload | Yes |
GET | /media | List and search | media.view | Yes |
GET | /media/:id | Get one item | media.view | Yes |
POST | /media/:id | Update alt text, description, tags | media.upload | No |
DELETE | /media/:id | Delete one item | media.delete | No |
POST | /media/bulk-delete | Delete many items | media.delete | No |
How do I upload a file to the media library?
POST /media/upload as multipart/form-data with the file in a field named file.
curl -X POST https://api.socifyr.com/api/media/upload \
-H "Authorization: Bearer sk_..." \
-F "file=@./banner.jpg"| Field | Type | Required | Constraints |
|---|---|---|---|
file | file | Yes | Max 500 MB. MIME type must start with image/, video/ or application/. |
{
"success": true,
"data": {
"id": "6a05031284584482ace13d3b",
"name": "banner.jpg",
"type": "image",
"mimeType": "image/jpeg",
"sizeBytes": 330665,
"url": "https://storage.example.com/signed-url",
"isArchived": false,
"tags": [],
"createdAt": "2026-11-13T09:00:00.000Z"
}
}url is a signed URL that expires. thumbnailUrl is added when a thumbnail exists. Fetch the item again for a fresh URL.
| Status | Cause | Fix |
|---|---|---|
| 400 | No file, wrong MIME type, or file over 500 MB | Send a supported file under the limit. |
| 403 | Storage limit reached for your plan... | Delete unused media or upgrade. Limits are in Limits. |
| 403 | Upload limit reached for your plan... | See Limits. |
You can also skip the library: POST /content/photos and /content/video accept a public URL or a direct file. Public URLs must use http or https, point to a public host, and be at most 600 MB.
How do I list and search media?
curl "https://api.socifyr.com/api/media?type=image&search=banner&page=1&limit=20&sortBy=createdAt&sortOrder=desc" \
-H "Authorization: Bearer sk_..."| Query | Type | Default | Constraints |
|---|---|---|---|
type | enum | all | image, video, document |
search | string | none | Case-insensitive match on name or tags |
page | integer | 1 | Min 1 |
limit | integer | 20 | 1 to 100 |
sortBy | enum | createdAt | createdAt, name |
sortOrder | string | desc | asc or desc |
{
"success": true,
"data": {
"results": [
{
"id": "6a05031284584482ace13d3b",
"name": "banner.jpg",
"type": "image",
"mimeType": "image/jpeg",
"sizeBytes": 330665,
"url": "https://storage.example.com/signed-url",
"thumbnailUrl": "https://storage.example.com/thumb-signed-url",
"isArchived": false,
"alt": "Launch banner",
"tags": ["evergreen"],
"createdAt": "2026-11-13T09:00:00.000Z",
"usedInContentCount": 2
}
],
"page": 1,
"limit": 20,
"total": 47,
"pages": 3
}
}How do I get one media item?
GET /media/:id returns the same fields as upload, including alt, description and tags. It returns 404 Media not found if the ID is not in this workspace.
How do I edit alt text and tags?
POST /media/:id. The route uses POST, not PATCH. All fields are optional.
| Field | Type | Notes |
|---|---|---|
alt | string | Alt text |
description | string | Free text |
tags | string[] | Replaces the tag list |
curl -X POST https://api.socifyr.com/api/media/6a05031284584482ace13d3b \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{ "alt": "Launch banner", "tags": ["evergreen"] }'The response is the updated item: id, name, type, mimeType, sizeBytes, url, alt, description, tags, createdAt.
How do I delete media?
DELETE /media/:id returns 204 with no body, or 404 Media not found.
POST /media/bulk-delete takes { "ids": ["...", "..."] } (a non-empty array of strings) and returns the count:
{ "success": true, "data": { "deleted": 2 } }It returns 404 No media found if none of the IDs exist in the workspace. Deleting media also removes it from any post that referenced it.
Frequently asked questions
Can a guarded API key delete or edit media? No. Guarded keys can upload, list and read media. Edit and delete need a dashboard session or an unrestricted key.
How do I reuse an uploaded file in a post? Pass its id in the medias array of POST /content/photos, /content/video or /content/document.