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?

• 🔗 No API Keys Required - Direct communication with the running app
• ⚡ Zero Latency - Instant local IPC, no network calls
• 🛠️ Universal Integration - Works with any tool that can open URLs
• 🔒 Sandbox-Friendly - Full macOS sandbox support with smart permission handling
• 🎯 Simple & Intuitive - Clear, self-documenting action names

Base Scheme

statuz://

For Debug builds, use statuz-dev://

Quick Example

Post to social media with a single command:

Schedule a post:

Attach media:

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

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:

• Quick post from clipboard
• Schedule weekly announcements
• Share screenshots with captions
• Create threads from long-form content

3. Raycast/Alfred Workflows

Build custom workflows:

• Post selected text to Statuz
• Schedule posts with natural language dates
• Quick account switching

4. Keyboard Maestro

Trigger Statuz actions with custom hotkeys:

• Screenshot → Composer with image
• Copy text → Schedule for morning
• Select files → Create thread

5. Hazel Rules

Automate based on file system events:

• New file in folder → Post to social media
• Daily report generated → Schedule post
• Screenshot saved → Open composer

Platform Support

The URL Scheme API supports all Statuz platforms:

• X (Twitter) - Platform identifier: x
• BlueSky - Platform identifier: bluesky
• Mastodon - Platform identifier: mastodon

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:

1. First Time - Statuz prompts for folder access and stores a security-scoped bookmark
2. Subsequent Calls - Silent access using stored bookmarks
3. Remote URLs - Automatically downloaded (supports PNG/JPG/GIF images plus MP4/MOV video), no prompts needed

User Consent

• Posts opened via URL scheme require user action in the UI
• Use stealthMode=true parameter to skip confirmation dialogs (for scheduled edits)
• Publishing always requires valid license for premium features

Credentials

Account credentials are never exposed through the URL scheme:

• OAuth must be done through the app's secure UI
• The API can only modify safe fields (nicknames, enabled status)
• Tokens and passwords remain in macOS Keychain

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:

• UTC: 2024-12-25T10:00:00Z
• With timezone: 2024-12-25T10:00:00-05:00
• Local time: 2024-12-25T10:00:00

Next Steps

• Compose Action - Create and publish posts
• Schedule Action - Schedule posts for later
• Scheduled Action - Edit or delete queued posts
• Calendar Action - Jump directly to any view/date
• Settings Action - Deep-link into configuration panes
• License Action - Handle activation, verification, or purchase
• Accounts Action - Manage social accounts
• Example Scripts - Ready-to-use automation ideas

Support

Questions or issues with the URL Scheme API?

• 📧 Email: [email protected]
• 📚 Examples: GitHub Repository