Skip to main content

API Reference

The Upload-Post API provides comprehensive endpoints for content management across multiple social media platforms. All endpoints require authentication via API key in the Authorization header.

Core Upload APIs​

Video Upload API​

Upload videos to TikTok, Instagram, LinkedIn, YouTube, Facebook, X (Twitter), Threads, Pinterest, Bluesky, Discord, Telegram, and Google Business Profile. Supports both synchronous and asynchronous uploads with scheduling capabilities. Reddit posting is currently unavailable (HTTP 503 error_code: "reddit_unavailable").

Endpoint: POST /api/upload

Supported Platforms: TikTok, Instagram, LinkedIn, YouTube, Facebook, X (Twitter), Threads, Pinterest, Bluesky, Discord, Telegram, Google Business Profile, Mastodon, WordPress. Reddit posting is currently unavailable (reddit_unavailable).

Photo Upload API​

Upload photos and image carousels to LinkedIn, Facebook, X (Twitter), Instagram, TikTok, Threads, Pinterest, Bluesky, Discord, Telegram, and Google Business Profile. Perfect for visual content distribution across platforms. Reddit posting is currently unavailable.

Endpoint: POST /api/upload_photos

Supported Platforms: LinkedIn, Facebook, X (Twitter), Instagram, TikTok, Threads, Pinterest, Bluesky, Discord, Telegram, Google Business Profile, Mastodon, Lemmy, WordPress. Reddit posting is currently unavailable (reddit_unavailable).

Text Upload API​

Create and distribute text-only posts across social platforms. Ideal for announcements, updates, and text-based content.

Endpoint: POST /api/upload_text

Supported Platforms: X (Twitter), LinkedIn, Facebook, Threads, Bluesky, Discord, Telegram, Google Business Profile, Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop, Listmonk. Reddit posting is currently unavailable (reddit_unavailable).

Also covers: LinkedIn polls (linkedin_poll_question + linkedin_poll_options[]) and long-form X Articles (x_article_title, publish or save as draft).

Platform How-To Guides​

Step-by-step guides for the most requested platforms, with cURL, Python and JavaScript examples:

Upload Management APIs​

Webhooks & Notifications​

Real-time POST notifications for upload results and social account connection changes, signed with HMAC-SHA256 (X-Upload-Post-Signature). Account-level and per-profile webhooks.

Endpoints: GET/POST/DELETE /api/uploadposts/users/notifications, POST /api/uploadposts/users/webhook-secret, GET/POST/DELETE /api/uploadposts/users/profile-webhook

Upload Status​

Track the progress and results of asynchronous uploads initiated with async_upload=true or scheduled posts. Essential for monitoring long-running upload operations and checking scheduled post execution status.

Endpoint: GET /api/uploadposts/status

Parameters: request_id (for async uploads) or job_id (for scheduled posts)

Use Case: Check status of background uploads and scheduled posts, get detailed results per platform

Upload History​

Retrieve a paginated history of all your past uploads across platforms. Includes detailed metadata, success/failure status, and platform-specific information.

Endpoint: GET /api/uploadposts/history

Features: Pagination, filtering, comprehensive upload metadata

Filters: platform, status, profile_username, start/end, and exact request_id / job_id / external_id lookups

Schedule Management​

Schedule posts for future publication across supported platforms. Manage your content calendar programmatically.

Endpoint: Various scheduling endpoints

Supported Platforms: X (Twitter), LinkedIn, Facebook, Instagram, TikTok, Bluesky, Threads, Pinterest, YouTube, Discord, Telegram

Correlation: Send an external_id on upload to map scheduled jobs back to records in your own system without matching on the (editable) title.

AI Shorts API​

Send a short-form video and get AI-written titles, descriptions, captions and hashtags per platform, or rewrite existing captions into another language. Uses the monthly AI Shorts quota of your plan.

Endpoints: POST /api/uploadposts/analyze-shorts, POST /api/uploadposts/rewrite-captions

Supported Platforms: YouTube, Instagram, TikTok, Facebook

Set YouTube Thumbnail​

Set or replace the custom thumbnail of an already-published YouTube video from a file or a public URL.

Endpoint: POST /api/uploadposts/youtube/thumbnail

Supported Platforms: YouTube

Instagram Interactions​

Media List​

Retrieve a list of recent media (posts, reels, videos, pins, tweets, etc.) from any connected social media account. Supports Instagram, TikTok, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, and Reddit.

Endpoint: GET /api/uploadposts/media

Returns: Media IDs, captions, media types, permalinks, timestamps, thumbnail URLs

Pagination: limit (default 25, max 100, capped per platform) and cursor for cursor-based paging. LinkedIn, Discord and Telegram support limit only.

Comments (all platforms)​

List, create and delete comments on your posts across Instagram, Facebook, YouTube, LinkedIn, TikTok, X, Threads and Bluesky with one consistent API. Reddit comments return 503 reddit_unavailable.

Endpoints:

  • GET /api/uploadposts/comments - List comments on a post; add comment_id to get the replies under one comment instead
  • POST /api/uploadposts/comments/create - Comment on a post or reply to a comment
  • DELETE /api/uploadposts/comments/delete - Delete a comment
  • POST /api/uploadposts/comments/action - platform-specific verbs (hide / unhide, like / unlike, pin / unpin, Facebook edit, YouTube hold, Instagram enable_comments / disable_comments, Threads approve / ignore)

TikTok: supported on accounts that report the comments capability, i.e. reconnected accounts. post_id is the video id. A comment created on TikTok takes ~10 s to appear in a listing.

Instagram Comments​

Retrieve comments on Instagram posts and send private replies (DMs) to commenters. Supports both media IDs and post URLs.

Endpoints:

  • GET /api/uploadposts/comments - Get comments on an Instagram post
  • POST /api/uploadposts/comments/reply - Send a private reply DM to a commenter

Required Permission: instagram_business_manage_comments

Instagram Direct Messages​

Send direct messages to Instagram users and retrieve DM conversations. Supports customer support workflows and follow-up messaging within Instagram's 24-hour messaging window policy.

Endpoints:

  • POST /api/uploadposts/dms/send - Send a DM to an Instagram user by IGSID
  • GET /api/uploadposts/dms/conversations - Retrieve Instagram DM conversations

Required Permission: instagram_business_manage_messages

AutoDM Monitors​

Set up persistent monitors that automatically send private DMs to users who comment on your Instagram posts. Monitors run in the background 24/7 with built-in duplicate prevention and rate limiting.

Endpoints:

  • POST /api/uploadposts/autodms/start - Start a new comment monitor
  • GET /api/uploadposts/autodms/status - Get status of all monitors (supports ?include_inactive=true to also return stopped/expired ones)
  • GET /api/uploadposts/autodms/logs - Get activity logs for a monitor
  • POST /api/uploadposts/autodms/pause - Pause a monitor
  • POST /api/uploadposts/autodms/resume - Resume a paused monitor
  • POST /api/uploadposts/autodms/stop - Stop a monitor
  • POST /api/uploadposts/autodms/delete - Delete a monitor

Limits: 2 monitors per profile per day, auto-expires after 15 days

Platform Integration APIs​

Analytics API​

Retrieve detailed analytics and performance metrics for your social media profiles across connected platforms.

Endpoint: GET /api/analytics/{profile_username}

Supported Platforms: Instagram, TikTok, LinkedIn, Facebook, X (Twitter), YouTube, Threads, Pinterest, Reddit

Metrics: Followers, impressions, reach, profile views, time-series data, metric_type, Instagram follower_demographics and engaged_audience_demographics

Total Impressions & Post Analytics​

Get unified total impressions aggregated across platforms, per-post analytics, and platform metrics config. All analytics endpoints are consolidated in the Analytics API page.

Endpoints: GET /api/uploadposts/total-impressions/{profile_username} · GET /api/uploadposts/post-analytics/{request_id} · GET /api/uploadposts/post-analytics?platform_post_id= · GET /api/uploadposts/post-analytics/cached

Features: Date range filtering, per-platform breakdown, live post metrics, profile snapshots, analytics for organic posts via platform_post_id, and the full TikTok per-post breakdown (retention curve, impression sources, audience types, reach, favorites, new followers)

Cached Post Analytics​

Bulk replay of per-post metrics Upload-Post already fetched, instead of calling the platforms again. Only contains posts previously read through a live endpoint; there is no background refresh. Not subject to the 100 requests / 5 minutes platform analytics rate limit.

Endpoint: GET /api/uploadposts/post-analytics/cached

Features: Cursor pagination (up to 200 posts per page), platform filter, since/until date range, per-row captured_at freshness marker

Audience Insights​

Who follows an account, when they are online, what they tap on the profile and how it compares to its category. One endpoint with a platform, the same shape as /comments and /post-analytics. activity_by_hour is the field to build a publishing schedule on.

Endpoint: GET /api/uploadposts/audience

Returns: range (the window actually used, after trimming), audience (countries / cities / ages / genders), activity_by_hour, followers_daily, profile_actions, bio_description, benchmark_categories, and benchmark when benchmark_category is sent

Supported platforms: tiktok

Required capability: profile_analytics

Get Facebook Pages​

Retrieve all Facebook pages accessible through connected accounts. Required for posting to specific Facebook pages.

Endpoint: GET /api/uploadposts/facebook/pages

Returns: Page IDs, names, profile pictures, account associations

Pin a Facebook Page to a Profile​

Pin one Facebook Page to a profile so every upload from that profile targets it without passing facebook_page_id. The pin takes precedence over the request parameter.

Endpoint: GET/POST/DELETE /api/uploadposts/users/facebook-page

Returns: Available Pages plus the pinned facebook_page_id / facebook_page_name

Get LinkedIn Pages​

Fetch LinkedIn company pages associated with your connected accounts. Essential for business page posting.

Endpoint: GET /api/uploadposts/linkedin/pages

Returns: Organization URNs, company names, vanity URLs, page logos

Pin a LinkedIn Page to a Profile​

Pin one LinkedIn company Page to a profile so every upload from that profile posts as that Page without passing target_linkedin_page_id. The pin takes precedence over the request parameter.

Endpoint: GET/POST/DELETE /api/uploadposts/users/linkedin-page

Returns: Available Pages plus the pinned linkedin_page_id / linkedin_page_name

Get Google Business Locations​

List the Google Business Profile locations available to an account. Essential for agencies and SaaS platforms where users manage multiple locations. Pass the chosen location's name as gbp_location_id on the upload request, or pin it to the profile once and omit the parameter.

Endpoint: GET /api/uploadposts/google-business/locations

Returns: Location IDs and business names

Post destinations: Local Posts (the "Updates" tab, default) or the location's Media/Gallery tab via gbp_post_type=MEDIA + gbp_media_category

Pin a Google Business Location to a Profile​

Pin one Google Business location to a profile so every upload from that profile publishes there without passing gbp_location_id. Google's OAuth chooser only picks the Google account, so this is how a multi-location account stops being asked to select one on every post. The pin takes precedence over the request parameter.

Endpoint: GET/POST/DELETE /api/uploadposts/users/google-business-location

Returns: Available locations plus the pinned gbp_location_id / gbp_location_name

Get Pinterest Boards​

List all Pinterest boards (public and secret) from connected accounts. Required for targeting specific boards when pinning content.

Endpoint: GET /api/uploadposts/pinterest/boards

Returns: Board IDs, names, associated Pinterest accounts

List trending tracks from TikTok's Commercial Music Library — the catalogue of songs you can attach to a video through the API with tiktok_music_id.

Endpoint: GET /api/uploadposts/tiktok/music/trending

Returns: Track id (what you send as tiktok_music_id), titles, artists, duration, artwork and audio previews

Search TikTok Music​

Search the Commercial Music Library by song title or artist. TikTok has no music search endpoint, so the search runs over the trending charts Upload-Post caches — not over TikTok's whole catalogue.

Endpoint: GET /api/uploadposts/tiktok/music/search

Returns: The same track objects as the trending endpoint, ranked by relevance

Get TikTok Locations​

Search TikTok places to tag a location on a post with tiktok_location_id + tiktok_location_name.

Endpoint: GET /api/uploadposts/tiktok/locations

Returns: location_id, location_name and postal address (max 20 matches)

Get TikTok Publishing Settings​

What a connected TikTok account is actually allowed to publish. TikTok narrows the four privacy_level values per account — a private account has no PUBLIC_TO_EVERYONE — so ask here before offering them.

Endpoint: GET /api/uploadposts/tiktok/settings

Returns: privacy_level_options, max_video_post_duration_sec and the account's comment / duet / stitch switches

Instagram Publishing Limit​

Remaining Instagram content-publishing quota for a connected profile.

Endpoint: GET /api/uploadposts/instagram/publishing_limit

Threads Publishing Limit​

Remaining Threads posts and replies quota (250 posts / 1000 replies per 24 hours).

Endpoint: GET /api/uploadposts/threads/publishing_limit

Retry a Failed Upload​

Re-enqueue platforms that failed on an upload. The original media snapshot is reused.

Endpoint: POST /api/uploadposts/posts/retry

Unpublish a Published Post​

Delete a live post. Instagram, TikTok and Threads are not supported.

Endpoint: POST /api/uploadposts/posts/unpublish

Edit a Published Post​

Update caption or metadata on a live Facebook, LinkedIn, X, YouTube or Google Business post.

Endpoint: POST /api/uploadposts/posts/edit

Repost​

Reshare a LinkedIn post or retweet an X post.

Endpoint: POST /api/uploadposts/posts/repost

Save a Pinterest Pin​

Save (repin) a Pinterest pin onto a board.

Endpoint: POST /api/uploadposts/posts/save

Suggestions​

What to tag a post with and what people search around a keyword. One endpoint with a platform and a type, not one per network.

Endpoint: GET /api/uploadposts/suggestions

Returns: hashtags[] with name (no leading #) and view_count for type=hashtags; keywords[] with each term and its search volume for type=keywords

Supported platforms: tiktok

Required capability: profile_analytics for type=hashtags; trend_search (reconnected account) for type=keywords

ChatGPT Ads​

Run ads inside ChatGPT from the same API key you publish with. Connect an OpenAI Ads account once, then create campaigns, ad groups and ads, upload creatives and pull performance insights. Spend runs on your own OpenAI billing; every object is created paused unless you ask for active.

Endpoints: POST /api/uploadposts/ads/chatgpt/connect, GET/DELETE /api/uploadposts/ads/chatgpt/accounts, GET/POST /api/uploadposts/ads/chatgpt/campaigns, GET/POST /api/uploadposts/ads/chatgpt/adgroups, GET/POST /api/uploadposts/ads/chatgpt/ads, POST /api/uploadposts/ads/chatgpt/creatives, POST /api/uploadposts/ads/chatgpt/promote, GET /api/uploadposts/ads/chatgpt/insights

Requires: an OpenAI Ads Manager account and an API key from ads.openai.com (one key per ad account)

User Management APIs​

User Profiles API​

Manage user profiles and generate JWTs for linking social accounts when integrating Upload-Post into your own platform. Essential for white-label integrations and multi-user applications.

Endpoints:

  • POST /api/uploadposts/users - Create user profiles
  • GET /api/uploadposts/users - Retrieve user profiles
  • DELETE /api/uploadposts/users - Delete user profiles
  • POST /api/uploadposts/users/generate-jwt - Generate authentication tokens
  • GET /api/uploadposts/users/validate-jwt - Validate tokens

White-label: the connect page supports en, es, de, fr, pt, pl and tr, plus per-key text overrides via ui_labels.

See the User Profile Integration Guide for implementation workflow.

Connect API​

Build your own social account connection page instead of using the hosted one. Server-side OAuth start endpoints return the authorize URL for each platform; a single-use state authenticates the callback, and the end user returns to your redirect_url with connect_status=success|cancelled|error and a stable error_code on failure.

Endpoint:

  • POST /api/uploadposts/oauth/{platform}/start - Get the authorize URL for a platform

Supported Platforms: TikTok, Instagram, Facebook, LinkedIn, YouTube, X (Twitter), Threads, Reddit, Pinterest, Google Business Profile, Snapchat

Current User API​

Validate your API key and retrieve basic account information including email and subscription plan.

Endpoint: GET /api/uploadposts/me

Use Case: API key validation, plan verification, account confirmation

Content Requirements​

Photo Requirements​

Comprehensive format specifications, file size limits, aspect ratios, and technical requirements for photo uploads across all supported platforms.

Covers: Instagram, TikTok, Facebook, X (Twitter), LinkedIn, Threads, Pinterest, Reddit, Bluesky, Discord, Telegram

Video Requirements​

Detailed video format requirements, codec specifications, resolution limits, and encoding guidelines for optimal compatibility across platforms.

Covers: TikTok, Instagram, YouTube, LinkedIn, Facebook, X (Twitter), Threads, Pinterest, Reddit, Bluesky, Discord, Telegram

Includes: FFmpeg re-encoding solutions for compatibility issues

MCP Server (AI Agents)​

MCP Server Integration​

Every endpoint on this page is also exposed through Upload-Post's official, open-source Model Context Protocol server. Point ChatGPT, claude.ai, Claude Desktop, Claude Code or Cursor at it and your agent can publish, schedule and analyze content without a hand-written REST client.

Hosted endpoint: https://mcp.upload-post.com/mcp

In ChatGPT: listed as a reviewed app in the ChatGPT app directory — add Upload-Post in ChatGPT in one click, no Developer mode required

Authentication: API key, or OAuth 2.1 with PKCE for agents that authorize themselves

Source: github.com/Upload-Post/upload-post-mcp (MIT)

Getting Started​

  1. Authentication: All requests require an API key in the Authorization: Apikey your-api-key-here header
  2. Base URL: https://api.upload-post.com/api
  3. Rate Limits: Free tier includes 10 uploads per month
  4. Content Guidelines: Review platform-specific requirements before uploading

For implementation examples and integration guides, see our SDK Examples and Integration Guides.