# 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 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 ```json { "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) ```json { "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) ```json { "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`) ```json { "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 ```json { "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 ```json { "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.
STATUSDescription
pendingThe post has been successfully created in the system but has not yet started the publishing process. It is waiting to be processed.
processingThe post is currently being processed for publishing. This may include media upload, API communication with the social platform, formatting, or validation steps.
scheduledThe 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.
queuedThe 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.
publishedThe post has been successfully published and is now live on the social media platform.
failedThe 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 ```bash curl --location 'https://app.marketingblocks.ai/api/v1/social-sparks/create-post' \ --header 'Authorization: Bearer ' \ --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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.marketingblocks.ai/agentic-ai-docs/api-reference/social-growth-engine/post-publishing-and-schedule/create-posts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.