HTTP API
Anything with an HTTP client can send. The URL key is enough for a personal inbox; the bearer token is for code you ship.
Doors
POST youlmk.com/k/{key}
Plain text becomes the title. JSON sets every field.
GET youlmk.com/k/{key}?title=&body=
For tools that cannot POST. Takes title, body, priority, url, url_label, group and image as query parameters.
POST youlmk.com/w/{key}
A service's own webhook shape, mapped into a notification. See Webhooks.
POST youlmk.com/v1/notify
The same JSON, with Authorization: Bearer ylk_… instead of the key in the URL. What the libraries and MCP use.
$ curl youlmk.com/k/k_7hq2nk3f9qd8w4 -d "backup finished"
$ curl "youlmk.com/k/k_7hq2nk3f9qd8w4?title=backup%20finished&priority=low"
$ curl youlmk.com/v1/notify \
-H "authorization: Bearer ylk_…" \
-H "content-type: application/json" \
-d '{ "title": "backup finished", "body": "4.2 GB · 3 min 10 s" }'
A body is read as JSON when the content type says so or when it starts with {; anything else is text and becomes the title. Every field is in the payload reference.
Responses
200
{ "ok": true, "id": "ntf_…", "receipt": "rcpt_…", "grouped": false, "held": false }. grouped is true when the notification joined an open card; held is true when quiet hours are holding it.
400
bad_json. The body was not JSON and did not read as text.
401
unknown_key. No source has this key or token, or the account is gone.
402
trial_used. The first 10 notifications are free; this one is kept for 7 days under Not delivered and released when you subscribe.
410
key_rotated. The key was rotated more than 24 hours ago, or the source was deleted.
413
too_large. The body is over 8 KB.
422
invalid_field, with "field" naming it: title, body, priority, url, url_label, actions, group, image or fields.
429
rate_limited with Retry-After in seconds; or daily_cap once the account has sent 100,000 in a day.
503
sending_paused with Retry-After: 60. Sending is switched off on our side; retry later.
Errors are JSON with one error code, so a script can branch on it. During the 24 hours after a rotation the old key still answers 200 and adds Deprecation: true.
Retries and idempotency
Send an Idempotency-Key header and the same key within 24 hours returns the first answer without a second notification, so a retrying sender cannot multiply deliveries. Keys are scoped to the source.
Limits
60 sends a minute per key, in bursts of up to 10 a second; above that, 429 with Retry-After. An abuse cap of 600 a minute answers 429 as well. 10,000 sends in a day sends the account's owner a Banner and blocks nothing; 100,000 in a day is the ceiling, and the rest of the day answers 429 daily_cap. Grouping absorbs legitimate bursts, so a limit is almost always a bug on the sender's side.
Keys and tokens
The URL key is k_ and 14 characters from a 32-letter alphabet, about 70 bits. The bearer token is ylk_ and 32 characters, shown once and stored hashed. Both belong to one source; rotating replaces both. A key that ships in a client app is public, so a client app sends through your server or through a source whose Reach you are happy to let strangers reach.
Next
Payload reference · Webhooks · MCP server