notifications reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

POST /v1/notifications/send

Authentication: Secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ title: string;
  body: string;
  customerId?: string | undefined;
  email?: string | undefined;
  emails?: string[] | undefined;
  apnsTokens?: string[] | undefined;
  data?: Record<string, string> | undefined;
  badge?: number | undefined;
  sound?: string | undefined;
  }

Validation schemas: sendPushNotificationRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

SendPushNotificationResult

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: sendPush.

POST /v1/notifications/devices

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ transport: "apns" | "fcm";
  token: string;
  bundleId?: string | undefined;
  pushEnvironment?: "production" | "development" | undefined;
  deviceModel?: string | undefined;
  osVersion?: string | undefined;
  appVersion?: string | undefined;
  ownershipTransition?: "explicit_sign_out" | undefined;
  }

Validation schemas: registerDeviceTokenRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  id: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: registerDevice.

DELETE /v1/notifications/devices

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ transport: "apns" | "fcm";
  token: string;
  }

Validation schemas: unregisterDeviceTokenRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

{ success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: unregisterDevice.