Skip to content

Content API ​

The Content API creates and manages posts. One request publishes to one or more connected accounts, and each account is a "channel" with its own result. All endpoints live under /api/content.

Every request needs Authorization: Bearer sk_.... See REST API overview for the shared rules.

Which content endpoints can I call? ​

MethodPathPurposePermissionGuarded API key
POST/content/textPublish or schedule a text postpost.createYes
POST/content/photosPublish photos (1 or more)post.createYes
POST/content/videoPublish one videopost.createYes
POST/content/documentPublish one document (PDF)post.createYes
GET/contentList postspost.viewYes
GET/content/statusLook up a post by requestIdpost.viewYes
GET/content/:idGet one postpost.viewYes
PATCH/content/:idEdit a draft or scheduled postpost.createYes (drafts only)
POST/content/:id/publishPublish a draftpost.publishYes, unless requireApproval
POST/content/:id/publish-nowPublish a scheduled post nowpost.publishYes, unless requireApproval
POST/content/:id/retryRetry failed channelspost.publishYes
POST/content/bulk-scheduleSchedule many text postspost.createYes
PATCH/content/:id/archiveArchivepost.archiveYes
PATCH/content/:id/unarchiveUnarchivepost.unarchiveYes
DELETE/content/:idDeletepost.deleteYes
POST/content/bulk-deleteDelete manypost.deleteNo
POST/content/bulk-archiveArchive manypost.archiveNo
POST/content/bulk-unarchiveUnarchive manypost.unarchiveNo
POST/content/:id/submit-for-approvalSend a draft for reviewpost.createYes
POST/content/:id/approveApprove and publishpost.approveNo
POST/content/:id/rejectSend back to draftpost.approveNo

"Guarded API key" means a key that has a daily post limit, an X spend cap, or require-approval turned on. Those keys can only call routes marked allowed. See API keys and guardrails. Approval routes are covered in Drafts and approvals.

Content routes are rate limited to 60 requests per minute. GET /content and GET /content/:id allow 240 per minute.

How do I publish a text post with the API? ​

POST /content/text with JSON. connections and text are the minimum.

bash
curl -X POST https://api.socifyr.com/api/content/text \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "connections": ["linkedin-mybrand", "x-mybrand"],
    "text": "We just shipped scheduled posts."
  }'

Body parameters (shared by all create endpoints) ​

FieldTypeRequiredDefaultConstraints
connectionsstring[]Yes, in practicenoneConnection slugs such as instagram-mybrand (ObjectIds also resolve). Empty or missing returns 400. Also accepted as a JSON string or repeated connections[] form fields.
textstringYes for /content/textnoneMax 25 000 characters. Must not be blank on /content/text.
titlestringNononeMax 500. Fallback caption, used as the title on some platforms.
descriptionstringNononeMax 5 000. Used by LinkedIn, YouTube, Facebook.
scheduledAtISO 8601 stringNopublish nowMust parse as a date. Every plan can schedule; on Free a future scheduledAt uses one of 5 scheduled posts a month, and past that the API returns 403 Scheduled post allowance reached....
timezonestringNoUTCIANA name such as America/New_York, used to read scheduledAt.
firstCommentstring or objectNononeA string is treated as { text }. Object fields: text (max 2 200), linkUrl, imageUrl.
mediasstring[]No on text, required on media endpointsnoneLibrary media IDs or public URLs.
contentFormatenumNoinferredOne of the values in CONTENT_FORMATS from @socifyr/shared, for example photo_carousel.
platformOptionsobjectNo{}Per-connection settings. Keys can be a connection slug, an ObjectId, or a platform name. Each platform validates its own values at publish time. See Platforms.
saveDraftbooleanNofalseCreate a draft and do not publish.
asyncbooleanNofalseReturn as soon as the job is queued, without uploadId.
idempotencyKeystringNononeMax 64 characters.

Unknown fields are rejected with 400, because the API runs with forbidNonWhitelisted.

Success response ​

json
{
  "success": true,
  "data": {
    "success": true,
    "requestId": "97005ec5-6361-4953-8a69-ce7292ad9f11",
    "uploadId": "6a05033584584482ace13d72",
    "usage": { "count": 3, "limit": 5, "remaining": 2 }
  }
}

usage shows this month's uploads against the plan cap. On Free limit is a hard cap. On paid plans it is a fair-use ceiling that never blocks posting. -1 means unlimited. The full picture is in Usage API.

With "async": true the response has no uploadId. It adds message, scheduledAt and totalChannels:

json
{
  "success": true,
  "data": {
    "success": true,
    "requestId": "97005ec5-6361-4953-8a69-ce7292ad9f11",
    "usage": { "count": 3, "limit": 5, "remaining": 2 },
    "message": "Upload processing started",
    "scheduledAt": null,
    "totalChannels": 2
  }
}

With "saveDraft": true:

json
{ "success": true, "data": { "success": true, "draftId": "6a05032a84584482ace13d52" } }

With a requireApproval key, the post is parked for review:

json
{
  "success": true,
  "data": {
    "success": true,
    "uploadId": "6a05033584584482ace13d72",
    "status": "pending_approval",
    "message": "This API key requires approval — the post is pending review before it publishes."
  }
}

Errors ​

StatusCauseFix
400connections missing or emptySend at least one slug.
400Connection "x" not found or not activeRun list connections and use a slug from the list.
400text is required/content/text needs non-blank text.
400Platforms do not support text: ...A target platform cannot take this content type. See Content formats.
400Validation array, for example scheduledAt must be a valid ISO 8601 date stringFix the listed fields.
403Upload limit reached for your plan...Wait for the monthly reset or upgrade.
403Scheduled post allowance reached (5/month on your plan)...Free plan: the month's 5 scheduled posts are used. Publish now or upgrade.
403Free plan daily limit reached for "<account>"...Free plan: the account already has 5 posts in the last 24 hours. Wait, schedule it, or upgrade.
403X (Twitter) post allowance reached...Plan X allowance and X post pack credits are used up. Each tweet uses 1 unit, or 5 with a link; thread tweets and a first comment count separately.
403Posts with links can’t go to X (Twitter) on the Free plan — X charges extra for them. Remove the link (including from the first comment) or upgrade to Creator.Free can't post links to X, in the post, a thread tweet or the first comment. Remove the link or upgrade.
403<platform> daily posting limit reached for "<account>"...The account hit the platform's rolling 24 hour cap. Wait or use another account.
403API key "<label>" reached its daily post limit...A key guardrail. Resets at 00:00 UTC, or raise the limit in the dashboard.
409Duplicate in-progress request with the same idempotency keyWait for the first request to finish.
429Rate limitBack off and retry.

How do I avoid duplicate posts on retries? ​

Send an Idempotency-Key header (the server also reads X-Idempotency-Key and X-Request-Id) on POST requests. A second request with the same key in the same workspace returns the stored response of the first one.

How do I publish photos or a video with the API? ​

POST /content/photos and POST /content/video take the same body fields as text, plus media. Give media as library IDs or public URLs in JSON, or upload files as multipart/form-data.

bash
# JSON with a library ID and a public URL
curl -X POST https://api.socifyr.com/api/content/photos \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "connections": ["instagram-mybrand"],
    "text": "Launch day",
    "medias": ["6a04f715d3d7d93575e65d13", "https://cdn.example.com/img2.png"],
    "contentFormat": "photo_carousel"
  }'

# Multipart file upload
curl -X POST https://api.socifyr.com/api/content/video \
  -H "Authorization: Bearer sk_..." \
  -F "connections[]=youtube-mychannel" \
  -F "title=Release walkthrough" \
  -F "medias[]=@./walkthrough.mp4"
EndpointMediaMax file sizeNotes
/content/photosUp to 10 files30 MB eachFields media, medias or medias[].
/content/video1 file512 MBAn empty result returns 400.
/content/document1 file100 MBFor example a PDF. Only platforms that accept documents (see Platforms).

Extra errors: 400 Provide photo files via media field, or a media[] array with library IDs or public URLs (same wording pattern for video and document), 400 Media not found: <id>, and for YouTube Shorts targets a 400 explaining that the video is landscape or too long for a Short. Upload and storage limits can also return 403 Storage limit reached for your plan....

Reuse the same file across posts by uploading it once. See Media API.

How do I schedule a post with the API? ​

Add scheduledAt (and optionally timezone) to any create request. The post is queued and publishes at that time.

bash
curl -X POST https://api.socifyr.com/api/content/text \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "connections": ["linkedin-mybrand"],
    "text": "Webinar starts in one hour.",
    "scheduledAt": "2026-12-01T09:00:00",
    "timezone": "America/New_York",
    "async": true
  }'
json
{
  "success": true,
  "data": {
    "success": true,
    "requestId": "7b1d6f0e-2c1a-4d7e-9a6c-0f5b8a2d3e11",
    "usage": { "count": 4, "limit": 5, "remaining": 1 },
    "message": "Upload scheduled",
    "scheduledAt": "2026-12-01T14:00:00.000Z",
    "totalChannels": 1
  }
}

A scheduled post has status pending with a future scheduledAt. Edit it with PATCH /content/:id, publish it early with POST /content/:id/publish-now, or remove it with DELETE /content/:id. See the scheduling guide.

How do I schedule many posts at once? ​

POST /content/bulk-schedule takes up to 500 text posts as rows or as a csv string. See Bulk scheduling API for the full contract.

How do I list posts? ​

GET /content

bash
curl "https://api.socifyr.com/api/content?page=1&limit=20&status=completed&type=video" \
  -H "Authorization: Bearer sk_..."
QueryTypeDefaultConstraints
pagenumber string1
limitnumber string20Capped at 100.
statusenumalldraft, queued, pending, processing, publishing, completed, partial_failure, failed. Scheduled posts are pending. pending_approval is not an accepted filter value.
platformenumallOne value from SUPPORTED_PLATFORMS.
typeenumallvideo, photo, text, document.
from, toISO 8601noneFilters by creation date.
archived"true" or "false"excludes archivedtrue returns only archived posts.
json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "6a05033584584482ace13d72",
        "type": "text",
        "status": "completed",
        "text": "We just shipped scheduled posts.",
        "requestId": "97005ec5-6361-4953-8a69-ce7292ad9f11",
        "mediaThumbnail": null,
        "channels": [
          {
            "platform": "linkedin",
            "connectionId": "6a04f715d3d7d93575e65d13",
            "targetName": "My Brand",
            "result": { "status": "success", "postId": "urn:li:share:123", "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:123", "publishedAt": "2026-11-13T09:00:04.000Z" }
          }
        ],
        "scheduledAt": null,
        "createdAt": "2026-11-13T09:00:00.000Z"
      }
    ],
    "meta": { "total": 156, "page": 1, "limit": 20, "totalPages": 8 }
  }
}

Note the double data: the envelope's data holds { data, meta }.

How do I check the status of a post? ​

GET /content/:id returns the full post. GET /content/status?requestId=... looks up by the requestId from a create response, and also accepts the post ID.

bash
curl "https://api.socifyr.com/api/content/6a05033584584482ace13d72" \
  -H "Authorization: Bearer sk_..."
json
{
  "success": true,
  "data": {
    "id": "6a05033584584482ace13d72",
    "type": "text",
    "status": "partial_failure",
    "text": "We just shipped scheduled posts.",
    "timezone": "UTC",
    "mediaIds": [],
    "channels": [
      {
        "platform": "linkedin",
        "connectionId": "6a04f715d3d7d93575e65d13",
        "targetName": "My Brand",
        "result": { "status": "success", "postId": "urn:li:share:123", "postUrl": "https://www.linkedin.com/feed/update/urn:li:share:123", "publishedAt": "2026-11-13T09:00:04.000Z" }
      },
      {
        "platform": "x",
        "connectionId": "6a04f715d3d7d93575e65d14",
        "targetName": "@mybrand",
        "result": { "status": "failed", "error": "reconnect_required" }
      }
    ],
    "scheduledAt": null,
    "createdAt": "2026-11-13T09:00:00.000Z",
    "platformOptions": {},
    "archivedAt": null
  }
}

The status response from GET /content/status has this shape: requestId, uploadId, status, type, channels, createdAt.

Post statuses: draft, pending_approval, pending (also scheduled), queued, processing, publishing, completed, partial_failure, failed. Channel result statuses include success, failed and pending.

Errors: GET /content/:id returns 404 Upload not found. GET /content/status returns 400 Upload not found for an unknown requestId.

How do I retry a failed post? ​

POST /content/:id/retry, no body. Only failed channels are re-queued. Channels that already succeeded are not touched.

bash
curl -X POST https://api.socifyr.com/api/content/6a05033584584482ace13d72/retry \
  -H "Authorization: Bearer sk_..."
json
{ "success": true, "data": { "success": true, "uploadId": "6a05033584584482ace13d72", "retriedChannels": 1 } }
StatusCauseFix
400No failed channels to retryNothing failed.
404Upload not foundCheck the ID and workspace.
409Cannot retry an upload with status "..."Retry works only for failed and partial_failure.

If a channel failed with reconnect_required, fix the connection first. See Connections API and Connections and slugs.

How do I edit a draft or scheduled post? ​

PATCH /content/:id with any of the fields below. Fields you leave out stay as they are. Only drafts and scheduled posts are editable.

FieldTypeConstraints
typeenumvideo, photo, text, document
connectionsstring[]The complete desired list, not a change set. Replaces the post's channels.
titlestringMax 500
descriptionstringMax 5 000
textstringMax 25 000
firstCommentobject{ text?, linkUrl?, imageUrl? }
mediaIdsstring[]Library media IDs. The edit endpoint uses mediaIds, not medias.
scheduledAtstringNew time. Must be in the future for a scheduled post.
timezonestringIANA name
platformOptionsobjectReplaces stored options
contentFormatenumFrom CONTENT_FORMATS
bash
curl -X PATCH https://api.socifyr.com/api/content/6a05033584584482ace13d72 \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Updated copy", "scheduledAt": "2026-12-02T09:00:00Z" }'
json
{ "success": true, "data": { "success": true, "draftId": "6a05033584584482ace13d72" } }

Errors: 404 Post not found, 409 Cannot edit a post with status "..." — only drafts and scheduled posts can be edited, 400 Scheduled time must be in the future, 400 Invalid scheduledAt — provide a valid ISO 8601 date/time. A guarded API key can only edit drafts it created itself (403 otherwise).

How do I publish a draft or scheduled post now? ​

bash
curl -X POST https://api.socifyr.com/api/content/6a05032a84584482ace13d52/publish \
  -H "Authorization: Bearer sk_..."

/publish moves a draft to publishing and returns the same shape as an async create (requestId, usage, message, scheduledAt, totalChannels). A draft with a future scheduledAt is scheduled instead of sent. Errors: 404 Draft not found, 409 Draft is already being published.

POST /content/:id/publish-now takes a scheduled post and sends it immediately:

json
{ "success": true, "data": { "success": true, "uploadId": "6a05033584584482ace13d72", "requestId": "7b1d6f0e-2c1a-4d7e-9a6c-0f5b8a2d3e11" } }

Errors: 404 Upload not found, 409 Cannot publish an upload with status "...", 400 Upload does not have a scheduled time. Both routes return 403 This API key requires approval and cannot ... for a requireApproval key.

How do I delete or archive a post? ​

DELETE /content/:id returns 200 with per-platform delete outcomes. For published posts, Socifyr also tries to delete on platforms whose APIs allow it (TikTok, Facebook, X, YouTube). Other platforms report local_only.

json
{
  "success": true,
  "data": {
    "success": true,
    "uploadId": "6a05033584584482ace13d72",
    "platformDeletes": []
  }
}

Errors: 404 Upload not found, 400 Cannot delete an upload with status "..." (for example while publishing).

PATCH /content/:id/archive and /unarchive return { "success": true, "uploadId": "..." }.

Bulk routes take { "ids": ["...", "..."] } (at least one valid ObjectId):

RouteSuccess data
POST /content/bulk-delete{ "success": true, "deleted": <n>, "skipped": <n> }. Only draft, queued, pending, failed and partial_failure items are deleted.
POST /content/bulk-archive{ "success": true, "archived": <n> }
POST /content/bulk-unarchive{ "success": true, "unarchived": <n> }

Frequently asked questions ​

Why does my create call return 201 but the post is not live yet? Publishing is asynchronous. The response confirms the job is queued. Poll GET /content/:id until status is completed, partial_failure or failed.

Can I send connections as platform names such as instagram? Use slugs. They are the stable contract. Platform names are only valid as keys inside platformOptions.

What is the difference between requestId and uploadId?uploadId is the post's database ID. requestId is a UUID created when the job is queued. Both work with GET /content/status.

Next steps ​