Mobile push subscriptions API

Register mobile devices to receive push notifications for the authenticated user’s to-do items. Every push notification corresponds to a to-do item. Registering a device does not deliver notifications by itself: delivery is enabled separately for the instance with the mobile_push_notifications_dispatch feature flag.

Every notification carries the user’s pending to-do count as the app badge. When the mobile_push_badge_sync feature flag is also enabled, a change to that count that creates no to-do item (marking to-do items as done or restoring them, snoozing them, or deleting their target) sends a badge-only notification a few seconds later: no alert text and no sound, only the new count. One badge-only notification is sent per user and change window, however many to-do items the change affected.

Register a device

Registers a device token for the authenticated user. This endpoint is an idempotent upsert: registering an existing token again refreshes its attributes and last_seen_at timestamp, so clients re-register on every application start. Attributes omitted from the request keep their stored values when the token is already registered. Registering a token that belongs to another user reassigns it to the authenticated user.

Each user can register up to 20 devices. Subscriptions not seen for 90 days are removed automatically.

POST /user/push_subscriptions

Supported attributes:

Example request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "device_token=abcdef0123456789abcdef0123456789" \
  --data "apns_environment=sandbox" \
  --url "https://gitlab.example.com/api/v4/user/push_subscriptions"

If successful, returns 201 and the following response attributes:

Example response:

{
  "id": 1,
  "created_at": "2026-07-30T18:15:31.189Z"
}

Unregister a device

Deletes every subscription for a device token, including subscriptions that other users registered. For example, call this endpoint when a user signs out. If a previous user’s sign-out request did not reach GitLab, this call also stops that user’s notifications on the device. The token is passed in the request body rather than the URL so it does not appear in access logs. Returns 204 No Content on success and 404 Not Found when no subscription exists for the token.

DELETE /user/push_subscriptions

Supported attributes:

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "device_token=abcdef0123456789abcdef0123456789" \
  --url "https://gitlab.example.com/api/v4/user/push_subscriptions"