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 Transom 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

Transom 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
Authorization: Bearer <your-token>

{"title": "Build finished", "message": "Ready to ship"}
2

The transom:// URL scheme

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

open "transom://post?title=Build%20finished&message=Ready%20to%20ship"

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.

⚿

Authentication

Include your token as a Bearer header: Authorization: Bearer <your-token>. Find it in Preferences → Advanced → Local API (or read the Keychain item "Transom Local API Token"). Requests without a valid token get a 401.

curl -s -X POST 127.0.0.1:17893 \
  -H "Authorization: Bearer $TRANSOM_TOKEN" \
  -d '{"title":"Build done","symbol":"checkmark.seal.fill"}'

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 Transom never makes outbound calls on your behalf. Every post must carry your Mac's local API token, which Transom stores in the Keychain, and Transom validates each request's Origin and Host. So a website you visit can't reach the API, and no other app can post without the token.

Recipes

Copy, paste, adjust. These examples mirror the current API.

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:
transom://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 Transom 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.