{"openapi":"3.1.0","info":{"title":"disk.zone FS API","version":"1.0.0","description":"disk.zone 的 FS 文件存储：以根目录组织，文件分发在 Cloudflare 的静态资源 CDN 上，按路径或按 key 下载；用 disk.zone 账号管理。"},"servers":[{"url":"https://fs.disk.zone"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"disk.zone 访问令牌或账户 API Key（dzk.…）"},"cookie":{"type":"apiKey","in":"cookie","name":"dz_at","description":"disk.zone 的登录 Cookie"},"namespaceKey":{"type":"http","scheme":"bearer","description":"命名空间 Key（kvk_…）；也可放在 ?apikey= 或 x-api-key"}}},"paths":{"/v1/{root}/{path}":{"put":{"operationId":"file_put","summary":"上传文件","description":"请求体就是文件，一次请求最多约 100 MB；同一路径再传就是替换。返回 {path, key, size, readyAt, url}：key 是文件的永久下载凭据，url 是不需要登录的下载地址。","tags":["files"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","required":false,"name":"type","description":"文件的 Content-Type（不给则用请求头）","schema":{"type":"string"}},{"in":"query","required":false,"name":"upload","description":"超过 100 MB 时分几次上传：自定的 32 位十六进制 id，各次相同","schema":{"type":"string"}},{"in":"query","required":false,"name":"offset","description":"这一段在文件里的起点（字节）","schema":{"type":"integer"}},{"in":"query","required":false,"name":"total","description":"文件总长（字节）","schema":{"type":"integer"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]},"get":{"operationId":"file_get","summary":"下载文件","description":"返回文件本身，支持 Range。刚上传的文件在分发到 CDN 前返回 425 和 retry-after，稍后再试。","tags":["files"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]},"delete":{"operationId":"file_delete","summary":"删除文件","description":"删除这个路径。","tags":["files"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/v1/{root}/{path}?meta":{"get":{"operationId":"file_meta","summary":"文件记录","description":"{path, key, size, type, at}。","tags":["files"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/v1/{root}/{dir}/":{"get":{"operationId":"files_list","summary":"列出目录","description":"以 / 结尾的路径列出该目录下（含子目录）的文件：{files: [{path, size, type, at}], next}；翻页时把 next 放进 ?after=。","tags":["files"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}},{"name":"dir","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","required":false,"name":"limit","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"in":"query","required":false,"name":"after","schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/f/{key}":{"get":{"operationId":"file_by_key","summary":"按 key 下载","description":"不需要登录：拿到 key 就能下载，适合分享和外链。多个 key 用 . 连起来就一次下载它们拼在一起的内容。","tags":["files"],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}}}},"/api/me":{"get":{"operationId":"me","summary":"当前账号","description":"{user: {id}}。","tags":["account"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/roots":{"get":{"operationId":"roots_list","summary":"我的根目录","description":"{items: [{name, created}]}。","tags":["roots"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]},"post":{"operationId":"root_create","summary":"新建根目录","description":"新建一个根目录；名字全站唯一，先到先得。","tags":["roots"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,47}$","description":"1–48 个小写字母、数字、_ 或 -，以字母或数字开头"}},"required":["name"]}}}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/roots/{root}":{"get":{"operationId":"root_get","summary":"一个根目录","description":"{name, created}。","tags":["roots"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]},"delete":{"operationId":"root_delete","summary":"删除根目录","description":"只能删除空的根目录：先删掉里面的文件。","tags":["roots"],"parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/health":{"get":{"operationId":"health","summary":"健康检查","description":"{service, status}。","tags":["service"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}}}}}}