SchedulePost API
Publish, schedule, or queue videos to all your connected platforms from any script or automation.
API Keys
Sign in to generate and manage your API keys.
Authentication
Pass your API key in every request:
x-api-key: sp_your_api_key_here
New keys default to read-only access for 90 days. Select posts:write for publishing, scheduling, uploads and deletion. Webhook operations require webhooks:read or webhooks:write. Write permissions include read access for the same resource. These permissions also apply when using a key with MCP.
Expired or revoked keys return 401; a missing permission returns 403 with code insufficient_scope. Existing legacy keys retain full access and never expire. To replace one, create a scoped key, update your integration, verify it works, then revoke the old key. If you send both x-api-key and Authorization, only x-api-key is used.
Base URL
https://schedulepost.fulinlabs.com/api/v1
Endpoints
/posts/bulkAtomically delete or reschedule 1–100 explicitly selected scheduled posts. Requires posts:write. Each entry needs id and expectedScheduledFor from the queue; reschedule entries also need an absolute scheduledFor with a timezone. All new times must be future times within 60 days from now. Missing, foreign, already claimed or rescheduled sources fail together with 409 queue_conflict and no partial writes. Content and targets are preserved. Retrying the same reschedule destinations never shifts posts twice. Deletion cannot be undone; after a lost response, read the queue before retrying.
Example
curl -X POST -H "x-api-key: sp_xxx" -H "Content-Type: application/json" \
-d '{"action":"reschedule","posts":[{"id":"00000000-0000-4000-8000-000000000001","expectedScheduledFor":"2026-12-01T12:00:00Z","scheduledFor":"2026-12-02T12:00:00Z"}]}' \
https://schedulepost.fulinlabs.com/api/v1/posts/bulk
# Delete uses {"action":"delete","posts":[{"id":"...","expectedScheduledFor":"..."}]}
# Keep the same absolute destinations when retrying a reschedule.Response
{
"success": true,
"action": "reschedule",
"postIds": ["00000000-0000-4000-8000-000000000001"]
}/uploadUpload a media file (video or image) as multipart/form-data or a raw binary body. A Content-Length header bounded by the 512 MB limit is required and is validated before the body is read. JSON presign requests are no longer accepted here — see /api/v2/upload.
Parameters
file(File)— Media file (multipart form field) or raw binary with x-filenameExample
# Multipart form upload curl -X POST -H "x-api-key: sp_xxx" \ -F "file=@/path/to/video.mp4" \ https://schedulepost.fulinlabs.com/api/v1/upload # Raw binary upload curl -X POST -H "x-api-key: sp_xxx" \ -H "x-filename: my-video.mp4" \ --data-binary @/path/to/video.mp4 \ https://schedulepost.fulinlabs.com/api/v1/upload
Response
{
"success": true,
"videoUrl": "https://pub-xxx.r2.dev/user-id/uuid.mp4",
"path": "user-id/uuid.mp4",
"message": "Video uploaded. Use the videoUrl in /publish, /schedule, or /queue."
}/uploadv1 JSON presign requests (Content-Type: application/json) are rejected with 426 Upgrade Required — the v1 contract had no way to bind an exact upload size. Migrate to /api/v2/upload.
Example
curl -X POST -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{"filename":"my-video.mp4","contentType":"video/mp4"}' \
https://schedulepost.fulinlabs.com/api/v1/upload
# -> 426 Upgrade RequiredResponse
{
"error": "UPLOAD_CONTRACT_UPGRADED",
"message": "JSON presign requests are no longer supported on /api/v1/upload because they cannot bind an exact upload size. Use /api/v2/upload with a bounded contentLength instead.",
"upgradeTo": "/api/v2/upload"
}/api/v2/uploadRequest a presigned R2 upload target for large media. Requires an exact contentLength (bytes), which is bound to the signed PUT so R2 rejects a body that doesn't match.
Parameters
contentLength(number, required)— Exact size of the file in bytes, bounded by the 512 MB limitfilename(string)— Original filename, used only to infer the storage key extensioncontentType(string)— MIME type, must be video/* or image/*Example
curl -X POST -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{"filename":"my-video.mp4","contentType":"video/mp4","contentLength":10485760}' \
https://schedulepost.fulinlabs.com/api/v2/upload
# PUT the file to the returned uploadUrl with matching Content-Type and
# Content-Length headers, then publish or schedule using the returned videoUrl.Response
{
"success": true,
"uploadUrl": "https://...r2.cloudflarestorage.com/...?X-Amz-Signature=...",
"videoUrl": "https://pub-xxx.r2.dev/user-id/uuid.mp4",
"path": "user-id/uuid.mp4",
"expiresIn": 900,
"message": "Upload the media with PUT and a matching Content-Length header, then use videoUrl in /publish, /schedule, or /queue."
}/connectionsList all connected platform accounts. Use the returned IDs in publish/schedule/queue requests.
Example
curl -H "x-api-key: sp_xxx" \ https://schedulepost.fulinlabs.com/api/v1/connections
Response
{
"connections": [
{
"id": "uuid-1",
"platform": "youtube",
"account_name": "My Channel",
"account_id": "UC..."
},
{
"id": "uuid-2",
"platform": "tiktok",
"account_name": "@myhandle",
"account_id": "123..."
}
]
}/publishPublish immediately with text, single media, or carousel media. `videoUrl` is still supported for backward compatibility. TikTok defaults to direct public posting. Reuse an Idempotency-Key header or idempotencyKey body value for the same intent: replay returns stored results without sending again. A pending attempt returns status publishing; changed intent with the same key returns 409.
Parameters
idempotencyKey(string)— Optional request key (also accepted as Idempotency-Key header). Reuse for retries of this request; use a new key for a new post.videoUrl(string)— Legacy single-video URL (backward compatibility)mediaUrls(string[])— Array of public media URLs. Type is inferred from file extension.mediaItems({url,mediaType}[])— Preferred media payload for precise control. mediaType: "IMAGE" or "VIDEO". Use 2+ items for carousels.caption(string)— Post text — you can also use "title", "text", or "description" as aliaseshashtags(string)— Hashtags string (e.g. "#shorts #viral")connectionIds(string[], required)— Array of connection IDs from /connectionsyoutubeTitle(string)— Optional YouTube-only title override (max 100 chars)youtubeDescription(string)— Optional YouTube-only description overrideyoutubePrivacy(string)— YouTube privacy status: "public" (default), "unlisted", or "private"tiktokPostMode(string)— TikTok mode: "DIRECT_POST" (default) or "MEDIA_UPLOAD" (draft to TikTok inbox)tiktokPrivacy(string)— TikTok Direct Post privacy. Defaults to "PUBLIC_TO_EVERYONE". Must match one creator_info option.tiktokCommercialType(number)— TikTok commercial content type: 0=none, 1=your brand, 2=branded content, 3=bothtiktokDisableComment(boolean)— Disable comments on TikTok post (default: false)tiktokDisableDuet(boolean)— Disable duet on TikTok post (default: false)tiktokDisableStitch(boolean)— Disable stitch on TikTok post (default: false)Example
curl -X POST -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{
"caption": "Check out the new feature demo",
"mediaItems": [
{ "url": "https://example.com/video-1.mp4", "mediaType": "VIDEO" }
],
"hashtags": "#shorts #viral",
"connectionIds": ["uuid-1", "uuid-2"],
"youtubeTitle": "Quarterly feature demo",
"youtubeDescription": "Long-form YouTube description for the same upload.",
"youtubePrivacy": "private",
"tiktokPostMode": "DIRECT_POST",
"tiktokPrivacy": "PUBLIC_TO_EVERYONE"
}' \
https://schedulepost.fulinlabs.com/api/v1/publishResponse
{
"success": true,
"allPublished": true,
"status": "published",
"idempotentReplay": false,
"postId": "post-uuid",
"platforms": [
{
"connectionId": "uuid-1",
"platform": "youtube",
"success": true,
"platformPostId": "yt-abc"
},
{
"connectionId": "uuid-2",
"platform": "tiktok",
"success": true,
"platformPostId": "tt-123"
}
]
}/scheduleSchedule text, single media, or carousel media for a specific date/time. Reuse a request key only for identical intent. New keys reused with changed content, targets, or time return 409; retries return the stored post even after edits or publishing. `videoUrl` remains supported.
Parameters
idempotencyKey(string)— Optional request key (also accepted as Idempotency-Key header). Reuse for retries of this request; use a new key for a new post.videoUrl(string)— Legacy single-video URLmediaUrls(string[])— Array of public media URLsmediaItems({url,mediaType}[])— Preferred media payload. mediaType: "IMAGE" | "VIDEO"caption(string)— Post text — you can also use "title", "text", or "description" as aliaseshashtags(string)— Hashtags stringconnectionIds(string[], required)— Array of connection IDsscheduledFor(string, required)— ISO 8601 datetime (e.g. 2026-03-20T15:00:00Z). Must be in the future and at most 60 days from now; media is stored until it publishes. Later dates return 400 with code schedule_horizon_exceeded.youtubeTitle(string)— Optional YouTube-only title overrideyoutubeDescription(string)— Optional YouTube-only description overrideyoutubePrivacy(string)— YouTube privacy status: "public" (default), "unlisted", or "private"tiktokPostMode(string)— TikTok mode: "DIRECT_POST" (default) or "MEDIA_UPLOAD" (draft to TikTok inbox)tiktokPrivacy(string)— TikTok Direct Post privacy. Defaults to "PUBLIC_TO_EVERYONE". Must match one creator_info option.tiktokCommercialType(number)— TikTok commercial content type: 0=none, 1=your brand, 2=branded content, 3=bothtiktokDisableComment(boolean)— Disable comments on TikTok post (default: false)tiktokDisableDuet(boolean)— Disable duet on TikTok post (default: false)tiktokDisableStitch(boolean)— Disable stitch on TikTok post (default: false)Example
curl -X POST -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{
"mediaItems": [
{ "url": "https://example.com/image-a.jpg", "mediaType": "IMAGE" },
{ "url": "https://example.com/image-b.jpg", "mediaType": "IMAGE" }
],
"caption": "Dropping this tomorrow!",
"connectionIds": ["uuid-1"],
"scheduledFor": "2026-03-20T15:00:00Z",
"youtubePrivacy": "private",
"tiktokPostMode": "DIRECT_POST",
"tiktokPrivacy": "PUBLIC_TO_EVERYONE"
}' \
https://schedulepost.fulinlabs.com/api/v1/scheduleResponse
{
"success": true,
"postId": "post-uuid",
"scheduledFor": "2026-03-20T15:00:00.000Z",
"platforms": ["youtube"],
"connectionIds": ["uuid-1"]
}/queueSmart queue — automatically picks the next available slot for text, single media, or carousels. Reuse a request key only for identical content, targets and settings; conflicting retries return 409. No need to specify a date.
Parameters
idempotencyKey(string)— Optional request key (also accepted as Idempotency-Key header). Reuse for retries of this request; use a new key for a new post.videoUrl(string)— Legacy single-video URLmediaUrls(string[])— Array of public media URLsmediaItems({url,mediaType}[])— Preferred media payload. mediaType: "IMAGE" | "VIDEO"caption(string)— Post text — you can also use "title", "text", or "description" as aliaseshashtags(string)— Hashtags stringconnectionIds(string[], required)— Array of connection IDssettings(object)— Supported settings: postsPerDay 1|2|3, allowedDays (nonempty weekdays 0=Sunday through 6=Saturday), timezone (IANA zone; default UTC). Unknown settings, preferredTimes and jitterMinutes are rejected.youtubeTitle(string)— Optional YouTube-only title overrideyoutubeDescription(string)— Optional YouTube-only description overrideyoutubePrivacy(string)— YouTube privacy status: "public" (default), "unlisted", or "private"tiktokPostMode(string)— TikTok mode: "DIRECT_POST" (default) or "MEDIA_UPLOAD" (draft to TikTok inbox)tiktokPrivacy(string)— TikTok Direct Post privacy. Defaults to "PUBLIC_TO_EVERYONE". Must match one creator_info option.tiktokCommercialType(number)— TikTok commercial content type: 0=none, 1=your brand, 2=branded content, 3=bothtiktokDisableComment(boolean)— Disable comments on TikTok post (default: false)tiktokDisableDuet(boolean)— Disable duet on TikTok post (default: false)tiktokDisableStitch(boolean)— Disable stitch on TikTok post (default: false)Example
curl -X POST -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{
"mediaItems": [
{ "url": "https://example.com/photo-1.jpg", "mediaType": "IMAGE" },
{ "url": "https://example.com/photo-2.jpg", "mediaType": "IMAGE" }
],
"caption": "Auto-queued!",
"connectionIds": ["uuid-1", "uuid-2"],
"youtubePrivacy": "private",
"tiktokPostMode": "DIRECT_POST",
"tiktokPrivacy": "PUBLIC_TO_EVERYONE",
"settings": {
"postsPerDay": 2,
"allowedDays": [1,2,3,4,5]
}
}' \
https://schedulepost.fulinlabs.com/api/v1/queueResponse
{
"success": true,
"postId": "post-uuid",
"scheduledFor": "2026-03-17T14:32:00.000Z",
"message": "Post added to queue with smart scheduling.",
"platforms": ["youtube", "tiktok"],
"connectionIds": ["uuid-1", "uuid-2"],
"scheduleSettings": {
"postsPerDay": 2,
"allowedDays": [1,2,3,4,5]
}
}/postsList your posts, newest first. Filters combine before pagination. Keep filters unchanged and pass nextCursor to load the next page.
Parameters
limit(number)— Page size (default 50, maximum 100)cursor(string)— Opaque nextCursor from the previous response, URL encoded. Omit for the first page.status(string)— Query param: "draft", "scheduled", "publishing", "published", "failed", or "partial"search(string)— Literal case-insensitive search across captions, hashtags and YouTube titles (maximum 200 characters).connection_id(string)— Only posts targeting this connection UUID.scheduled_after(string)— Inclusive scheduled time, as an ISO timestamp with timezone.scheduled_before(string)— Exclusive scheduled time, as an ISO timestamp with timezone. Must follow scheduled_after when both are provided.overdue_only(boolean)— true selects still-scheduled posts whose scheduled time has passed. Accepts true or false.Example
curl -H "x-api-key: sp_xxx" \ "https://schedulepost.fulinlabs.com/api/v1/posts?status=scheduled"
Response
{
"posts": [
{
"id": "post-uuid",
"video_url": "https://...",
"media_items": [{"url":"https://...","mediaType":"IMAGE"}],
"caption": "...",
"youtube_title": "My YouTube title",
"youtube_description": "My YouTube description",
"youtube_privacy": "private",
"status": "scheduled",
"scheduled_for": "2026-03-20T15:00:00Z",
"platforms": ["youtube"],
"connection_ids": ["uuid-1"],
"created_at": "2026-03-31T22:00:00.000Z"
}
],
"nextCursor": null
}/posts/:idRead your post and saved per-channel delivery results by the postId returned from publish, schedule or queue. Requires posts:read. delivery_complete is false for scheduled or publishing posts; checkpoints may already appear while siblings are still publishing. Reading never retries delivery. Missing or unowned IDs return 404.
Parameters
id(string (UUID), required)— Post ID in the URL pathExample
curl -H "x-api-key: sp_xxx" "https://schedulepost.fulinlabs.com/api/v1/posts/11111111-1111-4111-8111-111111111111"
Response
{
"post": {
"id": "11111111-1111-4111-8111-111111111111",
"caption": "Hello",
"status": "published",
"platforms": ["telegram"],
"connection_ids": ["uuid-1"],
"scheduled_for": null,
"created_at": "2026-10-13T12:00:00.000Z",
"retry_of_post_id": null
},
"delivery_complete": true,
"results": [{
"connection_id": "uuid-1",
"account_name": "My channel",
"platform": "telegram",
"status": "published",
"platform_post_id": "123",
"error": null,
"failure_phase": null,
"error_code": null,
"retryable": false,
"analytics_status": null,
"attempted_at": "2026-10-13T12:00:01.000Z"
}]
}/postsCancel a scheduled post (only works for posts with status 'scheduled').
Parameters
id(string, required)— Post ID to cancelExample
curl -X DELETE -H "x-api-key: sp_xxx" \
-H "Content-Type: application/json" \
-d '{"id": "post-uuid"}' \
https://schedulepost.fulinlabs.com/api/v1/postsResponse
{ "success": true }/groupsList your account groups — named bundles of platform connection IDs you can target when scheduling or queueing posts. Requires the posts:read scope.
Example
curl -H "x-api-key: sp_xxx" \\ https://schedulepost.fulinlabs.com/api/v1/groups
Response
{
"groups": [
{
"id": "group-uuid",
"name": "Main Channel",
"connection_ids": ["uuid-1", "uuid-2"]
}
]
}TypeScript Example
const API_KEY = "sp_your_key";
const BASE = "https://schedulepost.fulinlabs.com/api/v1";
// 1. Request a direct upload target (recommended for large videos)
const fs = require("fs");
const upload = await fetch(`${BASE}/upload`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ filename: "video.mp4", contentType: "video/mp4" }),
}).then(r => r.json());
await fetch(upload.uploadUrl, {
method: "PUT",
headers: { "Content-Type": "video/mp4" },
body: fs.readFileSync("./video.mp4"),
});
console.log(upload.videoUrl);
// → "https://pub-xxx.r2.dev/user-id/uuid.mp4"
// 2. List connections to find account IDs
const connections = await fetch(`${BASE}/connections`, {
headers: { "x-api-key": API_KEY },
}).then(r => r.json());
// 3. Publish the uploaded video with YouTube-specific metadata
const result = await fetch(`${BASE}/publish`, {
method: "POST",
headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
mediaItems: [{ url: upload.videoUrl, mediaType: "VIDEO" }],
caption: "Feature launch video",
connectionIds: [connections.connections[0].id],
youtubeTitle: "Feature launch video",
youtubeDescription: "Longer YouTube description for the same upload.",
youtubePrivacy: "private",
}),
}).then(r => r.json());
console.log(result);
// → { success: true, postId: "...", scheduledFor: "2026-03-17T14:32:00Z", ... }Agent webhooks
Receive post.completed for published, partial and failed posts that finish while the endpoint is active. The event data is the same outcome returned by GET /api/v1/posts/:id. No polling is required during normal operation.
POST /api/v1/webhooks {"url":"https://example.com/callback"}
GET /api/v1/webhooks
POST /api/v1/webhooks/:id {"action":"rotate" | "test" | "resume"}
DELETE /api/v1/webhooks/:id
GET /api/v1/webhooks/:id/deliveries?status=exhausted&limit=50&cursor=...
POST /api/v1/webhooks/:id/deliveries {"deliveryId":"..."}Use your API key or OAuth webhooks:read / webhooks:write scopes. Write implies read within that scope family. API keys have full access. Creation and rotation return the secret once. Up to five endpoints are allowed. Test sends webhook.test through the cron worker; it returns a delivery_id immediately.
{
"id": "stable-event-uuid",
"type": "post.completed",
"created_at": "2026-10-15T12:00:00.000Z",
"data": { "post": { "id": "...", "status": "partial", "...": "..." },
"delivery_complete": true, "results": [] }
}Verify X-SchedulePost-Signature before parsing JSON. It contains t=UNIX_SECONDS,v1=HEX_DIGEST. Compute HMAC-SHA256 with your secret over the timestamp, a literal period, and the exact raw request body. Compare in constant time and reject timestamps more than five minutes old or in the future. Keep clocks synchronized.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(secret, rawBody, header) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '')
if (!match || Math.abs(Date.now()/1000 - Number(match[1])) > 300) return false
const expected = createHmac('sha256', secret)
.update(match[1] + '.').update(rawBody).digest()
return timingSafeEqual(expected, Buffer.from(match[2], 'hex'))
}Deduplicate X-SchedulePost-Event-Id (also body.id) transactionally with your processing. X-SchedulePost-Delivery-Id identifies one endpoint delivery. Return 2xx after durably accepting the event. Delivery is at least once: a crash after receipt may cause repeats. Non-2xx responses, redirects and transport failures retry with gaps of 1m, 4m, 25m, 90m, 4h, 6h and 12h, subject to cron timing. Delayed attempts retain those gaps rather than immediately consuming the remaining retries. Each attempt has a ten-second deadline and 64 KiB response limit. After eight failed attempts a delivery is exhausted. Twenty consecutive failures disable an endpoint; inspect history and resume after fixing it.
Rotating a secret takes effect immediately for subsequent claims. An in-flight request can still use the old secret. Temporarily accept both during rotation. Deletion cancels pending work; requests already in flight may arrive. Disabled endpoints do not receive new events. Failure notifications use your configured Telegram channel and failure preference.
Recover failed callbacks
Delivery history returns deliveries and nextCursor. Use limit (1–100, default 50), status (all, pending, delivered or exhausted) and the opaque cursor to read older pages in newest-first order. Follow nextCursor until null. Filters describe the current state; deliveries can change status between pages. History omits signing secrets and callback bodies.
Fix your receiver, resume a disabled endpoint, then POST a deliveryId to its deliveries endpoint, or choose Retry delivery in Channels. Only exhausted deliveries can be retried; delivered and pending deliveries return 409 delivery_not_retryable. Recovery queues a fresh eight-attempt cycle and returns 202 with delivery_id. It retains the same body, event ID and delivery ID, and does not republish the social post. Attempts is the lifetime count; cycle_attempts counts the current cycle. Concurrent retry requests queue only one cycle. Continue deduplicating event IDs: an exhausted callback may already have reached your receiver. New attempts use the currently configured signing secret.
Reconcile after downtime
GET /api/v1/posts supports status, limit (maximum 100), cursor, created_after (inclusive) and created_before (exclusive), using ISO timestamps with timezones. Follow nextCursor and use GET /api/v1/posts/:id for saved outcomes. These filters refer to post creation time, so include older scheduled posts when reconciling. MCP provides register_webhook, list_webhook_deliveries and retry_webhook_delivery.
Machine-readable errors
Webhook management and post-read validation return code alongside error: invalid_request, invalid_webhook_url, webhook_limit, webhook_disabled, delivery_not_retryable or not_found. Shared guards return unauthorized, insufficient_scope or rate_limited. Bounded JSON errors return invalid_request or body_too_large. Internal failures return internal_error and correlationId. Other existing endpoints may still return only error; clients should also handle HTTP status.
Error Codes
| Status | Meaning |
|---|---|
| 401 | Missing, invalid, expired or revoked credentials |
| 400 | Bad request (missing params, invalid connections, no slots) |
| 403 | Insufficient API key or OAuth scope (insufficient_scope) |
| 409 | Publishing or scheduling request key reused with different intent |
| 404 | Post not found or not owned by this account |
| 405 | Method not allowed |
| 408 | Request body timed out |
| 413 | JSON body or media exceeds its byte limit |
| 429 | Rate limit exceeded (120 requests/minute per key). Wait for the Retry-After seconds, then retry. Repeated invalid credentials are throttled per client address. |
| 500 | Server error |