openapi-administration.json

{
    "openapi": "3.0.3",
    "info": {
        "title": "notifications-administration",
        "version": "0.0.1",
        "description": "This app provides a backend and frontend for the notification API available in Nextcloud.",
        "license": {
            "name": "agpl"
        }
    },
    "components": {
        "securitySchemes": {
            "basic_auth": {
                "type": "http",
                "scheme": "basic"
            },
            "bearer_auth": {
                "type": "http",
                "scheme": "bearer"
            }
        },
        "schemas": {
            "Capabilities": {
                "type": "object",
                "required": [
                    "notifications"
                ],
                "properties": {
                    "notifications": {
                        "type": "object",
                        "required": [
                            "ocs-endpoints",
                            "push",
                            "admin-notifications"
                        ],
                        "properties": {
                            "ocs-endpoints": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "push": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "admin-notifications": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "OCSMeta": {
                "type": "object",
                "required": [
                    "status",
                    "statuscode"
                ],
                "properties": {
                    "status": {
                        "type": "string"
                    },
                    "statuscode": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    },
                    "totalitems": {
                        "type": "string"
                    },
                    "itemsperpage": {
                        "type": "string"
                    }
                }
            },
            "RichObjectParameter": {
                "type": "object",
                "required": [
                    "type",
                    "id",
                    "name"
                ],
                "properties": {
                    "type": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "server": {
                        "type": "string"
                    },
                    "link": {
                        "type": "string"
                    },
                    "call-type": {
                        "type": "string",
                        "enum": [
                            "one2one",
                            "group",
                            "public"
                        ]
                    },
                    "icon-url": {
                        "type": "string"
                    },
                    "message-id": {
                        "type": "string"
                    },
                    "boardname": {
                        "type": "string"
                    },
                    "stackname": {
                        "type": "string"
                    },
                    "size": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    },
                    "mimetype": {
                        "type": "string"
                    },
                    "preview-available": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ]
                    },
                    "mtime": {
                        "type": "string"
                    },
                    "latitude": {
                        "type": "string"
                    },
                    "longitude": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "thumb": {
                        "type": "string"
                    },
                    "website": {
                        "type": "string"
                    },
                    "visibility": {
                        "type": "string",
                        "enum": [
                            "0",
                            "1"
                        ]
                    },
                    "assignable": {
                        "type": "string",
                        "enum": [
                            "0",
                            "1"
                        ]
                    },
                    "conversation": {
                        "type": "string"
                    },
                    "etag": {
                        "type": "string"
                    },
                    "permissions": {
                        "type": "string"
                    },
                    "width": {
                        "type": "string"
                    },
                    "height": {
                        "type": "string"
                    }
                }
            },
            "RichObjectParameters": {
                "type": "object",
                "additionalProperties": {
                    "$ref": "#/components/schemas/RichObjectParameter"
                }
            }
        }
    },
    "paths": {
        "/ocs/v2.php/apps/notifications/api/{apiVersion}/admin_notifications/{userId}": {
            "post": {
                "operationId": "api-generate-notification",
                "summary": "Generate a notification for a user (deprecated, use v3 instead)",
                "description": "This endpoint requires admin access",
                "deprecated": true,
                "tags": [
                    "api"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "shortMessage"
                                ],
                                "properties": {
                                    "shortMessage": {
                                        "type": "string",
                                        "description": "Subject of the notification"
                                    },
                                    "longMessage": {
                                        "type": "string",
                                        "default": "",
                                        "description": "Message of the notification"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "apiVersion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "v1",
                                "v2"
                            ],
                            "default": "v2"
                        }
                    },
                    {
                        "name": "userId",
                        "in": "path",
                        "description": "ID of the user",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "OCS-APIRequest",
                        "in": "header",
                        "description": "Required to be true for the API request to pass",
                        "required": true,
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Notification generated successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Generating notification is not possible",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "User not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Current user is not logged in",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Logged in account must be an admin",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ocs/v2.php/apps/notifications/api/{apiVersion3}/admin_notifications/{userId}": {
            "post": {
                "operationId": "api-generate-notification-v3",
                "summary": "Generate a notification with rich object parameters for a user",
                "description": "This endpoint requires admin access",
                "tags": [
                    "api"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "subject": {
                                        "type": "string",
                                        "default": "",
                                        "description": "Subject of the notification"
                                    },
                                    "message": {
                                        "type": "string",
                                        "default": "",
                                        "description": "Message of the notification"
                                    },
                                    "subjectParameters": {
                                        "$ref": "#/components/schemas/RichObjectParameters",
                                        "default": [],
                                        "description": "Rich objects to fill the subject placeholders, {@see \\OCP\\RichObjectStrings\\Definitions}"
                                    },
                                    "messageParameters": {
                                        "$ref": "#/components/schemas/RichObjectParameters",
                                        "default": [],
                                        "description": "Rich objects to fill the message placeholders, {@see \\OCP\\RichObjectStrings\\Definitions}"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "apiVersion3",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^(v3)$"
                        }
                    },
                    {
                        "name": "userId",
                        "in": "path",
                        "description": "ID of the user",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "OCS-APIRequest",
                        "in": "header",
                        "description": "Required to be true for the API request to pass",
                        "required": true,
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Notification generated successfully, returned id is the notification ID for future delete requests",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "type": "object",
                                                    "required": [
                                                        "id"
                                                    ],
                                                    "properties": {
                                                        "id": {
                                                            "type": "integer",
                                                            "format": "int64"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Provided data was invalid, check error field of the response of log file for details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "type": "object",
                                                    "required": [
                                                        "error"
                                                    ],
                                                    "properties": {
                                                        "error": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Current user is not logged in",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Logged in account must be an admin",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ocs/v2.php/apps/notifications/api/{apiVersion}/settings/admin": {
            "post": {
                "operationId": "settings-admin",
                "summary": "Update default notification settings for new users",
                "description": "This endpoint requires admin access",
                "tags": [
                    "settings"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "batchSetting",
                                    "soundNotification",
                                    "soundTalk",
                                    "webpushEnabled",
                                    "webpushBrowsersEnabled"
                                ],
                                "properties": {
                                    "batchSetting": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "How often E-mails about missed notifications should be sent (off: 0; hourly: 1; every three hours: 2; daily: 3; weekly: 4)",
                                        "minimum": 0,
                                        "maximum": 4
                                    },
                                    "soundNotification": {
                                        "type": "string",
                                        "description": "Enable sound for notifications ('yes' or 'no')"
                                    },
                                    "soundTalk": {
                                        "type": "string",
                                        "description": "Enable sound for Talk notifications ('yes' or 'no')"
                                    },
                                    "webpushEnabled": {
                                        "type": "string",
                                        "description": "Enable web push notifications ('yes' or 'no')"
                                    },
                                    "webpushBrowsersEnabled": {
                                        "type": "string",
                                        "description": "Enable web push for browsers ('yes' or 'no')"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "apiVersion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "v2"
                            ],
                            "default": "v2"
                        }
                    },
                    {
                        "name": "OCS-APIRequest",
                        "in": "header",
                        "description": "Required to be true for the API request to pass",
                        "required": true,
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Admin settings updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Current user is not logged in",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Logged in account must be an admin",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "tags": []
}