Developer API

开发者 API 文档

用 API Key 以编程方式管理你的空间、文档与附件，把 857Wiki 接入你的 CI、脚本或自有产品。基础地址：https://857.wiki/api/public/v1

概览

所有接口返回 JSON，请求体为 JSON 时请设置Content-Type: application/json。附件上传使用multipart/form-data。权限与网页端一致：你能通过 API 做的事，不会超过你在该空间的角色（viewer / editor / admin / owner）。

认证

在设置 → API 密钥创建密钥，然后通过 Authorization 头携带：

curl https://857.wiki/api/public/v1/spaces \
  -H "Authorization: Bearer 857wk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

完整密钥仅在创建时显示一次；服务端只保存其 SHA-256 哈希。若密钥泄露，可在设置页立即撤销。

错误与限流

出错时返回非 2xx 状态码与{ "error": "…" }：

状态码	含义
400	请求参数不合法 / 请求体不是 JSON
401	缺少或无效的 API Key
403	权限不足（角色或可见性限制）
404	资源不存在或对你不可见
413	附件超过大小限制
415	不支持的文件类型
500	服务器内部错误

为保证免费额度下的公平使用，请控制调用频率；滥用可能导致密钥被停用。

空间

GET/spaces

列出空间

返回你所在的全部空间，以及所有公开空间。

示例请求

curl https://857.wiki/api/public/v1/spaces \
  -H "Authorization: Bearer $KEY"

响应

{
  "spaces": [
    {
      "id": "…",
      "name": "团队知识库",
      "slug": "团队知识库-bcg5u3nk",
      "description": "…",
      "visibility": "public",
      "role": "owner",
      "createdAt": "2026-08-01T08:00:00.000Z"
    }
  ]
}

POST/spaces

创建空间

创建一个新的知识空间，你自动成为 owner。

参数	说明
name	必填，空间名称，≤48 字符
description	可选，空间描述
visibility	可选，public / unlisted / private，默认 private

示例请求

curl -X POST https://857.wiki/api/public/v1/spaces \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的文档","visibility":"public"}'

响应

{ "space": { "id": "…", "name": "我的文档", "slug": "我的文档-xxxx" } }

GET/spaces/{slug}

空间详情

按 slug 获取空间信息。私有空间仅成员可见。

示例请求

curl https://857.wiki/api/public/v1/spaces/我的空间-xxxx \
  -H "Authorization: Bearer $KEY"

DELETE/spaces/{slug}

删除空间

仅 owner 可删除，空间内所有文档与附件一并删除，不可恢复。

示例请求

curl -X DELETE https://857.wiki/api/public/v1/spaces/我的空间-xxxx \
  -H "Authorization: Bearer $KEY"

文档

GET/spaces/{slug}/pages

列出文档

返回空间下的文档树。非成员只能看到已发布文档。

示例请求

curl https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/pages \
  -H "Authorization: Bearer $KEY"

POST/spaces/{slug}/pages

创建文档

在空间内创建文档，需要 editor 及以上权限。

参数	说明
title	可选，默认“未命名文档”
parentId	可选，父文档 id，用于构建层级
contentText	可选，纯文本正文（自动转为段落）
published	可选，true 时直接发布并触发 page.published

示例请求

curl -X POST https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/pages \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"快速开始","contentText":"欢迎使用 857Wiki","published":true}'

响应

{ "page": { "id": "…", "title": "快速开始", "slug": "快速开始-xxxx" } }

GET/spaces/{slug}/pages/{id}

文档详情

返回文档元数据与正文（ProseMirror JSON 与纯文本两种形式）。

响应

{
  "page": {
    "id": "…",
    "title": "快速开始",
    "slug": "…",
    "status": "published",
    "contentJson": { "type": "doc", "content": [ … ] },
    "contentText": "欢迎使用 857Wiki",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  }
}

PUT/spaces/{slug}/pages/{id}

更新文档

更新标题、正文或发布状态。正文可传 contentText（纯文本）或 contentJson（ProseMirror doc）。

参数	说明
title	可选，新标题
contentText	可选，纯文本正文
contentJson	可选，完整 ProseMirror doc（优先于 contentText）
published	可选，true 发布 / false 转回草稿

示例请求

curl -X PUT https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/pages/{id} \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"快速开始（第二版）","published":true}'

DELETE/spaces/{slug}/pages/{id}

删除文档

默认移入回收站；追加 ?permanent=1 可彻底删除（需 admin）。

示例请求

curl -X DELETE "https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/pages/{id}" \
  -H "Authorization: Bearer $KEY"

附件

GET/spaces/{slug}/attachments

列出附件

返回空间附件库。支持 ?q=名称关键词与 ?kind=image/pdf/… 过滤；非成员仅见 public 附件。

示例请求

curl "https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/attachments?kind=pdf" \
  -H "Authorization: Bearer $KEY"

POST/spaces/{slug}/attachments

上传附件

multipart/form-data 上传，字段名为 file。同名文件会自动生成新版本。需要 editor 权限。

示例请求

curl -X POST https://857.wiki/api/public/v1/spaces/团队知识库-xxxx/attachments \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./release.pdf"

响应

{ "attachment": { "id": "…", "name": "release.pdf", "version": 1, "isNew": true } }

GET/attachments/{id}

附件详情 / 下载

默认返回元数据；追加 ?download=1 直接返回文件（下载计数 +1）。

示例请求

curl -L "https://857.wiki/api/public/v1/attachments/{id}?download=1" \
  -H "Authorization: Bearer $KEY" -o release.pdf

DELETE/attachments/{id}

删除附件

删除附件及其历史版本。仅上传者本人或空间 admin 可操作。

示例请求

curl -X DELETE https://857.wiki/api/public/v1/attachments/{id} \
  -H "Authorization: Bearer $KEY"

Webhooks

在设置 → Webhooks配置回调地址并勾选事件。触发时我们会向你的地址发送 POST 请求，请求头包含：

x-857-event: page.published
x-857-delivery: <投递 id>
x-857-signature: sha256=<HMAC-SHA256(请求体, 签名密钥)>

支持的事件：

page.published	文档发布（草稿 → 已发布）
page.updated	已发布文档内容更新（60 秒节流）
attachment.uploaded	附件上传或新增版本
attachment.deleted	附件被删除

请求体形如：

{
  "id": "<投递 id>",
  "event": "page.published",
  "createdAt": "2026-08-28T10:00:00.000Z",
  "data": {
    "spaceId": "…",
    "pageId": "…",
    "title": "快速开始"
  }
}

用你的签名密钥校验签名（Node.js 示例）：

import { createHmac, timingSafeEqual } from "node:crypto";

const secret = process.env.WEBHOOK_SECRET; // whsec_…
const signature = req.headers["x-857-signature"];
const expected = "sha256=" + createHmac("sha256", secret)
  .update(rawBody)
  .digest("hex");

const ok = signature === expected &&
  timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

投递失败（非 2xx 或超时）会在 30 秒、2 分钟后自动重试，共 3 次。投递结果可在设置页查看。出于安全考虑，回调地址不能指向内网或本机。