DEVELOPER DOCS · SCHEMA v1

Post anything to your notch.

Anything on your Mac — a script, a Shortcut, an app, a cron job — can put a card in your notch with one line. No SDK, no account, no library to install.

Try it right now — paste into Terminal while Marqee is running 
curl -X POST 127.0.0.1:17893 -d '{"title":"Hello from Terminal"}'

A card appears in your notch. That's the whole learning curve.

Two doors, same room

Marqee accepts posts two ways. They do exactly the same thing — pick whichever fits your tool.

1

Local HTTP

For anything that can make a web request.

POST http://127.0.0.1:17893/
Content-Type: application/json

{"title": "Build finished", "message": "All 25 tests passing"}
2

The marqee:// URL scheme

For Shortcuts, AppleScript, or anything that can open a URL.

open "marqee://post?title=Build%20finished&message=All%2025%20tests%20passing"

URL-scheme values must be URL-encoded (spaces become %20). In the Shortcuts app, pass your text through the built-in "URL Encode" action first.

The fields

One required field, seven optional. In the URL scheme these are query parameters; booleans accept 1 or true.

Field Type Req Default What it does
title string yes — The card's headline. Truncated at 300 characters.
message string — none Body text under the title. Truncated at 4,000 characters, wraps up to 8 lines.
symbol string — bell.fill Any SF Symbols name, e.g. checkmark.seal.fill, hammer.fill, cart.fill.
duration number — 6 Seconds before a non-persistent card dismisses itself.
persistent boolean — false true = the card stays until you click its X. Use for things that must not be missed.
replyHandle string — none A phone number or iMessage address. The card gains an inline reply field that sends through Messages.
openURL string — none A URL. The card gains an open button.

Responses (HTTP)

200 {"ok":true} Card accepted.
400 {"ok":false,"error":"..."} Body wasn't valid JSON or title was missing.
413 {"ok":false,"error":"body too large"} Body over 64 KB. Cards are headlines, not documents.

Behavior you should know

Four things that make automation posts safe to fire and forget.

☾

Focus mode holds posts

Automation posts are deliberately low-priority: while Focus is on they're held and counted, then shown in the digest when Focus ends. Your build notification never interrupts deep work.

≡

Cards queue

If a persistent card is on screen when another arrives, nothing is lost — the newest shows with a "+1" chip and dismissing reveals the next.

↺

Everything lands in history

Recent Notifications in the menu bar keeps the last 200 cards, including the ones that were held.

⚿

Local only

The server binds to 127.0.0.1 exclusively; nothing on your network can reach it, and Marqee never makes outbound calls on your behalf. In v1 any local process may post — there's no token yet.

Recipes

Copy, paste, adjust. Every one is verified against the shipping code.

shell Know when a long job finishes 
make build && curl -s -X POST 127.0.0.1:17893 \
  -d '{"title":"Build done","symbol":"checkmark.seal.fill"}' \
  || curl -s -X POST 127.0.0.1:17893 \
  -d '{"title":"Build FAILED","symbol":"xmark.octagon.fill","persistent":true}'
Shortcuts A Shortcut with no code at all 
# Add a "Text" action containing:
marqee://post?title=Leave%20now&message=22%20min%20to%20school&symbol=car.fill

# then an "Open URLs" action. Wire it to a
# time-of-day automation. Done.
Python Post from Python 
import requests
requests.post("http://127.0.0.1:17893",
              json={"title": "Export finished", "symbol": "film.fill",
                    "openURL": "file:///Users/you/Movies/render.mp4"})
AppleScript AppleScript / Automator 
do shell script "curl -s -X POST 127.0.0.1:17893 -d '{\"title\":\"Backup complete\"}'"
shell A sticky card you can answer 
curl -X POST 127.0.0.1:17893 -d '{
  "title": "Standup reminder",
  "message": "Tell Dana you are running late?",
  "persistent": true,
  "replyHandle": "+15551234567",
  "symbol": "clock.badge.exclamationmark"
}'
Node.js Post from Node.js 
fetch("http://127.0.0.1:17893", {
  method: "POST",
  body: JSON.stringify({ title: "Deploy live", symbol: "paperplane.fill",
                         openURL: "https://yourapp.com" })
});

Troubleshooting

Nothing appears Is Marqee running? (Sparkles icon in the menu bar.) The listener only exists while the app does.
Card appeared then vanished That's the 6-second default — send "persistent": true or a longer duration.
Shortcut does nothing The deep-link values probably weren't URL-encoded; run each dynamic value through "URL Encode" first.
Posted during Focus and saw nothing Working as designed — check the digest when Focus ends, or look in Recent Notifications.
VERSIONING PROMISE

A script you write today keeps working.

This is schema v1. Fields will be added over time — always optional — and existing fields will never be renamed, removed, or change meaning.