nextcloud-server/apps/dav/openapi.json

{
    "openapi": "3.0.3",
    "info": {
        "title": "dav",
        "version": "0.0.1",
        "description": "WebDAV endpoint",
        "license": {
            "name": "agpl"
        }
    },
    "components": {
        "securitySchemes": {
            "basic_auth": {
                "type": "http",
                "scheme": "basic"
            },
            "bearer_auth": {
                "type": "http",
                "scheme": "bearer"
            }
        },
        "schemas": {
            "Capabilities": {
                "type": "object",
                "required": [
                    "dav"
                ],
                "properties": {
                    "dav": {
                        "type": "object",
                        "required": [
                            "chunking"
                        ],
                        "properties": {
                            "chunking": {
                                "type": "string"
                            },
                            "bulkupload": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "CurrentOutOfOfficeData": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/OutOfOfficeDataCommon"
                    },
                    {
                        "type": "object",
                        "required": [
                            "id",
                            "startDate",
                            "endDate",
                            "shortMessage"
                        ],
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "startDate": {
                                "type": "integer",
                                "format": "int64"
                            },
                            "endDate": {
                                "type": "integer",
                                "format": "int64"
                            },
                            "shortMessage": {
                                "type": "string"
                            }
                        }
                    }
                ]
            },
            "OCSMeta": {
                "type": "object",
                "required": [
                    "status",
                    "statuscode"
                ],
                "properties": {
                    "status": {
                        "type": "string"
                    },
                    "statuscode": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    },
                    "totalitems": {
                        "type": "string"
                    },
                    "itemsperpage": {
                        "type": "string"
                    }
                }
            },
            "OutOfOfficeData": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/OutOfOfficeDataCommon"
                    },
                    {
                        "type": "object",
                        "required": [
                            "id",
                            "firstDay",
                            "lastDay",
                            "status"
                        ],
                        "properties": {
                            "id": {
                                "type": "integer",
                                "format": "int64"
                            },
                            "firstDay": {
                                "type": "string"
                            },
                            "lastDay": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string"
                            }
                        }
                    }
                ]
            },
            "OutOfOfficeDataCommon": {
                "type": "object",
                "required": [
                    "userId",
                    "message",
                    "replacementUserId",
                    "replacementUserDisplayName"
                ],
                "properties": {
                    "userId": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    },
                    "replacementUserId": {
                        "type": "string",
                        "nullable": true
                    },
                    "replacementUserDisplayName": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "UpcomingEvent": {
                "type": "object",
                "required": [
                    "uri",
                    "calendarUri",
                    "start",
                    "summary",
                    "location"
                ],
                "properties": {
                    "uri": {
                        "type": "string"
                    },
                    "calendarUri": {
                        "type": "string"
                    },
                    "start": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "location": {
                        "type": "string",
                        "nullable": true
                    }
                }
            }
        }
    },
    "paths": {
        "/ocs/v2.php/apps/dav/api/v1/direct": {
            "post": {
                "operationId": "direct-get-url",
                "summary": "Get a direct link to a file",
                "tags": [
                    "direct"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "fileId",
                                    "expirationTime"
                                ],
                                "properties": {
                                    "fileId": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "ID of the file"
                                    },
                                    "expirationTime": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "Duration until the link expires"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "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": "Direct link returned",
                        "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": [
                                                        "url"
                                                    ],
                                                    "properties": {
                                                        "url": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "File not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Getting direct link 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": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing permissions to get direct link",
                        "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/dav/api/v1/events/upcoming": {
            "get": {
                "operationId": "upcoming_events-get-events",
                "summary": "Get information about upcoming events",
                "tags": [
                    "upcoming_events"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "location": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "location/URL to filter by"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "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": "Upcoming events",
                        "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": [
                                                        "events"
                                                    ],
                                                    "properties": {
                                                        "events": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#/components/schemas/UpcomingEvent"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "When not authenticated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ocs/v2.php/apps/dav/api/v1/outOfOffice/{userId}/now": {
            "get": {
                "operationId": "out_of_office-get-current-out-of-office-data",
                "summary": "Get the currently configured out-of-office data of a user",
                "tags": [
                    "out_of_office"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "description": "The user id to get out-of-office data for.",
                        "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": "Out-of-office data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "$ref": "#/components/schemas/CurrentOutOfOfficeData"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No out-of-office data was 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
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ocs/v2.php/apps/dav/api/v1/outOfOffice/{userId}": {
            "get": {
                "operationId": "out_of_office-get-out-of-office",
                "summary": "Get the configured out-of-office data of a user.",
                "tags": [
                    "out_of_office"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "description": "The user id to get out-of-office data for.",
                        "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": "Out-of-office data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "$ref": "#/components/schemas/OutOfOfficeData"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No out-of-office data was 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
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "out_of_office-set-out-of-office",
                "summary": "Set out-of-office absence",
                "tags": [
                    "out_of_office"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "firstDay",
                                    "lastDay",
                                    "status",
                                    "message"
                                ],
                                "properties": {
                                    "firstDay": {
                                        "type": "string",
                                        "description": "First day of the absence in format `YYYY-MM-DD`"
                                    },
                                    "lastDay": {
                                        "type": "string",
                                        "description": "Last day of the absence in format `YYYY-MM-DD`"
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "Short text that is set as user status during the absence"
                                    },
                                    "message": {
                                        "type": "string",
                                        "description": "Longer multiline message that is shown to others during the absence"
                                    },
                                    "replacementUserId": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "User id of the replacement user"
                                    },
                                    "replacementUserDisplayName": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "Display name of the replacement user"
                                    }
                                }
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "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": "Absence data",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ocs"
                                    ],
                                    "properties": {
                                        "ocs": {
                                            "type": "object",
                                            "required": [
                                                "meta",
                                                "data"
                                            ],
                                            "properties": {
                                                "meta": {
                                                    "$ref": "#/components/schemas/OCSMeta"
                                                },
                                                "data": {
                                                    "$ref": "#/components/schemas/OutOfOfficeData"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "When the first day is not before the last day",
                        "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",
                                                            "enum": [
                                                                "firstDay"
                                                            ]
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "When the 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": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "When the replacementUserId was provided but replacement user was 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
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "out_of_office-clear-out-of-office",
                "summary": "Clear the out-of-office",
                "tags": [
                    "out_of_office"
                ],
                "security": [
                    {
                        "bearer_auth": []
                    },
                    {
                        "basic_auth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "userId",
                        "in": "path",
                        "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": "When the absence was cleared successfully",
                        "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": "When the 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": {
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "tags": []
}