Publish
Send a message to a project, with priority, tags, actions and attachments.
POST /v1/projects/{project}/messages
Authorization: Bearer nt_...
Content-Type: application/jsonThe token's owner must be an owner or publisher of the project, and the project must be in the token's scope.
Examples
curl -X POST "$NOTIFIER_URL/v1/projects/backups/messages" \
-H "Authorization: Bearer $NOTIFIER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"body":"Nightly backup finished in 4m12s"}'Response
201 Created
{
"id": "msg_01jd8x5k2m9q7r4t6v8w0y3z5a",
"project": "deploys",
"createdAt": "2026-11-20T12:00:00.000Z",
"expiresAt": "2026-12-20T12:00:00.000Z"
}Fields
The authoritative schema is PublishInput in packages/contract/src/message.ts, and limits live in MESSAGE_LIMITS.
Prop
Type
Priority
| Value | Name | On Android |
|---|---|---|
| 5 | urgent | Pops up, long vibration, can bypass Do Not Disturb |
| 4 | high | Pops up on screen |
| 3 | default | Sound and vibration |
| 2 | low | Silent, listed in the shade |
| 1 | min | Silent, collapsed, no status bar icon |
Each level is its own notification channel, so users can change how it behaves in system settings.
Actions
Every action has a label (up to 40 characters), an optional key, and clear, which dismisses the notification after the action runs. If key is left out, it becomes the action's index ("0", "1", …). Replies refer to it.
{ "type": "view", "label": "Open PR", "url": "https://github.com/acme/app/pull/42" }Opens the URL in the browser, or in another app if it is a deep link.
{ "type": "http", "label": "Approve", "url": "https://hooks.example.com/approve/42", "method": "POST", "body": "{\"ok\":true}" }The phone sends the request in the background. url must be HTTPS. method is GET, POST (the default), PUT or DELETE. body is up to 1,024 characters.
Open: no secrets
There is no headers field. Everything in an action is stored and sent to every subscriber's phone, so a secret in it would leak. Use an unguessable URL, or a server-side action later. Open
{ "type": "reply", "key": "ack", "label": "Got it" }With input: false (the default), tapping the button records an ack. With input: true, Android shows a text field in the notification. placeholder sets its hint, and up to 3 quickReplies appear as one-tap suggestions. Each person can respond to an action once.
At most 3 actions fit on an Android notification; the rest appear only in the message screen. Open
Conversations and features
Every conversation is a feature. A message with conversation is filed under the project's feature for conversation.id, which is created on first use; a message without one goes to the project-level thread, p:<projectId>. The same rule applies to the REST API, the app API and MCP, so all three put the same conversation in the same thread.
- Slug. An
idthat is a valid feature slug once lowercased ([a-z0-9][a-z0-9-]{0,62}) is the slug, and an existing feature with it is reused as it is. Any otheridis turned into one: accents removed, lowercased, everything else becomes-, cut to 63 characters (org/repobecomesorg-repo). If that slug already belongs to a feature with a different name,-2,-3and so on is appended. - Name. A new feature is named
conversation.title, elseid. An existing feature keeps its name. - Stored as
conversation = { id: <feature slug>, title: <feature name> }, in the threadc:<slug>. Each message moves the feature'slastMessageAt, which ordersfeatures.list.
A tap on the notification opens that thread. The clickUrl is an Open button on the message there, and an action on the notification.
Projects
The project in the URL must already exist. Publishing to an unknown project returns 404 NOT_FOUND instead of creating it, so a typo cannot create a project nobody is subscribed to. Projects are created in the dashboard or the app. Open
Attachments
Attaching a file takes two steps. First upload the file, then publish with its ID:
Upload
curl -X POST "$NOTIFIER_URL/v1/projects/ci/attachments" \
-H "Authorization: Bearer $NOTIFIER_TOKEN" \
-F "file=@report.html"{ "id": "att_01jd8x7q3n1p5s8u0w2y4a6c8e", "expiresAt": "2026-11-20T13:00:00.000Z" }Publish
{ "title": "Coverage report", "attachmentId": "att_01jd8x7q3n1p5s8u0w2y4a6c8e" }Uploads not used within an hour are deleted. The proposed size cap is 15 MB per file (ATTACHMENT_MAX_BYTES); larger files get 413 PAYLOAD_TOO_LARGE. Open
Subscribers download through short-lived signed URLs in message.attachment.url. The file expires together with its message.