API: Notifications

Notifications are created through notifiable actions in OpenProject. This endpoint only returns in-app notifications.

Actions

None yet

Linked Properties

Link Description Type Constraints Supported operations Condition
self This notification Notification not null READ  
project The project containng the resource Project not null READ  
actor The user that caused the notification User not null READ  
resource The resource the notification belongs to Polymorphic not null READ  
activity The journal the notification belongs to Polymorphic   READ optional

Local Properties

Property Description Type Constraints Supported operations Condition
id Primary key Integer   READ  
subject The subject of the notification String   READ  
details Array of formattable details []Formattable   READ  
reason The reason causing the notification String   READ  
readIAN Whether the notification is read Boolean   READ  

Methods

List notifications

Lists available in-app notifications. The notifications returned depend on the provided parameters and also on the requesting user’s permissions.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by primary key

  • reason: Sort by notification reason

  • readIAN: Sort by read status

Example:
[["reason", "asc"]]

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • readIAN: Filter by read status
  • id: Filter by primary key

Example:
[{ "readIAN": { "operator": "=", "values": ["t"] } }]

200

OK

List_notificationsModel

{
  "type": "object",
  "example": {
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "readIAN": {
              "href": "/api/v3/notifications/1/read_ian",
              "method": "post"
            },
            "actor": {
              "href": "/api/v3/users/2",
              "title": "Peggie Feeney"
            },
            "activity": {
              "href": "/api/v3/activities/1234"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "Seeded Project"
            },
            "self": {
              "href": "/api/v3/notifications/1"
            }
          },
          "_type": "Notification",
          "createdAt": "2021-07-20T08:32:18Z",
          "updatedAt": "2021-07-20T08:33:19Z",
          "details": {
            "format": "markdown",
            "raw": "<mention class=\"mention\" data-id=\"90\" data-type=\"user\" data-text=\"@Recipeint User\">@Recipient User</mention>  test",
            "html": "<p class=\"op-uc-p\"><a class=\"user-mention op-uc-link\" title=\"User Recipient User\" href=\"/users/90\">Recipient User</a>  test</p>"
          },
          "id": 1,
          "reason": "mentioned",
          "subject": "You have been mentioned in Task #1234 An important task"
        }
      ],
      "_links": {
        "changeSize": {
          "href": "/api/v3/notifications?offset=1&pageSize=%7Bsize%7D",
          "templated": true
        },
        "jumpTo": {
          "href": "/api/v3/notifications?offset=%7Boffset%7D&pageSize=2",
          "templated": true
        },
        "nextByOffset": {
          "href": "/api/v3/notifications?offset=2&pageSize=2"
        },
        "self": {
          "href": "/api/v3/notifications?offset=1&pageSize=2"
        }
      },
      "_type": "Collection",
      "count": 1,
      "offset": 1,
      "pageSize": 50,
      "total": 1
    }
  }
}

400

Returned if the client sends invalid request parameters e.g. filters

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": [
    "Filters Invalid filter does not exist."
  ]
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}

View notification

id
integer

required path

notification id

Example:
1

200

OK

NotificationModel

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Notification id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "subject": {
      "type": "string",
      "description": "The subject of the notification",
      "readOnly": true
    },
    "details": {
      "type": "Array",
      "description": "An array of formattable details",
      "readOnly": true
    },
    "reason": {
      "type": "string",
      "description": "The reason for the notification (such as mentioned, involved, watched)",
      "readOnly": true
    },
    "readIAN": {
      "type": "boolean",
      "description": "Whether the notification is marked as read",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the notification was created at",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the notification was last updated",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "actor"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This notification\n\n**Resource**: Notification",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the notification originated in\n\n**Resource**: Project",
              "readOnly": true
            }
          ]
        },
        "actor": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user that caused the notification\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "resource": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The linked resource of the notification, if any.\n\n**Resource**: Polymorphic",
              "readOnly": true
            }
          ]
        },
        "activity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The journal activity, if the notification originated from a journal entry\n\n**Resource**: Activity",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "News",
    "id": 1,
    "title": "asperiores possimus nam doloribus ab",
    "summary": "Celebrer spiculum colo viscus claustrum atque. Id nulla culpa sumptus. Comparo crapula depopulo demonstro.",
    "description": {
      "format": "markdown",
      "raw": "Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.",
      "html": "<p>Videlicet deserunt aequitas cognatus. Concedo quia est quia pariatur vorago vallum. Calco autem atavus accusamus conscendo cornu ulterius. Tam patria ago consectetur ventito sustineo nihil caecus. Supra officiis eos velociter somniculosus tonsor qui. Suffragium aduro arguo angustus cogito quia tolero vulnus. Supplanto sortitus cresco apud vestrum qui.</p>"
    },
    "createdAt": "2015-03-20T12:57:01Z",
    "_links": {
      "self": {
        "href": "/api/v3/news/1",
        "title": "asperiores possimus nam doloribus ab"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A project"
      },
      "author": {
        "href": "/api/v3/users/2",
        "title": "Peggie Feeney"
      }
    },
    "_embedded": {
      "project": {
        "_type": "Project..."
      },
      "author": {
        "_type": "User..."
      }
    }
  }
}

404

Returned if the notification does not exist or if the user does not have permission to view it.

Required permission being recipient of the notification

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}