{
  "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: /<root-id>/<relative 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: /<root-id>/<relative 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: /<root-id>/<relative 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: /<root-id>/<relative 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: /<root-id>/<relative 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"
          }
        }
      }
    }
  }
}