/api/v1/workspaces
List all workspaces
Returns all workspaces the authenticated user owns.
No parameters.
API reference
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.
All API requests must be authenticated using a Bearer token in the Authorization header.
# 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"
Postspread uses standard HTTP status codes. All errors return a JSON body with an error or message key.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — invalid or missing token |
| 403 | Forbidden — insufficient permissions or plan |
| 404 | Resource not found |
| 422 | Validation error — check the errors object |
| 500 | Server error |
List endpoints return a data array and a meta object.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of items per page (default: 10) |
| page | integer | Page number (default: 1) |
{
"data": [ // array of items ],
"meta": {
"total": 48,
"offset": 0,
"limit": 10,
"next": "https://postspread.com/api/v1/posts?page=2"
}
}
Retrieve workspaces you own. Most other endpoints scope their data to your active workspace.
/api/v1/workspaces
Returns all workspaces the authenticated user owns.
No parameters.
Create, schedule, list, update, and delete social media posts.
/api/v1/posts
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.
| Name | Type | Description |
|---|---|---|
| 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. |
/api/v1/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.
| Name | Type | Description |
|---|---|---|
| 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). |
/api/v1/posts/{id}
Returns one post record with its settings, per-platform publish results, first-comment state and links to the live post.
| Name | Type | Description |
|---|---|---|
| id required | integer | Post ID. |
/api/v1/posts/{id}
Changes a draft or scheduled post. Fields you leave out keep their current value. Published posts cannot be changed.
| Name | Type | Description |
|---|---|---|
| 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. |
/api/v1/posts/{id}
Deletes a draft or scheduled post. Published posts cannot be deleted.
| Name | Type | Description |
|---|---|---|
| id required | integer | Post ID. |
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.
media_id to a post promptly./api/v1/media/upload
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.
| Name | Type | Description |
|---|---|---|
| file required | file | The binary file, sent as the file form field. |
/api/v1/media
Returns all media files uploaded by the authenticated user.
| Name | Type | Description |
|---|---|---|
| limit optional | integer | Items per page (default 10). |
/api/v1/media/{id}
Returns the details and public URL for a single media file.
| Name | Type | Description |
|---|---|---|
| id required | integer | Media ID. |
/api/v1/media/{id}
Permanently deletes a media file and removes it from storage.
| Name | Type | Description |
|---|---|---|
| id required | integer | Media ID. |
Retrieve social accounts connected to your workspace. Use the account IDs when creating posts with per-account targeting.
/api/v1/social-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.
| Name | Type | Description |
|---|---|---|
| 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). |
/api/v1/social-accounts/{id}
Returns details for a single connected social account.
| Name | Type | Description |
|---|---|---|
| id required | integer | Social account ID. |
/api/v1/social-accounts/{id}/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.
| Name | Type | Description |
|---|---|---|
| id required | integer | A Discord or Slack account ID from GET /social-accounts. |
Retrieve the publishing results and platform responses for published posts.
/api/v1/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.
| Name | Type | Description |
|---|---|---|
| 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. |
/api/v1/post-results/{id}
The publish result for one post record.
| Name | Type | Description |
|---|---|---|
| id required | integer | Post ID. |
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.
/api/v1/analytics
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.
| Name | Type | Description |
|---|---|---|
| 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). |
/api/v1/analytics?platform=instagram&days=7
Each Instagram account in your workspaces with its numbers for the last 7 days. Kept for an hour per account and period.
No parameters.
/api/v1/analytics/{id}
The account-stats row for a single connected account.
| Name | Type | Description |
|---|---|---|
| id required | integer | Social account ID (from GET /social-accounts). |
/api/v1/analytics/sync
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.