Skip to content

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.

Base URLhttps://postelk.com/api/v1

What 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.

You do not need to know how to code. The steps below are copy, paste, done. The developer reference further down is only there if you want to build something yourself.

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

  1. Open the API page

    In Postelk, click API in the left sidebar, under Developers. Go there now →

  2. 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.

  3. 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.

Treat it like a password. Anyone holding your key can post as you. Do not paste it into a public chat, a screenshot, or a shared document. If it leaks, delete it on the API page — it stops working within a minute.

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.

ToolHow it connects
Claude, ChatGPT, GeminiMCP connector — paste the server URL, sign in, approve
Notion, Perplexity, ManusMCP connector — same three steps
Claude Code, Cursor, AntigravityMCP, from a config file or one terminal command
Zapier, n8nAn HTTP step with your API key in the header
Anything else that speaks MCPSame 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.

Give each app its own key. If you connect Claude and Zapier, make two keys. Then if one misbehaves you delete that key alone instead of breaking everything at once.

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 seeWhat 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 messageThat account already hit its 24-hour cap around that time. Pick a later time.
The assistant invents an account nameTell 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.


Developer reference

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 /accounts first. 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 with POST /imports, or use a GET /renders URL. 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_7Kq2xR9mVb4TzL1nWpH8sYeA

Create keys in Settings → API. A key is ugcd_live_ followed by 32 URL-safe characters.

The key is shown once. We store only a SHA-256 hash of it — we cannot recover or re-display it. If you lose a key, revoke it and generate a new one.

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.

Session tokens are not API keys. The API deliberately rejects Supabase JWTs. If your token contains a ., 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.

ScopeWhat it allowsUsed by
posts:readRead 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:writeCreate, 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:readRead connected accounts, usage and Pinterest boards.GET /accounts, GET /usage, GET /pinterest/boards
renders:readRead videos you created or imported in Postelk.GET /renders
uploads:writeUpload or import media for posting.POST /uploads, POST /uploads/ticket, POST /uploads/confirm, POST /imports
tools:writeRun 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:readRead 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:writeAnswer 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.

CodeHTTPWhat happenedWhat to do
unauthorized401No key, or the header was malformed.Send Authorization: Bearer ugcd_live_…. Session JWTs are rejected on purpose.
invalid_key401The key does not exist.Check for a copy/paste error, or generate a new key.
key_revoked401The key was revoked in the dashboard.Generate a new key. Revocation takes effect within 60 seconds.
key_expired401The key passed its expiry date.Generate a new key. Keys can also be created with no expiry.
account_suspended403The Postelk account is suspended.Contact support. No endpoint works while suspended.
subscription_required403The plan does not include posting.Read endpoints keep working. Upgrade to post.
insufficient_scope403The key lacks the permission this endpoint needs.The response includes required_scope. Create a key with that permission.
forbidden403The account is not connected to your profile.Re-read GET /accounts; ids are not portable between users.
account_not_found404One or more account ids are unknown.The response lists the offending ids in account_ids.
not_found404No post with that id.Post ids are UUIDs returned by POST /posts.
already_published409The post is already live.Published posts cannot be cancelled through the API — remove them on the platform.
too_many_keys409You already have 10 active keys.Revoke one first. This applies to the dashboard, not to API calls.
file_too_large413Upload exceeded the limit (95 MB on POST /uploads, 2 GB with an upload ticket).Use an upload ticket for big files, or compress.
storage_full413Workspace storage is full.Delete old videos in Created videos, then retry.
not_uploaded404Confirm was called before the PUT finished.Finish the PUT, then confirm.
unsupported_media415File type not accepted.mp4, mov, webm, jpg, png, webp.
rate_limited429Too many API requests for this key.60 requests/minute and 600/hour per key. Back off and retry.
daily_limit_reached429That 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_reached429The 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_full429The Free plan allows 10 scheduled posts waiting at a time.Wait for queued posts to publish (slots free up automatically) or upgrade.
account_locked403This 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_request400Something in the body is missing or malformed.The message names the field. Nothing was created.
media_required400Instagram, TikTok, YouTube and Pinterest need a photo or video.Attach media, or drop those accounts from the post.
pinterest_board_required400A Pinterest account was targeted without a board.Pass pinterest.board_id — list boards with GET /pinterest/boards.
caption_too_long400The 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_refused400The 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_media400A 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_unavailable400A 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_queued502The 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_reconnect403A targeted account's connection is broken.Reconnect it in Postelk → Connections, then retry. GET /accounts shows needs_reconnect.
not_editable409Only scheduled posts and drafts can be edited.Create a new post instead.
editing_locked403The 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_found404media_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_busy429A 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_reached429The hourly video limit for this tool is used up (shared with the site).The response carries retry_after in seconds.
server_busy429All render slots are taken right now.Wait a minute and retry.
unsupported_provider400The 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_account404account 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_published409The post has not gone out on that account yet.Comments exist only after publishing — GET /posts/{id} shows the per-account status.
unsupported400That 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_missing409The account has to be reconnected.Reconnect it in Postelk → Connections, then retry.
token_expired409The account's connection expired or was revoked.Reconnect it in Postelk → Connections, then retry.
permission409Meta 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_closed409Meta'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_sent409A private reply was already sent for this comment.Meta allows one private reply per comment. If the person answered, continue in the inbox.
empty400The reply or message has no text.Send text.
too_long400The 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_error502Meta returned an error Postelk could not translate.The message carries Meta's text. Check the account in Connections before retrying.
unavailable503Meta did not answer in time, or the feature is not set up on the server yet.Retry in a moment.
not_failed409The 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_retry409Every account on the post is already live.Nothing to do — the post went out everywhere it was meant to.
delete_on_platform409The 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_full507Your render storage is full.Delete saved videos in Created videos, then retry.
import_failed422The link could not be downloaded.Share the file publicly (Google Drive: Anyone with the link) or use a direct file link.
publish_failed502The post could not be created downstream.It may or may not exist — call GET /posts before retrying.
cancel_failed502The cancellation did not go through.The post is still scheduled. Retry; do not assume it was cancelled.
service_unavailable503We could not reach our own storage.Your key is fine. Retry after a few seconds.
Never blindly retry a failed 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:

WindowLimit
1 minute60 requests
1 hour600 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.

Platform24-hour cap
Instagram50 per account per rolling 24 hours
TikTok10 per account per rolling 24 hours
YouTube5 per account per rolling 24 hours
Facebook50 per account per rolling 24 hours
Threads250 per account per rolling 24 hours
LinkedIn50 per account per rolling 24 hours
Pinterest50 per account per rolling 24 hours
Bluesky50 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

ThingLimit
Accounts per post20
Media items per post10
Upload size95 MB per POST /uploads request · up to 2 GB with an upload ticket
Scheduling horizon30 days ahead
Active API keys10
Posts per page (GET /posts)100

Get current account

GET/me

Confirms 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

GET/accountsrequires accounts:read

Returns 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
    }
  ]
}
FieldTypeNotes
idstringPass this in accounts when creating a post.
platformstringinstagram · tiktok · youtube · facebook · threads · linkedin · pinterest · bluesky
usernamestringHandle on the platform.
display_namestringProfile name, may be null.
activebooleanFalse usually means the connection needs re-authorising in the dashboard.
connected_attimestampWhen the account was linked.
lockedbooleantrue 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

POST/uploadsrequires uploads:write

Uploads 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"
}
RuleValue
Field namefile
Encodingmultipart/form-data
Max size95 MB — larger returns 413 file_too_large
Video typesvideo/mp4, video/quicktime, video/webm
Image typesimage/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.mp4

3 · 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"
}
RuleValue
extmp4, mov, webm, m4v, jpg, png, webp — anything else returns 415 unsupported_media
sizethe 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
Ticketvalid for 15 minutes, one file, write-only (it cannot read, list or delete anything)
Max size2 GB per file on paid plans — larger returns 413 file_too_large
Storage100 GB per workspace — full returns 413 storage_full
Rate30 tickets a minute, 300 an hour — more returns 429
Confirmchecks 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

POST/postsrequires posts:write

Publishes 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

FieldTypeRequiredNotes
accountsstring[]yesAccount ids from GET /accounts. Max 20. Objects with an id key are also accepted.
captionstringone ofPost 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.
mediaobject[]one ofObjects 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_atstringnoISO-8601 UTC. Omit to publish now. Max 30 days ahead.
first_commentstringnoPosted as a reply by the same account right after the post. Not delivered on TikTok, Pinterest or YouTube.
comment_delay_minintegernoMinutes after publishing to post the first comment (0–1440; default 0 = with the post).
storybooleannoPublish as a Story — Instagram and/or Facebook only, exactly one image or video, no caption, no comment.
ig_coverobjectnoInstagram Reel cover: {"offset_ms": 1500} picks a frame, {"url": "https://…jpg"} uses a JPEG hosted by Postelk. Single-video Reels only.
trial_reelbooleannoInstagram: 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_reelbooleannoFacebook: publish the single video as a Page Reel (3–90 s, 9:16) instead of a plain Page video.
tiktok_privacystringnoPUBLIC_TO_EVERYONE (default) · MUTUAL_FOLLOW_FRIENDS · FOLLOWER_OF_CREATOR · SELF_ONLY.
pinterestobjectwhen Pinterest is targetedboard_id (required — see boards), optional title ≤100, link (https), alt_text ≤500.
optionsobjectnoOptional per-network settings — the gear icon on each post in the composer. See Per-network options.
overridesobjectnoPer-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.
draftbooleannoSave as a draft instead of publishing. Publish it later with PATCH /posts/{id}.
use_defaultsbooleannoDefault 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.

FieldTypeNotes
options.youtube.titlestringVideo title, ≤100. Default: the first line of the caption (cut at a word, 100 max). The caption itself is the description.
options.youtube.privacystringpublic (default) · unlisted · private.
options.youtube.made_for_kidsbooleanDeclare the video as made for kids.
options.youtube.synthetic_mediabooleanDisclose realistic altered or AI-generated content.
options.youtube.shortbooleanAdds #shorts to the description. YouTube itself decides what is a Short (vertical or square, up to 3 minutes).
options.youtube.tagsstring[]Up to 30 tags, 450 characters in total.
options.youtube.category_idstringYouTube 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_stitchbooleanDefault true. Duet and Stitch apply to videos only.
options.tiktok.ai_generatedbooleanLabel the post as AI-generated.
options.tiktok.brand_organic · brand_contentbooleanDisclosure labels: promotes your own brand · paid partnership. A paid partnership cannot be combined with tiktok_privacy: SELF_ONLY.
options.tiktok.photo_title · auto_musicstring · booleanPhoto posts only: title ≤90 (default: start of the caption) and TikTok's recommended music.
options.instagram.ai_generatedbooleanAdds Instagram's “AI info” label.
options.instagram.collaboratorsstring[]Up to 3 public usernames invited as collaborators (feed posts and Reels, not Stories).
options.instagram.trial_graduationstringWith trial_reel: manual (default) or performance — Instagram shares the reel with followers on its own if it does well.
options.instagram.alt_textstringImage posts: alt text, ≤1,000.
options.instagram.comments_offbooleanTurns 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_controlstringeveryone (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"
  }'
NetworkImages per postNotes
Instagram2–10Every slide is cropped to the first image's shape.
Facebook · Threads · LinkedIn · TikTokup to 10TikTok shows them as a photo post.
Pinterestup to 5More returns 400 too_many_media.
Blueskyup to 4More 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 }
  ]
}
FieldNotes
idPostelk post id — use it for GET and DELETE /posts/{id}.
post_idUpstream scheduling id. Informational.
statusscheduled, posted or failed.
accountsPer-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_accountsPresent 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_defaultsPresent when saved default post settings filled something in — e.g. ["youtube.privacy", "tiktok.allow_duet"].
Partial success is normal. If you target five accounts and one has an expired token, the other four still publish. Read the 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

GET/postsrequires posts:read
curl "https://postelk.com/api/v1/posts?status=scheduled&limit=50" \
  -H "Authorization: Bearer $POSTELK_KEY"
QueryDefaultNotes
statusallscheduled · 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_results01 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.
limit501–100.
offset0For 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

GET/posts/{id}requires posts:read
curl 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

DELETE/posts/{id}requires posts:write
curl -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.

Published posts cannot be cancelled. They return 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

PATCH/posts/{id}requires posts:write

Change 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

POST/posts/batchrequires posts:write

Queue 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

GET/usagerequires accounts:read

Your 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

POST/importsrequires uploads:write

Download 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

GET/captionsrequires posts:read

Your 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

GET/post-defaultsrequires posts:read

Rules 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
CallScopeWhat it does
GET /post-defaultsposts:readYour rules as defaults, a plain-English summary, and the allowed fields per network.
PATCH /post-defaultsposts:writeMerge by network: only the fields you send change. A field set to null is removed, a network set to null is cleared.
PUT /post-defaultsposts:writeReplace all rules with the body ({} clears everything).
NetworkFields
instagramai_generated, collaborators, trial_reel, trial_graduation (with trial_reel)
tiktokprivacy (the four tiktok_privacy values), allow_comments, allow_duet, allow_stitch, ai_generated, brand_organic, brand_content, auto_music
youtubeprivacy, made_for_kids, synthetic_media, short, tags, category_id
facebookreel — publish single videos as Reels
threadsreply_control
pinterestlink — 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

GET/pinterest/boards?account_id=…requires accounts:read

Pinterest 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

GET/rendersrequires renders:read

Returns 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

GET/analytics/postsrequires posts:read

Views, 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

GET/analytics/summary?days=30requires posts:read

The 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

GET/posts/{id}/comments?account=…requires posts:read

The 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" }
        }
      ]
    }
  ]
}
FieldNotes
accountRequired query parameter: an account id from GET /accounts that is part of the post. One network per call.
capsWhat this network allows: reply, like (Facebook Pages only), hide, delete (not on Threads), dm and inbox (Instagram and Facebook).
comments[].dmcan — 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[].likedtrue or false on Facebook Pages (whether your Page liked it); null where the network does not say.
comments[].hidden · is_mineHidden comments stay in the list, marked. is_mine is a reply written by your account.
nextPass 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

POST/posts/{id}/comments/{cid}/replyrequires posts:write
POST/posts/{id}/comments/{cid}/likerequires posts:write
POST/posts/{id}/comments/{cid}/hiderequires posts:write
DELETE/posts/{id}/comments/{cid}?account=…requires posts:write
curl -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

POST/posts/{id}/comments/{cid}/messagerequires inbox:write
curl -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

GET/inbox?account=…requires inbox:read

Direct 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
    }
  ]
}
FieldNotes
threads[].peer_idThe other person's id on that network — use it in the endpoints below.
threads[].can_replytrue while the person wrote to you within the last 24 hours (window_hours). Meta does not deliver messages outside that window.
threads[].unreadMessages from them you have not marked read.
refresh=1Pull 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.
warningSet when the refresh could not reach Meta; the stored conversations are still returned.

One conversation

GET/inbox/{peer}?account=…&limit=60requires inbox:read
curl "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

POST/inbox/{peer}requires inbox:write
POST/inbox/{peer}/readrequires inbox:write
curl -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

POST/posts/{id}/retryrequires posts:write

Sends 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." }
FieldTypeRequiredNotes
accountsstring[]noAccount 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

POST/tools/mixrequires tools:write

The 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 }]
}
FieldTypeRequiredNotes
batchesstring[][]yes2–10 batches of 1–20 video URLs each — your own Postelk videos. At most 24 different source videos per job.
countintegernoUnique videos to make, 1–250. Cannot exceed the product of the batch sizes. Default: the smaller of that product and 10.
color · strengthboolean · stringnoTiny colour variation per output so files differ (default on), light or hard.
musicobject[]noUp 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"
}
One job at a time. Video jobs started through the API or an AI app run one at a time per account — a second call while one is running returns 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

POST/tools/split-screenrequires tools:write

Two 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.

FieldTypeRequiredNotes
top_url · bottom_urlstringyesYour own Postelk videos.
rationumbernoHeight of the top video, 20–80 percent of the frame. Default 60.
top_volume · bottom_volumenumberno0–100. Defaults: top 0, bottom 100.
top_pan · bottom_pannumbernoWhich part stays visible when a clip is cropped, 0–100. Default 50 (centre).
top_start · top_end · bottom_start · bottom_endnumbernoTrim in seconds. An end of 0 means “to the end”.

Captions

POST/tools/captionsrequires tools:write

Burns 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 }
  ]
}
FieldTypeRequiredNotes
media_urlstringyesOne of your Postelk videos.
captionsobject[]noYour own captions: text, start, end (seconds). Up to 600. Omit for automatic transcription.
position_x · position_ynumbernoCentre of the captions in percent of the frame. Defaults 50 · 80 (80 sits above most app interface).
sizenumberno0.5–2. Default 1.
color · outline_color · outline_widthstring · string · numbernoHex colours (outline_color may be auto); width 0–100, default 35.
fontstringnoA 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

GET/tools/jobs/{id}requires renders:read

Poll 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" }
  ]
}
FieldNotes
statusrunning, done or failed.
progress · message0–100 and a short description of the current step.
requested · producedHow many were asked for and how many were made. Videos that could not be made are returned to your hourly allowance.
outputsFinished 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.

ThingValue
Server URLhttps://mcp.postelk.com/mcp
TransportStreamable HTTP (some clients call it just HTTP)
Protocol versions2025-06-18 · 2025-03-26 · 2024-11-05
AuthenticationOAuth (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/mcp

Then 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 skipped

Uploading 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 open

When 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).

Ask it to confirm before posting. The server tells every client to show you the caption and the time and wait for your approval, but saying so yourself never hurts.

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:

SpecWhat it covers
RFC 9728Protected resource metadata — how a client finds the authorization server
RFC 8414Authorization server metadata — endpoints and capabilities
RFC 7591Dynamic client registration — clients register themselves, no manual setup
RFC 7636PKCE. S256 only — plain is rejected
RFC 8707Resource 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"
EndpointPurpose
/.well-known/oauth-protected-resourceWhere the authorization server lives
/.well-known/oauth-authorization-serverEndpoints, scopes, supported grants
POST /oauth/registerDynamic client registration
GET /oauth/authorizeSends the user to the consent screen
POST /oauth/tokenCode exchange and refresh
POST /oauth/revokeDrop a refresh token

Rules worth knowing

  • Public clients only — there is no client secret. PKCE does that job.
  • redirect_uri must 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.
Disconnecting an app on the API page kills its tokens within a minute. The same applies if the account is suspended.

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 /imports or 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.title or the first line). Use overrides to 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

StatusMeaning
scheduledQueued for its target time. Can be cancelled.
postedPublished. Cannot be cancelled through the API.
failedEvery targeted account rejected it. The slot was returned.
cancelledCancelled by you. The slot was returned.
draftSaved 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.

Ready to start?

Create a key, then pick your app on the Integrations page.

Open API settings