Skip to Content
Pocket Notifier

Publish

Send a message to a project, with priority, tags, actions and attachments.

POST /v1/projects/{project}/messages
Authorization: Bearer nt_...
Content-Type: application/json

The 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

ValueNameOn Android
5urgentPops up, long vibration, can bypass Do Not Disturb
4highPops up on screen
3defaultSound and vibration
2lowSilent, listed in the shade
1minSilent, 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.

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 id that 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 other id is turned into one: accents removed, lowercased, everything else becomes -, cut to 63 characters (org/repo becomes org-repo). If that slug already belongs to a feature with a different name, -2, -3 and so on is appended.
  • Name. A new feature is named conversation.title, else id. An existing feature keeps its name.
  • Stored as conversation = { id: <feature slug>, title: <feature name> }, in the thread c:<slug>. Each message moves the feature's lastMessageAt, which orders features.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.

On this page