OCS Notifications API (v1)
Check Server Capabilities
In order to find out if notifications is installed and enabled on the server, you can run a request against the capabilities endpoint.
-
Path:
ocs/v2.php/cloud/capabilities
-
Method:
GET
Request Parameters
Attribute | Type | Description |
---|---|---|
|
string |
The format to return the response in.
It can be either |
Returns
On success, the request returns either an XML (the default) or a JSON response, along with an HTTP 200 OK
status code, which shows the server’s notifications capabilities.
Example Responses
{
"ocs": {
"data": {
"capabilities": {
"notifications": {
"ocs-endpoints": [
"list",
"get",
"delete"
]
}
}
}
}
}
<?xml version="1.0"?>
<ocs>
<!-- remainder of the response -->
<data>
<!-- remainder of the data element -->
<capabilities>
<notifications>
<ocs-endpoints>
<element>list</element>
<element>get</element>
<element>delete</element>
</ocs-endpoints>
</notifications>
</capabilities>
</data>
</ocs>
Code Example
#!/usr/bin/env bash
USERNAME=admin
PASSWORD=password
API_PATH="ocs/v2.php/cloud/capabilities"
SERVER_URI="https://owncloud.install.com/owncloud"
# Get server capabilities in XML format
curl "$SERVER_URI/$API_PATH/" \
--user "$USERNAME:$PASSWORD"
# Get server capabilities in JSON format
curl "$SERVER_URI/$API_PATH?format=json" \
--user "$USERNAME:$PASSWORD" | jq
Get User Notifications
This endpoint supports retrieving a list of notifications for a user.
-
Path:
ocs/v2.php/apps/notifications/api/v1/notifications
-
Method:
GET
In order to get a single notification, you can send a
|
Request Parameters
Attribute | Type | Description |
---|---|---|
|
string |
The format to return the response in.
It can be either |
Returns
On success, the request returns either an XML (the default) or a JSON response, along with an HTTP 200 OK
status code, which shows the server’s notifications capabilities.
Example Responses
Response With Notifications
{
"ocs": {
"meta": {
"itemsperpage": "",
"message": "OK",
"status": "ok",
"statuscode": 200,
"totalitems": ""
},
"data": [{
"notification_id": 61,
"app": "files_sharing",
"user": "admin",
"datetime": "2004-02-12T15:19:21+00:00",
"object_type": "remote_share",
"object_id": "13",
"subject": "You received admin@localhost as a remote share from test",
"message": "",
"link": "http://localhost/index.php/apps/files_sharing/pending",
"actions": [{
"label": "Accept",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "POST",
"primary": true
}, {
"label": "Decline",
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
"type": "DELETE",
"primary": false
}]
}]
}
}
Specification
Optional elements are still set in the array, the value is just empty:
Type | Empty value |
---|---|
array |
|
string |
|
Notification Element
Field name | Type | Value description |
---|---|---|
|
array |
(Optional) An array of action elements. |
|
string |
The name of the app that triggered the notification. |
|
string |
The ISO 8601 date and time of when the notification was published. |
|
string |
(Optional) A link that should be followed when the subject/message is clicked. |
|
string |
(Optional) The translated, potentially longer, message that should be presented to the user. |
|
int |
The unique notification identifier. It can be used to dismiss a notification. |
|
string |
The ID of the object which the notification is about. The id can be used in PHP to mark a notification as resolved. |
|
string |
The type of the object which the notification is about. It can be used in PHP to mark a notification as resolved. |
|
string |
The translated short subject that should be presented to the user. |
|
string |
The user id of the user that receives the notification. |
Action Element
Field name | Type | Value description |
---|---|---|
|
string |
The translated short label of the action/button that should be presented to the user. |
|
string |
A link that should be followed when the action is performed/clicked. |
|
bool |
If the action is the primary action for the notification or not. |
|
string |
The HTTP method that should be used for the request against the link.
It can be one of |
Code Example
#!/usr/bin/env bash
USERNAME=admin
PASSWORD=password
API_PATH="ocs/v2.php/apps/notifications/api/v1/notifications"
SERVER_URI="https://owncloud.install.com/owncloud"
# Get response in XML format
curl "$SERVER_URI/$API_PATH/" \
--user "$USERNAME:$PASSWORD"
# Get response in JSON format
curl "$SERVER_URI/$API_PATH?format=json" \
--user "$USERNAME:$PASSWORD" | jq
If the HTTP status code is 204 (No Content), you can slow down the polling to once per hour.
This status code means that there is no app that can generate notifications.
|
Delete a User Notification
To delete a notification, send a DELETE
request against ocs/v2.php/apps/notifications/api/v1/notifications/<id>
-
Path:
ocs/v2.php/apps/notifications/api/v1/notifications/<id>
-
Method:
DELETE
Returns
On success, the request returns either an HTTP 100 Continue status code, and no response body.