Postelk API
Schedule and publish short-form video to every connected account from your own code, scripts, agents or automations. Same publishing pipeline as the app, same limits, same validation.
https://postelk.com/api/v1What this is
Normally you post from the Postelk dashboard. An API key lets something else do it for you — an AI assistant, an automation tool, or a script you wrote.
The most common reason people want one: telling Claude or a similar assistant what to post, in plain English. "Schedule this clip for my TikTok tomorrow evening" instead of clicking through the composer.
Everything an app does with your key is something you could have done yourself in the dashboard. It cannot connect new social accounts, change your plan, see your password, or post more than your normal 24-hour limits allow.
Get a key
Open the API page
In Postelk, click API in the left sidebar, under Developers. Go there now →
Click New key
Give it a name you'll recognise later — the name of the app you're connecting is a good choice. Leave the permissions as they are unless you want to restrict it.
Copy the key immediately
It starts with
ugcd_live_and is shown once. We store only a scrambled version of it, so we genuinely cannot show it to you again. If you lose it, delete that key and make a new one — it takes ten seconds.
Connect an app
Almost every AI tool connects the same way now: you paste one server URL, sign in to Postelk, and choose what the tool may do. No key to copy.
| Tool | How it connects |
|---|---|
| Claude, ChatGPT, Gemini | MCP connector — paste the server URL, sign in, approve |
| Notion, Perplexity, Manus | MCP connector — same three steps |
| Claude Code, Cursor, Antigravity | MCP, from a config file or one terminal command |
| Zapier, n8n | An HTTP step with your API key in the header |
| Anything else that speaks MCP | Same server URL — see the MCP section |
Step-by-step instructions for each app live in the app itself, under Integrations.
If your tool has no MCP support
Some tools can only make plain web requests. Create a key, then paste the text below in, replacing PASTE_YOUR_KEY_HERE with your actual key. That single message teaches it everything it needs.
You can post to my social accounts through the Postelk API.
Base URL: https://postelk.com/api/v1
Send this header on every request:
Authorization: Bearer PASTE_YOUR_KEY_HERE
What you can do:
GET /accounts list my connected accounts (use the id values)
GET /usage how many posts each account can still make (24h window)
POST /uploads upload a file (form field: file) -> returns { url }
POST /imports { url } import a public Google Drive / Dropbox / direct link -> { url }
GET /renders videos I made in Postelk (?unused=1 = not posted yet)
POST /posts { accounts: [id], caption, media: [{url, type}], scheduled_at?,
first_comment?, comment_delay_min?, story?, trial_reel?, fb_reel?,
ig_cover?, tiktok_privacy?, pinterest?: {board_id}, options?, overrides?, draft? }
options = per-network extras, all optional:
youtube {title, privacy, made_for_kids, synthetic_media, short, tags, category_id}
tiktok {allow_comments, allow_duet, allow_stitch, ai_generated, brand_organic, brand_content}
instagram {ai_generated, collaborators, trial_graduation, alt_text, comments_off} threads {reply_control}
POST /posts/batch { items: [...], stagger: {start, gap_minutes} } -> batch_id
PATCH /posts/{id} edit a scheduled post or draft (returns a new id)
GET /posts ?status=scheduled|posted|failed&include_results=1 (why it failed)
DELETE /posts/{id} cancel a scheduled post (?remove=1 also drops it from history)
GET /analytics/posts views, likes, comments, shares per post
POST /tools/mix { batches: [[url,...],[url,...]], count, color?, strength?, music?: [{url, volume?, from_batch?, to_batch?}] }
every output = one clip from EACH batch, in order (hooks x bodies x endings) -> many unique videos -> { job_id } (one job at a time)
POST /tools/split-screen { top_url, bottom_url, ratio? 20-80, top_volume?, bottom_volume?, *_start?, *_end? }
POST /tools/captions { media_url, captions?: [{text,start,end}], position_y?, size?, color?, outline_color?, font? }
no captions = the speech is transcribed automatically
GET /tools/jobs/{id} poll every 10-20 s until status is "done" -> outputs[].url are postable
Rules:
- Always call GET /accounts first. Never guess an account id.
- Media must be a URL that POST /uploads, POST /imports or GET /renders gave you.
- Photos and videos can't be mixed in one post.
- Times are UTC, like 2026-08-12T15:00:00Z, max 30 days ahead.
- Errors look like {"error":{"code","message"}} - read the code.
- If you get 429 daily_limit_reached, that account is full for the 24 hours before that time - suggest a later time. Don't retry.
- Never retry a failed POST /posts without checking GET /posts first.
Always show me the caption and the time and wait for my OK before posting.That last line matters: it tells the assistant to check with you before anything goes out. Keep it.
What to ask for
Once connected, talk to it normally. Some things that work well:
- "Show me everything I have scheduled this week."
- "Post this video to my TikTok and Instagram tomorrow at 6pm UTC."
- "Write three caption options for this clip, then schedule the one I pick."
- "What went out yesterday, and did anything fail?"
- "Cancel everything scheduled for Friday."
- "Spread these five clips across next week, one a day at 3pm."
- "How many of my posts passed 400 views this week? Give me the links."
- "Which videos have I not posted yet? Schedule the rest, one a day."
- "How many posts can I still make today on each account?"
- "Post this Google Drive link to Instagram as a Trial reel, with a first comment ten minutes later."
- "Why did yesterday's TikTok post fail?"
- "Move tomorrow's post to 6pm and change the caption."
- "Pin this to my Recipes board on Pinterest."
- "Post these six photos as one swipeable carousel on Instagram and Threads."
- "Read the comments on yesterday's reel and reply to everyone asking which app I use."
- "Any unread DMs on Instagram? Answer the ones I can still reply to."
- "Yesterday's post failed on Facebook — send it again."
- "From now on, always post my YouTube videos as unlisted and never allow Duets on TikTok."
- "Mix my three hooks and four bodies into 12 videos and post them to Instagram and TikTok, one every two hours."
- "Upload this to YouTube as unlisted, title it “3 edits that doubled my watch time”, tags: editing, shorts."
- "Post it on TikTok with Duet and Stitch off and the AI label on."
With the MCP server connected there are also ready-made commands — usage, status, post, post-remaining, performance, accounts, import, comments, inbox — see MCP server.
Two habits worth keeping. First, ask it to show you the caption and the time before posting — the setup text already tells it to, but saying so again never hurts. Second, if something looks wrong, check the Posts page in Postelk. That is always the truth.
When it does not work
| What you see | What it usually means |
|---|---|
| "This API key is not valid" | The key was pasted wrong, or you deleted it. Make a new one. |
| "This account is suspended" | Contact support — nothing will work until that's resolved. |
| "Your plan does not include posting" | The subscription lapsed. Reading still works; posting needs an active plan. |
| A daily limit message | That account already hit its 24-hour cap around that time. Pick a later time. |
| The assistant invents an account name | Tell it to call GET /accounts first and use the real ids. |
What you can and can't do
The API is deliberately narrower than the dashboard. It can do the everyday posting work and nothing that would let an automation dig you into a hole.
It can
- List the social accounts you already connected
- Upload a video or photo
- Import a video or image from a public Google Drive, Dropbox or direct link
- Publish right now, or schedule up to 30 days ahead — with everything the composer offers: first comment (and a delay), Stories, Instagram Reel covers and Trial reels, Facebook Reels, TikTok privacy, Pinterest boards, a different caption per platform, and the per-post options (YouTube title, visibility and tags, TikTok comments / Duet / Stitch, AI labels, collaborators)
- Post several images as one swipeable carousel
- Save default post settings once (“always unlisted”, “no Duets”) so every later post follows them
- Run the video tools: Repurposer (mix batches of clips into many unique videos), Split screen and captions — then post the results
- Queue many posts at once, spaced out
- Show you what is scheduled, published or failed — why it failed, and whether retrying will help
- Edit or cancel something that has not gone out yet; save drafts
- Tell you how many posts each account can still make in its 24-hour window
- List the videos you made with the editing tools, and which ones you have not posted yet
- Read your post and account analytics, and your saved captions
It cannot
- Connect or remove social accounts — that stays in the dashboard, on purpose
- Get around your account limit: on a 5-account plan you have 5 accounts, whether you post by hand or by API
- Exceed your rolling 24-hour posting caps — they are shared with the dashboard
- Delete a post that is already live on the platform
- Change your plan, billing or password
- Create videos — rendering stays in the app
About the limits
There is no separate API quota. If your plan lets you connect five accounts and TikTok allows ten posts per rolling 24 hours, that is ten TikTok posts per 24 hours in total — not ten in the app plus ten more through the API. An automation that goes haywire runs into exactly the same wall you would.
The cap is a rolling 24-hour window ending at the moment the post is for, not a calendar day. Scheduling next Tuesday counts against the 24 hours before that Tuesday slot.
API access is included on every paid plan, posting-only plans included. There is no developer tier and no extra charge.
Everything below is for people building something themselves. If you only wanted to connect an assistant, you are already done.
Introduction
The API is REST over HTTPS. Requests and responses are JSON, except POST /uploads, which takes multipart/form-data. There are no SDKs to install — every example here is plain curl.
Three things are worth knowing before you start:
- The API is not a second system. It runs the same publishing path as the dashboard, so daily caps, ownership checks, duplicate protection and account suspension behave identically whichever surface you use.
- Account ids come from us. Always call
GET /accountsfirst. Ids are stable per connected account and are never shared between users. - Media must be hosted by us. Upload through
POST /uploads, import a public link withPOST /imports, or use aGET /rendersURL. Arbitrary URLs are rejected at posting time.
Video creation (Repurposer, split screen, captions) runs on a limited render queue: one job at a time per account through POST /tools/*, with the same hourly limits as the site. You can also read the videos you already made with GET /renders and post them.
Authentication
Every request carries a bearer key:
Authorization: Bearer ugcd_live_7Kq2xR9mVb4TzL1nWpH8sYeACreate keys in Settings → API. A key is ugcd_live_ followed by 32 URL-safe characters.
Keys can carry an expiry date (30/90/180/365 days, or none) and a subset of permissions. You can hold up to 10 active keys; revoke one to make room.
Revocation takes effect within 60 seconds — verification results are cached that long to keep request latency low.
., it is a session token and returns 401 unauthorized.Permissions
Each key carries a set of scopes. An endpoint returns 403 insufficient_scope — including a required_scope field — when the key is missing the one it needs. Scopes cannot be edited after creation; make a new key instead.
| Scope | What it allows | Used by |
|---|---|---|
posts:read | Read posts, results, analytics, saved captions and comments. | GET /posts, GET /posts/{id}, GET /posts/batch/{id}, GET /analytics/*, GET /captions, GET /posts/{id}/comments |
posts:write | Create, edit and cancel posts; save captions; answer, like, hide and delete comments; retry a failed post. | POST /posts, POST /posts/batch, PATCH /posts/{id}, DELETE /posts/{id}, POST/DELETE /captions, POST /posts/{id}/comments/{cid}/reply|like|hide, POST /posts/{id}/retry |
accounts:read | Read connected accounts, usage and Pinterest boards. | GET /accounts, GET /usage, GET /pinterest/boards |
renders:read | Read videos you created or imported in Postelk. | GET /renders |
uploads:write | Upload or import media for posting. | POST /uploads, POST /uploads/ticket, POST /uploads/confirm, POST /imports |
tools:write | Run the video tools — Repurposer, Split screen, captions. Uses the same hourly limits as the site. Keys and apps created before this permission existed do not have it. | POST /tools/mix, /tools/split-screen, /tools/captions |
inbox:read | Read the Instagram DM and Messenger inbox of accounts connected through Postelk's own connection. Deliberately separate from posts:read: a posting key never sees private messages. Keys and apps created before this permission existed do not have it. | GET /inbox, GET /inbox/{peer} |
inbox:write | Answer conversations, mark them read and send a private reply to a commenter — always inside Meta's reply windows. Keys and apps created before this permission existed do not have it. | POST /inbox/{peer}, POST /inbox/{peer}/read, POST /posts/{id}/comments/{cid}/message |
Give integrations the narrowest set that works. A read-only reporting script has no reason to hold posts:write.
Errors
Every error — without exception — has the same shape, so you only ever parse one structure:
{
"error": {
"code": "daily_limit_reached",
"message": "Posting limit reached for one account (Tiktok: 10/10 in the 24 hours before that time). Pick a later time or fewer posts.",
"docs": "https://postelk.com/docs/api",
"platform": "tiktok",
"account_id": "acct_9f2a…",
"daily_limit": 10
}
}Branch on error.code, never on error.message — messages are written for humans and may be reworded. Some codes add extra fields, listed below.
Status families: 401 means the key is the problem. 403 means the key is fine but the account or permission is not. 429 means slow down. 5xx means the problem is ours.
| Code | HTTP | What happened | What to do |
|---|---|---|---|
unauthorized | 401 | No key, or the header was malformed. | Send Authorization: Bearer ugcd_live_…. Session JWTs are rejected on purpose. |
invalid_key | 401 | The key does not exist. | Check for a copy/paste error, or generate a new key. |
key_revoked | 401 | The key was revoked in the dashboard. | Generate a new key. Revocation takes effect within 60 seconds. |
key_expired | 401 | The key passed its expiry date. | Generate a new key. Keys can also be created with no expiry. |
account_suspended | 403 | The Postelk account is suspended. | Contact support. No endpoint works while suspended. |
subscription_required | 403 | The plan does not include posting. | Read endpoints keep working. Upgrade to post. |
insufficient_scope | 403 | The key lacks the permission this endpoint needs. | The response includes required_scope. Create a key with that permission. |
forbidden | 403 | The account is not connected to your profile. | Re-read GET /accounts; ids are not portable between users. |
account_not_found | 404 | One or more account ids are unknown. | The response lists the offending ids in account_ids. |
not_found | 404 | No post with that id. | Post ids are UUIDs returned by POST /posts. |
already_published | 409 | The post is already live. | Published posts cannot be cancelled through the API — remove them on the platform. |
too_many_keys | 409 | You already have 10 active keys. | Revoke one first. This applies to the dashboard, not to API calls. |
file_too_large | 413 | Upload exceeded the limit (95 MB on POST /uploads, 2 GB with an upload ticket). | Use an upload ticket for big files, or compress. |
storage_full | 413 | Workspace storage is full. | Delete old videos in Created videos, then retry. |
not_uploaded | 404 | Confirm was called before the PUT finished. | Finish the PUT, then confirm. |
unsupported_media | 415 | File type not accepted. | mp4, mov, webm, jpg, png, webp. |
rate_limited | 429 | Too many API requests for this key. | 60 requests/minute and 600/hour per key. Back off and retry. |
daily_limit_reached | 429 | That account hit its cap for the 24 hours before the target time. | The response carries platform, account_id and daily_limit. Schedule a later time. |
free_monthly_limit_reached | 429 | The Free plan's 250-posts-per-month cap is used up. | The response carries count and limit. The counter resets on the 1st (UTC) — or upgrade for unlimited posting. |
free_queue_full | 429 | The Free plan allows 10 scheduled posts waiting at a time. | Wait for queued posts to publish (slots free up automatically) or upgrade. |
account_locked | 403 | This connected account is beyond your plan's account limit (after a downgrade the most recently connected accounts stay active, older ones are locked). | Upgrade to unlock it, or disconnect another account in Connections so this one becomes active. |
bad_request | 400 | Something in the body is missing or malformed. | The message names the field. Nothing was created. |
media_required | 400 | Instagram, TikTok, YouTube and Pinterest need a photo or video. | Attach media, or drop those accounts from the post. |
pinterest_board_required | 400 | A Pinterest account was targeted without a board. | Pass pinterest.board_id — list boards with GET /pinterest/boards. |
caption_too_long | 400 | The caption (or first comment) is over a platform's limit. | The message says which platform and by how much. Shorten it, or give that platform its own caption in overrides. |
content_refused | 400 | The caption, first comment or a network title contains content Postelk does not publish (sexual content involving minors, explicit sexual content, threats or calls for violence, weapons or terrorism, other illegal activity, hate). | Nothing was created. The same rule applies on the site and to Elk. Refused requests are logged. |
too_many_media | 400 | A multi-image post has more images than one of the targeted networks takes (Pinterest 5, Bluesky 4). | Remove some images, or post to that network separately. Nothing was created. |
media_unavailable | 400 | A media file is gone from storage (deleted or expired) or is empty (0 bytes). | The message says which item. Upload it again and retry — nothing was created and no slot was used. |
not_queued | 502 | The publishing service saved the post but could not queue it, so nothing will go out. | Postelk already removed the stored copy and returned the slots — simply create the post again. |
account_needs_reconnect | 403 | A targeted account's connection is broken. | Reconnect it in Postelk → Connections, then retry. GET /accounts shows needs_reconnect. |
not_editable | 409 | Only scheduled posts and drafts can be edited. | Create a new post instead. |
editing_locked | 403 | The plan does not include this tool. Free has no video tools; the Posting plans (individual or Team) include captions (the Video editor) but not mix_videos or split_screen. | Captions work on every paid plan. The Repurposer (mix_videos) and Split screen are only available on existing Editing + Repurposing subscriptions, which are no longer sold (since November 15, 2026). Make those videos elsewhere and upload them. |
media_not_found | 404 | media_url is not one of your Postelk videos. | Take the URL from GET /renders, or bring an outside link in with POST /imports first. |
render_busy | 429 | A video job you started through the API is still running. | Jobs run one at a time per account. The response carries its job_id — wait for it with GET /tools/jobs/{id}. |
tool_quota_reached | 429 | The hourly video limit for this tool is used up (shared with the site). | The response carries retry_after in seconds. |
server_busy | 429 | All render slots are taken right now. | Wait a minute and retry. |
unsupported_provider | 400 | The post was published through the previous provider, which has no comment or inbox access. | Only posts published through Postelk's own connections (Instagram, Facebook Pages, Threads) have comments and messages. Nothing to retry. |
bad_account | 404 | account is not one of your Postelk-connected accounts. | Use an account id from GET /accounts whose connection is Postelk's own — accounts connected through the previous provider have no comment or inbox access. |
not_published | 409 | The post has not gone out on that account yet. | Comments exist only after publishing — GET /posts/{id} shows the per-account status. |
unsupported | 400 | That network does not allow the action through its API. | The message names it: liking comments on Instagram or Threads, deleting on Threads, messaging on Threads. |
token_missing | 409 | The account has to be reconnected. | Reconnect it in Postelk → Connections, then retry. |
token_expired | 409 | The account's connection expired or was revoked. | Reconnect it in Postelk → Connections, then retry. |
permission | 409 | Meta refused the action because a permission is missing. | Accounts connected before comments and messages existed must be reconnected in Connections to grant the new permission. |
window_closed | 409 | Meta's time window has passed. | Private replies: within 7 days of the comment. Messages: only while the person wrote to you in the last 24 hours. Wait for their next message, or answer one of their comments. |
already_sent | 409 | A private reply was already sent for this comment. | Meta allows one private reply per comment. If the person answered, continue in the inbox. |
empty | 400 | The reply or message has no text. | Send text. |
too_long | 400 | The reply or message is over the network's limit. | Replies: Instagram 2,200 characters, Facebook 8,000, Threads 500. Messages: Instagram 1,000, Facebook 2,000. The response carries limit. |
provider_error | 502 | Meta returned an error Postelk could not translate. | The message carries Meta's text. Check the account in Connections before retrying. |
unavailable | 503 | Meta did not answer in time, or the feature is not set up on the server yet. | Retry in a moment. |
not_failed | 409 | The post is not in a failed state, so there is nothing to retry. | Only posts that failed on at least one account can be retried. |
nothing_to_retry | 409 | Every account on the post is already live. | Nothing to do — the post went out everywhere it was meant to. |
delete_on_platform | 409 | The post went out through Postelk's own connection and is live, so removing only the Postelk record is no longer possible: deleting it also removes it from the networks. | Delete it from the post page in Postelk, which removes it from the networks and from your history. Nothing was changed by this call. |
storage_full | 507 | Your render storage is full. | Delete saved videos in Created videos, then retry. |
import_failed | 422 | The link could not be downloaded. | Share the file publicly (Google Drive: Anyone with the link) or use a direct file link. |
publish_failed | 502 | The post could not be created downstream. | It may or may not exist — call GET /posts before retrying. |
cancel_failed | 502 | The cancellation did not go through. | The post is still scheduled. Retry; do not assume it was cancelled. |
service_unavailable | 503 | We could not reach our own storage. | Your key is fine. Retry after a few seconds. |
POST /posts. On 502 publish_failed the post may or may not have been created. Call GET /posts and look for it before sending again. We also apply a 30-minute duplicate guard on identical requests — if it catches yours you get 200 with "duplicate_skipped": true, and nothing is posted twice.Rate limits & caps
Request rate — per key
Two rolling windows, applied per API key:
| Window | Limit |
|---|---|
| 1 minute | 60 requests |
| 1 hour | 600 requests |
Exceeding either returns 429 rate_limited. This is a brake against runaway loops, not a posting quota.
Publishing caps — per connected account
The real posting limit is per account, per calendar day (UTC), and it is shared with the dashboard. Scheduling a post reserves a slot on its target day, not on the day you called the API.
| Platform | 24-hour cap |
|---|---|
| 50 per account per rolling 24 hours | |
| TikTok | 10 per account per rolling 24 hours |
| YouTube | 5 per account per rolling 24 hours |
| 50 per account per rolling 24 hours | |
| Threads | 250 per account per rolling 24 hours |
| 50 per account per rolling 24 hours | |
| 50 per account per rolling 24 hours | |
| Bluesky | 50 per account per rolling 24 hours |
Hitting a cap returns 429 daily_limit_reached with the platform and the number. Cancelling a scheduled post returns its slot; a post that fails on the network for a fixable reason (expired token, rejected media) also returns its slot.
Other ceilings
| Thing | Limit |
|---|---|
| Accounts per post | 20 |
| Media items per post | 10 |
| Upload size | 95 MB per POST /uploads request · up to 2 GB with an upload ticket |
| Scheduling horizon | 30 days ahead |
| Active API keys | 10 |
Posts per page (GET /posts) | 100 |
Get current account
/meConfirms a key works and reports what it is attached to. Useful as a health check in CI or after rotating keys. No scope required — any valid key can call it.
curl https://postelk.com/api/v1/me \
-H "Authorization: Bearer $POSTELK_KEY"Response
{
"user_id": "3f1c…",
"plan": "post_pro",
"subscription_status": "active",
"scopes": ["posts:read", "posts:write", "accounts:read", "renders:read", "uploads:write", "tools:write", "inbox:read", "inbox:write"]
}List connected accounts
/accountsrequires accounts:readReturns every social account connected to your profile. The id values are what you pass to POST /posts.
curl https://postelk.com/api/v1/accounts \
-H "Authorization: Bearer $POSTELK_KEY"Response
{
"accounts": [
{
"id": "acct_9f2a4b…",
"platform": "tiktok",
"username": "yourhandle",
"display_name": "Your Handle",
"active": true,
"connected_at": "2026-05-14T08:21:00Z",
"locked": false
}
]
}| Field | Type | Notes |
|---|---|---|
id | string | Pass this in accounts when creating a post. |
platform | string | instagram · tiktok · youtube · facebook · threads · linkedin · pinterest · bluesky |
username | string | Handle on the platform. |
display_name | string | Profile name, may be null. |
active | boolean | False usually means the connection needs re-authorising in the dashboard. |
connected_at | timestamp | When the account was linked. |
locked | boolean | true when the account is beyond your plan's connected-account limit (after a downgrade the most recently connected accounts stay active). Posting to a locked account returns account_locked. |
Cache this list — it changes only when you connect or remove an account. Never hard-code ids across users.
Upload media
/uploadsrequires uploads:writeUploads a file to our media storage and returns a URL you can post. This is the only way to get a postable media URL — arbitrary links are rejected for security.
curl -X POST https://postelk.com/api/v1/uploads \
-H "Authorization: Bearer $POSTELK_KEY" \
-F "file=@./clip.mp4"Response · 201
{
"url": "https://media.postelk.com/api-uploads/3f1c…/8a2b….mp4",
"bytes": 14238211,
"type": "video"
}| Rule | Value |
|---|---|
| Field name | file |
| Encoding | multipart/form-data |
| Max size | 95 MB — larger returns 413 file_too_large |
| Video types | video/mp4, video/quicktime, video/webm |
| Image types | image/jpeg, image/png, image/webp |
Anything else returns 415 unsupported_media. The returned URL does not expire — you can reuse it across several posts.
Large files: upload ticket
Files over 95 MB cannot go through POST /uploads — the proxy in front of the API caps a request body at 100 MB. Ask for an upload ticket instead and send the bytes straight to our storage. The confirmed URL is postable like any other.
1 · Ticket — POST /uploads/ticket (uploads:write)
curl -X POST https://postelk.com/api/v1/uploads/ticket \
-H "Authorization: Bearer $POSTELK_KEY" \
-H "Content-Type: application/json" \
-d '{ "ext": "mp4", "size": 734003200 }'Response · 201
{
"upload_url": "https://…r2.cloudflarestorage.com/…/api-uploads/3f1c…/8a2b….mp4?X-Amz-Signature=…",
"key": "api-uploads/3f1c…/8a2b….mp4",
"headers": { "Content-Type": "video/mp4" },
"expires_in": 900,
"max_bytes": 2147483648,
"type": "video"
}2 · Send the file — PUT upload_url (no Postelk key; the URL is signed)
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--data-binary @./clip.mp43 · Confirm — POST /uploads/confirm
curl -X POST https://postelk.com/api/v1/uploads/confirm \
-H "Authorization: Bearer $POSTELK_KEY" \
-H "Content-Type: application/json" \
-d '{ "key": "api-uploads/3f1c…/8a2b….mp4" }'Response · 201
{
"url": "https://media.postelk.com/api-uploads/3f1c…/8a2b….mp4",
"bytes": 734003200,
"type": "video"
}| Rule | Value |
|---|---|
ext | mp4, mov, webm, m4v, jpg, png, webp — anything else returns 415 unsupported_media |
size | the exact byte count of the file. The signature covers the size and the Content-Type: a different size or type is refused by storage with 403 SignatureDoesNotMatch |
| Ticket | valid for 15 minutes, one file, write-only (it cannot read, list or delete anything) |
| Max size | 2 GB per file on paid plans — larger returns 413 file_too_large |
| Storage | 100 GB per workspace — full returns 413 storage_full |
| Rate | 30 tickets a minute, 300 an hour — more returns 429 |
| Confirm | checks the stored object: empty, over the limit or not a video/image is deleted and returns 400 / 413 / 415; confirming before the PUT finished returns 404 not_uploaded |
Assistants and MCP clients cannot upload binaries themselves; they hand a public link to POST /imports or ask you to run these three calls.
Create a post
/postsrequires posts:writePublishes immediately, or schedules for later when you pass scheduled_at. One call can target several accounts across several platforms.
curl -X POST https://postelk.com/api/v1/posts \
-H "Authorization: Bearer $POSTELK_KEY" \
-H "Content-Type: application/json" \
-d '{
"accounts": ["acct_9f2a4b…", "acct_c71d0e…"],
"caption": "Three takes, one afternoon.",
"media": [{ "url": "https://media.postelk.com/api-uploads/…/clip.mp4", "type": "video" }],
"scheduled_at": "2026-08-12T15:00:00Z"
}'Body
| Field | Type | Required | Notes |
|---|---|---|---|
accounts | string[] | yes | Account ids from GET /accounts. Max 20. Objects with an id key are also accepted. |
caption | string | one of | Post text. text is accepted as an alias. On YouTube it is the video description; the title comes from options.youtube.title, else from the caption's first line. |
media | object[] | one of | Objects with url and type (video or image). A bare string is treated as a video URL. 2–10 images = one swipeable post (a carousel), shown in the order given — see Carousels. More than 10 returns 400 bad_request. |
scheduled_at | string | no | ISO-8601 UTC. Omit to publish now. Max 30 days ahead. |
first_comment | string | no | Posted as a reply by the same account right after the post. Not delivered on TikTok, Pinterest or YouTube. |
comment_delay_min | integer | no | Minutes after publishing to post the first comment (0–1440; default 0 = with the post). |
story | boolean | no | Publish as a Story — Instagram and/or Facebook only, exactly one image or video, no caption, no comment. |
ig_cover | object | no | Instagram Reel cover: {"offset_ms": 1500} picks a frame, {"url": "https://…jpg"} uses a JPEG hosted by Postelk. Single-video Reels only. |
trial_reel | boolean | no | Instagram: publish the single video as a Trial reel (shown to non-followers first; graduate it in the Instagram app). After Instagram rejects a trial reel on an account (follower requirement), Postelk keeps Trial reel off for that account for 7 days: trial_reel_blocked. |
fb_reel | boolean | no | Facebook: publish the single video as a Page Reel (3–90 s, 9:16) instead of a plain Page video. |
tiktok_privacy | string | no | PUBLIC_TO_EVERYONE (default) · MUTUAL_FOLLOW_FRIENDS · FOLLOWER_OF_CREATOR · SELF_ONLY. |
pinterest | object | when Pinterest is targeted | board_id (required — see boards), optional title ≤100, link (https), alt_text ≤500. |
options | object | no | Optional per-network settings — the gear icon on each post in the composer. See Per-network options. |
overrides | object | no | Per-platform differences keyed by platform: each value may set caption, first_comment, comment_delay_min, scheduled_at. A platform with an override becomes its own post (same media), exactly like the composer. |
draft | boolean | no | Save as a draft instead of publishing. Publish it later with PATCH /posts/{id}. |
use_defaults | boolean | no | Default true: your saved default post settings fill in anything this request does not set itself. false ignores them for this post. |
You must send caption, media, or both. A post with neither returns 400 bad_request. Instagram, TikTok, YouTube and Pinterest need media (400 media_required); a caption over a platform's limit — Threads 500, X 280, Bluesky 300, Pinterest 500, Instagram and TikTok 2,200, LinkedIn 3,000, YouTube 5,000 (there it is the video description) — returns 400 caption_too_long before anything is created. Captions, first comments and network titles also pass Postelk's content check: text that promotes something illegal or harmful (see content_refused below) is refused before anything is created, exactly as on the site.
Everything the composer offers
{
"accounts": ["acct_ig…", "acct_tt…", "acct_yt…"],
"caption": "Weekend batch is done — 12 clips, one afternoon.",
"media": [{ "url": "https://media.postelk.com/renders/…/video_001.mp4", "type": "video" }],
"scheduled_at": "2026-09-20T15:00:00Z",
"first_comment": "Full breakdown on the site — link in bio.",
"comment_delay_min": 10,
"trial_reel": true,
"tiktok_privacy": "PUBLIC_TO_EVERYONE",
"options": {
"youtube": { "title": "12 clips in one afternoon", "privacy": "unlisted", "tags": ["ugc", "editing"] },
"tiktok": { "allow_duet": false, "ai_generated": true },
"instagram": { "collaborators": ["maya.collins"] }
},
"overrides": {
"threads": { "caption": "12 clips, one afternoon. Thread below." }
}
}Here YouTube gets its own title and goes out unlisted, TikTok turns Duet off and carries the AI label, and Threads gets its own shorter caption — which makes Threads a separate post. The response then carries one entry per created post in posts; the top-level fields describe the first one.
Per-network options
Everything behind the gear icon on a post in the composer. All of it is optional: send only what you want to change, anything left out keeps the network's default, and settings for a network the post does not target are ignored. An unknown field or value returns 400 bad_request naming it.
| Field | Type | Notes |
|---|---|---|
options.youtube.title | string | Video title, ≤100. Default: the first line of the caption (cut at a word, 100 max). The caption itself is the description. |
options.youtube.privacy | string | public (default) · unlisted · private. |
options.youtube.made_for_kids | boolean | Declare the video as made for kids. |
options.youtube.synthetic_media | boolean | Disclose realistic altered or AI-generated content. |
options.youtube.short | boolean | Adds #shorts to the description. YouTube itself decides what is a Short (vertical or square, up to 3 minutes). |
options.youtube.tags | string[] | Up to 30 tags, 450 characters in total. |
options.youtube.category_id | string | YouTube category id. Default 22 People & Blogs; e.g. 24 Entertainment, 10 Music, 20 Gaming, 26 Howto & Style, 27 Education, 28 Science & Technology. |
options.tiktok.allow_comments · allow_duet · allow_stitch | boolean | Default true. Duet and Stitch apply to videos only. |
options.tiktok.ai_generated | boolean | Label the post as AI-generated. |
options.tiktok.brand_organic · brand_content | boolean | Disclosure labels: promotes your own brand · paid partnership. A paid partnership cannot be combined with tiktok_privacy: SELF_ONLY. |
options.tiktok.photo_title · auto_music | string · boolean | Photo posts only: title ≤90 (default: start of the caption) and TikTok's recommended music. |
options.instagram.ai_generated | boolean | Adds Instagram's “AI info” label. |
options.instagram.collaborators | string[] | Up to 3 public usernames invited as collaborators (feed posts and Reels, not Stories). |
options.instagram.trial_graduation | string | With trial_reel: manual (default) or performance — Instagram shares the reel with followers on its own if it does well. |
options.instagram.alt_text | string | Image posts: alt text, ≤1,000. |
options.instagram.comments_off | boolean | Turns commenting off right after the post is published — Instagram has no setting at creation time, so Postelk applies it immediately after. Postelk's own Instagram connection only (accounts on the previous provider get 400); not for Stories. |
options.threads.reply_control | string | everyone (default) · accounts_you_follow · mentioned_only · followers_only · parent_post_author_only. The last two need Postelk's own Threads connection. Cannot be changed after publishing. |
Carousels — several images, one post
Send 2–10 images in media and they become one swipeable post, in the order you list them; the first image is the cover. One post means one caption, one schedule time and one slot per account — not ten. In the composer this is the Combine into one swipeable post action on the Media step. To publish the images as separate posts instead, make one request per image (or use POST /posts/batch).
curl -X POST https://postelk.com/api/v1/posts \
-H "Authorization: Bearer $POSTELK_KEY" -H "Content-Type: application/json" \
-d '{
"accounts": ["acct_9f2a4b…", "acct_c71d0e…"],
"caption": "Six looks for autumn — swipe and tell me your favourite",
"media": [
{"url": "https://media.postelk.com/api-uploads/…/look-1.jpg", "type": "image"},
{"url": "https://media.postelk.com/api-uploads/…/look-2.jpg", "type": "image"},
{"url": "https://media.postelk.com/api-uploads/…/look-3.jpg", "type": "image"}
],
"scheduled_at": "2026-10-02T17:00:00Z"
}'| Network | Images per post | Notes |
|---|---|---|
| 2–10 | Every slide is cropped to the first image's shape. | |
| Facebook · Threads · LinkedIn · TikTok | up to 10 | TikTok shows them as a photo post. |
| up to 5 | More returns 400 too_many_media. | |
| Bluesky | up to 4 | More returns 400 too_many_media. |
| YouTube · Stories | — | Single video / single item only. |
Photos and videos cannot be mixed in one post. Editing a scheduled carousel with PATCH /posts/{id} keeps all of its images unless you send a new media list.
Response · 201
{
"id": "8c31d0e2-…",
"post_id": "ost_51ba…",
"status": "scheduled",
"scheduled_at": "2026-08-12T15:00:00Z",
"accounts": [
{ "platform": "tiktok", "username": "yourhandle", "status": "pending", "error": null }
]
}| Field | Notes |
|---|---|
id | Postelk post id — use it for GET and DELETE /posts/{id}. |
post_id | Upstream scheduling id. Informational. |
status | scheduled, posted or failed. |
accounts | Per-account outcome. For immediate posts this is the real publish result. A failed entry carries the raw error, a plain-English why and a next_step — whether retrying helps and what to fix first. |
warning · dropped_accounts | Present only when the publishing service could not find one of the targeted accounts: the post was created for the others, the missing account's slot was returned, and warning says which network to reconnect. |
applied_defaults | Present when saved default post settings filled something in — e.g. ["youtube.privacy", "tiktok.allow_duet"]. |
accounts array — entries with status: "failed" carry an error string. The failed account's slot is returned automatically.Field names and types are checked
Field names are exact and snake_case. A misspelled field — scheduledAt, first-comment, Caption — returns 400 bad_request with the right name instead of being ignored, so a typo can never turn a scheduled post into one that publishes now. Booleans must be JSON true / false (the strings "true" and "false" are read as what they say; anything else is a 400), text fields must be strings, media may be a single item or a list, and stagger must be an object. Through the MCP server every unknown field is rejected the same way, with a “did you mean” hint.
Checked before anything is created
Every media file is looked up in storage first. A file that was deleted, has expired or is empty returns 400 media_unavailable naming the item — no post is created and no slot is used. If our own lookup cannot reach storage, the post goes ahead (we never block on our own hiccup).
Duplicate protection
Identical requests (same media, text, minute and accounts) inside a 30-minute window are collapsed. The second call returns 200:
{
"duplicate_skipped": true,
"id": null,
"post_id": null,
"status": "skipped",
"message": "An identical post was already created moments ago."
}This is a safety net for timeouts and retries — treat it as success, not as an error.
List posts
/postsrequires posts:readcurl "https://postelk.com/api/v1/posts?status=scheduled&limit=50" \
-H "Authorization: Bearer $POSTELK_KEY"| Query | Default | Notes |
|---|---|---|
status | all | scheduled · posted · failed · cancelled · draft |
from / to | — | ISO-8601 (UTC) bounds on the scheduled time. |
platform | — | instagram · tiktok · youtube · facebook · threads · linkedin · pinterest · bluesky · x |
account_id | — | Only posts that target this account. |
query | — | Search the caption text — every word must appear (case-insensitive), like the search box on the Posts page. |
include_results | 0 | 1 adds results (per-account status, raw error, a plain-English why and a next_step), plus top-level why, next_step and urls to every post. |
limit | 50 | 1–100. |
offset | 0 | For paging. |
Response
{
"posts": [
{
"id": "8c31d0e2-…",
"caption": "Three takes, one afternoon.",
"video_url": "https://media.postelk.com/…/clip.mp4",
"platforms": ["instagram", "tiktok"],
"channel_ids": ["acct_9f2a4b…", "acct_c71d0e…"],
"scheduled_at": "2026-08-12T15:00:00Z",
"status": "scheduled",
"outstand_post_id": "ost_51ba…",
"created_at": "2026-08-07T09:12:44Z"
}
],
"limit": 50,
"offset": 0,
"has_more": false
}Sorted newest first by scheduled time, falling back to creation time. Page until has_more is false.
Get one post
/posts/{id}requires posts:readcurl https://postelk.com/api/v1/posts/8c31d0e2-… \
-H "Authorization: Bearer $POSTELK_KEY"Returns the same object as the list endpoint, always with the per-account outcome: results (status, the raw platform error and a plain-English why), why (the first failure reason) and urls (public links once published). Unknown ids return 404 not_found; ids that are not UUIDs return 400 bad_request. You can only read your own posts.
{
"id": "8c31d0e2-…", "status": "failed", "platforms": ["tiktok"],
"results": [
{ "platform": "tiktok", "username": "lena.creates", "status": "failed",
"error": "privacy_level_option_mismatch",
"why": "TikTok doesn't allow that “Who can view” option on this account — pick another one and post again.", "url": null }
],
"why": "TikTok doesn't allow that “Who can view” option on this account — pick another one and post again.",
"urls": []
}Cancel a scheduled post
/posts/{id}requires posts:writecurl -X DELETE https://postelk.com/api/v1/posts/8c31d0e2-… \
-H "Authorization: Bearer $POSTELK_KEY"Response
{ "id": "8c31d0e2-…", "status": "cancelled" }Cancels the post upstream first, then marks it cancelled and returns the slot. If the upstream cancellation fails you get 502 cancel_failed and the post stays scheduled — deliberately, so a failed cancel never leaves a post that goes out while your records say it will not.
409 already_published. The content is already on the platform; remove it there.Add ?remove=1 to also drop the record from your Postelk history — for a scheduled post that means cancel first, then remove; for a posted, failed, cancelled or draft post it just removes the record (status removed). Nothing is ever deleted on the platform itself.
Edit a scheduled post or draft
/posts/{id}requires posts:writeChange any field of a scheduled post or a draft — accounts, caption, media, time, comment, overrides, all of it. Send only the fields you want to change; the rest is kept.
curl -X PATCH https://postelk.com/api/v1/posts/8c31d0e2-… \
-H "Authorization: Bearer $POSTELK_KEY" \
-H "Content-Type: application/json" \
-d '{ "scheduled_at": "2026-09-21T18:00:00Z", "caption": "New caption" }'Like the edit dialog in the app, this releases the old version at the scheduling provider and creates a new one, so the post gets a new id (returned as id; the old one is replaced_id). A draft stays a draft when you edit it — changing its caption never publishes it. To publish a draft, PATCH it with "draft": false and the wanted scheduled_at (or none to post now). Published posts return 409 already_published; cancelled or failed ones 409 not_editable.
Create many posts
/posts/batchrequires posts:writeQueue up to 60 posts in one call. Each item takes the same fields as POST /posts; accounts at the top level is the default for items without their own, and stagger spaces them out: item i is scheduled at start + i × gap_minutes unless it sets its own scheduled_at.
{
"accounts": ["acct_ig…", "acct_tt…"],
"stagger": { "start": "2026-09-22T09:00:00Z", "gap_minutes": 120 },
"items": [
{ "caption": "Clip 1", "media": [{ "url": "https://media.postelk.com/renders/…/video_001.mp4" }] },
{ "caption": "Clip 2", "media": [{ "url": "https://media.postelk.com/renders/…/video_002.mp4" }] },
{ "caption": "Clip 3", "media": [{ "url": "https://media.postelk.com/renders/…/video_003.mp4" }] }
]
}Response · 202
{ "ok": true, "batch_id": "3f9a1c7e2b4d", "total": 3, "status_url": "/api/v1/posts/batch/3f9a1c7e2b4d" }Posts are created in the background, one after another. Poll GET /posts/batch/{batch_id} until finished is true; each result carries the created posts or an error and a plain-English why. If validation fails for any item, nothing is queued and the error names the item (index).
Usage and limits
/usagerequires accounts:readYour plan, the connected-account limit, and for every account how many posts were used and are left in the rolling 24-hour window ending now, plus queued posts. Free plans also get the monthly (250) and queue (10) counters. Paid plans also get elk: how many Elk AI assistant commands were used this month and the monthly cap for the plan (3,000 on Starter; on Growth / Pro / Agency one shared team pool of 10,000 / 20,000 / 30,000, and shared: true; earlier plans keep the caps they had).
{
"plan": "pro",
"account_limit": 8,
"accounts": [
{ "id": "acct_ig…", "platform": "instagram", "username": "maya.collins",
"limit_24h": 50, "used_24h": 3, "remaining_24h": 47, "queued": 4,
"needs_reconnect": false, "locked": false }
],
"free": null,
"elk": { "commands_used": 412, "monthly_limit": 3000, "month": "2026-09-01" },
"api_rate_limit": { "per_minute": 60, "per_hour": 600 }
}remaining_24h is the answer to "how many more can I post today". A post scheduled for later counts in the 24 hours before its own time, so the window for a future slot can differ.
Import from a link
/importsrequires uploads:writeDownload a public file into Postelk so it can be posted: a Google Drive share link (Anyone with the link), a Dropbox share link, or any direct https link to an mp4, mov, webm, jpg, png or webp up to 95 MB. This is how assistants get a file in — they cannot upload binaries, but they can hand over a link.
curl -X POST https://postelk.com/api/v1/imports \
-H "Authorization: Bearer $POSTELK_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://drive.google.com/file/d/1AbC…/view?usp=sharing" }'Response · 201
{
"url": "https://media.postelk.com/renders/…/output.mp4",
"type": "video",
"bytes": 18422011,
"job": "9f1c…", "file": "output.mp4",
"source": "https://drive.google.com/file/d/1AbC…/view?usp=sharing"
}The file also appears in GET /renders, so it takes part in the used / ?unused=1 bookkeeping. A link that returns a web page instead of a file (a private Drive file, for example) returns 422 import_failed with the fix.
Saved captions
/captionsrequires posts:readYour saved caption library — the same list the composer's Auto captions uses. Add one with POST /captions (text, optional group; scope posts:write) and remove one with DELETE /captions/{id}.
Default post settings
/post-defaultsrequires posts:readRules you set once and that then apply to every new post — “YouTube always unlisted”, “never allow Duets”, “label everything as AI”. They are the Post settings page in the app (Settings → Post settings) and work the same everywhere: the composer starts each post with them, and POST /posts, POST /posts/batch and the MCP tools fill in anything a request does not set itself. A request always wins over a rule — even when it sets the network default — and use_defaults: false ignores the rules for one post. The response of a create call lists what was filled in under applied_defaults.
# set once
curl -X PATCH https://postelk.com/api/v1/post-defaults \
-H "Authorization: Bearer $POSTELK_KEY" -H "Content-Type: application/json" \
-d '{"defaults": {"youtube": {"privacy": "unlisted"}, "tiktok": {"allow_duet": false, "ai_generated": true}}}'
# from now on every post uses them; one post can still say otherwise
# "options": {"youtube": {"privacy": "public"}} or "use_defaults": false| Call | Scope | What it does |
|---|---|---|
GET /post-defaults | posts:read | Your rules as defaults, a plain-English summary, and the allowed fields per network. |
PATCH /post-defaults | posts:write | Merge by network: only the fields you send change. A field set to null is removed, a network set to null is cleared. |
PUT /post-defaults | posts:write | Replace all rules with the body ({} clears everything). |
| Network | Fields |
|---|---|
instagram | ai_generated, collaborators, trial_reel, trial_graduation (with trial_reel) |
tiktok | privacy (the four tiktok_privacy values), allow_comments, allow_duet, allow_stitch, ai_generated, brand_organic, brand_content, auto_music |
youtube | privacy, made_for_kids, synthetic_media, short, tags, category_id |
facebook | reel — publish single videos as Reels |
threads | reply_control |
pinterest | link — destination link for every pin |
Values follow the same rules as per-network options. Things that belong to one post — a YouTube title, alt text, a Pinterest board — cannot be defaults and return 400 bad_request. Only values that differ from the network default are stored, so setting a field back to its default removes the rule.
Pinterest boards
/pinterest/boards?account_id=…requires accounts:readPinterest needs a board for every pin. List the boards of a connected Pinterest account and pass the chosen id as pinterest.board_id when creating the post.
{ "account_id": "acct_pi…", "boards": [ { "id": "1120…", "name": "Reels & clips", "privacy": "PUBLIC" } ] }List your created videos
/rendersrequires renders:readReturns videos you produced with the Postelk editing tools, grouped by render job. Their URLs are postable directly.
curl "https://postelk.com/api/v1/renders?limit=20" \
-H "Authorization: Bearer $POSTELK_KEY"Response
{
"renders": [
{
"id": "b41e77c2…",
"count": 12,
"created": 1786134000,
"files": [
{ "name": "video_001.mp4", "url": "https://media.postelk.com/renders/…/video_001.mp4", "size": 8241905,
"used": null, "scheduled": false, "label": "Beach intro" }
]
}
]
}limit accepts 1–200 (default 50). created is a Unix timestamp. Renders are not stored forever — download or post what you need. Every file carries used: posted, scheduled or null, and scheduled: true while the file sits in a post that has not gone out yet (deleting such a file makes that post fail); add ?unused=1 to get only the files that have not been posted or scheduled yet. A file you renamed in Created videos also carries label — the display name only; name and url never change.
Post performance
/analytics/postsrequires posts:readViews, likes, comments and shares for your published posts, newest window first, with a direct link to each post. Answers questions like "which posts passed 400 views this week".
curl "https://postelk.com/api/v1/analytics/posts?days=7&min_views=400&sort=views" \
-H "Authorization: Bearer ugcd_live_…"Response
{
"days": 7,
"since": "2026-09-08",
"summary": { "posts": 14, "matching": 6, "below_min_views": 8, "total_views": 18240, "metrics_pending": 1, "min_views": 400, "platform": null },
"posts": [
{
"id": "8c31d0e2-…",
"platform": "instagram",
"account": "maya.collins",
"caption": "Weekend batch is done ✅ 12 clips, one afternoon…",
"published_at": "2026-09-13T15:00:12Z",
"views": 5120, "likes": 210, "comments": 14, "shares": 9,
"url": "https://www.instagram.com/reel/DAbCdEfGhIj/",
"metrics_updated_at": "2026-09-14T09:10:03Z"
}
]
}Query: days 1–90 (default 7, by publish day, UTC), min_views, max_views, query (caption search), platform (instagram, tiktok, youtube, facebook, threads, linkedin, pinterest, bluesky, x), sort (views, likes, comments, newest, fewest_views), limit 1–200. Numbers are refreshed in the background every few hours; metrics_updated_at is null while a post waits for its first refresh. Views are not reported by every network — X and some Facebook posts return likes and comments only.
Account analytics
/analytics/summary?days=30requires posts:readThe top of the Analytics page as JSON: totals for views, likes, comments and shares in the window, the change against the previous window, engagement rate, followers, and a per-account breakdown. days is 1–90 (default 30). TikTok, YouTube and Bluesky report lifetime snapshots rather than date ranges (listed under snapshot); X is skipped.
“No data” is not zero. When a platform does not report a metric (Meta retired several in June 2026, Stories have no likes, a disconnected account reports nothing) the number is unknown, not 0. Each account row lists those metrics in no_data, and totals_no_data names the metrics that no account could report — show them as “—” rather than 0.
Comments
/posts/{id}/comments?account=…requires posts:readThe comments under one of your published posts, the way the post page in Postelk shows them: top-level comments newest first, replies nested under each one, like counts, who wrote what, which comments you hid, and for every commenter whether you can still send a private message. Available for posts published through Postelk's own connections — Instagram, Facebook Pages and Threads. A post that went out through the previous provider returns 400 unsupported_provider.
curl "https://postelk.com/api/v1/posts/8c31d0e2-…/comments?account=instagram:17841400000000000" \
-H "Authorization: Bearer ugcd_live_…"Response
{
"account": "instagram:17841400000000000",
"platform": "instagram",
"username": "maya.collins",
"platform_post_id": "17895695668004550",
"caps": { "reply": true, "like": false, "hide": true, "delete": true, "dm": true, "inbox": true },
"total": 9,
"next": "QVFIUlpX…",
"dm_window_days": 7,
"comments": [
{
"id": "17851234567890123",
"text": "This is exactly the hook I needed 🙌",
"username": "dana.k",
"user_id": "17841401234567890",
"avatar": null,
"created_at": "2026-10-19T14:02:11+00:00",
"like_count": 12,
"reply_count": 1,
"hidden": false,
"is_mine": false,
"liked": null,
"can_dm": true,
"dm": { "can": true, "sent": false, "sent_at": null, "deadline": "2026-10-26T14:02:11+00:00" },
"replies": [
{
"id": "17860000000000001",
"text": "Glad it helped — more on Friday",
"username": "maya.collins",
"is_mine": true,
"like_count": 4,
"hidden": false,
"created_at": "2026-10-19T15:10:40+00:00",
"dm": { "can": false, "sent": false, "sent_at": null, "deadline": "2026-10-26T15:10:40+00:00" }
}
]
}
]
}| Field | Notes |
|---|---|
account | Required query parameter: an account id from GET /accounts that is part of the post. One network per call. |
caps | What this network allows: reply, like (Facebook Pages only), hide, delete (not on Threads), dm and inbox (Instagram and Facebook). |
comments[].dm | can — a private reply is still possible: within dm_window_days of the comment, once per comment, never to your own comment. sent and sent_at once you used it; deadline is when the window closes. |
comments[].liked | true or false on Facebook Pages (whether your Page liked it); null where the network does not say. |
comments[].hidden · is_mine | Hidden comments stay in the list, marked. is_mine is a reply written by your account. |
next | Pass it back as ?after= for the next page; null on the last page. |
Reading is limited to 90 calls a minute and 1,500 an hour per user; the actions below to 15 a minute and 120 an hour. These are Postelk's limits, shared with the site — Meta applies its own on top.
Reply, like, hide, delete
/posts/{id}/comments/{cid}/replyrequires posts:write/posts/{id}/comments/{cid}/likerequires posts:write/posts/{id}/comments/{cid}/hiderequires posts:write/posts/{id}/comments/{cid}?account=…requires posts:writecurl -X POST "https://postelk.com/api/v1/posts/8c31d0e2-…/comments/17851234567890123/reply" \
-H "Authorization: Bearer ugcd_live_…" -H "Content-Type: application/json" \
-d '{"account": "instagram:17841400000000000", "text": "Glad it helped — more on Friday 💚"}'
{ "ok": true, "id": "17860000000000001", "username": "maya.collins" }
# like (Facebook Pages only) body {"account": "facebook:102000000000000", "on": true} -> { "ok": true, "liked": true }
# hide / unhide body {"account": "instagram:1784…", "hidden": true} -> { "ok": true, "hidden": true }
# delete DELETE …/comments/17851234567890123?account=instagram:1784… -> { "ok": true }Every body carries account. reply takes text (Instagram 2,200 characters, Facebook 8,000, Threads 500) and answers with the new reply's id; on Instagram a reply to a reply attaches to the top-level comment, as the app does. like takes on (default true; false unlikes) and only works on Facebook Pages — Instagram and Threads do not allow it through their APIs (400 unsupported). hide takes hidden (default true); a hidden comment stays in the list with hidden: true. Deleting is permanent and not available on Threads. Reply text goes through the same content check as captions (400 content_refused).
Private reply to a commenter
/posts/{id}/comments/{cid}/messagerequires inbox:writecurl -X POST "https://postelk.com/api/v1/posts/8c31d0e2-…/comments/17851234567890123/message" \
-H "Authorization: Bearer ugcd_live_…" -H "Content-Type: application/json" \
-d '{"account": "instagram:17841400000000000", "text": "Sent you the template link — enjoy!"}'
{ "ok": true, "message_id": "aWdfZAG1faXRlbTo…", "peer_id": "17841401234567890" }Sends one direct message — Instagram DM or Facebook Messenger — to the person who wrote the comment, with Meta's rules checked before the call: within 7 days of the comment, once per comment, never to your own comment (409 window_closed, 409 already_sent). Instagram messages take 1,000 characters, Facebook 2,000. peer_id and peer_name are optional — Postelk takes them from the comment. The message lands in the conversation with that person; if they answer, continue in the inbox.
Inbox
/inbox?account=…requires inbox:readDirect messages of an account connected through Postelk's own connection: Instagram DMs and Facebook Page Messenger. Without account the response lists the accounts that have an inbox. With it, you get the conversations, newest first — the same list as the Messages page in Postelk.
Own permission. Reading the inbox needs inbox:read, answering needs inbox:write — deliberately separate from posts:*, so a key made for scheduling never sees private messages. Keys and connected apps created before these permissions existed do not carry them: create a new key, or reconnect the app and accept them on the consent screen. The private reply to a commenter uses inbox:write too.
curl "https://postelk.com/api/v1/inbox" -H "Authorization: Bearer ugcd_live_…"
{ "accounts": [ { "key": "instagram:17841400000000000", "platform": "instagram", "username": "maya.collins", "nickname": null } ],
"hint": "Pass ?account=<id> to list that inbox." }
curl "https://postelk.com/api/v1/inbox?account=instagram:17841400000000000&refresh=1" \
-H "Authorization: Bearer ugcd_live_…"Response
{
"account": "instagram:17841400000000000",
"platform": "instagram",
"window_hours": 24,
"warning": null,
"threads": [
{
"peer_id": "17841401234567890",
"peer_name": "dana.k",
"peer_avatar": null,
"platform": "instagram",
"account_key": "instagram:17841400000000000",
"conversation_id": "aWdfZAG0…",
"last_text": "Yes please send me the link!",
"last_at": "2026-10-20T12:16:02+00:00",
"last_direction": "in",
"last_kind": "message",
"last_in_at": "2026-10-20T12:16:02+00:00",
"unread": 1,
"total": 4,
"can_reply": true
}
]
}| Field | Notes |
|---|---|
threads[].peer_id | The other person's id on that network — use it in the endpoints below. |
threads[].can_reply | true while the person wrote to you within the last 24 hours (window_hours). Meta does not deliver messages outside that window. |
threads[].unread | Messages from them you have not marked read. |
refresh=1 | Pull the latest conversations from Meta before answering (at most once every two minutes per account). New messages also arrive on their own through Meta's webhooks. |
warning | Set when the refresh could not reach Meta; the stored conversations are still returned. |
One conversation
/inbox/{peer}?account=…&limit=60requires inbox:readcurl "https://postelk.com/api/v1/inbox/17841401234567890?account=instagram:17841400000000000" \
-H "Authorization: Bearer ugcd_live_…"
{
"account": "instagram:17841400000000000",
"platform": "instagram",
"peer_id": "17841401234567890",
"can_reply": true,
"window_hours": 24,
"window_closes_at": "2026-10-21T12:16:02+00:00",
"messages": [
{ "id": "7f1c…", "direction": "in", "kind": "message", "text": "Hey! Loved the reel 😍", "attachments": [],
"platform_message_id": "aWdfZAG1…", "comment_id": null, "sent_at": "2026-10-19T10:05:30+00:00",
"read_at": "2026-10-19T10:40:00+00:00", "peer_name": "dana.k", "peer_avatar": null },
{ "id": "7f1d…", "direction": "out", "kind": "private_reply", "text": "Here's the caption tool I use", "attachments": [],
"platform_message_id": "aWdfZAG2…", "comment_id": "17851234567890123", "sent_at": "2026-10-19T11:00:00+00:00",
"read_at": null, "peer_name": "dana.k", "peer_avatar": null },
{ "id": "7f1e…", "direction": "in", "kind": "message", "text": "Do you have a template?",
"attachments": [ { "type": "image", "url": "https://lookaside.fbsbx.com/…", "name": null } ],
"platform_message_id": "aWdfZAG3…", "comment_id": null, "sent_at": "2026-10-20T12:16:02+00:00",
"read_at": null, "peer_name": "dana.k", "peer_avatar": null }
]
}The messages exchanged with one person, oldest first: direction is in or out, kind is message or private_reply (a message you sent from a comment; comment_id says which), attachments carry Meta's media links. can_reply and window_closes_at say whether you can still answer. limit accepts 1–200.
Send a message · mark as read
/inbox/{peer}requires inbox:write/inbox/{peer}/readrequires inbox:writecurl -X POST "https://postelk.com/api/v1/inbox/17841401234567890" \
-H "Authorization: Bearer ugcd_live_…" -H "Content-Type: application/json" \
-d '{"account": "instagram:17841400000000000", "text": "Here you go: postelk.com/editor"}'
{ "ok": true, "message_id": "aWdfZAG1faXRlbTo…", "sent_at": "2026-10-20T13:16:40+00:00" }
curl -X POST "https://postelk.com/api/v1/inbox/17841401234567890/read" \
-H "Authorization: Bearer ugcd_live_…" -H "Content-Type: application/json" \
-d '{"account": "instagram:17841400000000000"}'
{ "ok": true, "marked": 2 }You can only answer an existing conversation, and only while can_reply is true (409 window_closed otherwise). The API cannot start a conversation with someone who never wrote to you — that is Meta's rule, not Postelk's. Text is checked like a caption. /read marks every message from that person as read and answers with how many it marked.
Retry a failed post
/posts/{id}/retryrequires posts:writeSends a post that failed on one or more accounts again — the same post, same id, no duplicate in your history. Accounts where it already published are skipped; the rest are queued immediately and go out within about a minute, through the same limits as a new post (rolling 24-hour caps, plan locks). Available for posts published through Postelk's own connection; for a post that went through the previous provider, create it again instead (400 unsupported_provider). Fix the cause first — reconnect an expired account, replace a rejected file — or the same failure repeats.
curl -X POST "https://postelk.com/api/v1/posts/8c31d0e2-…/retry" \
-H "Authorization: Bearer ugcd_live_…" -H "Content-Type: application/json" \
-d '{"accounts": ["instagram:17841400000000000"]}'
{ "ok": true, "id": "8c31d0e2-…", "accounts": ["instagram:17841400000000000"], "scheduled_at": "2026-10-20T13:20:05+00:00",
"message": "Sending again — it usually goes out within a minute." }| Field | Type | Required | Notes |
|---|---|---|---|
accounts | string[] | no | Account ids to retry. Default: every account the post failed on. |
Errors: 409 not_failed (the post did not fail), 409 nothing_to_retry (every account is already live), 429 limit_reached with account (that account's rolling 24-hour cap is full — nothing was queued), 403 account_locked. GET /posts/{id} shows the new per-account status.
Mix clips into many videos
/tools/mixrequires tools:writeThe Repurposer from the site. batches is a list of positions in the final video — say hooks, bodies and endings. Every output takes exactly one clip from each batch, joined in batch order, so 3 hooks × 4 bodies × 2 endings can make up to 24 unique videos. Up to 250 videos per job and 250 per hour (shared with the site).
{
"batches": [
["https://media.postelk.com/renders/…/hook_a.mp4", "https://media.postelk.com/renders/…/hook_b.mp4", "…/hook_c.mp4"],
["https://media.postelk.com/renders/…/body_a.mp4", "…/body_b.mp4", "…/body_c.mp4", "…/body_d.mp4"],
["https://media.postelk.com/renders/…/ending_a.mp4", "…/ending_b.mp4"]
],
"count": 24,
"music": [{ "url": "https://www.dropbox.com/s/…/beat.mp3", "volume": 20, "from_batch": 2, "to_batch": 3 }]
}| Field | Type | Required | Notes |
|---|---|---|---|
batches | string[][] | yes | 2–10 batches of 1–20 video URLs each — your own Postelk videos. At most 24 different source videos per job. |
count | integer | no | Unique videos to make, 1–250. Cannot exceed the product of the batch sizes. Default: the smaller of that product and 10. |
color · strength | boolean · string | no | Tiny colour variation per output so files differ (default on), light or hard. |
music | object[] | no | Up to 4 tracks mixed under the original audio; each output gets one at random. Each: url (public https mp3 / m4a / wav / aac / ogg, ≤60 MB — Drive and Dropbox links work), volume 0–100 (25), song_start and video_start in seconds, from_batch–to_batch to play only over some batches (1-based). |
Response · 202
{
"job_id": "5f0c2a9e7b1d4e6f8a3b2c1d0e9f8a7b",
"tool": "mix", "status": "running", "count": 24, "batches": [3, 4, 2], "max_unique": 24,
"color": true, "strength": "light", "music_tracks": 1,
"status_url": "/api/v1/tools/jobs/5f0c2a9e7b1d4e6f8a3b2c1d0e9f8a7b"
}429 render_busy with the running job_id. Nothing is lost: one job can still make up to 250 videos, and the hourly limit is the same as on the site. It only keeps a script from taking every render slot at once.Split screen
/tools/split-screenrequires tools:writeTwo of your videos stacked top and bottom in one 9:16 video — a reaction over gameplay, a talking clip over b-roll. 50 per hour, shared with the site.
| Field | Type | Required | Notes |
|---|---|---|---|
top_url · bottom_url | string | yes | Your own Postelk videos. |
ratio | number | no | Height of the top video, 20–80 percent of the frame. Default 60. |
top_volume · bottom_volume | number | no | 0–100. Defaults: top 0, bottom 100. |
top_pan · bottom_pan | number | no | Which part stays visible when a clip is cropped, 0–100. Default 50 (centre). |
top_start · top_end · bottom_start · bottom_end | number | no | Trim in seconds. An end of 0 means “to the end”. |
Captions
/tools/captionsrequires tools:writeBurns captions into a video, the way the Postelk video editor does. Leave captions out and the speech is transcribed automatically; pass it to use your own text — a translation, a corrected transcript, a hook line. The job has two steps (phase: transcribing, then rendering) under one job_id. 30 per hour, shared with the site.
{
"media_url": "https://media.postelk.com/renders/…/output.mp4",
"font": "anton", "color": "#ffe600", "position_y": 72, "size": 1.1,
"captions": [
{ "text": "Save this", "start": 0.0, "end": 0.9 },
{ "text": "before it's gone", "start": 0.9, "end": 2.1 }
]
}| Field | Type | Required | Notes |
|---|---|---|---|
media_url | string | yes | One of your Postelk videos. |
captions | object[] | no | Your own captions: text, start, end (seconds). Up to 600. Omit for automatic transcription. |
position_x · position_y | number | no | Centre of the captions in percent of the frame. Defaults 50 · 80 (80 sits above most app interface). |
size | number | no | 0.5–2. Default 1. |
color · outline_color · outline_width | string · string · number | no | Hex colours (outline_color may be auto); width 0–100, default 35. |
font | string | no | A font key such as anton, bebas-neue, archivo-black, bangers. Empty = default. |
If no speech is found, the job ends as failed with a message asking for your own captions; nothing is taken from the hourly allowance.
Video job status
/tools/jobs/{id}requires renders:readPoll every 10–20 seconds. When status is done, every entry in outputs carries a url you can pass straight to POST /posts or POST /posts/batch. The same videos also appear in GET /renders.
{
"job_id": "5f0c2a9e7b1d4e6f8a3b2c1d0e9f8a7b",
"tool": "mix", "status": "done", "progress": 100, "message": "Done — 24 videos",
"requested": 24, "produced": 24, "error": null,
"outputs": [
{ "file": "video_001.mp4", "type": "video", "url": "https://media.postelk.com/renders/…/video_001.mp4" },
{ "file": "video_002.mp4", "type": "video", "url": "https://media.postelk.com/renders/…/video_002.mp4" }
]
}| Field | Notes |
|---|---|
status | running, done or failed. |
progress · message | 0–100 and a short description of the current step. |
requested · produced | How many were asked for and how many were made. Videos that could not be made are returned to your hourly allowance. |
outputs | Finished videos: file, url, type. Empty while running. |
Jobs are kept in memory for a while. A job that finished long ago — or was running during a server restart — returns 404 not_found; its finished videos are still in GET /renders.
The whole pipeline
1. POST /imports { "url": "https://drive.google.com/file/d/…" } -> url (one call per take)
2. POST /tools/mix { "batches": [[hook_a, hook_b], [body_a, body_b]],
"count": 4 } -> job_id
3. GET /tools/jobs/{id} … until "status": "done" -> outputs[].url
4. POST /posts/batch { "accounts": [...], "items": [ one per output ],
"stagger": { "start": "2026-09-22T09:00:00Z", "gap_minutes": 120 } }MCP server
Most AI tools speak the Model Context Protocol. Instead of teaching them the API with a prompt, you point them at our MCP server once and they discover everything themselves — what they can do, what each action needs, and what came back.
| Thing | Value |
|---|---|
| Server URL | https://mcp.postelk.com/mcp |
| Transport | Streamable HTTP (some clients call it just HTTP) |
| Protocol versions | 2025-06-18 · 2025-03-26 · 2024-11-05 |
| Authentication | OAuth (recommended) or an API key |
Two ways to connect
OAuth — you paste only the server URL. The tool sends you to Postelk, you sign in and choose what it may do. Nothing to copy, and you can cut its access off from the API page at any time. This is what browser-based connectors (Claude, ChatGPT, Notion, Perplexity) use.
API key — put Authorization: Bearer ugcd_live_… in the client's headers. Handy for terminal tools and automation platforms that already have a headers field.
Both give the same tools and obey the same limits. Pick whichever the tool you are using makes easier.
Claude Code
claude mcp add --transport http postelk https://mcp.postelk.com/mcpThen run /mcp in a session, pick Postelk, and approve access.
Clients that use a config file
Cursor, Gemini CLI and most editors take a JSON block like this:
{
"mcpServers": {
"postelk": {
"httpUrl": "https://mcp.postelk.com/mcp"
}
}
}What the tools do
Everything the Postelk composer can do, the assistant can do too — the same rules, the same limits, the same publishing path.
list_accounts your connected accounts — health, locks, posts left today
get_usage plan, account limit, per-account 24h usage, free-plan counters
create_post publish now, schedule, or draft — several images = one swipeable carousel,
first comment, Story, Reel cover,
Trial reel, Facebook Reel, TikTok privacy, Pinterest board, overrides,
per-network options (YouTube title / visibility / tags, TikTok comments /
Duet / Stitch / AI label, Instagram collaborators, Threads reply control)
create_posts queue up to 60 posts, spaced out (stagger) — runs in the background
get_batch progress and per-item results of a create_posts batch
update_post edit a scheduled post or draft (new id)
cancel_post cancel something that has not gone out (remove=true drops it from history)
delete_post remove a post record from Postelk history
get_post one post with per-account status, the failure reason (why) and links
list_posts scheduled / posted / failed / cancelled / draft, filtered by date, platform, account, caption search
list_renders videos you made or imported (only_unused = not posted yet; scheduled = sits in a pending post)
import_media bring a Google Drive / Dropbox / direct link into Postelk
list_post_performance views, likes, comments and shares per published post, with links (min/max views, search)
get_analytics account-level totals, deltas, followers, per-account breakdown
list_saved_captions your saved caption library
save_caption add a caption to the library
list_pinterest_boards boards of a Pinterest account (board_id is required for pins)
get_post_defaults your saved per-network rules that apply to every post
set_post_defaults save rules once ("always post YouTube as unlisted") - they apply from then on
mix_videos batches of clips -> many unique videos, one clip per batch (Repurposer), optional music
split_screen two videos stacked into one vertical video
add_captions burn captions in - automatic transcription, or your own text and timings
get_job progress of a video job; when done, the finished videos as postable URLs
list_comments comments under a published post — replies nested, likes, hidden ones, who can still get a DM
reply_comment answer a comment publicly, as your account
like_comment like / unlike a comment (Facebook Pages only)
hide_comment hide or unhide a comment from everyone
delete_comment delete a comment for good (not on Threads)
send_private_reply one DM to a commenter — within 7 days of the comment, once per comment
list_inbox Instagram DM / Messenger conversations with unread counts and can_reply
read_conversation the messages exchanged with one person
send_message answer a conversation (only within 24 hours of their last message)
retry_post send a failed post again — same post, accounts that already published are skippedUploading a file from your computer is not an MCP tool — binary uploads do not travel well over this protocol. Give the assistant a link instead: import_media takes a Google Drive share link (Anyone with the link), a Dropbox link or any direct file link. Or ask for list_renders and post a video you already made.
Commands
The server also ships ready-made prompts. In Claude Code they appear as slash commands (/mcp__postelk__usage, /mcp__postelk__status, …); in Claude Desktop and other clients they sit in the prompt menu. Each one tells the assistant exactly which tools to call and in what order.
usage posts left per account today, plan, queue
accounts connected accounts with health, locks, remaining posts
post guided posting: accounts -> media -> caption -> time -> confirm -> post
post-remaining schedule every unused video, spaced out (gap_hours, start)
status the queue, what went out, what failed and why (days)
performance best posts with numbers and links (days, min_views)
import bring a Drive / Dropbox / direct link into Postelk (url)
comments read the comments on a post and answer them — reply, hide, or send a DM
inbox go through unread messages and answer the ones still openWhen a post fails, ask why: get_post and list_posts carry a plain-English reason next to the raw platform error, so the assistant can tell you what to fix (reconnect an account, shorten a caption, pick a board, wait for a cap to reset).
OAuth reference
Only relevant if you are building an MCP client yourself. If you are connecting an existing tool, the section above is all you need.
The server implements OAuth 2.1 as required by the MCP specification:
| Spec | What it covers |
|---|---|
| RFC 9728 | Protected resource metadata — how a client finds the authorization server |
| RFC 8414 | Authorization server metadata — endpoints and capabilities |
| RFC 7591 | Dynamic client registration — clients register themselves, no manual setup |
| RFC 7636 | PKCE. S256 only — plain is rejected |
| RFC 8707 | Resource indicators — tokens are bound to this server and checked on use |
Discovery
An unauthenticated request returns 401 with a pointer to the metadata:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Postelk MCP",
resource_metadata="https://mcp.postelk.com/.well-known/oauth-protected-resource"| Endpoint | Purpose |
|---|---|
/.well-known/oauth-protected-resource | Where the authorization server lives |
/.well-known/oauth-authorization-server | Endpoints, scopes, supported grants |
POST /oauth/register | Dynamic client registration |
GET /oauth/authorize | Sends the user to the consent screen |
POST /oauth/token | Code exchange and refresh |
POST /oauth/revoke | Drop a refresh token |
Rules worth knowing
- Public clients only — there is no client secret. PKCE does that job.
redirect_urimust match a registered value exactly. Mismatches are refused on our page, not bounced to the URI.- Redirect URIs must be https, or http on localhost.
- Authorization codes last 10 minutes and work once.
- Access tokens last 1 hour. Refresh tokens rotate — the old one dies the moment you use it.
- Tokens are bound to
https://mcp.postelk.com/mcp. A token issued for anything else is rejected.
Media rules
These are platform rules, enforced before anything is created so you fail fast rather than half-publish:
- No mixing. Photos and videos cannot share one post. Split them into two calls.
- YouTube is video only. A photo post targeting YouTube is rejected.
- TikTok photo posts are supported. A photo post targeting TikTok publishes as a TikTok photo post (title:
options.tiktok.photo_title, else the first 90 characters of the caption). - Media must be ours. Only URLs from
POST /uploads,POST /importsor your Postelk renders are accepted. This stops the API being used to fetch arbitrary hosts. - Instagram, TikTok, YouTube and Pinterest need media. Text-only posts go to X, Threads, LinkedIn, Facebook and Bluesky.
- Pinterest needs a board. Every pin carries
pinterest.board_id. - Stories are one image or video, Instagram and/or Facebook, no caption, no comment.
- Caption limits are enforced. Threads 500 · X 280 · Bluesky 300 · Pinterest 500 · Instagram and TikTok 2,200 · LinkedIn 3,000 · YouTube 5,000 (the description; the title is
options.youtube.titleor the first line). Useoverridesto give a platform a shorter caption. - Ten items maximum per post.
Each rule returns 400 bad_request with a message naming the exact problem. Nothing is reserved and no quota is consumed.
Scheduling
scheduled_at is ISO-8601. Send UTC and be explicit about it:
"scheduled_at": "2026-08-12T15:00:00Z" <- correct
"scheduled_at": "2026-08-12T15:00:00+00:00" <- also correct
"scheduled_at": "2026-08-12 15:00" <- rejected (400)A value without a timezone is treated as UTC. A malformed value is rejected outright — it never silently degrades into "post now", which would be the worst possible failure mode.
The horizon is 30 days. Anything further ahead returns 400 bad_request.
A time in the past is rejected too (400 bad_request, with the server’s current UTC time in the message) — a past time would go out immediately, which is never what a wrong date means. A few minutes of clock skew are treated as “now”. The same applies to overrides.*.scheduled_at and to stagger.start in a batch. To publish right away, leave scheduled_at out.
Daily caps apply to the target day. Ten TikTok posts scheduled for next Tuesday consume next Tuesday's allowance, whichever day you created them.
Post lifecycle
| Status | Meaning |
|---|---|
scheduled | Queued for its target time. Can be cancelled. |
posted | Published. Cannot be cancelled through the API. |
failed | Every targeted account rejected it. The slot was returned. |
cancelled | Cancelled by you. The slot was returned. |
draft | Saved in the dashboard or with draft: true, never sent. Publish it with PATCH /posts/{id}. |
A post created without scheduled_at goes straight to posted — or to failed if every account rejected it. Immediate posts are checked against the network for a few seconds before we answer, so the accounts array in the response is a real result, not an optimistic guess.
Slow networks (Instagram and LinkedIn in particular) may still be pending when we respond. Those are not failures — poll GET /posts/{id} if you need the settled state.
Recipes
Publish one video now
#!/usr/bin/env bash
set -euo pipefail
KEY="$POSTELK_KEY"
BASE="https://postelk.com/api/v1"
# 1. pick a TikTok account
ACCOUNT=$(curl -s "$BASE/accounts" -H "Authorization: Bearer $KEY" \
| jq -r '.accounts[] | select(.platform=="tiktok") | .id' | head -1)
# 2. upload the file
URL=$(curl -s -X POST "$BASE/uploads" -H "Authorization: Bearer $KEY" \
-F "file=@./clip.mp4" | jq -r .url)
# 3. publish now
curl -s -X POST "$BASE/posts" -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d "$(jq -nc --arg a "$ACCOUNT" --arg u "$URL" \
'{accounts:[$a], caption:"Posted from a script", media:[{url:$u,type:"video"}]}')"Spread a batch across the week
import os, datetime as dt, requests
BASE = "https://postelk.com/api/v1"
H = {"Authorization": "Bearer " + os.environ["POSTELK_KEY"]}
accounts = [a["id"] for a in requests.get(BASE + "/accounts", headers=H).json()["accounts"]]
clips = ["a.mp4", "b.mp4", "c.mp4", "d.mp4", "e.mp4"]
slot = dt.datetime.now(dt.timezone.utc).replace(hour=15, minute=0, second=0, microsecond=0)
for i, path in enumerate(clips):
with open(path, "rb") as fh:
url = requests.post(BASE + "/uploads", headers=H, files={"file": fh}).json()["url"]
when = (slot + dt.timedelta(days=i + 1)).strftime("%Y-%m-%dT%H:%M:%SZ")
r = requests.post(BASE + "/posts", headers=H, json={
"accounts": accounts,
"caption": "Clip %d of %d" % (i + 1, len(clips)),
"media": [{"url": url, "type": "video"}],
"scheduled_at": when,
})
if r.status_code == 429 and r.json()["error"]["code"] == "daily_limit_reached":
print("cap reached for", when, "- move this clip to a later time")
continue
r.raise_for_status()
print(when, "->", r.json()["id"])Retry safely after a 5xx
resp = requests.post(BASE + "/posts", headers=H, json=payload)
if resp.status_code >= 500:
# The post MAY already exist. Look before leaping.
recent = requests.get(BASE + "/posts", headers=H,
params={"status": "scheduled", "limit": 20}).json()["posts"]
already = any(p["caption"] == payload["caption"]
and p["scheduled_at"] == payload["scheduled_at"] for p in recent)
if not already:
resp = requests.post(BASE + "/posts", headers=H, json=payload)Clear the scheduled queue
queued = requests.get(BASE + "/posts", headers=H,
params={"status": "scheduled", "limit": 100}).json()["posts"]
for p in queued:
r = requests.delete(BASE + "/posts/" + p["id"], headers=H)
if r.status_code == 409:
print("already published, skipping:", p["id"])FAQ
Which plans include API access?
Every paid plan — Posting and full plans alike. Free accounts can read (GET endpoints) but cannot post; posting returns 403 subscription_required.
Does the API have its own posting quota?
No, and that is deliberate. It shares the same per-account rolling 24-hour caps as the dashboard. Ten TikTok posts in a 24-hour window is ten in total, however you create them.
Can I create videos through the API?
Not in v1. Rendering runs on a limited queue and we are not opening it to unattended traffic yet. You can list and post videos you already rendered with GET /renders.
Can an assistant post a file from my Google Drive?
Yes. Share the file with Anyone with the link and hand the link over — POST /imports (MCP: import_media) pulls it into Postelk and returns a postable URL. Dropbox share links and direct file links work the same way.
Can it do everything the composer does?
That is the goal and the rule we build by: first comments and delays, Stories, Reel covers, Trial reels, Facebook Reels, TikTok privacy, Pinterest boards, per-network options (YouTube title and visibility, TikTok Duet / Stitch, AI labels, collaborators), per-platform captions, drafts, editing, batches, usage and failure reasons are all here. If you find something the composer can do and the API cannot, tell us — it is a bug.
Are there webhooks?
Not yet. Poll GET /posts for state changes. Results for immediate posts are already in the POST /posts response.
Is there a sandbox?
No. Test against a real connected account — a private or throwaway one is the usual approach.
What happens if my subscription lapses?
Posting stops immediately with 403 subscription_required. Read endpoints keep working so you can export your data. Keys are not deleted.
How do I rotate a key without downtime?
Generate the new key, deploy it, confirm with GET /me, then revoke the old one. Both work simultaneously — there is no limit on concurrent keys beyond the cap of 10.
Someone got hold of my key. What now?
Revoke it in Settings → API. It stops working within 60 seconds. Then check GET /posts for anything you did not create, and cancel what is still scheduled.
Are ids stable?
Account ids are stable while the account stays connected — disconnecting and reconnecting produces a new id. Post ids are permanent UUIDs.