{ "openapi": "3.0.3", "info": { "title": "Filemanager sync API", "version": "1.0.0", "description": "Versioned API for sync clients (phone, desktop, services). See docs/api.md for the OAuth flow and a sync walkthrough. A token can never see or change more than its user can in the web UI." }, "servers": [ { "url": "/api/v1" } ], "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Authorization code with PKCE (S256), public clients without secret.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": { "files:read": "Read and download files", "files:write": "Upload, create, move and delete (implies files:read)" } } } }, "personalToken": { "type": "http", "scheme": "bearer", "description": "Personal access token (fmp_...) created on /apps.html" } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "example": "conflict" }, "message": { "type": "string" }, "current": { "allOf": [ { "$ref": "#/components/schemas/Entry" } ], "nullable": true, "description": "Current state of the target on 409/412" }, "offset": { "type": "integer", "description": "Server offset on upload offset errors" } } }, "Entry": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id (device+inode); survives renames and moves" }, "path": { "type": "string", "example": "/~/Photos/a.jpg" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "size": { "type": "integer" }, "mtime": { "type": "string", "format": "date-time" }, "mtime_ms": { "type": "integer" }, "version": { "type": "string", "description": "Opaque version; also the ETag. Changes on every content change." }, "sha256": { "type": "string", "nullable": true, "description": "Hex SHA-256 when known (uploaded via API or requested with hash=1)" } } }, "DeltaEntry": { "type": "object", "properties": { "change": { "type": "string", "enum": [ "exists", "created", "modified", "moved", "deleted" ] }, "id": { "type": "string" }, "path": { "type": "string" }, "old_path": { "type": "string", "description": "Only for moved" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "size": { "type": "integer", "nullable": true }, "mtime_ms": { "type": "integer", "nullable": true }, "version": { "type": "string", "nullable": true } } }, "Upload": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "size": { "type": "integer" }, "offset": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "max_chunk_bytes": { "type": "integer" } } }, "Root": { "type": "object", "properties": { "id": { "type": "string", "description": "'~' is the user's own folder" }, "name": { "type": "string" }, "path": { "type": "string" }, "writable": { "type": "boolean" } } } }, "responses": { "Error": { "description": "JSON error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/me": { "get": { "summary": "Current user, scopes, roots and limits", "security": [ { "oauth2": [] }, { "personalToken": [] } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/roots": { "get": { "summary": "Roots the user can read", "security": [ { "oauth2": [ "files:read" ] }, { "personalToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "roots": { "type": "array", "items": { "$ref": "#/components/schemas/Root" } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/files/metadata": { "get": { "summary": "Metadata of one file or folder", "security": [ { "oauth2": [ "files:read" ] }, { "personalToken": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Virtual path: //, e.g. /~/Photos/a.jpg", "schema": { "type": "string" } }, { "name": "hash", "in": "query", "required": false, "description": "1 = compute sha256 now if unknown (limited by api.maxHashBytes)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/files/list": { "get": { "summary": "List a folder (sorted by name, paged)", "security": [ { "oauth2": [ "files:read" ] }, { "personalToken": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Virtual path: //, e.g. /~/Photos/a.jpg", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-1000, default 500", "schema": { "type": "integer" } }, { "name": "page_token", "in": "query", "required": false, "description": "From next_page_token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/Entry" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "next_page_token": { "type": "string", "nullable": true } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/files/content": { "get": { "summary": "Download (supports Range, If-Range, If-None-Match)", "security": [ { "oauth2": [ "files:read" ] }, { "personalToken": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Virtual path: //, e.g. /~/Photos/a.jpg", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "bytes=start-end", "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Version/ETag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes" }, "206": { "description": "Partial content" }, "304": { "description": "Not modified" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "summary": "Upload a whole file in one request (small/medium files)", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Virtual path: //, e.g. /~/Photos/a.jpg", "schema": { "type": "string" } }, { "name": "mtime", "in": "query", "required": false, "description": "Epoch ms or ISO date to set as modification time", "schema": { "type": "string" } }, { "name": "overwrite", "in": "query", "required": false, "description": "true = replace without If-Match", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "Replace only if current version matches", "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "* = create only", "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": false, "description": "Hex SHA-256; verified before the file becomes visible", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "507": { "$ref": "#/components/responses/Error" } } } }, "/folders": { "post": { "summary": "Create a folder", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "parents": { "type": "boolean" }, "exist_ok": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "200": { "description": "Already existed (exist_ok)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "409": { "$ref": "#/components/responses/Error" } } } }, "/files/move": { "post": { "summary": "Rename or move (also between roots)", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "if_match": { "type": "string" }, "overwrite": { "type": "boolean", "description": "Replace an existing file at 'to' (never folders)" } } } } } }, "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" } } } }, "/files": { "delete": { "summary": "Delete permanently (there is no trash)", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Virtual path: //, e.g. /~/Photos/a.jpg", "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "required": false, "description": "true to delete a non-empty folder", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "Only delete this version", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" } } } }, "/delta": { "get": { "summary": "Change feed per root", "description": "Without cursor: full snapshot (change=exists, reset=true), paged. Then pass the returned cursor to get created/modified/moved/deleted changes. Children of moved or deleted folders are implied. 410 means start over without a cursor.", "security": [ { "oauth2": [ "files:read" ] }, { "personalToken": [] } ], "parameters": [ { "name": "root", "in": "query", "required": false, "description": "Root id (from /roots)", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "From the previous response", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-1000, default 500", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reset": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DeltaEntry" } }, "cursor": { "type": "string" }, "has_more": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" } } } }, "/uploads": { "post": { "summary": "Start a resumable upload", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "size" ], "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "mtime": { "type": "integer" }, "if_match": { "type": "string" }, "if_none_match": { "type": "string", "enum": [ "*" ] }, "overwrite": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "507": { "$ref": "#/components/responses/Error" } } } }, "/uploads/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Upload id", "schema": { "type": "string" } } ], "get": { "summary": "Upload status (offset to resume from)", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "patch": { "summary": "Append a chunk at Upload-Offset", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "parameters": [ { "name": "Upload-Offset", "in": "header", "required": true, "description": "Must equal the current offset", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Cancel", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "responses": { "204": { "description": "Cancelled" } } } }, "/uploads/{id}/complete": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Upload id", "schema": { "type": "string" } } ], "post": { "summary": "Verify size/sha256 and atomically place the file", "security": [ { "oauth2": [ "files:write" ] }, { "personalToken": [] } ], "responses": { "200": { "description": "Replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } } } }