Skip to content

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? ​

MethodPathPurposePermissionGuarded API key
POST/media/uploadUpload one filemedia.uploadYes
GET/mediaList and searchmedia.viewYes
GET/media/:idGet one itemmedia.viewYes
POST/media/:idUpdate alt text, description, tagsmedia.uploadNo
DELETE/media/:idDelete one itemmedia.deleteNo
POST/media/bulk-deleteDelete many itemsmedia.deleteNo

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.

bash
curl -X POST https://api.socifyr.com/api/media/upload \
  -H "Authorization: Bearer sk_..." \
  -F "file=@./banner.jpg"
FieldTypeRequiredConstraints
filefileYesMax 500 MB. MIME type must start with image/, video/ or application/.
json
{
  "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.

StatusCauseFix
400No file, wrong MIME type, or file over 500 MBSend a supported file under the limit.
403Storage limit reached for your plan...Delete unused media or upgrade. Limits are in Limits.
403Upload 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? ​

bash
curl "https://api.socifyr.com/api/media?type=image&search=banner&page=1&limit=20&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer sk_..."
QueryTypeDefaultConstraints
typeenumallimage, video, document
searchstringnoneCase-insensitive match on name or tags
pageinteger1Min 1
limitinteger201 to 100
sortByenumcreatedAtcreatedAt, name
sortOrderstringdescasc or desc
json
{
  "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.

FieldTypeNotes
altstringAlt text
descriptionstringFree text
tagsstring[]Replaces the tag list
bash
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:

json
{ "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.

Next steps ​