Create Posts

Create or schedule social media posts across connected channels (e.g., Facebook, YouTube, Twitter/X). Supports immediate and scheduled publishing, media attachments, hashtags, YouTube-specific metadata, and Twitter threads.

Method: POST URL: https://app.marketingblocks.ai/api/v1/social-sparks/create-post Permission: social-create-post Headers:

Authorization: Bearer <token>
Content-Type: application/json

Parameters

Parameter	Type	Requirement	Description	Options
channel_type	string	Mandatory	Type of social channel	facebook, instagram, youtube, linkedin, tiktok, threads, twitter
channel_id	integer	Mandatory	Unique ID of connected account	—
post_type	string	Mandatory	Type of post to create	post, reel, story, tweet, thread
caption_text	string	Mandatory	Main text content of the post	—
media_urls	array[string]	Mandatory	URLs to images or videos	—
publish_mode	string	Mandatory	Determines when post should be published	now, scheduled, queued, share_next
schedule_time	string	Conditional	Scheduled date & time (if publish_mode = scheduled)	Format: 2025-08-01 14:30
time_zone	string	Conditional	Timezone for interpreting schedule_time	America/New_York, Europe/London, America/Los_Angeles, Europe/Berlin, Asia/Dubai, Asia/Kolkata
hash_tags	string	Optional	Comma or space-separated hashtags	—
twitter_threads	array[obj]	Conditional	Thread items for Twitter/X (if post_type = thread)	Structured array of thread objects
post_extra	object	Conditional	Extra YouTube fields (if channel_type = youtube)	See YouTube field structure

post_extra (YouTube Only)

Field	Type	Requirement	Description	Options
title	string	Mandatory	Title of the YouTube video	—
category	integer	Mandatory	YouTube category ID	See category table below
privacyStatus	string	Mandatory	Privacy level of the video	public, private, unlisted

YouTube Category IDs

ID	Category Name
1	Film & Animation
2	Autos & Vehicles
10	Music
15	Pets & Animals
17	Sports
18	Short Movies
19	Travel & Events
20	Gaming
21	Videoblogging
22	People & Blogs
23	Comedy
24	Entertainment
25	News & Politics
26	Howto & Style
27	Education
28	Science & Technology
29	Nonprofits & Activism
30	Movies
31	Anime/Animation
32	Action/Adventure
33	Classics
34	Comedy (Extended Label)
35	Documentary
36	Drama
37	Family
38	Foreign
39	Horror
40	Sci-Fi/Fantasy
41	Thriller
42	Shorts
43	Shows
44	Trailers

twitter_threads item

{
  "message": "Tweet text",
  "media_urls": ["https://.../media.jpg"]
}

• message (string, required) — Tweet text

• media_urls (array[string], optional) — Media for that tweet

post_extra (YouTube)

{
  "title": "Title of the post",
  "category": 22,
  "privacyStatus": "public"
}

• title (string, required)

• category (integer, optional) — YouTube category ID

• privacyStatus (string, optional) — public, private, or unlisted

---

Example Request Bodies

Basic (Facebook, Scheduled)

{
  "channel_type": "facebook",
  "channel_id": 254,
  "post_type": "post",
  "caption_text": "This is a scheduled post.",
  "media_urls": ["https://videos.pexels.com/video-files/8382685/8382685-uhd_1440_2732_25fps.mp4"],
  "publish_mode": "scheduled",
  "schedule_time": "2025-08-01 14:30",
  "time_zone": "Africa/Lagos",
  "hash_tags": "#socialsparks #facebook #bettercoding"
}

YouTube (+ post_extra)

{
  "channel_type": "youtube",
  "channel_id": 321,
  "post_type": "post",
  "caption_text": "Check out my new video!",
  "media_urls": ["https://videos.pexels.com/video-files/8382685/8382685-uhd_1440_2732_25fps.mp4"],
  "publish_mode": "now",
  "post_extra": {
    "title": "Title of the post",
    "category": 22,
    "privacyStatus": "public"
  }
}

Twitter Thread

{
  "channel_type": "twitter",
  "channel_id": 443,
  "post_type": "thread",
  "publish_mode": "now",
  "twitter_threads": [
    {
      "message": "First tweet in thread.",
      "media_urls": [
        "https://videos.pexels.com/video-files/8382685/8382685-uhd_1440_2732_25fps.mp4"
      ]
    },
    {
      "message": "Second tweet in thread.",
      "media_urls": [
        "https://marketingblocks.s3.amazonaws.com/public/media/image1.jpeg"
      ]
    }
  ],
  "hash_tags": "#socialsparks #twitter #threading"
}

---

Example Response

{
  "message": "Post processing. Check Find Post for post status",
    "data": {
      "post_id": 1XXXX1,
      "STATUS": "processing",
      "find_post_url": "https://app.marketingblocks.ai/api/v1/social-sparks/post/1XXXX1"
  },
  "status": true
}

---

To retrieve the latest status of a post, call the Find Post endpoint using the find_post_url provided in the response body. Ensure that you include your authentication token in the request. Refer to the Authentication section for details on how to include the token properly.

STATUS	Description
pending	The post has been successfully created in the system but has not yet started the publishing process. It is waiting to be processed.
processing	The post is currently being processed for publishing. This may include media upload, API communication with the social platform, formatting, or validation steps.
scheduled	The post has been scheduled to be published at a specific date and time provided during post creation. It will automatically move to processing at the scheduled time.
queued	The post has been placed in a publishing queue and will be published in the next available time slot based on the user's queue or automation settings.
published	The post has been successfully published and is now live on the social media platform.
failed	The post failed to publish. The system will store an error message explaining the reason (e.g., API rejection, invalid media format, authentication error, or network failure).

cURL

curl --location 'https://app.marketingblocks.ai/api/v1/social-sparks/create-post' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel_type": "facebook",
    "channel_id": 254,
    "post_type": "post",
    "caption_text": "This is a scheduled post.",
    "media_urls": ["https://videos.pexels.com/video-files/8382685/8382685-uhd_1440_2732_25fps.mp4"],
    "publish_mode": "scheduled",
    "schedule_time": "2025-08-01 14:30",
    "time_zone": "Africa/Lagos",
    "hash_tags": "#socialsparks #facebook #bettercoding"
  }'

Notes

• Always send the body as raw JSON.

• Use a valid channel_id for the chosen channel_type.

• For scheduled posts, both schedule_time and time_zone are required.