KV 使用文档与 API

服务入口：https://kv.disk.zone · disk.zone 的 KV 键值存储

KV 把数据放在按命名空间组织的键值存储里：值存放在 B2 存储池，带命名空间 Key 的单个键读写在离你最近的边缘完成。账号就是 disk.zone 账号，和 disk.zone 的所有项目共用登录和 API Key。

个人空间：登录后新建、管理命名空间，浏览数据
API 索引 · OpenAPI · llms.txt
disk.zone 开发者文档：登录、API Key、统一响应格式

快速开始

打开个人空间，用 disk.zone 账号登录。
新建一个命名空间，例如 my-app。页面会显示它的 Key（kvk_…），以后也随时可以在控制台查看、复制。
用这把 Key 读写：

KEY='kvk_…'
curl -X PUT "https://kv.disk.zone/v1/my-app/greeting" -H "Authorization: Bearer $KEY" --data-binary "hello"
curl "https://kv.disk.zone/v1/my-app/greeting" -H "Authorization: Bearer $KEY"
# → hello

三种凭据

凭据	形式	能做什么
命名空间 Key	`kvk_…`，新建或更换命名空间时返回	读写这一个命名空间的数据。最快：单个键的请求在边缘直接完成
账户 API Key	`dzk.<用户名>.<keyid>.<secret>`，在 disk.zone 账户页创建	管理名下全部命名空间，也能读写它们的数据
网页登录	disk.zone 的登录 Cookie（*.disk.zone 共享）	个人空间网页里的一切操作

请求里怎么带：

Authorization: Bearer <凭据>（三种都可以）
命名空间 Key 也可以放在 ?apikey= 或 x-api-key 头里，方便浏览器和简单脚本

命名空间 Key 只能操作自己的命名空间；账户 Key 和登录只能操作自己名下的命名空间。命名空间不存在和 Key 不对返回同样的 401，不会泄露哪些名字已被占用。

命名空间

命名空间名：1–64 个字母、数字、_ 或 -，以字母或数字开头。名字全站唯一，先到先得。

方法	地址	结果
GET	`/api/namespaces`	自己的命名空间：`{items: [{name, state, created}]}`
POST	`/api/namespaces`，body `{"name":"my-app"}`	新建，`201 {name, key, created}`；名字已被占用 409
GET	`/api/namespaces/{ns}`	`{name, state, created}`
POST	`/api/namespaces/{ns}/key`	换一把新 Key，返回 `{name, key}`；旧 Key 一分钟内失效
DELETE	`/api/namespaces/{ns}`	删除：Key 立即失效，数据在后台清空，清空后名字才能再用

这些接口用账户 API Key、访问令牌或网页登录调用：

curl -X POST "https://kv.disk.zone/api/namespaces" -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" --data '{"name":"my-app"}'
# → {"ok":true,"data":{"name":"my-app","key":"kvk_…","created":1793900000000}}

命名空间 Key 随时可以查看：控制台里点开命名空间就能看到，接口 GET /api/namespaces 和 GET /api/namespaces/{ns} 也会返回 key（只有所有者能看到）。换一把 Key（POST /api/namespaces/{ns}/key）后旧 Key 在一分钟内失效。

读写单个键

方法	地址	说明
PUT	`/v1/{ns}/{key}`	请求体就是值，任意字节；再写就是覆盖。返回 `{etag, expires}`
GET	`/v1/{ns}/{key}`	返回值本身，不加任何包装；不存在 404
HEAD	`/v1/{ns}/{key}`	只要头部：大小、etag、到期时间
DELETE	`/v1/{ns}/{key}`	删除这个键的全部版本；不存在也算成功

键可以包含 /，例如 users/alice/profile.json；每一段分别 URL 编码。键不能有 . 或 .. 段，不能有控制字符，整个对象名不超过 1024 字节。

读取的响应头：

etag：版本号，写入时返回的 etag 就是它
content-type：写入时的 Content-Type
x-kv-metadata：写入时附带的元数据（URL 编码的 JSON）
x-kv-expiration：到期时刻（Unix 秒），没有到期时间则没有这个头

过期、元数据与条件请求

写入时可以带：

?ttl=3600：多少秒后过期（也接受 ?expiration_ttl=）
?expiration=1793900000：到期时刻（Unix 秒）
?metadata={"v":1} 或请求头 x-kv-metadata（URL 编码的 JSON）

到期的键读起来就像不存在，并在读到时被删除。

读取支持 Range: bytes=…（单个区间，返回 206）、If-Range、If-Match、If-Unmodified-Since。

curl -X PUT "https://kv.disk.zone/v1/my-app/session/42?ttl=600" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" --data '{"user":"alice"}'
curl -r 0-99 "https://kv.disk.zone/v1/my-app/big.bin" -H "Authorization: Bearer $KEY" -o head.bin

列出与批量删除

curl "https://kv.disk.zone/v1/my-app?prefix=users/&limit=1000" -H "Authorization: Bearer $KEY"
# → {"ok":true,"data":{"keys":[{"name":"users/alice","size":42,"modified":"…","id":"…","expires":null}],"cursor":"…","list_complete":false}}

参数	说明
`prefix`	只列出以它开头的键
`limit`	每页最多多少个，默认 1000
`cursor`	上一页返回的 cursor，原样带回
`after` / `before`	只列出名字在这两者之间的（都不含）

键按 UTF-8 字节顺序返回。一页可能少于 limit，是否列完以 list_complete 为准。id 是版本号，批量删除时带上可以更快。

批量删除一次最多 1000 个：

curl -X POST "https://kv.disk.zone/v1/my-app?delete" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" --data '{"keys":["a","b"],"ids":["<id of a>",null]}'
# → {"ok":true,"data":{"deleted":2,"failed":[]}}

响应格式与错误

除了读取（直接返回值），所有接口都返回 disk.zone 统一的格式：

{"ok":true,"data":…}
{"ok":false,"error":{"code":"snake_case","message":"中文说明"}}

状态	常见 code	含义
400	`bad_request`、`invalid_name`	参数、键名或命名空间名不合法
401	`unauthorized`	没带凭据、凭据不对，或命名空间不存在
404	`not_found`	键或命名空间不存在
409	`name_taken`、`name_not_free`	名字已被占用，或删除后还在清理
502	存储上游的 code	存储暂时出错，可以重试
503	`storage_unavailable` 等	暂时不可用，按 `retry-after` 重试

响应头 x-kv-via 说明这次请求由边缘入口（snippet）还是后端（worker）完成，排查时有用。

限制

项目	限制
单个值	约 100 MB（一次请求的上限）
键	整个对象名不超过 1024 字节，不能有 `.` / `..` 段和控制字符
命名空间名	1–64 个字母、数字、`_`、`-`
批量删除	一次 1–1000 个
列出	每页最多 1 万个 × 存储桶数
更换 Key	新 Key 几秒内各地可用；旧 Key 最多一分钟后失效
删除命名空间	Key 最多一分钟后各地失效

给 AI 的说明

把这份文档（https://kv.disk.zone/docs.md）和一把命名空间 Key 交给 AI，它就可以直接读写这个命名空间。要让 AI 新建或管理命名空间，给它账户 API Key（dzk.…），并让它先调用 GET /api/me 确认身份。

读写用 /v1/{ns}/{key}，读取得到的就是值本身
其他接口都返回 {"ok":…}，以 error.code 判断错误
忘了 Key 就用 GET /api/namespaces/{ns} 取回
不要把 Key 写进公开的代码、日志或网页