Notification

A subscription ties one user to one topic over one transport, rendered in one locale. A topic is the function instance itself, not a per-device evaluation of it — one subscription covers a graph bound to a whole device group. Subscribing takes read access to the instance and to whatever it is bound to.

Nothing is rendered or sent here: a functions graph names the template, and email resolves the audience from these entries and re-checks each subscriber's access before delivering. Changes go out as NOTIFICATION_SUBSCRIBE, NOTIFICATION_SUBSCRIPTION_UPDATE and NOTIFICATION_UNSUBSCRIBE events over the websocket.

POST	Subscribe to a topic/api/v1/notifications/subscribe
GET	List own subscriptions/api/v1/notifications/subscribe
PATCH	Change a subscription's locale/api/v1/notifications/subscribe/:subscriptionId
DELETE	Cancel a subscription/api/v1/notifications/subscribe/:subscriptionId

Subscribe to a topic

Subscribes the calling user to one function instance's notifications; topic is the instance CRN. No recipient travels in the body — delivery resolves the address from the caller's own account.

POST/api/v1/notifications/subscribe

Body

Name	Description
topicstring	Unique Coldwave resource name (CRN) that identifies a resource
typeenum	Transport the notification is delivered over. Only email is delivered today; apn, gcm and webpush are named by the schema but refused with 400. Possible values: email, apn, gcm, webpush
localestring	Language tag as en or en-GB: two lowercase letters, optionally a region in uppercase. Pattern: ^[a-z]{2}(-[A-Z]{2})?$

Response

Name	Description
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource

Errors

Status	Description	Body
403	You do not have permission to perform this action
400	Either type names a transport that is not delivered yet, or topic is not a function instance of this tenant. message says which of the two.	message: string
409	This user already subscribes to this topic over this transport; a second entry would only double every notification. The existing one is in the subscription list.
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

List own subscriptions

The caller's own subscriptions and nothing else — no route lists another user's. Entries vanish by themselves once the function instance behind their topic is deleted.

GET/api/v1/notifications/subscribe

Response

Name	Description
topicstring	Unique Coldwave resource name (CRN) that identifies a resource
typeenum	Transport this subscription is delivered over; email for every subscription that can be created today. Possible values: email, apn, gcm, webpush
localestring	Language tag as en or en-GB: two lowercase letters, optionally a region in uppercase. Pattern: ^[a-z]{2}(-[A-Z]{2})?$
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Errors

Status	Description	Body
403	You do not have permission to perform this action
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Change a subscription's locale

locale is the only field a PATCH may change. Topic and transport are the subscription's identity — to change either, delete it and subscribe again.

PATCH/api/v1/notifications/subscribe/Yk3pL7rWq2

Path Parameters

Name	Description
subscriptionIdstring	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Body

Name	Description
localestring	Language tag as en or en-GB: two lowercase letters, optionally a region in uppercase. Pattern: ^[a-z]{2}(-[A-Z]{2})?$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No subscription with this id under the caller's own user — another user's id reads exactly the same. Valid ids come from the subscription list.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Cancel a subscription

Stops delivery and removes the entry, including its index on the topic. The id resolves only under the caller's own user, so somebody else's subscription answers 404 rather than 403.

DELETE/api/v1/notifications/subscribe/Yk3pL7rWq2

Path Parameters

Name	Description
subscriptionIdstring	Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$

Errors

Status	Description	Body
403	You do not have permission to perform this action
404	No subscription with this id under the caller's own user — another user's id reads exactly the same. Valid ids come from the subscription list.
400	The request did not match the schema for this endpoint. The details field carries the specific failures.	error: Validation Error
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---

Events

Published on the tenant's event stream and delivered over the websocket to every subscriber holding read on the resource the message names. resourceIdentifier is the resource the action changed; the payload is the shape below.

Event	Description
NOTIFICATION_SUBSCRIBE	A user subscribed to a topic; the entry is indexed on the topic in the same step, which is what lets delivery find it.
NOTIFICATION_SUBSCRIPTION_UPDATE	The locale of a subscription was changed; the payload carries the whole entry as it now stands, not just the new value.
NOTIFICATION_UNSUBSCRIBE	A user cancelled a subscription. The payload is empty — the CRN of the removed entry is the whole of it.

Subscription created

A user subscribed to a topic; the entry is indexed on the topic in the same step, which is what lets delivery find it.

EVENTNOTIFICATION_SUBSCRIBE

Payload

Name	Description
topicstring	Unique Coldwave resource name (CRN) that identifies a resource
typeenum	Transport this subscription is delivered over; email for every subscription that can be created today. Possible values: email, apn, gcm, webpush
localestring	Language tag as en or en-GB: two lowercase letters, optionally a region in uppercase. Pattern: ^[a-z]{2}(-[A-Z]{2})?$
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Subscription updated

The locale of a subscription was changed; the payload carries the whole entry as it now stands, not just the new value.

EVENTNOTIFICATION_SUBSCRIPTION_UPDATE

Payload

Name	Description
topicstring	Unique Coldwave resource name (CRN) that identifies a resource
typeenum	Transport this subscription is delivered over; email for every subscription that can be created today. Possible values: email, apn, gcm, webpush
localestring	Language tag as en or en-GB: two lowercase letters, optionally a region in uppercase. Pattern: ^[a-z]{2}(-[A-Z]{2})?$
resourceIdentifierstring	Unique Coldwave resource name (CRN) that identifies a resource
createdBystring	Resource identifier of the entity that created this resource
createdAtinteger	Unix timestamp in milliseconds when this resource was created.

Subscription removed

A user cancelled a subscription. The payload is empty — the CRN of the removed entry is the whole of it.

EVENTNOTIFICATION_UNSUBSCRIBE

Payload

Name	Description