my-assistant/skills/dingtalk-document/references/api.md

dingtalk-document API 参考

所有接口均已验证可用。 NEW_TOKEN = 新版 token（api.dingtalk.com 用），获取方式 bash scripts/dt_helper.sh --token OPERATOR_ID = 用户 unionId，获取方式 bash scripts/dt_helper.sh --get DINGTALK_MY_OPERATOR_ID ⚠️ 重要：所有接口均需传 operatorId（unionId），缺少则返回 MissingoperatorId 错误。

---

1. 查询知识库列表

GET https://api.dingtalk.com/v2.0/wiki/workspaces?operatorId={OPERATOR_ID}&maxResults=20&nextToken=
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

参数	类型	必填	说明
operatorId	string	✅	用户 unionId
maxResults	int	❌	每页数量，默认 20
nextToken	string	❌	分页令牌，首次为空

响应：

{
  "workspaces": [
    {
      "workspaceId": "QXvd5SLN2AxOQz0Z",
      "name": "团队知识库",
      "description": "...",
      "rootNodeId": "P0MALyR8kl3qpB7qTkM1xn3mW3bzYmDO",
      "type": "TEAM",
      "url": "https://alidocs.dingtalk.com/i/spaces/.../overview",
      "createTime": "2024-01-01T00:00Z",
      "modifiedTime": "2024-06-01T00:00Z"
    }
  ],
  "nextToken": "..."
}

翻页：nextToken 非空时传入下次请求继续获取。

---

2. 查询知识库信息

GET https://api.dingtalk.com/v2.0/wiki/workspaces/{workspaceId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

响应：单个 workspace 对象（结构同列表项）

---

3. 查询节点列表

GET https://api.dingtalk.com/v2.0/wiki/nodes?parentNodeId={nodeId}&operatorId={OPERATOR_ID}&maxResults=50&nextToken=
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

参数	类型	必填	说明
parentNodeId	string	✅	父节点 ID，传知识库的 rootNodeId 可列出顶层内容
operatorId	string	✅	用户 unionId
maxResults	int	❌	每页数量，默认 20
nextToken	string	❌	分页令牌

响应：

{
  "nodes": [
    {
      "nodeId": "LeBq413JAw31yaz1fB0BBdLGWDOnGvpb",
      "name": "使用文档.adoc",
      "type": "FILE",
      "category": "ALIDOC",
      "extension": "adoc",
      "workspaceId": "QXvd5SnBnzmZdZ0Z",
      "url": "https://alidocs.dingtalk.com/i/nodes/...",
      "createTime": "2026-03-04T16:58Z",
      "modifiedTime": "2026-03-04T17:51Z"
    }
  ],
  "nextToken": "..."
}

type：FILE（文档/文件）| FOLDER（文件夹）

---

4. 查询单个节点

GET https://api.dingtalk.com/v2.0/wiki/nodes/{nodeId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

响应：{ "node": { nodeId, name, type, category, workspaceId, url, ... } }

---

5. 通过 URL 查询节点

POST https://api.dingtalk.com/v2.0/wiki/nodes/queryByUrl?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

请求体：

{
  "url": "https://alidocs.dingtalk.com/i/nodes/<nodeId>",
  "operatorId": "{OPERATOR_ID}"
}

响应：与 GET 单个节点相同的 node 结构。

---

6. 创建文档

POST https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

请求体：

{
  "operatorId": "{OPERATOR_ID}",
  "docType": "DOC",
  "name": "文档标题"
}

参数	类型	必填	说明
operatorId	string	✅	用户 unionId
docType	string	✅	固定填 "DOC"（ALIDOC 富文本格式）
name	string	✅	文档标题

响应：

{
  "dentryUuid": "aaa",
  "nodeId": "xxx",
  "docKey": "yyy",
  "workspaceId": "zzz",
  "url": "https://..."
}

重要：

• docKey / dentryUuid：用于 /v1.0/doc/suites/documents/{id} 内容读写
• nodeId：用于 /v1.0/doc/workspaces/{workspaceId}/docs/{nodeId} 删除/管理

---

7. 删除文档

DELETE https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

workspaceId 和 nodeId 均使用创建文档响应中的值。成功返回 200 {}。

---

8. 读取文档内容（Block 结构）

GET https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

docKey 的来源：

• 通过 wiki nodes 接口查到的 nodeId 本质是 dentryUuid，可直接用于正文读写
• 通过创建文档接口新建的文档：可使用响应中的 docKey 或 dentryUuid
• 创建响应中的 nodeId（通常出现在 /docs/<nodeId> 链接中）不能直接用于正文读写

响应：

{
  "result": {
    "data": [
      { "blockType": "heading", "heading": { "level": "heading-2", "text": "快速开始" }, "index": 0, "id": "xxx" },
      { "blockType": "paragraph", "paragraph": { "text": "正文内容..." }, "index": 1, "id": "yyy" },
      { "blockType": "table", "table": { "colSize": 2, "rowSize": 10 }, "index": 2, "id": "zzz" },
      { "blockType": "unknown", "index": 3, "id": "aaa", "unknown": {} }
    ]
  },
  "success": true
}

blockType 枚举：heading、paragraph、unorderedList、orderedList、table、blockquote、unknown（代码块/图片等）

---

9. 覆盖写入文档内容

POST https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/overwriteContent?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

⚠️ operatorId 必须同时作为 query param 和请求体字段传入，缺一会报 Missingcontent 错误。

请求体：

{
  "operatorId": "{OPERATOR_ID}",
  "content": "# 新标题\n\n新的正文内容，支持 Markdown 格式。",
  "contentType": "markdown"
}

⚠️ 此操作全量覆盖文档内容，不可撤销。

---

10. 追加文本到段落

POST https://api.dingtalk.com/v1.0/doc/suites/documents/{docKey}/blocks/{blockId}/paragraph/appendText
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

请求体：

{ "operatorId": "{OPERATOR_ID}", "text": "追加的文字" }

---

11. 添加文档成员

POST https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

请求体：

{
  "operatorId": "{OPERATOR_ID}",
  "members": [
    { "id": "<userId>", "roleType": "viewer" }
  ]
}

参数	说明
id	用户 userId（注意：这里用 userId，不是 unionId）
roleType	viewer（只读）

---

12. 更新文档成员权限

PUT https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members/{memberId}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

请求体：

{ "operatorId": "{OPERATOR_ID}", "roleType": "viewer" }

---

13. 移除文档成员

DELETE https://api.dingtalk.com/v1.0/doc/workspaces/{workspaceId}/docs/{nodeId}/members/{memberId}?operatorId={OPERATOR_ID}
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

---

14. 搜索文档（用于找回可读写 ID）

GET https://api.dingtalk.com/v1.0/doc/docs?operatorId={OPERATOR_ID}&workspaceId={workspaceId}&keyword={keyword}&maxResults=20&nextToken=
Header: x-acs-dingtalk-access-token: {NEW_TOKEN}

说明：

• 需要权限：Document.WorkspaceDocument.Read
• 返回结果中的 docs[].nodeBO.nodeId 即可用于 /v1.0/doc/suites/documents/{id} 的读写（该值是 dentryUuid 风格 ID）

示例响应（节选）：

{
  "docs": [
    {
      "nodeBO": {
        "name": "测试创建.adoc",
        "nodeId": "np9zOoBVBYwB2OZBIn4y0G1vW1DK0g6l",
        "url": "https://alidocs.dingtalk.com/i/nodes/np9zOoBVBYwB2OZBIn4y0G1vW1DK0g6l"
      },
      "workspaceBO": {
        "workspaceId": "QXvd5SLN2AxOQz0Z"
      }
    }
  ],
  "hasMore": false
}

---

错误码

HTTP状态码	错误码	说明	处理建议
400	MissingoperatorId	operatorId 未传	补充 operatorId（unionId）
400	paramError	参数类型错误	operatorId 必须是 unionId，不是 userId
403	Forbidden.AccessDenied.AccessTokenPermissionDenied	应用缺少权限	错误中有 requiredScopes，开通对应权限
404	InvalidAction.NotFound	接口路径不存在	检查版本号（v1.0/v2.0）和路径
429	—	QPS 限流	1 秒后重试

---

所需应用权限

功能	权限 scope
查询知识库/节点	Wiki.Node.Read
读取文档正文	Storage.File.Read
写入文档正文	Storage.File.Write
创建/删除文档	Storage.File.Write
查询用户 unionId	Contact.User.Read