1. Reference
2. Web API
3. Notifications

Notifications

The Notifications API has methods for subscribing to updates and managing notifications.

Get notification

Get a notification by id.

GET /api/notifications/{id}

Path parameters

id integer required

Notification id.

Query parameters

trashed boolean

true to return notification even if trashed.

Example request

curl {WEAVY-URL}/api/notifications/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "id": "integer",
  "type": "string",
  "action": "string",
  "actor": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "avatar_url": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "directory_id": "integer",
    "created_at": "string",
    "updated_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "template": "string",
  "args": [
    "string"
  ],
  "text": "string",
  "html": "string",
  "plain": "string",
  "link": {
    "id": "integer",
    "type": "string"
  },
  "url": "string",
  "user": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "avatar_url": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "directory_id": "integer",
    "created_at": "string",
    "updated_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "is_unread": "boolean"
}

List notifications

List notifications for the authenticated user.

GET /api/notifications

Query parameters

action string

List notifications that were triggered by actions of this type, e.g. message_created or comment_updated etc.

type string

List notifications of specified type (activity, mention or reaction). When not specified notifications of all types are listed.

unread boolean

true lists unread notifications, false lists read notifications and null (default) lists all notifications whether they are read or not.

q string

A query used to find matching items.

tag string

List items with the specified tag.

trashed boolean

Indicates whether trashed items should be listed (default is false). Specify null to return both trashed and non-trashed items.

order_by string

Specifies the sort order and direction for the listing, e.g. "id" or "id+desc"

skip integer

The number of items to skip. Used together with take to return a specific range of items (for pagination).

take integer

Maximum number of items to return in the listing. Should be a value between 1 and 100. Default is 25.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Example request

curl {WEAVY-URL}/api/notifications?take=25&unread=true
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "type": "string",
      "action": "string",
      "template": "string",
      "args": [
        "string"
      ],
      "text": "string",
      "html": "string",
      "plain": "string",
      "url": "string",
      "metadata": "object",
      "created_at": "string",
      "updated_at": "string",
      "is_unread": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List app notifications

List the authenticated user's notifications related to the specified app.

GET /api/apps/{app}/notifications

Path parameters

app string required

App identifier (id or uid)

Query parameters

action string

List notifications that were triggered by actions of this type, e.g. message_created or comment_updated etc.

type string

List notifications of specified type (activity, mention or reaction). When not specified notifications of all types are listed.

unread boolean

true lists unread notifications, false lists read notifications and null (default) lists all notifications whether they are read or not.

q string

A query used to find matching items.

tag string

List items with the specified tag.

trashed boolean

Indicates whether trashed items should be listed (default is false). Specify null to return both trashed and non-trashed items.

order_by string

Specifies the sort order and direction for the listing, e.g. "id" or "id+desc"

skip integer

The number of items to skip. Used together with take to return a specific range of items (for pagination).

take integer

Maximum number of items to return in the listing. Should be a value between 1 and 100. Default is 25.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Example request

curl {WEAVY-URL}/api/apps/acme-chat/notifications?take=25&unread=true
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "data": [
    {
      "id": "integer",
      "type": "string",
      "action": "string",
      "template": "string",
      "args": [
        "string"
      ],
      "text": "string",
      "html": "string",
      "plain": "string",
      "url": "string",
      "metadata": "object",
      "created_at": "string",
      "updated_at": "string",
      "is_unread": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Subscribe to app

Subscribe authenticated user to notifications for an app.

POST /api/apps/{app}/subscribe

Path parameters

app string required

App identifier (id or uid).

Example request

curl -X POST {WEAVY-URL}/api/apps/acme-chat/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Subscribe to file

Subscribe authenticated user to notifications for a file.

POST /api/files/{id}/subscribe

Path parameters

id integer required

Id of the file.

Example request

curl -X POST {WEAVY-URL}/api/files/1/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Subscribe to post

Subscribe authenticated user to notifications for a post.

POST /api/posts/{id}/subscribe

Path parameters

id integer required

Id of the post.

Example request

curl -X POST {WEAVY-URL}/api/posts/1/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Subscribe to comment

Subscribe authenticated user to notifications for a comment.

POST /api/comments/{id}/subscribe

Path parameters

id integer required

Id of the comment.

Example request

curl -X POST {WEAVY-URL}/api/comments/1/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Subscribe to message

Subscribe authenticated user to notifications for a message.

POST /api/messages/{id}/subscribe

Path parameters

id integer required

Id of the message.

Example request

curl -X POST {WEAVY-URL}/api/messages/1/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Unsubscribe from app

Unsubscribe authenticated user from notifications for an app.

POST /api/apps/{app}/unsubscribe

Path parameters

app string required

App identifier (id or uid).

Example request

curl -X POST {WEAVY-URL}/api/apps/acme-chat/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Unsubscribe from file

Unsubscribe authenticated user from notifications for a file.

POST /api/files/{id}/unsubscribe

Path parameters

id integer required

Id of the file.

Example request

curl -X POST {WEAVY-URL}/api/files/1/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Unsubscribe from post

Unsubscribe authenticated user from notifications for a post.

POST /api/posts/{id}/unsubscribe

Path parameters

id integer required

Id of the post.

Example request

curl -X POST {WEAVY-URL}/api/posts/1/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Unsubscribe from comment

Unsubscribe authenticated user from notifications for a comment.

POST /api/comments/{id}/unsubscribe

Path parameters

id integer required

Id of the comment.

Example request

curl -X POST {WEAVY-URL}/api/comments/1/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Unsubscribe from message

Unsubscribe authenticated user from notifications for a message.

POST /api/messages/{id}/unsubscribe

Path parameters

id integer required

Id of the message.

Example request

curl -X POST {WEAVY-URL}/api/messages/1/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

Mark as read

Mark a notification as read.

PUT /api/notifications/{id}/mark

Path parameters

id integer required

Notification id.

Example request

curl -X PUT {WEAVY-URL}/api/notifications/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
404 Not Found

Mark as unread

Mark a notification as unread.

DELETE /api/notifications/{id}/mark

Path parameters

id integer required

Notification id.

Example request

curl -X DELETE {WEAVY-URL}/api/notifications/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Mark app notifications as read

Mark notifications for the authenticated user and app as read.

PUT /api/apps/{app}/notifications/mark

Path parameters

app string required

App identifier (id or uid)

Query parameters

id integer

Optional id of last seen notification. When specified, this and previous notifications are marked as read, otherwise all notifications (uncluding yet unseen) are marked as read.

Example request

curl -X PUT {WEAVY-URL}/api/apps/acme-chat/notifications/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
            
curl -X PUT {WEAVY-URL}/api/apps/acme-chat/notifications/mark?id=3
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content

Mark all notifications as read

Mark all notifications for the authenticated user as read.

PUT /api/notifications/mark

Query parameters

id integer

Optional id of last seen notification. When specified, this and previous notifications are marked as read, otherwise all notifications (uncluding yet unseen) are marked as read.

Example request

curl -X PUT {WEAVY-URL}/api/notifications/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
            
curl -X PUT {WEAVY-URL}/api/notifications/mark?id=3
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content

Delete notification

Delete a notification.

DELETE /api/notifications/{id}

Path parameters

id integer required

Notification id.

Example request

curl -X DELETE {WEAVY-URL}/api/notifications/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found