504 lines
11 KiB
JSON
504 lines
11 KiB
JSON
|
{
|
||
|
|
"openapi": "3.1.0",
|
||
|
|
"info": {
|
||
|
|
"title": "Nextcloud Files API (openwebui-friendly)",
|
||
|
|
"description": "simple file/directory access via nextcloud webdav, with local disk cache.",
|
||
|
|
"version": "1.0.1"
|
||
|
|
},
|
||
|
|
"servers": [
|
||
|
|
{
|
||
|
|
"url": "http://ollama-nextcloud:1111",
|
||
|
|
"description": "local server (use absolute url for tool discovery)"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"paths": {
|
||
|
|
"/ping": {
|
||
|
|
"get": {
|
||
|
|
"operationId": "nextcloudPing",
|
||
|
|
"summary": "health / verification probe",
|
||
|
|
"description": "simple json probe used by tool registrars to verify the server is reachable",
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "ok",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": true
|
||
|
|
},
|
||
|
|
"time": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "date-time",
|
||
|
|
"example": "2025-09-01T12:00:00Z"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"ok"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/file": {
|
||
|
|
"post": {
|
||
|
|
"operationId": "nextcloudGetFile",
|
||
|
|
"summary": "Fetch a file (proxied via WebDAV, cached locally)",
|
||
|
|
"description": "returns the raw file bytes. content-type mirrors the upstream mime when available; otherwise application/octet-stream. also supports an application/json metadata variant for tool registration and LLM-friendly responses.",
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"fpath": {
|
||
|
|
"type": "string",
|
||
|
|
"description": "absolute path in nextcloud webdav (e.g., /Documents/report.pdf)"
|
||
|
|
},
|
||
|
|
"bypasscache": {
|
||
|
|
"type": "boolean",
|
||
|
|
"default": false,
|
||
|
|
"description": "if true, skip the local cache and fetch from upstream"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"fpath"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"examples": {
|
||
|
|
"default": {
|
||
|
|
"value": {
|
||
|
|
"fpath": "/Documents/report.pdf",
|
||
|
|
"bypasscache": false
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "file bytes or metadata",
|
||
|
|
"headers": {
|
||
|
|
"content-type": {
|
||
|
|
"description": "mime type from upstream or application/octet-stream",
|
||
|
|
"schema": {
|
||
|
|
"type": "string"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"$ref": "#/components/schemas/FileMeta"
|
||
|
|
},
|
||
|
|
"examples": {
|
||
|
|
"example": {
|
||
|
|
"value": {
|
||
|
|
"filename": "/Documents/report.pdf",
|
||
|
|
"basename": "report.pdf",
|
||
|
|
"lastmod": "Mon, 01 Sep 2025 12:34:56 GMT",
|
||
|
|
"size": 2048,
|
||
|
|
"type": "file",
|
||
|
|
"etag": "\"a1b2c3d4e5\"",
|
||
|
|
"mime": "application/pdf",
|
||
|
|
"cached": true,
|
||
|
|
"download_url": "http://ollama-nextcloud:1111/file?fpath=/Documents/report.pdf"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"application/octet-stream": {
|
||
|
|
"schema": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "binary"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"*/*": {
|
||
|
|
"schema": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "binary"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"401": {
|
||
|
|
"$ref": "#/components/responses/Unauthorized"
|
||
|
|
},
|
||
|
|
"404": {
|
||
|
|
"$ref": "#/components/responses/NotFound"
|
||
|
|
},
|
||
|
|
"500": {
|
||
|
|
"$ref": "#/components/responses/ServerError"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"put": {
|
||
|
|
"operationId": "nextcloudUploadFile",
|
||
|
|
"summary": "Upload a file",
|
||
|
|
"description": "uploads a file into a target directory in nextcloud via webdav. requires a multipart/form-data body with the file part and the destination directory. the server will not overwrite existing files.",
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"multipart/form-data": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"fdir": {
|
||
|
|
"type": "string",
|
||
|
|
"description": "destination directory path (e.g., /Documents)"
|
||
|
|
},
|
||
|
|
"createnewdirs": {
|
||
|
|
"type": "boolean",
|
||
|
|
"default": false,
|
||
|
|
"description": "if true and the directory does not exist, create it recursively before uploading"
|
||
|
|
},
|
||
|
|
"file": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "binary",
|
||
|
|
"description": "the file contents"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"fdir",
|
||
|
|
"file"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "upload succeeded",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": true
|
||
|
|
},
|
||
|
|
"uploaded": {
|
||
|
|
"$ref": "#/components/schemas/DirEntry"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"ok",
|
||
|
|
"uploaded"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"text/plain": {
|
||
|
|
"schema": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"example": "file uploaded successfully to https://nextcloud.example.com/remote.php/dav/files/user/Documents/example.txt"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"400": {
|
||
|
|
"description": "missing file upload field",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": false
|
||
|
|
},
|
||
|
|
"error": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "missing file"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"text/plain": {
|
||
|
|
"schema": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"example": "missing file"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"401": {
|
||
|
|
"$ref": "#/components/responses/Unauthorized"
|
||
|
|
},
|
||
|
|
"503": {
|
||
|
|
"description": "file exists and overwrite is not permitted",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": false
|
||
|
|
},
|
||
|
|
"error": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "file already exists, you do not have permissions to overwrite files"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"text/plain": {
|
||
|
|
"schema": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"example": "file already exists, you do not have permissions to overwrite files"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"500": {
|
||
|
|
"$ref": "#/components/responses/ServerError"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/dir": {
|
||
|
|
"post": {
|
||
|
|
"operationId": "nextcloudListDirectory",
|
||
|
|
"summary": "List a directory",
|
||
|
|
"description": "lists directory entries from nextcloud webdav. supports shallow or deep listing.",
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"fpath": {
|
||
|
|
"type": "string",
|
||
|
|
"description": "directory path in nextcloud webdav (e.g., /Documents)"
|
||
|
|
},
|
||
|
|
"deep": {
|
||
|
|
"type": "boolean",
|
||
|
|
"default": false,
|
||
|
|
"description": "whether to recurse into subdirectories"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"fpath"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"examples": {
|
||
|
|
"default": {
|
||
|
|
"value": {
|
||
|
|
"fpath": "/Documents",
|
||
|
|
"deep": false
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "directory listing",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "array",
|
||
|
|
"items": {
|
||
|
|
"$ref": "#/components/schemas/DirEntry"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"401": {
|
||
|
|
"$ref": "#/components/responses/Unauthorized"
|
||
|
|
},
|
||
|
|
"404": {
|
||
|
|
"$ref": "#/components/responses/NotFound"
|
||
|
|
},
|
||
|
|
"500": {
|
||
|
|
"$ref": "#/components/responses/ServerError"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/openapi.json": {
|
||
|
|
"get": {
|
||
|
|
"operationId": "nextcloudGetOpenapi",
|
||
|
|
"summary": "Serve OpenAPI schema",
|
||
|
|
"description": "serves this specification (used by open webui when registering a tool server).",
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "openapi document",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"components": {
|
||
|
|
"schemas": {
|
||
|
|
"DirEntry": {
|
||
|
|
"type": "object",
|
||
|
|
"description": "entry returned by webdav client",
|
||
|
|
"properties": {
|
||
|
|
"filename": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "/Documents/report.pdf"
|
||
|
|
},
|
||
|
|
"basename": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "report.pdf"
|
||
|
|
},
|
||
|
|
"lastmod": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "Mon, 01 Sep 2025 12:34:56 GMT"
|
||
|
|
},
|
||
|
|
"size": {
|
||
|
|
"type": "integer",
|
||
|
|
"format": "int64",
|
||
|
|
"example": 2048
|
||
|
|
},
|
||
|
|
"type": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": [
|
||
|
|
"file",
|
||
|
|
"directory"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"etag": {
|
||
|
|
"type": "string",
|
||
|
|
"example": "\"a1b2c3d4e5\""
|
||
|
|
},
|
||
|
|
"mime": {
|
||
|
|
"type": "string",
|
||
|
|
"nullable": true,
|
||
|
|
"example": "application/pdf"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"basename",
|
||
|
|
"type"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"FileMeta": {
|
||
|
|
"type": "object",
|
||
|
|
"description": "metadata about a file (json-friendly alternative to raw bytes)",
|
||
|
|
"properties": {
|
||
|
|
"filename": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"basename": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"lastmod": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"size": {
|
||
|
|
"type": "integer",
|
||
|
|
"format": "int64"
|
||
|
|
},
|
||
|
|
"type": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": [
|
||
|
|
"file",
|
||
|
|
"directory"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"etag": {
|
||
|
|
"type": "string"
|
||
|
|
},
|
||
|
|
"mime": {
|
||
|
|
"type": "string",
|
||
|
|
"nullable": true
|
||
|
|
},
|
||
|
|
"cached": {
|
||
|
|
"type": "boolean",
|
||
|
|
"description": "whether the file was served from local cache"
|
||
|
|
},
|
||
|
|
"download_url": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "uri",
|
||
|
|
"description": "url to download raw bytes (may be the same endpoint with different accept header)"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"required": [
|
||
|
|
"basename",
|
||
|
|
"type"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"Unauthorized": {
|
||
|
|
"description": "not authorized to access the requested path (middleware denied or missing parameters)",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": false
|
||
|
|
},
|
||
|
|
"error": {
|
||
|
|
"type": "string"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"NotFound": {
|
||
|
|
"description": "path not found upstream",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": false
|
||
|
|
},
|
||
|
|
"error": {
|
||
|
|
"type": "string"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"ServerError": {
|
||
|
|
"description": "unexpected server error",
|
||
|
|
"content": {
|
||
|
|
"application/json": {
|
||
|
|
"schema": {
|
||
|
|
"type": "object",
|
||
|
|
"properties": {
|
||
|
|
"ok": {
|
||
|
|
"type": "boolean",
|
||
|
|
"example": false
|
||
|
|
},
|
||
|
|
"error": {
|
||
|
|
"type": "string"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|