API: Notifications

Notifications are created through notifiable actions in OpenProject. Notifications are triggered by actions carried out in the system by users, e.g. editing a work package, but can also be send out because of time passing e.g. when a user is notified of a work package that is overdue.

This endpoint only returns in-app notifications.

Actions

Link Description Condition
read_ian Marks the notification as read notification is unread
unread_ian Marks the notification as unread notification is read

Linked Properties

Link Description Type Constraints Supported operations Condition
self This notification Notification not null READ
project The project containing the resource Project not null READ
actor The user that caused the notification User READ optional
resource The resource the notification belongs to Polymorphic not null READ
activity The journal the notification belongs to Polymorphic READ optional
details A list of objects including detailed information 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
reason The reason causing the notification String READ
readIAN Whether the notification is read Boolean READ

Methods

Get notification collection

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

Contrary to most collections, this one also links to and embeds schemas for the details properties of the notifications returned. This is an optimization. Clients will receive the information necessary to display the various types of details that a notification can carry.

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.

Default:
20

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"]]

groupBy
string

optional query

string specifying group_by criteria.

  • reason: Group by notification reason

  • project: Sort by associated project

Example:
reason

filters
string

optional query

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

  • id: Filter by primary key

  • project: Filter by the project the notification was created in

  • readIAN: Filter by read status

  • reason: Filter by the reason, e.g. ‘mentioned’ or ‘assigned’ the notification was created because of

  • resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the resourceType filter.

  • resourceType: Filter by the type of the resource the notification was created for. Ideally used together with the resourceId filter.

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

200

OK

{
  "_type": "Collection",
  "count": 2,
  "total": 2,
  "offset": 1,
  "pageSize": 20,
  "_embedded": {
    "elements": [
      {
        "_hint": "Notification resource shortened for brevity",
        "id": 1,
        "readIAN": false,
        "reason": "mentioned"
      },
      {
        "_hint": "Notification resource shortened for brevity",
        "id": 2,
        "readIAN": false,
        "reason": "dateAlert",
        "_embedded": {
          "details": [
            {
              "_type": "Values::Property",
              "property": "startDate",
              "value": "2021-01-01",
              "_links": {
                "self": {
                  "href": "api/v3/notifications/123/details/0"
                },
                "schema": {
                  "href": "api/v3/values/schemas/startDate"
                }
              }
            }
          ]
        }
      }
    ],
    "detailsSchemas": [
      {
        "_type": "Schema",
        "property": {
          "name": "Property",
          "type": "String"
        },
        "value": {
          "name": "Start date",
          "type": "Date"
        },
        "_links": {
          "self": {
            "href": "/api/v3/values/schemas/startDate"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/notifications?offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/notifications?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/notifications?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    }
  }
}
NotificationCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This notification collection\n\n**Resource**: NotificationCollectionModel"
                }
              ]
            },
            "jumpTo": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The notification collection at another offset\n\n**Resource**: NotificationCollectionModel"
                }
              ]
            },
            "changeSize": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The notification collection with another size\n\n**Resource**: NotificationCollectionModel"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements",
            "detailsSchemas"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NotificationModel"
              }
            },
            "detailsSchemas": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/SchemaModel"
              }
            }
          }
        }
      }
    }
  ]
}

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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Read all notifications

Marks the whole notification collection as read. The collection contains only elements the authenticated user can see, and can be further reduced with filters.

filters
string

optional query

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

  • id: Filter by primary key

  • project: Filter by the project the notification was created in

  • reason: Filter by the reason, e.g. ‘mentioned’ or ‘assigned’ the notification was created because of

  • resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the resourceType filter.

  • resourceType: Filter by the type of the resource the notification was created for. Ideally used together with the resourceId filter.

Example:
[{ "reason": { "operator": "=", "values": ["mentioned"] } }]

204

OK

400

Returned if the request is not properly formatted.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": [
    "Filters Invalid filter does not exist."
  ]
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Unread all notifications

Marks the whole notification collection as unread. The collection contains only elements the authenticated user can see, and can be further reduced with filters.

filters
string

optional query

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

  • id: Filter by primary key

  • project: Filter by the project the notification was created in

  • reason: Filter by the reason, e.g. ‘mentioned’ or ‘assigned’ the notification was created because of

  • resourceId: Filter by the id of the resource the notification was created for. Ideally used together with the resourceType filter.

  • resourceType: Filter by the type of the resource the notification was created for. Ideally used together with the resourceId filter.

Example:
[{ "reason": { "operator": "=", "values": ["mentioned"] } }]

204

OK

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Get the notification

Returns the notification identified by the notification id.

id
integer

required path

notification id

Example:
1

200

OK

{
  "_type": "Notification",
  "id": 1,
  "readIAN": false,
  "reason": "dateAlert",
  "createdAt": "2022-04-05T14:38:28.361Z",
  "updatedAt": "2022-04-06T09:03:24.347Z",
  "_embedded": {
    "project": {
      "_hint": "Project resource shortened for brevity",
      "_type": "Project",
      "id": 11,
      "name": "Jedi Remnant Locator"
    },
    "resource": {
      "_hint": "WorkPackage resource shortened for brevity",
      "_type": "WorkPackage",
      "id": 77,
      "subject": "Educate Visas Marr"
    },
    "details": [
      {
        "_type": "Values::Property",
        "property": "startDate",
        "value": "2021-01-01",
        "_links": {
          "self": {
            "href": "api/v3/notifications/123/details/0"
          },
          "schema": {
            "href": "api/v3/values/schemas/startDate"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/notifications/1"
    },
    "readIAN": {
      "href": "/api/v3/notifications/1/read_ian",
      "method": "post"
    },
    "actor": {
      "href": null
    },
    "project": {
      "href": "/api/v3/projects/11",
      "title": "Jedi Remnant Locator"
    },
    "activity": {
      "href": null
    },
    "resource": {
      "href": "/api/v3/work_packages/77",
      "title": "Educate Visas Marr"
    }
  }
}

{
  "_type": "Notification",
  "id": 1,
  "readIAN": false,
  "reason": "mentioned",
  "createdAt": "2022-04-05T14:38:28.881Z",
  "updatedAt": "2022-04-06T09:03:24.591Z",
  "_embedded": {
    "author": {
      "_hint": "User resource shortened for brevity",
      "_type": "User",
      "id": 13,
      "name": "Darth Nihilus"
    },
    "project": {
      "_hint": "Project resource shortened for brevity",
      "_type": "Project",
      "id": 11,
      "name": "Jedi Remnant Locator"
    },
    "activity": {
      "_hint": "Activity resource shortened for brevity",
      "_type": "Activity::Comment",
      "id": 180,
      "version": 3
    },
    "resource": {
      "_hint": "WorkPackage resource shortened for brevity",
      "_type": "WorkPackage",
      "id": 77,
      "subject": "Educate Visas Marr"
    },
    "details": [

    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/notifications/1"
    },
    "readIAN": {
      "href": "/api/v3/notifications/1/read_ian",
      "method": "post"
    },
    "actor": {
      "href": "/api/v3/users/13",
      "title": "Darth Nihilus"
    },
    "project": {
      "href": "/api/v3/projects/11",
      "title": "Jedi Remnant Locator"
    },
    "activity": {
      "href": "/api/v3/activities/180"
    },
    "resource": {
      "href": "/api/v3/work_packages/77",
      "title": "Educate Visas Marr"
    }
  }
}
NotificationModel
{
  "type": "object",
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Notification"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Notification id",
      "minimum": 1
    },
    "reason": {
      "type": "string",
      "description": "The reason for the notification",
      "enum": [
        "assigned",
        "commented",
        "created",
        "dateAlert",
        "mentioned",
        "prioritized",
        "processed",
        "responsible",
        "subscribed",
        "scheduled",
        "watched"
      ]
    },
    "readIAN": {
      "type": "boolean",
      "description": "Whether the notification is marked as read"
    },
    "details": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ValuesPropertyModel"
          }
        ]
      },
      "description": "A list of objects including detailed information about the notification."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the notification was created at"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the notification was last updated"
    },
    "_embedded": {
      "type": "object",
      "required": [
        "project",
        "resource"
      ],
      "properties": {
        "actor": {
          "$ref": "#/components/schemas/UserModel"
        },
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "activity": {
          "$ref": "#/components/schemas/ActivityModel"
        },
        "resource": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/WorkPackageModel"
            }
          ]
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "actor",
        "activity",
        "resource",
        "details"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This notification\n\n**Resource**: Notification"
            }
          ]
        },
        "readIAN": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Request to mark the notification as read. Only available if the notification is currently unread."
            }
          ]
        },
        "unreadIAN": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Request to mark the notification as unread. Only available if the notification is currently read."
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the notification originated in\n\n**Resource**: Project"
            }
          ]
        },
        "actor": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user that caused the notification. This might be null in\ncase no user triggered the notification.\n\n**Resource**: User"
            }
          ]
        },
        "resource": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The linked resource of the notification, if any.\n\n**Resource**: Polymorphic"
            }
          ]
        },
        "activity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The journal activity, if the notification originated from a journal entry. This might be null in\ncase no activity triggered the notification.\n\n**Resource**: Activity"
            }
          ]
        },
        "details": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A list of objects including detailed information about the notification. The contents of\nand type of this can vary widely between different notification reasons.\n\n**Resource**: Polymorphic (e.g. Values::Property)"
              }
            ]
          }
        }
      }
    }
  }
}

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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Read notification

Marks the given notification as read.

id
integer

required path

notification id

Example:
1

204

OK

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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Unread notification

Marks the given notification as unread.

id
integer

required path

notification id

Example:
1

204

OK

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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Get a notification detail

Returns an individual detail of a notification identified by the notification id and the id of the detail.

notification_id
integer

required path

notification id

Example:
1

id
integer

required path

detail id

Example:
0

200

OK

{
  "_type": "Values::Property",
  "property": "startDate",
  "value": "2021-01-01",
  "_links": {
    "self": {
      "href": "api/v3/notifications/123/details/0"
    },
    "schema": {
      "href": "api/v3/values/schemas/startDate"
    }
  }
}

{
  "_type": "Values::Property",
  "property": "dueDate",
  "value": "2021-01-01",
  "_links": {
    "self": {
      "href": "api/v3/notifications/123/details/0"
    },
    "schema": {
      "href": "api/v3/values/schemas/dueDate"
    }
  }
}

{
  "_type": "Values::Property",
  "property": "date",
  "value": "2021-01-01",
  "_links": {
    "self": {
      "href": "api/v3/notifications/123/details/0"
    },
    "schema": {
      "href": "api/v3/values/schemas/date"
    }
  }
}
ValuesPropertyModel
{
  "type": "object",
  "required": [
    "_type",
    "property",
    "value",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Values::Property"
      ]
    },
    "property": {
      "type": "string",
      "description": "The key of the key - value pair represented by the Values::Property"
    },
    "value": {
      "type": "string",
      "description": "The value of the key - value pair represented by the Values::Property"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This key - value pair.\n\n**Resource**: Storage"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema describing the key - value pair.\n\n**Resource**: Schema"
            }
          ]
        }
      }
    }
  }
}

404

Returned if the notification or the detail of it 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."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}