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?
| Method | Path | Purpose | Permission | Guarded API key |
|---|---|---|---|---|
POST | /content/text | Publish or schedule a text post | post.create | Yes |
POST | /content/photos | Publish photos (1 or more) | post.create | Yes |
POST | /content/video | Publish one video | post.create | Yes |
POST | /content/document | Publish one document (PDF) | post.create | Yes |
GET | /content | List posts | post.view | Yes |
GET | /content/status | Look up a post by requestId | post.view | Yes |
GET | /content/:id | Get one post | post.view | Yes |
PATCH | /content/:id | Edit a draft or scheduled post | post.create | Yes (drafts only) |
POST | /content/:id/publish | Publish a draft | post.publish | Yes, unless requireApproval |
POST | /content/:id/publish-now | Publish a scheduled post now | post.publish | Yes, unless requireApproval |
POST | /content/:id/retry | Retry failed channels | post.publish | Yes |
POST | /content/bulk-schedule | Schedule many text posts | post.create | Yes |
PATCH | /content/:id/archive | Archive | post.archive | Yes |
PATCH | /content/:id/unarchive | Unarchive | post.unarchive | Yes |
DELETE | /content/:id | Delete | post.delete | Yes |
POST | /content/bulk-delete | Delete many | post.delete | No |
POST | /content/bulk-archive | Archive many | post.archive | No |
POST | /content/bulk-unarchive | Unarchive many | post.unarchive | No |
POST | /content/:id/submit-for-approval | Send a draft for review | post.create | Yes |
POST | /content/:id/approve | Approve and publish | post.approve | No |
POST | /content/:id/reject | Send back to draft | post.approve | No |
"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.
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)
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
connections | string[] | Yes, in practice | none | Connection slugs such as instagram-mybrand (ObjectIds also resolve). Empty or missing returns 400. Also accepted as a JSON string or repeated connections[] form fields. |
text | string | Yes for /content/text | none | Max 25 000 characters. Must not be blank on /content/text. |
title | string | No | none | Max 500. Fallback caption, used as the title on some platforms. |
description | string | No | none | Max 5 000. Used by LinkedIn, YouTube, Facebook. |
scheduledAt | ISO 8601 string | No | publish now | Must 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.... |
timezone | string | No | UTC | IANA name such as America/New_York, used to read scheduledAt. |
firstComment | string or object | No | none | A string is treated as { text }. Object fields: text (max 2 200), linkUrl, imageUrl. |
medias | string[] | No on text, required on media endpoints | none | Library media IDs or public URLs. |
contentFormat | enum | No | inferred | One of the values in CONTENT_FORMATS from @socifyr/shared, for example photo_carousel. |
platformOptions | object | No | {} | 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. |
saveDraft | boolean | No | false | Create a draft and do not publish. |
async | boolean | No | false | Return as soon as the job is queued, without uploadId. |
idempotencyKey | string | No | none | Max 64 characters. |
Unknown fields are rejected with 400, because the API runs with forbidNonWhitelisted.
Success response
{
"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:
{
"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:
{ "success": true, "data": { "success": true, "draftId": "6a05032a84584482ace13d52" } }With a requireApproval key, the post is parked for review:
{
"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
| Status | Cause | Fix |
|---|---|---|
| 400 | connections missing or empty | Send at least one slug. |
| 400 | Connection "x" not found or not active | Run list connections and use a slug from the list. |
| 400 | text is required | /content/text needs non-blank text. |
| 400 | Platforms do not support text: ... | A target platform cannot take this content type. See Content formats. |
| 400 | Validation array, for example scheduledAt must be a valid ISO 8601 date string | Fix the listed fields. |
| 403 | Upload limit reached for your plan... | Wait for the monthly reset or upgrade. |
| 403 | Scheduled post allowance reached (5/month on your plan)... | Free plan: the month's 5 scheduled posts are used. Publish now or upgrade. |
| 403 | Free plan daily limit reached for "<account>"... | Free plan: the account already has 5 posts in the last 24 hours. Wait, schedule it, or upgrade. |
| 403 | X (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. |
| 403 | Posts 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. |
| 403 | API key "<label>" reached its daily post limit... | A key guardrail. Resets at 00:00 UTC, or raise the limit in the dashboard. |
| 409 | Duplicate in-progress request with the same idempotency key | Wait for the first request to finish. |
| 429 | Rate limit | Back 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.
# 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"| Endpoint | Media | Max file size | Notes |
|---|---|---|---|
/content/photos | Up to 10 files | 30 MB each | Fields media, medias or medias[]. |
/content/video | 1 file | 512 MB | An empty result returns 400. |
/content/document | 1 file | 100 MB | For 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.
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
}'{
"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
curl "https://api.socifyr.com/api/content?page=1&limit=20&status=completed&type=video" \
-H "Authorization: Bearer sk_..."| Query | Type | Default | Constraints |
|---|---|---|---|
page | number string | 1 | |
limit | number string | 20 | Capped at 100. |
status | enum | all | draft, queued, pending, processing, publishing, completed, partial_failure, failed. Scheduled posts are pending. pending_approval is not an accepted filter value. |
platform | enum | all | One value from SUPPORTED_PLATFORMS. |
type | enum | all | video, photo, text, document. |
from, to | ISO 8601 | none | Filters by creation date. |
archived | "true" or "false" | excludes archived | true returns only archived posts. |
{
"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.
curl "https://api.socifyr.com/api/content/6a05033584584482ace13d72" \
-H "Authorization: Bearer sk_..."{
"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.
curl -X POST https://api.socifyr.com/api/content/6a05033584584482ace13d72/retry \
-H "Authorization: Bearer sk_..."{ "success": true, "data": { "success": true, "uploadId": "6a05033584584482ace13d72", "retriedChannels": 1 } }| Status | Cause | Fix |
|---|---|---|
| 400 | No failed channels to retry | Nothing failed. |
| 404 | Upload not found | Check the ID and workspace. |
| 409 | Cannot 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.
| Field | Type | Constraints |
|---|---|---|
type | enum | video, photo, text, document |
connections | string[] | The complete desired list, not a change set. Replaces the post's channels. |
title | string | Max 500 |
description | string | Max 5 000 |
text | string | Max 25 000 |
firstComment | object | { text?, linkUrl?, imageUrl? } |
mediaIds | string[] | Library media IDs. The edit endpoint uses mediaIds, not medias. |
scheduledAt | string | New time. Must be in the future for a scheduled post. |
timezone | string | IANA name |
platformOptions | object | Replaces stored options |
contentFormat | enum | From CONTENT_FORMATS |
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" }'{ "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?
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:
{ "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.
{
"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):
| Route | Success 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
- Drafts and approvals API
- Media API
- Webhooks API to get notified instead of polling
- Error handling guide