URL Scheme API
Schedule Action
Schedule posts for future publication with precise date/time control
Schedule Action
Schedule posts for future publication directly via URL scheme. Perfect for automation workflows that need to plan content in advance.
Syntax
statuz://schedule[?parameters]
Parameters
| Parameter | Type | Description | Required | Example |
|---|---|---|---|---|
text | string | Post content (URL-encoded) | No | Hello%20World |
date | ISO8601 | Schedule date/time | No* | 2024-12-25T10:00:00Z |
timezone | string | Timezone (IANA format) | No | America/New_York |
status | string | draft or queued | No | queued |
media | string | Comma-separated file paths/URLs | No | file:///path/img.png |
files | string | Alias for media when passing raw file paths | No | /Users/me/Desktop/img.png |
thread | boolean | Create thread | No | true |
autosplit | boolean | Auto-split long posts | No | true |
quote | string | URL or ID of post to quote | No | https://x.com/... |
platforms | string | Comma-separated platforms | No | x,bluesky |
postingMode | string | defaults, allEnabled, or specific | No | specific |
xMode | string | Override posting mode for X | No | allEnabled |
blueskyMode | string | Override posting mode for Bluesky | No | defaults |
mastodonMode | string | Override posting mode for Mastodon | No | specific |
xAccounts | string | Comma-separated X account identifiers | No | work,personal |
blueskyAccounts | string | Comma-separated Bluesky account identifiers | No | user.bsky.social |
mastodonAccounts | string | Comma-separated Mastodon identifiers | No | user@fosstodon.org |
xShareWithFollowers | string | true/1/all or comma-separated IDs | No | true |
stealthMode | boolean | Schedule silently without opening UI (default: false) | No | true |
* Date is optional but recommended. If omitted with status=queued, defaults to 1 hour from now.
Status Behavior
draft (default)
Saves the post without scheduling automatic publishing. The post appears in your calendar with the specified date, but requires manual publishing.
queued
Schedules the post for automatic publishing at the specified time. If no date is provided, defaults to 1 hour from now.
Account & Platform Selection
Stealth Mode
URL-scheme calls default to stealthMode=false, which opens the scheduling UI. Pass stealthMode=true to insert directly into the queue without showing any windows (ideal for unattended automations).
Examples
Basic Scheduled Post
Schedule a post for a specific date and time:
TEXT="Good morning everyone!"
DATE="2025-01-20T09:00:00Z"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&status=queued"Schedule with Timezone
Specify a timezone for local scheduling:
TEXT="Lunch announcement"
DATE="2025-01-20T12:00:00"
TZ="America/New_York"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&timezone=$TZ&status=queued"Schedule 1 Hour Ahead
Omit the date to schedule 1 hour from now:
TEXT="Quick update"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&status=queued"Save as Draft
Schedule a post as a draft (won't auto-publish):
TEXT="Review this later"
DATE="2025-01-20T14:00:00Z"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&status=draft"Schedule with Media
Schedule a post with attached media:
TEXT="Check out these results"
DATE="2025-01-20T10:00:00Z"
MEDIA="file:///Users/me/Desktop/chart.png"
ENCODED_TEXT=$(printf %s "$TEXT" | jq -sRr @uri)
ENCODED_MEDIA=$(printf %s "$MEDIA" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED_TEXT&date=$DATE&media=$ENCODED_MEDIA&status=queued"Schedule Thread
Schedule a multi-post thread:
TEXT="Post 1: Introduction
Post 2: Main content
Post 3: Conclusion"
DATE="2025-01-20T14:00:00Z"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&thread=true&status=queued"Schedule to Specific Platforms
Target specific platforms:
TEXT="Platform-specific announcement"
DATE="2025-01-20T10:00:00Z"
PLATFORMS="x,bluesky"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&platforms=$PLATFORMS&status=queued"Advanced Scheduling
Daily Morning Posts
#!/bin/bash
# Schedule tomorrow morning's post
TOMORROW=$(date -v+1d -u +"%Y-%m-%dT14:00:00Z") # 9 AM EST
TEXT="Good morning! Daily standup:
✅ Yesterday: Shipped features
📝 Today: Bug fixes
🚫 Blockers: None"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$TOMORROW&status=queued"Weekly Recap
#!/bin/bash
# Schedule Friday afternoon recap
FRIDAY=$(date -v friday -u +"%Y-%m-%dT21:00:00Z") # 4 PM EST
TEXT="🎉 Week in Review
This week we:
- Launched 3 features
- Fixed 12 bugs
- Improved performance by 25%
Have a great weekend!"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$FRIDAY&status=queued"Schedule Multiple Posts
#!/bin/bash
# Schedule a series of posts
DATES=(
"2025-01-20T09:00:00Z"
"2025-01-20T14:00:00Z"
"2025-01-20T18:00:00Z"
)
TEXTS=(
"Morning update"
"Afternoon check-in"
"Evening wrap-up"
)
for i in ${!DATES[@]}; do
TEXT="${TEXTS[$i]}"
DATE="${DATES[$i]}"
ENCODED=$(printf %s "$TEXT" | jq -sRr @uri)
open "statuz://schedule?text=$ENCODED&date=$DATE&status=queued"
sleep 1 # Avoid race conditions
doneRelative Scheduling
#!/bin/bash
# Schedule posts at relative times
schedule_in_hours() {
local text=$1
local hours=$2
local date=$(date -v+${hours}H -u +"%Y-%m-%dT%H:%M:%SZ")
local encoded=$(printf %s "$text" | jq -sRr @uri)
open "statuz://schedule?text=$encoded&date=$date&status=queued"
}
schedule_in_hours "1 hour from now" 1
schedule_in_hours "3 hours from now" 3
schedule_in_hours "Tomorrow same time" 24Date Format Reference
Statuz accepts ISO 8601 date/time formats:
UTC Time
2025-01-20T10:00:00Z
With Timezone Offset
2025-01-20T10:00:00-05:00 # EST
2025-01-20T10:00:00+01:00 # CET
Local Time (no timezone)
2025-01-20T10:00:00
Interpreted as local timezone unless timezone parameter is provided.
Date Only
2025-01-20
Defaults to midnight local time.
Timezone Reference
Use IANA timezone identifiers:
Americas
Europe
Asia/Pacific
Integration Examples
Python Automation
#!/usr/bin/env python3
from datetime import datetime, timedelta
from urllib.parse import quote
import subprocess
# Schedule for tomorrow at 9 AM
tomorrow = datetime.now() + timedelta(days=1)
schedule_time = tomorrow.replace(hour=9, minute=0, second=0)
iso_time = schedule_time.strftime('%Y-%m-%dT%H:%M:%S')
text = "Daily update: All systems operational ✅"
encoded_text = quote(text)
url = f"statuz://schedule?text={encoded_text}&date={iso_time}&timezone=America/New_York&status=queued"
subprocess.run(['open', url])Node.js Script
#!/usr/bin/env node
const { exec } = require('child_process');
// Schedule 2 hours from now
const scheduleDate = new Date();
scheduleDate.setHours(scheduleDate.getHours() + 2);
const isoDate = scheduleDate.toISOString();
const text = "Scheduled update from automation";
const encoded = encodeURIComponent(text);
const url = `statuz://schedule?text=${encoded}&date=${isoDate}&status=queued`;
exec(`open "${url}"`);AppleScript
-- Schedule post via AppleScript
set postText to "Automated post from AppleScript"
set scheduleDate to "2025-01-20T14:00:00Z"
set encodedText to do shell script "printf %s " & quoted form of postText & " | jq -sRr @uri"
set theURL to "statuz://schedule?text=" & encodedText & "&date=" & scheduleDate & "&status=queued"
do shell script "open " & quoted form of theURLError Handling
Common errors and solutions:
Invalid Date Format
❌ Error: "Invalid date format"
✅ Fix: Use ISO 8601: 2025-01-20T10:00:00Z
Date in Past
❌ Error: "Schedule date must be in the future"
✅ Fix: Verify your date is ahead of current time
Invalid Timezone
❌ Error: "Unknown timezone"
✅ Fix: Use IANA identifiers: America/New_York
Missing Text
❌ Error: "Text parameter is required"
✅ Fix: Always include text parameter
Best Practices
Platform Limits
Each platform has scheduling restrictions: