REST API

所有接口在 https://agentdocs.page 下。错误统一返回 { "error": { "code": "FILE_TOO_LARGE", "message": "...", "requestId": "..." } }。

上传

上传需要在 Authorization 头里带上传密钥。支持两种形式：

# 1) multipart
curl -H "Authorization: Bearer $AGENTDOCS_KEY" -F file=@report.md https://agentdocs.page/api/files

# 2) 原始 body（必须带 ?filename=）
curl -H "Authorization: Bearer $AGENTDOCS_KEY" -H "Content-Type: text/markdown" \
  --data-binary @report.md "https://agentdocs.page/api/files?filename=report.md"

成功返回 201：

{
  "id": "…",
  "filename": "report.md",
  "format": "md",
  "size": 1234,
  "createdAt": "…",
  "viewerUrl": "https://agentdocs.page/f/…",
  "downloadUrl": "https://agentdocs.page/api/files/…/download",
  "rawUrl": "https://agentdocs.page/f/…?raw"
}

把 viewerUrl 发给人阅读；Agent 用 rawUrl 取回原文。

R2 用量超过免费额度的 80% 时，上传返回 503。error.code 仍是 STORAGE_UNAVAILABLE，message 会说明上传已暂停。这不是限速，不会返回 429。

读取与下载

方法与路径	说明	鉴权
`GET /f/:id`	阅读页（人用）。带 `Accept: text/markdown` 或以 `text/plain` 开头时返回原文	无
`GET /f/:id.md`、`GET /f/:id?raw`	原文，`text/plain; charset=utf-8`	无
`GET /api/files/:id`	JSON：`id`、`filename`、`format`、`size`、`createdAt`、`experimental`、`source`	无
`GET /api/files/:id/download`	原始字节，`Content-Disposition: attachment`	无
`DELETE /api/files/:id`	删除，成功返回 `204`	管理密钥
`GET /api/health`	`{ ok, version }`	无

错误码

错误码	状态	含义
`BAD_REQUEST`	400	请求格式错误（缺少文件、缺少文件名等）
`UNAUTHORIZED`	401	密钥缺失、无效或权限不足
`FORBIDDEN`	403	跨域预检一律拒绝
`NOT_FOUND`	404	文件不存在、已删除，或 ID 格式不合法
`REVISION_CONFLICT`	409	文档的 `base_revision` 不是当前修订（文档 API，尚未开放）
`FILE_TOO_LARGE`	413	超过 1 MiB
`UNSUPPORTED_FORMAT`	415	扩展名不在白名单
`INVALID_TEXT`	422	不是合法 UTF-8、含 NUL 字节或为空文件
`EDIT_FAILED`	422	文档编辑的 `old_str` 无匹配或匹配多处（文档 API，尚未开放）
`RATE_LIMITED`	429	触发限速
`INTERNAL_ERROR`	500	服务端异常
`STORAGE_UNAVAILABLE`	503	存储暂时不可用，可重试；用量熔断暂停上传时也用这个码，消息会说明原因

格式与大小见格式说明和限制与隐私。

个人 API Key

登录后在「设置 → API Key」创建。Key 以 adk_ 开头，只显示一次；吊销后立即失效。Agent 或脚本用它访问 /api/docs：

curl -H "Authorization: Bearer $AGENTDOCS_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename":"report.md","content":"# 报告"}' https://agentdocs.page/api/docs

权限（scope）：docs:read 读取、docs:write 创建与编辑、docs:share 改可见性、docs:delete 删除。缺少权限返回 403。