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

format

string

The format to return the response in. It can be either XML or JSON.

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

  • JSON

  • XML

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

  • Curl

#!/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 GET request against the endpoint below. Note the <id> property at the end of the endpoint.

{request-base-path}/apps/notifications/api/v1/notifications/<id>

Request Parameters

Attribute Type Description

format

string

The format to return the response in. It can be either XML or JSON.

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

  • JSON

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

Response Without Notifications

  • JSON

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": null,
      "totalitems": "",
      "itemsperpage": ""
    },
    "data": []
  }
}

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

actions

array

(Optional) An array of action elements.

app

string

The name of the app that triggered the notification.

datetime

string

The ISO 8601 date and time of when the notification was published.

link

string

(Optional) A link that should be followed when the subject/message is clicked.

message

string

(Optional) The translated, potentially longer, message that should be presented to the user.

notification_id

int

The unique notification identifier. It can be used to dismiss a notification.

object_id

string

The ID of the object which the notification is about. The id can be used in PHP to mark a notification as resolved.

object_type

string

The type of the object which the notification is about. It can be used in PHP to mark a notification as resolved.

subject

string

The translated short subject that should be presented to the user.

user

string

The user id of the user that receives the notification.

Action Element

Field name Type Value description

label

string

The translated short label of the action/button that should be presented to the user.

link

string

A link that should be followed when the action is performed/clicked.

primary

bool

If the action is the primary action for the notification or not.

type

string

The HTTP method that should be used for the request against the link. It can be one of GET, POST, or DELETE.

Code Example

  • Curl

#!/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

Request Parameters

Attribute Type Description

id

integer

The id of the notification to delete.

Returns

On success, the request returns either an HTTP 100 Continue status code, and no response body.