Developer APIs
URL Scheme API Overview
Control Statuz programmatically with deep links from scripts, shortcuts, and external apps
URL Scheme API Overview
The Statuz URL Scheme API provides a powerful way to control Statuz programmatically from external applications, shell scripts, Shortcuts, and automation tools. Create posts, schedule content, manage accounts, and control the app—all via simple URL commands.
Why Use the URL Scheme API?
Base Scheme
statuz://
For Debug builds, use statuz-dev://
Quick Example
Post to social media with a single command:
open "statuz://compose?text=Hello%20World!"
Schedule a post:
open "statuz://schedule?text=Tomorrow's%20update&date=2025-01-20T09:00:00Z"
Attach media:
open "statuz://compose?text=Check%20this%20out&media=file:///path/to/image.png"
Need to pass raw file paths instead of file:// URLs? Use the files parameter (alias for media) to send absolute paths, even with spaces, straight to Statuz.
Available Actions
| Action | Purpose | Learn More |
|---|---|---|
| compose | Create and publish posts | Compose Action |
| schedule | Schedule posts for later | Schedule Action |
| scheduled | Edit or delete queued posts | Scheduled Action |
| accounts | Manage social accounts | Accounts Action |
| calendar | View and navigate calendar | Calendar Action |
| settings | Open specific settings panes | Settings Action |
| license | Manage license | License Action |
| open | Bring app to foreground | Open Action |
Common Use Cases
1. Automation Scripts
Automate social media posting from shell scripts, cron jobs, or CI/CD pipelines:
#!/bin/bash
# Daily status update
TEXT="Daily report: All systems operational ✅"
open "statuz://compose?text=$(echo "$TEXT" | jq -sRr @uri)"2. Apple Shortcuts
Create iOS/macOS shortcuts for:
3. Raycast/Alfred Workflows
Build custom workflows:
4. Keyboard Maestro
Trigger Statuz actions with custom hotkeys:
5. Hazel Rules
Automate based on file system events:
Platform Support
The URL Scheme API supports all Statuz platforms:
Platform and account selection is done in the Statuz UI when using compose action, or can be specified via parameters for schedule and scheduled actions.
Security & Permissions
File Access
Statuz respects macOS sandbox restrictions. When attaching files:
User Consent
Credentials
Account credentials are never exposed through the URL scheme:
Best Practices
URL Encoding
Always encode parameter values:
// JavaScript
const text = 'Hello World! 🎉';
const encoded = encodeURIComponent(text);
const url = `statuz://compose?text=${encoded}`;# Python
from urllib.parse import quote
encoded = quote("Hello World! 🎉")
url = f"statuz://compose?text={encoded}"# Shell (with jq)
ENCODED=$(printf %s "Hello World! 🎉" | jq -sRr @uri)
open "statuz://compose?text=$ENCODED"File Paths
Use file:// URLs for local media:
statuz://compose?media=file:///Users/username/Pictures/image.png
Multiple files (comma-separated):
statuz://compose?media=file:///path/1.png,file:///path/2.jpg
Date Formats
Use ISO 8601 for dates:
Next Steps
Support
Questions or issues with the URL Scheme API?