{
	"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 (application/json, base64-encoded)",
				"description": "Uploads a file into a target directory in nextcloud via webdav. the server will not overwrite existing files. the body must be application/json and include `fdir` and `file.buffer` (base64).",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/NewFileMeta"
							},
							"examples": {
								"json-base64": {
									"value": {
										"fdir": "/Documents",
										"createnewdirs": false,
										"file": {
											"filename": "file",
											"originalname": "photo.jpg",
											"mimetype": "image/jpeg",
											"size": 52345,
											"buffer": "/9j/4AAQSkZJRgABAQAAAQABAAD... (truncated base64)"
										}
									}
								}
							}
						}
					}
				},
				"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 or invalid base64",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"ok": {
											"type": "boolean",
											"example": false
										},
										"error": {
											"type": "string",
											"example": "missing file or invalid buffer"
										}
									}
								}
							},
							"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"
									},
									"startInd": {
										"type": "number",
										"default": 0,
										"description": "start listing from this index (for pagination)"
									},
									"limit": {
										"type": "number",
										"default": 250,
										"description": "maximum number of entries to return"
									}
								},
								"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"
				]
			},
			"NewFileMeta": {
				"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": "object",
						"description": "uploaded file metadata + contents (base64 if image or misc formats otherwise)",
						"properties": {
							"filename": {
								"type": "string",
								"description": "name of the form field associated with this file or client-side identifier"
							},
							"originalname": {
								"type": "string",
								"default": "",
								"description": "name of the file on the uploader's computer"
							},
							"mimetype": {
								"type": "string",
								"default": "text/plain",
								"description": "value of the Content-Type for this file, e.g. image/jpeg"
							},
							"size": {
								"type": "integer",
								"format": "int64",
								"default": 0,
								"description": "size of the file in bytes"
							},
							"buffer": {
								"type": "string",
								"format": "byte",
								"contentEncoding": "any",
								"contentMediaType": "application/octet-stream",
								"description": "the contents of the file"
							}
						},
						"required": [
							"filename",
							"mimetype",
							"buffer"
						]
					}
				},
				"required": [
					"fdir",
					"file"
				]
			}
		},
		"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"
								}
							}
						}
					}
				}
			}
		}
	}
}