> For the complete documentation index, see [llms.txt](https://docs.kiiglobal.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/notifications.md). # Notifications ## MarkUserPushNotificationsAsRead marks a list of push notifications as read for the authenticated user > Accepts up to 200 notification\_ids per call. Only affects notifications\ > owned by the caller ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Commands (write operations)","name":"NotificationsMsgService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["notifications.user_notifications.write"]},{"BearerAuth":["notifications.user_notifications.write"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1MarkUserPushNotificationsAsReadRequest":{"properties":{"notificationIds":{"items":{"type":"string"},"title":"notification_ids contains the list of push notification identifiers to mark as read","type":"array"}},"required":["notificationIds"],"title":"MarkUserPushNotificationsAsReadRequest is the body request from the mark notifications as read endpoint","type":"object"},"v1MarkUserPushNotificationsAsReadResponse":{"properties":{"notifications":{"items":{"$ref":"#/components/schemas/v1Notification"},"title":"notifications contains the updated push notifications","type":"array"}},"required":["notifications"],"title":"MarkUserPushNotificationsAsReadResponse is the body response from the mark notifications as read endpoint","type":"object"},"v1Notification":{"properties":{"channel":{"title":"channel is the way to send the notification","type":"string"},"createdAt":{"format":"date-time","title":"created_at is the date when the notification was created","type":"string"},"failReason":{"title":"fail_reason is the notification fail reason","type":"string"},"id":{"title":"id is the notification identifier","type":"string"},"notificationName":{"title":"notification_name is the notification name","type":"string"},"payload":{"title":"payload contains the notification information (headers and body)","type":"string"},"readAt":{"format":"date-time","title":"read_at is the timestamp when the notification was read (absent = unread)","type":"string"},"status":{"title":"status is the notification status","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the notification was updated","type":"string"},"userId":{"title":"user_id is the user identifier who has received the notification","type":"string"}},"required":["id","userId","channel","notificationName","status","payload","createdAt"],"title":"Notification contains all information with a notification","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/notifications/v1/me/notifications/push/read":{"post":{"description":"Accepts up to 200 notification_ids per call. Only affects notifications\nowned by the caller","operationId":"NotificationsMsgService_MarkUserPushNotificationsAsRead","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1MarkUserPushNotificationsAsReadRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1MarkUserPushNotificationsAsReadResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"MarkUserPushNotificationsAsRead marks a list of push notifications as read for the authenticated user","tags":["NotificationsMsgService"]}}}} ``` ## GetNotificationsByUserId returns all notification on the system associated to the provided user > Includes every channel and status, not just push. For a single user's\ > unread push notifications use GetUserPushNotifications instead ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"NotificationsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["notifications.user_notifications.read","notifications.user_notifications.read:all"]},{"BearerAuth":["notifications.user_notifications.read","notifications.user_notifications.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetNotificationsByUserIdResponse":{"properties":{"notifications":{"items":{"$ref":"#/components/schemas/v1Notification"},"title":"notifications contains the array of notifications","type":"array"},"pagination":{"$ref":"#/components/schemas/v1Pagination"}},"required":["notifications","pagination"],"title":"GetNotificationsByUserIdResponse is the body response from the get notifications by user id endpoint","type":"object"},"v1Notification":{"properties":{"channel":{"title":"channel is the way to send the notification","type":"string"},"createdAt":{"format":"date-time","title":"created_at is the date when the notification was created","type":"string"},"failReason":{"title":"fail_reason is the notification fail reason","type":"string"},"id":{"title":"id is the notification identifier","type":"string"},"notificationName":{"title":"notification_name is the notification name","type":"string"},"payload":{"title":"payload contains the notification information (headers and body)","type":"string"},"readAt":{"format":"date-time","title":"read_at is the timestamp when the notification was read (absent = unread)","type":"string"},"status":{"title":"status is the notification status","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the notification was updated","type":"string"},"userId":{"title":"user_id is the user identifier who has received the notification","type":"string"}},"required":["id","userId","channel","notificationName","status","payload","createdAt"],"title":"Notification contains all information with a notification","type":"object"},"v1Pagination":{"properties":{"currentPage":{"format":"int32","title":"current_page is the current page number","type":"integer"},"limit":{"format":"int32","title":"limit contains the limit used to calculate the page","type":"integer"},"totalItems":{"format":"int32","title":"total_items is the total number of items","type":"integer"},"totalPages":{"format":"int32","title":"total_pages is the total number of pages","type":"integer"}},"required":["currentPage","totalItems","totalPages","limit"],"title":"Pagination contains the keys to move between pages\nusing the cursor-based pagination","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/notifications/v1/users/{userId}/notifications":{"get":{"description":"Includes every channel and status, not just push. For a single user's\nunread push notifications use GetUserPushNotifications instead","operationId":"NotificationsQueryService_GetNotificationsByUserId","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}},{"description":"page is an optional query parameter to set the page number","in":"query","name":"page","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"limit is an optional query parameter to set the max amount of\nresults per page","in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetNotificationsByUserIdResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetNotificationsByUserId returns all notification on the system associated to the provided user","tags":["NotificationsQueryService"]}}}} ``` ## GetUserPushNotifications returns all unread push notifications for the authenticated user > Push channel only and unread only. Mark them read via\ > MarkUserPushNotificationsAsRead once shown to the user ```json {"openapi":"3.0.0","info":{"title":"KiiChain Pay Backend","version":"v1"},"tags":[{"description":"Queries (read operations)","name":"NotificationsQueryService"}],"servers":[{"description":"Production","url":"https://backend.pay.kiichain.io"},{"description":"Staging","url":"https://backend.pay.staging.kiichain.io"}],"security":[{"ApiKeyAuth":["notifications.user_notifications.read","notifications.user_notifications.read:all"]},{"BearerAuth":["notifications.user_notifications.read","notifications.user_notifications.read:all"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Send 'Authorization: APIKey ' to authenticate with a API key.","in":"header","name":"Authorization","type":"apiKey"},"BearerAuth":{"flows":{"password":{"scopes":{},"tokenUrl":"https://backend.pay.kiichain.io/users/v1/auth/login"}},"type":"oauth2"}},"schemas":{"v1GetUserPushNotificationsResponse":{"properties":{"notifications":{"items":{"$ref":"#/components/schemas/v1Notification"},"title":"notifications contains the array of unread push notifications for the authenticated user","type":"array"}},"required":["notifications"],"title":"GetUserPushNotificationsResponse is the body response from the get user push notifications endpoint","type":"object"},"v1Notification":{"properties":{"channel":{"title":"channel is the way to send the notification","type":"string"},"createdAt":{"format":"date-time","title":"created_at is the date when the notification was created","type":"string"},"failReason":{"title":"fail_reason is the notification fail reason","type":"string"},"id":{"title":"id is the notification identifier","type":"string"},"notificationName":{"title":"notification_name is the notification name","type":"string"},"payload":{"title":"payload contains the notification information (headers and body)","type":"string"},"readAt":{"format":"date-time","title":"read_at is the timestamp when the notification was read (absent = unread)","type":"string"},"status":{"title":"status is the notification status","type":"string"},"updatedAt":{"format":"date-time","title":"updated_at is the date when the notification was updated","type":"string"},"userId":{"title":"user_id is the user identifier who has received the notification","type":"string"}},"required":["id","userId","channel","notificationName","status","payload","createdAt"],"title":"Notification contains all information with a notification","type":"object"},"AppErrorStatus":{"description":"The error envelope this API returns for every non-2xx response. `details` always contains exactly one AppError.","properties":{"code":{"description":"gRPC status code","format":"int32","type":"integer"},"details":{"description":"Always contains exactly one AppError","items":{"$ref":"#/components/schemas/AppError"},"type":"array"},"message":{"description":"Human-readable error message","type":"string"}},"type":"object"},"AppError":{"description":"Structured error detail responded by any non-2xx response.","properties":{"@type":{"description":"Protobuf Any type URL, always \"type.googleapis.com/pay.common.error.v1.AppError\" for this API","type":"string"},"internalCode":{"description":"Internal error code, unique within the module","format":"int32","type":"integer"},"message":{"description":"Human-readable error message","type":"string"},"meta":{"additionalProperties":{"type":"string"},"description":"Additional structured context for the error, if any","type":"object"},"module":{"description":"Module name where the error occurred (e.g. \"accounts\", \"market\")","type":"string"}},"type":"object"}},"responses":{"AppError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorStatus"}}},"description":"An unexpected error response. `details[0]` is always an AppError, see #/components/schemas/AppError"}}},"paths":{"/notifications/v1/users/{userId}/notifications/push":{"get":{"description":"Push channel only and unread only. Mark them read via\nMarkUserPushNotificationsAsRead once shown to the user","operationId":"NotificationsQueryService_GetUserPushNotifications","parameters":[{"description":"user_id represents the user identifier","in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetUserPushNotificationsResponse"}}},"description":"A successful response."},"default":{"$ref":"#/components/responses/AppError"}},"summary":"GetUserPushNotifications returns all unread push notifications for the authenticated user","tags":["NotificationsQueryService"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiiglobal.io/docs/kiichain-pay/api-reference/notifications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.