Developers — Social Media Publishing & Scheduling API

Introduction

The Faceless Post Automation API is a simple REST API for scheduling and publishing social content at scale. Send one JSON request and we handle uploads, per-platform formatting, scheduling, and delivery through each network’s official API.

6 platforms from one call
Publish now or schedule for later
Per-platform captions & formats
Webhooks on publish / failure

Authentication

Authenticate every request with a Bearer API key in the Authorization header. Create and manage keys from your dashboard under Automation API. Keep keys secret — treat them like passwords and never expose them in client-side code.

Authorization header

Authorization: Bearer YOUR_API_KEY

Base URL & Endpoints

All endpoints are relative to the base URL:

Base URL

https://facelesspost.com/api/automation/v1

POST

/posts

Publish immediately or schedule a post across one or more connected channels.

GET

/channels

List your connected channels with their numeric account IDs.

Quickstart — publish a post

Send a POST to /posts with your caption, media, and target channels:

curl -X POST "https://facelesspost.com/api/automation/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "account_ids": [
    10482913
  ],
  "caption": "How we automated our entire creator workflow 🚀 #creator #automation",
  "title": "Automate Faceless Channels in 2026",
  "media_urls": [
    "https://cdn.example.com/videos/reel-1080p.mp4"
  ],
  "thumbnail": "https://cdn.example.com/thumbnails/cover.jpg",
  "mode": "scheduled",
  "schedule_at": "2026-10-15T14:30:00Z",
  "timezone": "America/New_York",
  "platform_formats": {
    "youtube": "short",
    "instagram": "reel",
    "tiktok": "video"
  },
  "publish_options": {
    "youtube": {
      "category_id": "27",
      "privacy": "public",
      "made_for_kids": false
    },
    "instagram": {
      "share_to_feed": true
    },
    "tiktok": {
      "privacy": "PUBLIC_TO_EVERYONE"
    }
  }
}'

Request Parameters

All parameters for the POST /posts body, grouped by purpose.

Publishing & Timing

modeoptional"now" | "scheduled"default: "scheduled"

Publishing trigger mode. Set to "now" to publish immediately or "scheduled" to queue for a future date/time.

When set to "now", the post is immediately handed off to the social networks and synchronous status is returned in the API response as well as dispatched to your webhooks.

Platforms: All Platforms

schedule_atoptionalstring (ISO 8601 UTC)default: Immediate if omitted

Target timestamp for publishing when mode="scheduled". Must be a valid ISO 8601 string.

Our worker processes scheduled posts automatically at the exact minute specified, e.g. "2026-10-15T14:30:00Z" or "2026-10-15T10:00:00-04:00".

Platforms: All Platforms

timezoneoptionalstring (IANA)default: "UTC"

IANA timezone string representing user schedule context and calendar alignment.

Supports all standard IANA identifiers like America/New_York, Europe/London, Asia/Kolkata, Australia/Sydney, UTC.

Platforms: All Platforms

Media & Visuals

thumbnailoptionalstring (HTTPS URL)

Direct public HTTPS image URL (.jpg, .png) used as the custom video cover / thumbnail.

Crucial for YouTube Shorts and Videos to display high-converting custom cover artwork instead of an auto-selected random frame.

Platforms: YouTube, Facebook, LinkedIn

media_urlsrequiredstring[] (URLs)

Array of direct public URLs to video files (.mp4, .mov) or images (.jpg, .png, .webp).

Provide 1 video URL for Reels, Shorts, and TikTok. Provide multiple image URLs for carousels (Instagram, LinkedIn, TikTok).

Platforms: All Platforms

Visual post container format (e.g. "reel", "short", "video", "post", "carousel", "story").

Platforms: All Platforms

media_typeoptional"video" | "image" | "text"default: Auto-inferred from media_urls

Explicit post type declaration. Automatically inferred from media URLs if omitted.

Platforms: All Platforms

platform_formatsoptionalRecord<string, format>

Per-platform format mapping, e.g. {"youtube":"short", "instagram":"reel"}.

Platforms: Cross-Platform

Content & Copy

captionrequiredstring

Primary text commentary, caption, or video description. On Instagram, place your text and up to 5 hashtags directly inside this caption.

Used as the caption on Instagram, TikTok, Facebook, and X, and as the video description on YouTube.

Platforms: All Platforms

titleoptionalstring

Video title or post headline (up to 100 characters on YouTube).

Required for YouTube long-form videos and recommended for YouTube Shorts and LinkedIn articles.

Platforms: YouTube, LinkedIn

tagsoptionalstring[] | string

YouTube video keyword tags for SEO discovery and search indexing.

Provide an array of strings or comma-separated terms. Combined tags length is automatically capped to 500 characters.

Platforms: YouTube

hashtagsoptionalstring[] | string

List of hashtags for platforms supporting separate tag arrays. (For Instagram, place up to 5 hashtags directly inside the caption.)

Platforms: TikTok, X, Facebook, LinkedIn

platform_contentoptionalRecord<string, { title?, caption?, hashtags? }>

Override title, caption, and hashtags for specific platforms in a single request.

Enables tailored messaging per platform while sending only one API call.

Platforms: Cross-Platform

Channel Routing

account_idsoptional(number | string)[]

Array of connected channel numeric IDs (find them on your Automation API dashboard).

Guarantees delivery to exact connected channels when multiple accounts exist for a platform.

Platforms: All Platforms

platformsoptionalstring[]

Platform slugs to target: ["youtube", "instagram", "tiktok", "facebook", "linkedin", "x"].

Platforms: All Platforms

Platform Settings

publish_optionsoptionalobject

Container object for platform-specific distribution, privacy, and categorization parameters.

Platforms: All Platforms

publish_options.youtube.category_idoptionalstringdefault: "22"

Standard YouTube category ID (22: People & Blogs, 27: Education, 28: Science & Tech, etc.).

Platforms: YouTube

publish_options.youtube.privacyoptional"public" | "unlisted" | "private"default: "public"

Visibility status of the video or Short on YouTube.

Platforms: YouTube

publish_options.youtube.made_for_kidsoptionalbooleandefault: false

Self-declaration for COPPA compliance (Children's Online Privacy Protection Act).

Platforms: YouTube

publish_options.instagram.share_to_feedoptionalbooleandefault: true

For Instagram Reels: whether to also feature the Reel on the main profile grid.

Platforms: Instagram

publish_options.tiktok.privacyoptional"PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY"default: "PUBLIC_TO_EVERYONE"

Audience privacy level for TikTok video uploads.

Platforms: TikTok

publish_options.tiktok.disable_commentoptionalbooleandefault: false

Prevent viewers from commenting on the TikTok video.

Platforms: TikTok

publish_options.linkedin.visibilityoptional"PUBLIC" | "CONNECTIONS"default: "PUBLIC"

Audience visibility on LinkedIn (Public to all vs 1st-degree connections only).

Platforms: LinkedIn

publish_options.x.reply_settingsoptional"everyone" | "mentionedUsers" | "following"default: "everyone"

Controls who is allowed to reply to the published tweet on X.

Platforms: X (Twitter)

Post Formats

Supported format values per platform. Use platform_formats to set a different format per platform in one request.

YouTube

YouTube Shortshort

Short-form vertical video distributed on the YouTube Shorts shelf.

9:16 Vertical1 Video (.mp4, .mov)< 60 seconds

Full Long-Form Videovideo

Standard landscape video with custom thumbnail and category.

16:9 Landscape1 Video (.mp4, .mov)Any duration

Instagram

Instagram Reelreel

Reels video with optional profile grid sharing.

9:16 Vertical1 Video (.mp4, .mov)Up to 90 seconds

Single Feed Postpost

Classic photo post published to the profile grid.

1:1 / 4:51 Image (.jpg, .png)Static Photo

Multi-Slide Carouselcarousel

Swipeable album post of up to 10 photos or videos.

1:1 / 4:52 to 10 Images/VideosSwipeable

Instagram Storystory

Temporary story visible at the top of followers’ feeds.

9:16 Vertical1 Image or Video24-hour Lifespan

TikTok

TikTok Videovideo

Standard vertical video with privacy, duet, and stitch controls.

9:16 Vertical1 Video (.mp4, .mov)Up to 10 minutes

Photo Mode Carouselcarousel

Swipeable photo mode gallery with background music.

9:16 or 1:12 to 35 PhotosSwipe

Facebook

Facebook Reelreel

Short-form video published to Facebook Page Reels.

9:16 Vertical1 Video (.mp4, .mov)Up to 90 seconds

Facebook Page Postpost

Standard wall post on your connected Facebook Page.

AnyImages, Video, or TextPermanent

Standard Post / Updatepost

Professional post with commentary and visibility controls.

1.91:1, 1:1, or TextImages, PDF, or TextPermanent

Native Video Postvideo

Native video player post uploaded directly to LinkedIn.

16:9 or 1:11 Video (.mp4, .mov)Up to 10 minutes

X (Twitter)

Standard Tweetpost

Tweet with media attachments and reply settings.

16:9, 1:1, or 4:5Up to 4 Images or 1 VideoMax 280 characters

Webhooks

Register a webhook URL in your dashboard to receive real-time delivery events. Each event is a JSON POST to your endpoint.

post.published

Fired when a post is successfully published to a platform.

post.failed

Fired when a post fails to publish (includes the error reason).

Sample delivery

{
  "event": "post.published",
  "post_id": "p_9f2c1a",
  "platform": "youtube",
  "account_id": 10482913,
  "status": "published",
  "url": "https://youtube.com/shorts/abc123",
  "published_at": "2026-10-15T14:30:05Z"
}

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with an error message.

400bad_request

Missing or invalid parameters (e.g. no caption or media_urls).

401unauthorized

Missing or invalid API key in the Authorization header.

403forbidden

The API key does not have access to the requested channel.

404not_found

A referenced channel or resource does not exist.

422unprocessable

The payload was understood but a platform rejected it (e.g. invalid format for media).

429rate_limited

Too many requests — slow down and retry after the cooldown.

500server_error

Something went wrong on our side. Safe to retry.

Rate Limits

API requests are rate-limited per key to keep the platform healthy. If you exceed the limit you’ll get a429 response — back off and retry after a short cooldown. Need higher throughput for an agency workload? Contact us.

Ready to automate?

Create an API key and publish your first post in minutes.

Get your API key