How to upload media once and reuse it ​

Upload a file to the media library with POST /api/media/upload (multipart, field name file, up to 500 MB). The response includes an id. Pass that ID in medias on any later content request instead of uploading the file again. IDs are 24-character hex strings.

Reusing IDs saves bandwidth when the same asset goes to several posts, and it is the only way to attach local files from the Python SDK and MCP, which accept IDs and public URLs but not file bytes.

How do I upload a file? ​

Sidebar > Media Library. Upload files there, or add them from the media dialog
while composing a post. See the media library page for search and delete.

socifyr media upload ./banner.jpg --alt "Launch banner"

import { readFileSync } from 'node:fs'

const item = await socifyr.media.upload(readFileSync('banner.jpg'), 'banner.jpg')
console.log(item.id, item.url)

# No media resource in the Python SDK. Upload with REST (requests shown here),
# then pass the returned id to client.uploads.photos().
import os, requests

r = requests.post(
    "https://api.socifyr.com/api/media/upload",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIFYR_API_KEY']}",
        "X-Workspace-Id": os.environ["SOCIFYR_WORKSPACE_ID"],
    },
    files={"file": open("banner.jpg", "rb")},
)
media_id = r.json()["data"]["id"]

curl -X POST https://api.socifyr.com/api/media/upload \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "X-Workspace-Id: $SOCIFYR_WORKSPACE_ID" \
  -F "file=@banner.jpg"

No upload tool. The agent can only reuse media that is already in the library
(list_media) or pass a public URL to post_image and post_video.

Response:

{
  "success": true,
  "data": {
    "id": "6a04f715d3d7d93575e65d13",
    "name": "banner.jpg",
    "type": "image",
    "mimeType": "image/jpeg",
    "sizeBytes": 482113,
    "url": "https://cdn.example.com/...",
    "thumbnailUrl": "https://cdn.example.com/...",
    "isArchived": false,
    "createdAt": "2026-12-01T14:00:00.000Z"
  }
}

The URL host depends on your storage setup. Accepted file types are image/*, video/* and application/*.

How do I list and find media? ​

socifyr media list --type image --search banner --limit 10
socifyr media get 6a04f715d3d7d93575e65d13

const { results, total } = await socifyr.media.list({ type: 'image', search: 'banner', limit: 10 })
const one = await socifyr.media.get('6a04f715d3d7d93575e65d13')

curl "https://api.socifyr.com/api/media?type=image&search=banner&limit=10" \
  -H "Authorization: Bearer $SOCIFYR_API_KEY"

{ "tool": "list_media", "arguments": { "type": "image", "search": "banner", "limit": 10 } }

The list response has results, page, limit, total and pages. Filters: type (image, video, document), search, sortBy (createdAt or name) and sortOrder. Each item also carries usedInContentCount.

How do I reuse an uploaded file in a post? ​

Put the ID in medias:

socifyr post "Launch day" --media-id 6a04f715d3d7d93575e65d13 --to instagram-mybrand

await socifyr.uploads.photos({
  connections: ['instagram-mybrand'],
  medias: ['6a04f715d3d7d93575e65d13'],
  text: 'Launch day',
})

client.uploads.photos(
    connections=["instagram-mybrand"],
    medias=["6a04f715d3d7d93575e65d13"],
    text="Launch day",
)

curl -X POST https://api.socifyr.com/api/content/photos \
  -H "Authorization: Bearer $SOCIFYR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connections":["instagram-mybrand"],"medias":["6a04f715d3d7d93575e65d13"],"text":"Launch day"}'

{
  "tool": "post_image",
  "arguments": { "connections": ["instagram-mybrand"], "images": ["6a04f715d3d7d93575e65d13"], "text": "Launch day" }
}

Prompt for your agent: "Show me the last five videos in my media library, then post the newest to TikTok." The agent calls list_media with type: video, then post_video.

How do I edit or delete media? ​

• Edit alt, description and tags with POST /api/media/:id or socifyr.media.update(id, { alt, description, tags }).
• Delete one item with DELETE /api/media/:id, or many with POST /api/media/bulk-delete and { "ids": [...] }. The CLI is socifyr media delete <ids...>, and MCP is delete_media with ids. MCP's delete_media is blocked for guarded keys.

What errors can I get, and how do I fix them? ​

FAQ ​

How much storage do I get? ​

It depends on the plan. See limits.

Can I pass a URL instead of uploading? ​

Yes. A public http or https URL works anywhere an ID does.

Next steps ​

• Publish an image post
• Publish a video post
• Media library in the dashboard
• REST reference: media