{"openapi":"3.1.0","info":{"title":"FileBrowser API","description":"FileBrowser is a web-based file manager that provides a REST API for file operations.\n\nThis API allows programmatic access to:\n- File and directory operations (list, upload, download, delete)\n- User authentication via JWT tokens\n- User management (admin only)\n- Share link management\n\n**Authentication Flow:**\n1. POST to `/api/login` with username/password to get JWT token\n2. Include token in `X-Auth` header for subsequent requests\n\n**Note:** This specification documents the community-discovered API endpoints.\nFileBrowser's official API documentation is limited.\n","version":"2.32.0","contact":{"name":"FileBrowser Project","url":"https://github.com/filebrowser/filebrowser"},"license":{"name":"Apache-2.0"}},"servers":[{"url":"https://upload.haiven.site","description":"Production (via Traefik)"},{"url":"http://upload:80","description":"Internal Docker network"}],"tags":[{"name":"Authentication","description":"Login and token management"},{"name":"Resources","description":"File and directory operations"},{"name":"Users","description":"User management (admin only)"},{"name":"Shares","description":"Share link management"},{"name":"Settings","description":"Server settings"}],"paths":{"/api/login":{"post":{"tags":["Authentication"],"summary":"Authenticate user","description":"Authenticate with username and password to receive a JWT token.\nInclude this token in the `X-Auth` header for subsequent API requests.\n","operationId":"login","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string","example":"admin"},"password":{"type":"string","format":"password","example":"your-password"},"recaptcha":{"type":"string","description":"reCAPTCHA token (if enabled)"}}}}}},"responses":{"200":{"description":"Authentication successful","content":{"text/plain":{"schema":{"type":"string","description":"JWT token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}}},"403":{"description":"Invalid credentials"}}}},"/api/renew":{"post":{"tags":["Authentication"],"summary":"Renew JWT token","description":"Get a new JWT token using an existing valid token","operationId":"renewToken","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"New token issued","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/resources/{path}":{"get":{"tags":["Resources"],"summary":"Get resource information or download file","description":"Retrieve information about a file or directory.\n- For directories: returns listing with metadata\n- For files: returns file metadata (use with checksum/download params)\n","operationId":"getResource","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"description":"Path to resource (URL encoded)","schema":{"type":"string"},"example":"uploads/models/gguf"},{"name":"checksum","in":"query","description":"Include checksum algorithms (e.g., md5, sha256)","schema":{"type":"string"}},{"name":"raw","in":"query","description":"If true, download the raw file content","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Resource information or file content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resource"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Resource not found"}}},"post":{"tags":["Resources"],"summary":"Upload file","description":"Upload a file to the specified path.\n- For single files: POST with file content\n- For chunked uploads: use resumable upload flow\n","operationId":"uploadFile","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"description":"Destination path (URL encoded)","schema":{"type":"string"},"example":"uploads/models/gguf/model.gguf"},{"name":"override","in":"query","description":"Overwrite if file exists","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Upload successful"},"409":{"description":"File already exists (use override=true)"},"507":{"description":"Insufficient storage"}}},"delete":{"tags":["Resources"],"summary":"Delete resource","description":"Delete a file or directory","operationId":"deleteResource","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resource deleted"},"403":{"description":"Permission denied"},"404":{"description":"Resource not found"}}},"patch":{"tags":["Resources"],"summary":"Update resource","description":"Rename, move, or copy a resource","operationId":"updateResource","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"query","required":true,"description":"Action to perform","schema":{"type":"string","enum":["rename","copy","move"]}},{"name":"destination","in":"query","required":true,"description":"Destination path for the action","schema":{"type":"string"}}],"responses":{"200":{"description":"Action completed"},"409":{"description":"Destination already exists"}}}},"/api/resources/{path}/mkdir":{"post":{"tags":["Resources"],"summary":"Create directory","description":"Create a new directory at the specified path","operationId":"createDirectory","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"},"example":"uploads/new-folder"}],"responses":{"200":{"description":"Directory created"},"409":{"description":"Directory already exists"}}}},"/api/search/{path}":{"get":{"tags":["Resources"],"summary":"Search files","description":"Search for files matching a query within a directory","operationId":"searchFiles","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}},{"name":"query","in":"query","required":true,"description":"Search query","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}}}}}}}},"/api/users":{"get":{"tags":["Users"],"summary":"List all users","description":"Get list of all users (admin only)","operationId":"listUsers","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}},"403":{"description":"Admin access required"}}},"post":{"tags":["Users"],"summary":"Create user","description":"Create a new user (admin only)","operationId":"createUser","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}}},"responses":{"201":{"description":"User created"},"409":{"description":"Username already exists"}}}},"/api/users/{id}":{"get":{"tags":["Users"],"summary":"Get user","description":"Get user details by ID","operationId":"getUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"User details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}},"put":{"tags":["Users"],"summary":"Update user","description":"Update user details","operationId":"updateUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}}},"responses":{"200":{"description":"User updated"}}},"delete":{"tags":["Users"],"summary":"Delete user","description":"Delete a user (admin only)","operationId":"deleteUser","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"User deleted"}}}},"/api/shares":{"get":{"tags":["Shares"],"summary":"List shares","description":"Get all share links created by the current user","operationId":"listShares","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of share links","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Share"}}}}}}}},"/api/share/{path}":{"post":{"tags":["Shares"],"summary":"Create share link","description":"Create a share link for a file or directory","operationId":"createShare","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expires":{"type":"string","format":"date-time","description":"Expiration time (ISO 8601)"},"password":{"type":"string","description":"Optional password protection"},"unit":{"type":"string","enum":["hours","days","weeks"],"description":"Time unit for expiration"}}}}}},"responses":{"201":{"description":"Share link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Share"}}}}}},"delete":{"tags":["Shares"],"summary":"Delete share link","description":"Delete a share link","operationId":"deleteShare","security":[{"BearerAuth":[]}],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Share deleted"}}}},"/api/settings":{"get":{"tags":["Settings"],"summary":"Get settings","description":"Get server settings (admin only)","operationId":"getSettings","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Server settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}}}}},"/health":{"get":{"summary":"Health check","description":"Basic health check endpoint","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"X-Auth","description":"JWT token from /api/login"}},"schemas":{"Resource":{"type":"object","properties":{"path":{"type":"string","description":"Full path to resource"},"name":{"type":"string","description":"Resource name"},"size":{"type":"integer","format":"int64","description":"Size in bytes"},"extension":{"type":"string","description":"File extension"},"modified":{"type":"string","format":"date-time","description":"Last modified timestamp"},"mode":{"type":"integer","description":"Unix file mode"},"isDir":{"type":"boolean","description":"True if directory"},"isSymlink":{"type":"boolean","description":"True if symbolic link"},"type":{"type":"string","description":"MIME type (for files)"},"items":{"type":"array","description":"Directory contents (if isDir)","items":{"$ref":"#/components/schemas/Resource"}},"numDirs":{"type":"integer","description":"Number of subdirectories"},"numFiles":{"type":"integer","description":"Number of files"}}},"User":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"password":{"type":"string","description":"Hashed password (not returned in responses)"},"scope":{"type":"string","description":"Base directory scope"},"locale":{"type":"string"},"lockPassword":{"type":"boolean"},"viewMode":{"type":"string","enum":["list","mosaic"]},"singleClick":{"type":"boolean"},"perm":{"$ref":"#/components/schemas/Permissions"},"commands":{"type":"array","items":{"type":"string"}},"sorting":{"type":"object","properties":{"by":{"type":"string"},"asc":{"type":"boolean"}}},"rules":{"type":"array","items":{"type":"object"}}}},"UserCreate":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string"},"password":{"type":"string"},"scope":{"type":"string","default":"/"},"locale":{"type":"string","default":"en"},"perm":{"$ref":"#/components/schemas/Permissions"}}},"Permissions":{"type":"object","properties":{"admin":{"type":"boolean","default":false},"execute":{"type":"boolean","default":false},"create":{"type":"boolean","default":true},"rename":{"type":"boolean","default":true},"modify":{"type":"boolean","default":true},"delete":{"type":"boolean","default":true},"share":{"type":"boolean","default":true},"download":{"type":"boolean","default":true}}},"Share":{"type":"object","properties":{"hash":{"type":"string","description":"Unique share hash"},"path":{"type":"string","description":"Path to shared resource"},"userID":{"type":"integer"},"expires":{"type":"string","format":"date-time"},"password":{"type":"boolean","description":"True if password protected"},"url":{"type":"string","description":"Full share URL"}}},"Settings":{"type":"object","properties":{"signup":{"type":"boolean"},"createUserDir":{"type":"boolean"},"userHomeBasePath":{"type":"string"},"defaults":{"$ref":"#/components/schemas/User"},"authMethod":{"type":"string"},"branding":{"type":"object","properties":{"name":{"type":"string"},"disableExternal":{"type":"boolean"},"color":{"type":"string"}}},"commands":{"type":"object"},"shell":{"type":"array","items":{"type":"string"}},"rules":{"type":"array","items":{"type":"object"}}}}}}}