{"openapi":"3.1.0","info":{"title":"disk.zone KV API","version":"1.0.0","description":"disk.zone 的 KV 键值存储：按命名空间组织，数据在 B2 存储池，单个 key 的读写在离用户最近的边缘完成。用 disk.zone 账号新建命名空间，用命名空间 Key 或账户 Key 通过 HTTP 读写。"},"servers":[{"url":"https://kv.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/{ns}/{key}":{"get":{"operationId":"kv_get","summary":"读取一个 key","description":"返回值本身（不加 ok/data 包装），带 etag（版本号）、x-kv-metadata、x-kv-expiration（Unix 秒）；支持 Range、If-Range、If-Match。HEAD 只要头部。不存在时 404。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]},"put":{"operationId":"kv_put","summary":"写入一个 key","description":"请求体就是值（任意字节，单次最大约 100 MB）。同一 key 再写就是覆盖。返回 {etag, expires}。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","required":false,"name":"ttl","description":"多少秒后过期","schema":{"type":"integer","minimum":1}},{"in":"query","required":false,"name":"expiration","description":"过期时刻（Unix 秒）","schema":{"type":"integer"}},{"in":"query","required":false,"name":"metadata","description":"附带的 JSON 元数据（也可放 x-kv-metadata 头，URL 编码）","schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]},"delete":{"operationId":"kv_delete","summary":"删除一个 key","description":"删除这个 key 的所有版本，不留痕迹。不存在也算成功。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]}},"/v1/{ns}":{"get":{"operationId":"kv_list","summary":"按前缀列出","description":"按字节顺序分页列出 key：{keys: [{name, size, modified, id, expires}], cursor, list_complete}。翻页时把 cursor 原样带回；一页可能少于 limit，以 list_complete 为准。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"in":"query","required":false,"name":"prefix","schema":{"type":"string"}},{"in":"query","required":false,"name":"limit","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1000}},{"in":"query","required":false,"name":"cursor","schema":{"type":"string"}},{"in":"query","required":false,"name":"after","description":"从这个名字之后开始（不含）","schema":{"type":"string"}},{"in":"query","required":false,"name":"before","description":"到这个名字之前为止（不含）","schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]}},"/v1/{ns}?get":{"post":{"operationId":"kv_get_many","summary":"一次读多个","description":"一次读 1–1000 个 key，按请求的顺序流式返回：每个 key 先是一行 JSON {key, status, size, etag?, type?, expires?, metadata?}，紧接着正好 size 个字节。status：200 整个值，206 请求的区间，404 不存在，416 区间起点超出末尾，502 这个 key 读存储失败（可以单独再读）。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000},"ranges":{"type":"array","description":"可选：和 keys 一一对应的 [起点, 字节数] 或 null（整个值）；字节数 0 只确认 key 存在","items":{"type":["array","null"],"items":{"type":"integer","minimum":0},"minItems":2,"maxItems":2}}},"required":["keys"]}}}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]}},"/v1/{ns}?delete":{"post":{"operationId":"kv_delete_many","summary":"批量删除","description":"一次删除 1–1000 个 key：{deleted, failed: [{key, code}]}。","tags":["kv"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000},"ids":{"type":"array","description":"可选：和 keys 一一对应的版本号（列表里的 id），给了就按版本删，更快","items":{"type":["string","null"]}}},"required":["keys"]}}}},"security":[{"namespaceKey":[]},{"bearer":[]},{"cookie":[]}]}},"/api/me":{"get":{"operationId":"me","summary":"当前账号","description":"当前 disk.zone 账号：{user: {id}}。","tags":["account"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/namespaces":{"get":{"operationId":"namespaces_list","summary":"我的命名空间","description":"当前账号的命名空间：{items: [{name, state, created, key}]}。key 是这个命名空间的 Key（kvk_…），随时可取。","tags":["namespaces"],"parameters":[],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]},"post":{"operationId":"namespace_create","summary":"新建命名空间","description":"新建一个命名空间，返回 {name, key, created}，key 是它的 Key（kvk_…），之后也能随时用 GET 取回。名字全站唯一，先到先得。","tags":["namespaces"],"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-Za-z0-9][A-Za-z0-9_-]{0,63}$","description":"1–64 个字母、数字、_ 或 -，以字母或数字开头"}},"required":["name"]}}}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/namespaces/{ns}":{"get":{"operationId":"namespace_get","summary":"一个命名空间","description":"{name, state, created, key}：key 是这个命名空间当前的 Key。","tags":["namespaces"],"parameters":[{"name":"ns","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":"namespace_delete","summary":"删除命名空间","description":"Key 立即失效（各地缓存最多一分钟）；后台随后删掉全部数据，删完名字才能再用。","tags":["namespaces"],"parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{\"ok\":true,\"data\":…}"},"default":{"description":"{\"ok\":false,\"error\":{\"code\",\"message\"}}"}},"security":[{"bearer":[]},{"cookie":[]}]}},"/api/namespaces/{ns}/key":{"post":{"operationId":"namespace_rekey","summary":"换一把 Key","description":"生成新的命名空间 Key 并返回 {name, key}；旧 Key 在一分钟内失效。","tags":["namespaces"],"parameters":[{"name":"ns","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\"}}"}}}}}}