API: Notifications

Notifications are created through notifiable actions in OpenProject. 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 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  
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.

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

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"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NotificationModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_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": "mentioned"
        }
      ],
      "_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
        }
      }
    }
  }
}

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

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."
    }
  }
}

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."
    }
  }
}

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."
    }
  }
}

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

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."
    }
  }
}

Get the notification

Returns the notification identified by the notification id.

id
integer

required path

notification id

Example:
1

200

OK

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 (such as mentioned, involved, watched)"
    },
    "readIAN": {
      "type": "boolean",
      "description": "Whether the notification is marked as read"
    },
    "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": [
        "actor",
        "project",
        "activity",
        "resource"
      ],
      "properties": {
        "actor": {
          "$ref": "#/components/schemas/UserModel"
        },
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "activity": {
          "$ref": "#/components/schemas/ActivityModel"
        },
        "resource": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Work_PackageModel"
            }
          ]
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project",
        "actor",
        "activity",
        "resource"
      ],
      "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\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\n\n**Resource**: Activity"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Notification",
    "id": 1,
    "readIAN": false,
    "reason": "mentioned",
    "createdAt": "2022-04-05T14:38:28Z",
    "updatedAt": "2022-04-06T09:03:24Z",
    "_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"
      }
    },
    "_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"
      }
    }
  }
}

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."
    }
  }
}