Tools

Shows which Post Social workspace this key acts for, the key's name, and whether it is a live or test key (test keys cannot publish).

GET /api/v1/me · postsocial get-workspace

Lists the social accounts connected to Post Social, with their ids, health, profile and what each can post (capabilities and limits).

GET /api/v1/accounts · postsocial list-social-accounts

• platform string: Only this platform.
• profile_id string: Only accounts in this profile (an id from list_profiles), or none for accounts in no profile.

Returns a link the person opens to connect a social account in Post Social. Accounts can only be connected by the person, never by an AI.

POST /api/v1/accounts/connect-link · postsocial request-connect-link

• platform string, required
• profile_id string: The profile the new account goes into (from list_profiles). Optional.

Lists the profiles accounts are grouped under (a business, organisation or client), with how many connected accounts each has. Filter list_social_accounts by profile_id to see a profile's accounts.

GET /api/v1/profiles · postsocial list-profiles

Creates a profile to group accounts under, such as a business, organisation or client.

POST /api/v1/profiles · postsocial create-profile

• name string, required: The profile's name, unique in the workspace.
• description string
• color string: A colour like #9B6CFF.
• timezone string: An IANA time zone, e.g. America/New_York.

Changes a profile's name, description, colour or time zone. Leave out what stays the same.

PATCH /api/v1/profiles/{profile_id} · postsocial update-profile

• profile_id string, required: The profile id.
• name string
• description string
• color string
• timezone string

Deletes a profile. Its accounts stay connected and move to no profile.

DELETE /api/v1/profiles/{profile_id} · postsocial delete-profile

• profile_id string, required: The profile id.

Puts a connected account in a profile, or in no profile when profile_id is none.

POST /api/v1/accounts/{account_id}/profile · postsocial move-account-to-profile

• account_id string, required: The connected account id.
• profile_id string, required: The profile id (from list_profiles), or none for no profile.

Sets how this TikTok account receives AI posts: direct (the default) posts straight away; inbox sends each post to the creator's TikTok inbox to finish and post in TikTok. Posts that leave delivery_mode out follow this; an account set to inbox refuses direct posts. Change it only when the person asks.

POST /api/v1/accounts/{account_id}/tiktok-delivery · postsocial set-tiktok-delivery

• account_id string, required: The connected TikTok account id.
• delivery string, required

Lists uploaded and imported media, newest first. Only media with status ready can be posted.

GET /api/v1/media · postsocial list-media

• media_type string
• include_hidden boolean
• limit integer: How many to return (1 to 100).
• offset integer: How many to skip, for paging.

Gets a media item's details and status. Ready items include a temporary view link (valid 1 hour).

GET /api/v1/media/{media_id} · postsocial get-media

• media_id string, required: The media id.

Copies an image or video from a public https link into Post Social. It is checked in the background; poll get_media until status is ready (or failed, with a reason).

POST /api/v1/media/import · postsocial import-media

• url string, required: A public https link to the file.
• name string

For tools that can send files (CLI, scripts). Returns upload links: PUT each part's bytes to its url, keep each response's ETag, then call finish_media_upload. Links last 1 hour. single_part: true returns one link for the whole file (for tools that send a file in one request, like Apple Shortcuts).

POST /api/v1/media/uploads · postsocial start-media-upload

• file_name string, required
• mime_type string: image/jpeg, image/png, image/webp, video/mp4 or video/quicktime. Left out, taken from the file name.
• size_bytes integer: Required, except with single_part: then the stored size is checked when the upload finishes.
• single_part boolean: One upload link for the whole file instead of parts.

Completes an upload started with start_media_upload. The file is then checked in the background; poll get_media until status is ready. parts can be left out when the tool can't read ETags; Post Social then reads them from storage.

POST /api/v1/media/{media_id}/complete · postsocial finish-media-upload

• media_id string, required: The media id.
• parts array

Removes a media item from the library. Files used by a post are kept until that post no longer needs them; unused files are deleted automatically later.

DELETE /api/v1/media/{media_id} · postsocial delete-media

• media_id string, required: The media id.

Checks a proposed post against every chosen platform's rules (caption length, media shape and length, post types) without saving anything. Returns plain-language problems per account. Each account is named by its profile name (account), its platform and its handle (account_handle, without the @; null for LinkedIn, Facebook Pages and YouTube, which share no handle with Post Social), so two accounts with the same name can be told apart.

POST /api/v1/posts/validate · postsocial validate-post

• caption string: The shared caption. Each platform's limit is checked (see list_social_accounts capabilities).
• media_ids array: Media to attach, in order (ids from list_media, import_media or an upload).
• destinations array, required: Where the post goes: one entry per connected account (ids from list_social_accounts).

Creates a post for one or more accounts. It is sent only when you say when: scheduled_at publishes at that time, publish: "now" publishes right away. Without either (or with draft: true) it is only saved as a draft and nothing is posted; tell the person, and call publish_post when they want it sent. To schedule a series, call it once per post with each time. Unknown fields are refused. The result's next_step says what happens. If the post has problems it is saved as a draft and the problems are returned.

POST /api/v1/posts · postsocial create-post

• caption string: The shared caption. Each platform's limit is checked (see list_social_accounts capabilities).
• media_ids array: Media to attach, in order (ids from list_media, import_media or an upload).
• destinations array, required: Where the post goes: one entry per connected account (ids from list_social_accounts).
• scheduled_at string: When to publish, in ISO 8601 with a timezone, e.g. 2026-10-05T15:00:00Z. Up to a year ahead. Without scheduled_at (or publish: "now") the post is only saved as a draft.
• publish string: Set to "now" to publish right away. Only use it when the person asked for the post to go out now. Not with scheduled_at or draft.
• draft boolean: Only save a draft; do not send or schedule.

Lists posts, newest first. Each post has published_at (when it first went out on any account; null until then), its destinations (one per account: status, live_url, published_at, error) and media (in order: id, media_type, mime_type, name, status, width, height, duration_seconds, url and thumbnail_url; url and thumbnail_url are temporary view links valid 1 hour, null until the item is ready; thumbnail_url is the image itself or a video's poster frame). Each account is named by its profile name (account), its platform and its handle (account_handle, without the @; null for LinkedIn, Facebook Pages and YouTube, which share no handle with Post Social), so two accounts with the same name can be told apart.

GET /api/v1/posts · postsocial list-posts

• status string
• platform string
• limit integer: How many to return (1 to 100).
• offset integer: How many to skip, for paging.

Gets one post with its caption, published_at (when it first went out on any account; null until then), each account's status, live_url, published_at and errors, its approval state, media_ids and media (in order: id, media_type, mime_type, name, status, width, height, duration_seconds, url and thumbnail_url; url and thumbnail_url are temporary view links valid 1 hour, null until the item is ready; thumbnail_url is the image itself or a video's poster frame). Each account is named by its profile name (account), its platform and its handle (account_handle, without the @; null for LinkedIn, Facebook Pages and YouTube, which share no handle with Post Social), so two accounts with the same name can be told apart. If the post is publishing right now, waits up to about 25 seconds for the accounts still sending, so the live links are usually all there.

GET /api/v1/posts/{post_id} · postsocial get-post

• post_id string, required: The post id.

Edits a draft, a post waiting for approval, or a scheduled post: its caption, time, media or accounts. Only the fields you pass change; media_ids and destinations each replace the whole list (to swap an image, upload the new one and pass its id in media_ids). To change a scheduled post, edit it here instead of creating a new post, which would publish twice. Editing an approved or scheduled post may send it back for approval.

PATCH /api/v1/posts/{post_id} · postsocial update-post

• post_id string, required: The post id.
• caption string: The shared caption. Each platform's limit is checked (see list_social_accounts capabilities).
• media_ids array: Media to attach, in order (ids from list_media, import_media or an upload).
• destinations array: Where the post goes: one entry per connected account (ids from list_social_accounts).
• scheduled_at string: When to publish, in ISO 8601 with a timezone, e.g. 2026-10-05T15:00:00Z. Up to a year ahead.

Publishes a draft now, or schedules it with scheduled_at.

POST /api/v1/posts/{post_id}/publish · postsocial publish-post

• post_id string, required: The post id.
• scheduled_at string: When to publish, in ISO 8601 with a timezone, e.g. 2026-10-05T15:00:00Z. Up to a year ahead. Leave out to publish now.

Changes the time of a scheduled post that has not started sending.

POST /api/v1/posts/{post_id}/reschedule · postsocial reschedule-post

• post_id string, required: The post id.
• scheduled_at string, required: The new time, ISO 8601 with a timezone.

Cancels a draft, a post waiting for approval, or a scheduled post before it starts sending. Posts already sent cannot be cancelled.

POST /api/v1/posts/{post_id}/cancel · postsocial cancel-post

• post_id string, required: The post id.

Permanently deletes a draft or a cancelled post. Sent posts are kept for the record.

DELETE /api/v1/posts/{post_id} · postsocial delete-post

• post_id string, required: The post id.

Shows usage for a period: posts published (by account and by who made them), posts created by AI, failed publishes, API calls per connection, a day-by-day series, and how close the workspace is to each plan limit.

GET /api/v1/usage · postsocial get-usage

• period string: Which period, in UTC.

Lists published posts with their stats (views, likes, comments, shares, and saves, reposts or quotes where the platform reports them), plus totals per platform. Sort by any stat to find what performed best.

GET /api/v1/analytics · postsocial list-analytics

• platform string
• period string: Posts published in this period.
• sort string
• limit integer: How many to return (1 to 100).
• offset integer: How many to skip, for paging.

Shows one post's stats on each platform it went to, with a day-by-day history.

GET /api/v1/posts/{post_id}/analytics · postsocial get-post-analytics

• post_id string, required: The post id.

Fetches fresh stats from the platforms for one post (or all recent posts) instead of waiting for the next automatic update. At most every 30 minutes per post.

POST /api/v1/analytics/refresh · postsocial refresh-analytics

• post_id string: The post id.

Shows each account's outcome: published (with the live link), failed (with the platform's reason in plain language), or still in progress. One post's results (waiting up to about 25 seconds for accounts still sending), or the most recent overall. Each account is named by its profile name (account), its platform and its handle (account_handle, without the @; null for LinkedIn, Facebook Pages and YouTube, which share no handle with Post Social), so two accounts with the same name can be told apart.

GET /api/v1/results · postsocial list-post-results

• post_id string: The post id.
• limit integer: How many to return (1 to 100).
• offset integer: How many to skip, for paging.