Schedule a post
sprkly_schedule_postQueue a post for publishing, in ONE call. Attach media by passing the user's link straight to media_urls: sprkly downloads it into storage itself for the platforms that need that, so no upload tool has to run first. Runs the same quota, duplicate-content and platform pre-flight checks as the sprkly app. Instagram and TikTok require media at submission time; YouTube and TikTok require a title, and TikTok also requires platform_meta.tiktok.privacyLevel — just send the level the user asked for and this tool names the allowed values if it is not one of them. It reads the real bytes of the media and the response says what will actually publish on each platform (a Reel, a 3-slide carousel, a photo set, a Page feed video) plus anything worth passing on: relay that to the user. Confirm the date, time and target accounts with the user first. If a target platform has more than one connected account and profile_ids is not given, the tool returns needsAccountChoice with the options instead of scheduling — put that choice to the user, then re-call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Post title. Required for YouTube (max 100 characters) and TikTok (max 150 characters). | |
| caption | No | Post caption, max 2200 characters. | |
| category | No | Optional content category, e.g. "fitness". | |
| media_id | No | Id of a single media file already uploaded to sprkly. Shorthand for a one-item media_ids. | |
| media_ids | No | Ids of media files already uploaded to sprkly, in slide order. Array order is the published order. Use these when the user already has media in sprkly, or when one file is going on several posts; for a link the user just gave you, media_urls is fewer steps. Every photo in a set must be the SAME shape or the call is refused: export them all at 1080x1920 (9:16), 1080x1440 (3:4), 1080x1350 (4:5) or 1080x1080 (1:1). Instagram takes at most 10 slides; TikTok photo sets take up to 35. | |
| platforms | No | Platforms to publish to. A platform with exactly one connected account is targeted directly; one with several makes the tool answer needsAccountChoice so the user can pick. | |
| media_urls | No | Publicly reachable image or video URLs to attach, in slide order. Pass links through for ANY platform. Instagram and Threads fetch them directly; for TikTok, YouTube and Facebook sprkly downloads the file into its own storage while scheduling, so a link works there too and any problem with it is reported now, in this call. Google Drive and Dropbox share links are converted automatically. JPEG, PNG, WebP, GIF, MP4, MOV and WebM only: AVIF and HEIC (the iPhone camera default) are refused with re-export instructions, because sprkly cannot convert them. Each file must be publicly reachable and under 50 MB. | |
| profile_ids | No | Specific accounts to publish to, from sprkly_list_profiles. When given, this list IS the target set — platforms are not fanned out. | |
| all_accounts | No | Explicitly post to EVERY connected account on every listed platform, skipping the needsAccountChoice question. Only pass true when the user has said they want all accounts. | |
| approval_note | No | Optional note to the owner, shown in the approval email. Only used with requires_approval. | |
| first_comment | No | Instagram only. Optional text sprkly posts as the first comment under the post right after it publishes, e.g. "Comment GUIDE and I will send you the link." Up to 2,200 characters. Ignored for other platforms. Refused on a story (surface story): stories take no comments. Creator and Power only: Free gets upgrade_required. | |
| platform_meta | No | Platform-specific publishing options, keyed by platform. | |
| scheduled_time | No | ISO 8601 timestamp to publish at. Must be in the future. If omitted the post goes out on the next publisher run, about a minute from now — there is no smart slot-picking, so pass an explicit time unless the user wants it published immediately. sprkly_get_analytics can suggest one. | |
| requires_approval | No | Hold the post until the owner approves it. It is saved as pending_approval and never publishes on its own; the owner gets an email with an Approve link and can also approve or reject in the sprkly calendar. Poll sprkly_get_post_approval_status for the answer. Power plan only: other plans get upgrade_required. |