Push device API — Voidhash Docs

The client API endpoints that register, refresh and unregister a device's push token, with their headers, fields and responses.

Your app registers each device's push token with the client API, so Voidhash can send push notifications to it. Register devices for push has the app code for Swift, Kotlin and React Native; this page is the reference behind it.

Endpoint	Body
`POST /api/v1/sdk/push-devices/register`	The device; see Register a device.
`POST /api/v1/sdk/push-devices/refresh`	`pushDeviceTokenId` and the new `platformToken`.
`POST /api/v1/sdk/push-devices/unregister`	`pushDeviceTokenId`.

The examples target Voidhash Cloud; a self-hosted install uses its own API origin.

Headers

The endpoints take the publishable key and the same headers the SDKs send. Every header is required except x-distinct-id-encoding. A request missing one fails with 400 and a body whose _tag is Api/SdkValidationError, with a message naming the problem.

Header	Value
`x-publishable-key`	The project's publishable key: `vh_pk_...`, or `vh_pk_test_...` in debug builds.
`x-distinct-id`	The person's distinct ID, the one the SDK uses.
`x-client-bundle-id`	The app's bundle ID on iOS or package name on Android.
`x-platform`	`ios` or `android`.
`x-platform-flavor`	`native` in an app.
`x-sdk`	The Voidhash SDK your app embeds: `ios`, `android` or `react-native`.
`x-sdk-version`	That SDK's version, such as `0.0.1-alpha.1`.
`x-is-debug-build`	`true` in a debug build, otherwise `false`.
`x-is-backgrounded`	`true` when the app sends the request from the background, otherwise `false`.
`x-observer-mode`	`true` when the SDK runs in observer mode, otherwise `false`.
`x-distinct-id-encoding`	Optional. `percent` when `x-distinct-id` is percent-encoded because the ID isn't printable ASCII.

The anonymous IDs the SDK creates never need percent-encoding.

Register a device

curl https://api.voidhash.com/api/v1/sdk/push-devices/register \
  -H "x-publishable-key: vh_pk_..." \
  -H "x-distinct-id: user_123" \
  -H "x-client-bundle-id: com.example.app" \
  -H "x-platform: ios" \
  -H "x-platform-flavor: native" \
  -H "x-sdk: ios" \
  -H "x-sdk-version: 0.0.1-alpha.1" \
  -H "x-is-debug-build: false" \
  -H "x-is-backgrounded: false" \
  -H "x-observer-mode: false" \
  -H "content-type: application/json" \
  -d '{
    "platform": "ios",
    "provider": "apns",
    "platformToken": "<device token as hex>",
    "bundleId": "com.example.app",
    "environment": "production"
  }'

Field	Description
`platform`	`ios` or `android`.
`provider`	`apns` for an APNs device token, `fcm` for an FCM registration token.
`platformToken`	The token from the platform. For APNs, the device token as a hex string.
`bundleId`	Required for `apns`.
`environment`	Required for `apns`: `sandbox` for builds run from Xcode, `production` for TestFlight and the App Store.
`previousPushDeviceTokenId`	Optional. The ID from an earlier install or token, so Voidhash drops that registration.

The response holds a pushDeviceTokenId; keep it on the device. Registering the same token again returns the same ID. A device belongs to the person who registered it last: registering the token under another distinct ID moves it.

Refresh and unregister

When the platform rotates the token, call refresh with pushDeviceTokenId and the new platformToken. When the person signs out, call unregister with pushDeviceTokenId before the SDK signs out. Both send the same headers as register. They answer 404 for a device that another distinct ID registered, which is why unregistering after signOut() fails.

When APNs or FCM reports that a token no longer exists, Voidhash stops sending to it.

Responses

Registration never needs to block the UI or a purchase. Run it in the background and treat a failure as "try again next launch".

Response	Meaning	What to do
Network error, `500`	Voidhash couldn't be reached or failed.	Retry on the next launch or token change.
`400`	A header or body field is missing or invalid, such as `apns` without `bundleId` and `environment`.	Fix the request; retrying won't help.
`401`	The publishable key is wrong.	Check the key and its environment.
`403`	Push notifications aren't turned on for your team.	Ask us to turn them on; don't retry.
`404`	The device isn't registered to this distinct ID.	On unregister, treat it as done.

Next steps

Register devices for push: the app code for each platform.
Push notifications: connect APNs or FCM, send and follow delivery.
People and identity: how distinct IDs map devices to people.

Endpoint	Body
`POST /api/v1/sdk/push-devices/register`	The device; see Register a device.
`POST /api/v1/sdk/push-devices/refresh`	`pushDeviceTokenId` and the new `platformToken`.
`POST /api/v1/sdk/push-devices/unregister`	`pushDeviceTokenId`.