Skip to content

API reference

PostSpread API

Automate publishing, upload media, manage connected accounts and pull analytics over a simple REST API. Every endpoint below shows the request on the left and a real response on the right.

BASE URL https://postspread.com/api/v1

Authentication

All API requests must be authenticated using a Bearer token in the Authorization header.

Generate an API key from Settings → API Keys in your PostSpread dashboard. AI assistants (Claude, ChatGPT, Claude Code) don't need a key: they sign in through OAuth via the MCP connector, and the same endpoints below answer their calls.
# Include this header with every request
Authorization: Bearer YOUR_API_KEY
# Example curl
curl https://postspread.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Errors

Postspread uses standard HTTP status codes. All errors return a JSON body with an error or message key.

CodeMeaning
200Success
400Bad request — invalid parameters
401Unauthorized — invalid or missing token
403Forbidden — insufficient permissions or plan
404Resource not found
422Validation error — check the errors object
500Server error

Workspaces WORKSPACE

Retrieve workspaces you own. Most other endpoints scope their data to your active workspace.

GET /api/v1/workspaces

List all workspaces

Returns all workspaces the authenticated user owns.

No parameters.

Posts POSTS

Create, schedule, list, update, and delete social media posts.

POST /api/v1/posts

Create a post

Creates one post record per account and returns their ids in post_ids. Omit scheduled_at to publish right away (publishing runs in the background: poll GET /posts/{id} or GET /post-results?post_id= for the outcome and live link), set it to schedule, or set is_draft to save without publishing. Attach media with media_ids from POST /media/upload or public media_urls.

Team approvals: if the workspace requires approval and the token belongs to a member (not an owner or admin), the post is held with status: pending_approval and the response carries pending_approval: true. An owner or admin approves it in PostSpread.

X (Twitter): needs the Bloom or Forest plan; a 403 with upgrade_required is returned otherwise. X posts are counted per calendar month against the workspace owner's plan (Bloom 300, Forest 1,000), and every post sent to X counts, thread parts and each X account included. A post that would go past this month's allowance gets a 403 with x_limit_reached and x_posts (limit, used, resets_on). Links are removed from X posts and thread parts (full URLs and bare domains like example.com); the rest of the text posts as written. A post that is only a link fails, unless it has media.

Parameters
NameTypeDescription
caption required string The post text (up to 60,000 characters; each platform's own limit still applies).
social_accounts required integer[] Account IDs from GET /social-accounts. The workspace is resolved from these; no workspace_id is needed. Ids are looked up only inside your own workspaces.
social_account_details optional object[] Optional [{"id": 12, "account_type": "instagram_account"}] pairs (from GET /social-accounts) to make the lookup explicit when ids overlap across account types.
scheduled_at optional datetime ISO 8601 with timezone, at least 5 minutes ahead. Omit to publish immediately.
is_draft optional boolean Save as a draft; nothing is published or scheduled.
title optional string Optional title (used for YouTube and Pinterest when they have none of their own).
media_urls optional string[] Public image/video URLs. PostSpread downloads and stores them.
media_ids optional integer[] IDs returned by POST /media/upload or GET /media.
platform_configurations optional object Per-platform options, see the object below. Unknown keys are stored as-is.
platform_configurations.first_comment optional string First comment posted under the post on Facebook, Instagram, LinkedIn and Telegram (a reply to the message). Override per platform with facebook.first_comment etc.
platform_configurations.first_comment_delay_minutes optional integer 0 to 1440. Wait this long after publishing before posting the first comment.
platform_configurations.first_comment_image_url optional string Public image URL attached to the first comment on Facebook, LinkedIn and Telegram. Instagram comments are text only.
platform_configurations.thread optional array Extra parts for X, Threads and Bluesky (up to 6). Strings, or objects {"text": "…", "media_urls": ["…"]}. The caption is part 1.
platform_configurations.instagram optional object post_type: feed (default) or stories. A feed post with a single video is published as a Reel automatically; reels is accepted as an alias of feed. collaborators: up to 3 usernames (feed posts only). Stories take no caption, collaborators, thumbnail or first comment; several files are published as consecutive stories.
platform_configurations.pinterest optional object board_id (required for Pinterest), title (100 chars), link, alt_text. Several images become a carousel pin; video pins use the first image as cover.
platform_configurations.youtube optional object title (100 chars). The caption becomes the video description.
platform_configurations.tiktok optional object One video or 1–10 images. title (optional, photo posts only, 90 chars; videos use the caption), privacy_level (PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR or SELF_ONLY; public / friends / private are accepted too), allow_comments, allow_duet, allow_stitch, disclose_content, your_brand, branded_content.
platform_configurations.discord optional object channel: the Discord channel id to post in (required for Discord; get ids from GET /social-accounts/{id}/channels). Up to 10 files, 2,000 characters.
platform_configurations.slack optional object channel: the Slack channel id to post in (required for Slack; get ids from GET /social-accounts/{id}/channels). Images only, 3,000 characters.
platform_configurations.mastodon optional object visibility: public (default), unlisted or private. Up to 4 images or 1 video.
platform_configurations.twitter optional object community: post into an X Community, as its link (https://x.com/i/communities/1493446837214187523) or its id. The X account must have joined it. share_with_followers (default true) also shows the post to the account's followers. In a thread only the first post goes to the community.
GET /api/v1/posts

List posts

Returns posts from every workspace you belong to, newest first. One record per account: a post sent to two accounts appears twice, sharing a post_ref_id. Published posts include links to the live post on each network.

Parameters
NameTypeDescription
status optional string draft, scheduled, processing, published, failed or pending_approval.
platform optional string twitter, instagram, linkedin, facebook, tiktok, threads, bluesky, pinterest, youtube, telegram, mastodon, discord or slack.
limit optional integer Items per page (default 10, max 50).
page optional integer Page number (default 1).
GET /api/v1/posts/{id}

Get a post

Returns one post record with its settings, per-platform publish results, first-comment state and links to the live post.

Parameters
NameTypeDescription
id required integer Post ID.
PATCH /api/v1/posts/{id}

Update a post

Changes a draft or scheduled post. Fields you leave out keep their current value. Published posts cannot be changed.

Parameters
NameTypeDescription
caption optional string New post text.
scheduled_at optional datetime New time (ISO 8601 with timezone).
is_draft optional boolean Set false with a scheduled_at to turn a draft into a scheduled post.
social_accounts optional integer[] Replace the target accounts.
media_ids optional integer[] Replace attached media.
platform_configurations optional object Same object as on create.
DELETE /api/v1/posts/{id}

Delete a post

Deletes a draft or scheduled post. Published posts cannot be deleted.

Parameters
NameTypeDescription
id required integer Post ID.

Media MEDIA

Upload images or videos and attach them to posts using the returned media_id. Uploaded media expires after 24 hours if not attached to a post.

24-hour expiry: Unattached media is automatically deleted after 24 hours. Always attach the returned media_id to a post promptly.
POST /api/v1/media/upload

Upload media

Uploads one image or video as multipart/form-data and returns its id and public url. Use the id in media_ids when creating a post. Limits: 150MB on Free, 500MB on paid plans; jpg, png, gif, webp, heic, mp4, mov, webm, mkv, avi. A 413 means the file is over the plan or server limit.

Parameters
NameTypeDescription
file required file The binary file, sent as the file form field.
GET /api/v1/media

List media

Returns all media files uploaded by the authenticated user.

Parameters
NameTypeDescription
limit optional integer Items per page (default 10).
GET /api/v1/media/{id}

Get media by ID

Returns the details and public URL for a single media file.

Parameters
NameTypeDescription
id required integer Media ID.
DELETE /api/v1/media/{id}

Delete media

Permanently deletes a media file and removes it from storage.

Parameters
NameTypeDescription
id required integer Media ID.

Social Accounts ACCOUNTS

Retrieve social accounts connected to your workspace. Use the account IDs when creating posts with per-account targeting.

GET /api/v1/social-accounts

List connected accounts

Returns every social account connected in the workspaces you belong to. Use id values in social_accounts when posting; account_type tells PostSpread which table the id refers to and speeds up workspace resolution when passed back as social_account_details.

Parameters
NameTypeDescription
platform optional string Filter by platform: twitter, instagram, linkedin, facebook, tiktok, threads, bluesky, pinterest, youtube, telegram, mastodon, discord, slack.
limit optional integer Items per page (default 10).
offset optional integer Items to skip (default 0).
GET /api/v1/social-accounts/{id}

Get account by ID

Returns details for a single connected social account.

Parameters
NameTypeDescription
id required integer Social account ID.
GET /api/v1/social-accounts/{id}/channels

List Discord or Slack channels

Channels of a connected Discord server or Slack workspace. Discord and Slack posts need one of these ids in platform_configurations.discord.channel or platform_configurations.slack.channel. Discord channels carry their category in group; Slack private channels only appear once the app has been invited to them.

Parameters
NameTypeDescription
id required integer A Discord or Slack account ID from GET /social-accounts.

Post Results RESULTS

Retrieve the publishing results and platform responses for published posts.

GET /api/v1/post-results

List post results

Per-platform outcome of each processed post, newest first: the raw results PostSpread stored when publishing (ids on the network, errors, first-comment state) plus links to the live post.

Parameters
NameTypeDescription
post_id optional integer|integer[] One post ID or several (post_id[]=1&post_id[]=2), e.g. the post_ids returned when creating.
status optional string published, failed or processing.
limit optional integer Items per page (default 10, max 50).
page optional integer Page number.
GET /api/v1/post-results/{id}

Get result by ID

The publish result for one post record.

Parameters
NameTypeDescription
id required integer Post ID.

Analytics ANALYTICS

Follower and post counts for every connected account, plus each account's analytics on a network: the same numbers as the Analytics page in PostSpread, fetched from the network and kept for an hour. Call /analytics/sync to refresh.

GET /api/v1/analytics

Account stats and platform insights

Without platform: one row per connected account with followers, posts and when the numbers were last refreshed. With platform: every account on that network in each workspace you belong to, with its metrics. A series metric has a value per day in points, its value for the period (added up, or averaged for rates) and change, the percentage against the period before when the network reports far enough back. A total metric is one figure, such as followers. Formats: number, percent (0.042 is 4.2%), seconds, minutes. An account the network refuses has error and reason (reconnect, unsupported or error) instead. Available for instagram, facebook, linkedin (company pages), tiktok, youtube, threads, pinterest and bluesky.

Parameters
NameTypeDescription
platform optional string Return analytics for each account on this network instead of account stats.
days optional integer 7 (default), 30 or 90. Snapped to what the network offers: Instagram and Threads go to 30, TikTok only has current totals. trend (7d, 30d, 90d) still works.
workspace_id optional integer Limit to one workspace.
limit optional integer Account rows per page (default 50).
GET /api/v1/analytics?platform=instagram&days=7

Analytics for one network

Each Instagram account in your workspaces with its numbers for the last 7 days. Kept for an hour per account and period.

No parameters.

GET /api/v1/analytics/{id}

Stats for one account

The account-stats row for a single connected account.

Parameters
NameTypeDescription
id required integer Social account ID (from GET /social-accounts).
POST /api/v1/analytics/sync

Refresh stats

Pulls fresh follower and post counts from the networks for up to 25 of your accounts, clears the kept analytics so the next request fetches new numbers, and returns the refreshed account rows. Takes a few seconds per account.

No parameters.