Publish - Grantiva

Backend-facing endpoint, authenticated with the app’s secret key (grv_sec_, sent as X-API-Key or Authorization: Bearer). Never ship the secret key in a client app — a public key on this route returns 403.

POST /v1/apps/:appID/publish

event is your own event name, 1–100 characters. Publish to one channel with channel or up to 100 with channels.

Alert push

{
  "channel": "order:42:status",
  "event": "order:shipped",
  "excludeTokens": ["<hex of originating device>"],
  "push": {
    "type": "alert",
    "title": "Your order shipped",
    "body": "Arriving Thursday",
    "badge": 1,
    "sound": "default",
    "payload": { "orderId": "42" }
  }
}

payload is merged at the APNs payload root as custom userInfo. Use channels: ["a", "b"] instead of channel to publish to several channels — a token subscribed to more than one still receives a single push.

Live Activity push

{
  "channel": "delivery:42",
  "event": "delivery:progress",
  "push": {
    "type": "liveactivity",
    "liveActivityEvent": "update",
    "activityID": "optional — restrict update/end to one activity",
    "contentState": { "eta": "12:45", "stop": 3 },
    "staleDate": "2026-06-11T19:00:00Z",
    "relevanceScore": 0.9,
    "alert": { "title": "Almost there", "body": "3 stops away" }
  }
}

`liveActivityEvent`	Routed to	Required fields
`start`	`liveactivity-start` tokens	`attributesType`, `attributes`, `contentState`
`update`	`liveactivity-update` tokens (filtered by `activityID` when given)	`contentState`
`end`	`liveactivity-update` tokens	— (`dismissalDate` optional)

Grantiva sets apns-push-type: liveactivity, topic <bundleID>.push-type.liveactivity, priority 10, and the payload envelope (timestamp, event, content-state, plus attributes-type/attributes on start).

Response

{ "delivered": 41, "failed": 0, "pruned": 2 }

pruned — subscriptions deleted because APNs returned 410 Unregistered or 400 BadDeviceToken.
Publishing to a channel with zero subscribers is a 200 with delivered: 0.
Publishing before the app’s APNs credentials are configured returns 409.

Fan-out is concurrent (capped at 16 in-flight APNs sends) and synchronous within the request.

Errors

Status	Meaning
400	Neither `channel` nor `channels` given, more than 100 channels, an invalid channel name, an `event` outside 1–100 characters, `push.type` not `alert`/`liveactivity`, `push.liveActivityEvent` not `start`/`update`/`end`, or a Live Activity push missing `contentState` (or `attributesType`/`attributes` on `start`)
401	Missing or invalid API key
403	A public key was used — publishing requires the secret key
409	APNs credentials are not configured for this app