Notifications alert users of platform activities, such as due dates, updates, and more. They appear in multiple locations, including the bell icon and email.

Notifications relevant only to the signed-in user appear under the bell icon. By default, they will also receive an email whenever they get a notification. This can be turned off and customized in the user’s profile settings.

Queries

Get notifications

Returns metadata about a user's notifications
Can only be queried directly at the root; can't be nested within another query

query {
  notifications(filter_read: true) {
    text
    title
    id
  }
}

{
  "data": {
    "notifications": [
      {
        "text": "This is a notification",
        "title": "New test notification",
        "id": "123456"
      }
    ]
  },
  "extensions": {
    "request_id": "YOUR_REQUEST_ID"
  }
}

Arguments

Argument	Type	Description
cursor	`ID`	The unique identifier of the last notification to retrieve.
filter_read	`Boolean`	Whether to retrieve only unread notifications.
limit	`Int`	The number of notifications returned. The default is 25.
since	`ISO8601DateTime`	Filter notifications from this date (inclusive).

Fields

Field	Type	Description
board	`Board`	The board associated with the notification.
created_at	`Date`	The notification's creation date.
creators	`[User!]!`	The notifications creator(s).
id	`ID!`	The notification's unique identifier.
item	`Item`	The item associated with the notification.
read	`Boolean!`	Whether the notification has been read.
text	`String`	The notification's text.
title	`String`	The notification's title.
update	`Update`	The update associated with the notification.

Mutations

Required scope:notifications:write

Create notification

Sends a notification to the bell icon via the API. Doing so may also send an email if the recipient's email preferences are set up accordingly.

If you send a notification from a board view or widget using seamless authentication, it will be sent from the app and display its name and icon. If you use a personal API key to make the call, the notification will appear to come from the user who installed the app on the account.

This mutation only sends the notification. Since notifications are asynchronous, you can't query back the notification ID when running the mutation.

mutation {
  create_notification(
    user_id: 12345678
    target_id: 674387
    text: "This is a notification"
    target_type: Project
  ) {
    text
  }
}

Arguments

Argument	Type	Description	Enum Values
target_id	`ID!`	The target's unique identifier. The value depends on the `target_type`: • `Post`: update or reply ID • `Project`: item or board ID
target_type	`NotificationTargetType!`	The target's type.	`Post` (sends a notification referring to an update or reply) `Project` (sends a notification referring to an item or board)
text	`String!`	The notification's text.
user_id	`ID!`	The user's unique identifier.