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

TOKEN=$(security find-generic-password -s com.transom.app -a local-api-token -w)
curl -X POST 127.0.0.1:17893 \
  -H "Authorization: Bearer $TOKEN" \
  -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.

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"}

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, eight 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.
priority	string	-	normal	HTTP door only. "urgent" lets the card through a Focus instead of being held. Still held by "VIPs and codes only" and by "Nothing gets through". Unknown values, and anything sent through transom://, are normal.

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 low-priority by default: while a Focus is on they're held and counted, then shown in the digest when it ends. Your build notification never interrupts deep work. Some machine messages are not build notifications, though. Send "priority":"urgent" on the token'd door and the card rides the same lane an urgent text from an unsaved number does: through a Focus, still held by "VIPs and codes only" and by Sleep.

≡

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 \
  -H "Authorization: Bearer $TRANSOM_TOKEN" \
  -d '{"title":"Build done","symbol":"checkmark.seal.fill"}' \
  || curl -s -X POST 127.0.0.1:17893 \
  -H "Authorization: Bearer $TRANSOM_TOKEN" \
  -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 os, requests
requests.post("http://127.0.0.1:17893",
              headers={"Authorization": "Bearer " + os.environ["TRANSOM_TOKEN"]},
              json={"title": "Export finished", "symbol": "film.fill",
                    "openURL": "file:///Users/you/Movies/render.mp4"})

AppleScript AppleScript / Automator

do shell script "TOKEN=$(security find-generic-password -s com.transom.app -a local-api-token -w); curl -s -X POST 127.0.0.1:17893 -H \"Authorization: Bearer $TOKEN\" -d '{\"title\":\"Backup complete\"}'"

shell A sticky card you can answer

curl -X POST 127.0.0.1:17893 \
  -H "Authorization: Bearer $TRANSOM_TOKEN" \
  -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",
  headers: { Authorization: `Bearer ${process.env.TRANSOM_TOKEN}` },
  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 for a normal post: check the digest when Focus ends, or look in Recent Notifications. If the card genuinely can't wait, send "priority":"urgent" on the HTTP door.

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.