# 在线文档块接口

# 创建嵌套块

请求 URL

POST https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/descendant

请求头

参数	是否必须	说明
Content-Type	是	固定值："application/json; charset=utf-8"
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号，作为块创建者

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

使用说明

本接口支持两种使用方式:

创建简单块(无嵌套关系):只需在 descendant 数组中指定块内容,无需指定 block_id 和 children 字段。服务端会自动生成块 ID。适用于创建平级的、互不包含的块。
创建嵌套块(有父子关系):需要使用临时 ID 描述块之间的父子关系:
- 在 children 参数中指定第一级子块的临时 ID 列表
- 在 descendant 数组的每个块中设置 block_id(临时 ID) 和 children(子块临时 ID 列表)
- 服务端返回的 block_id_relation 包含临时 ID 与实际 ID 的映射关系
块类型限制: 以下块类型不支持设置 children 字段:
- 标题块: h1, h2, h3, h4, h5
- 代码块: code
- 媒体块: image, attachment, video
- 功能块: divider, mermaid, plantuml

请求示例 1：创建标题块(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "h2",
      "heading2": {
        "elements": [
          {
            "text_run": {
              "content": "这是一段"
            }
          },
          {
            "text_run": {
              "content": "带下划线的",
              "text_style": {
                "underline": true
              }
            }
          },
          {
            "text_run": {
              "content": "H2标题"
            }
          }
        ]
      }
    }
  ]
}

请求示例 2：创建代码块(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "code",
      "code": {
        "elements": [
          {
            "text_run": {
              "content": "text := getter(openBlock)"
            }
          }
        ],
        "style": {
          "language": "go",
          "wrap": true
        }
      }
    }
  ]
}

请求示例 3：创建任务块(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "task",
      "task": {
        "name": "这是开放接口添加的任务",
        "done": false,
        "due_at": {
          "date": "2025-12-31",
          "time": "12:00:00"
        },
        "assignees": [
          {
            "staff_uuid": "af7cd4b2ff3f11e8a0dd787b8aca2306"
          }
        ]
      }
    }
  ]
}

请求示例 4：创建高亮块(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "callout",
      "callout": {
        "icon": "1FAE1",
        "color": "#6CEF82"
      }
    }
  ]
}

请求示例 5：创建分栏容器(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "column_list",
      "column_list": {
        "column_size": 3
      }
    }
  ]
}

请求示例 6：创建空表格(简单块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "descendant": [
    {
      "block_type": "table",
      "table": {
        "row_size": 2,
        "column_size": 3,
        "header_row": true,
        "header_column": true
      }
    }
  ]
}

请求示例 7：创建表格并填充内容(嵌套块)

{
  "parent_block_id": "parent-block-id",
  "index": 0,
  "children": ["table-1"],
  "descendant": [
    {
      "block_id": "table-1",
      "block_type": "table",
      "table": {
        "row_size": 3,
        "column_size": 3,
        "column_width": [200, 200, 200],
        "header_row": true,
        "header_column": false
      },
      "children": [
        "cell-1-1",
        "cell-1-2",
        "cell-1-3",
        "cell-2-1",
        "cell-2-2",
        "cell-2-3",
        "cell-3-1",
        "cell-3-2",
        "cell-3-3"
      ]
    },
    {
      "block_id": "cell-1-1",
      "block_type": "table_cell",
      "table_cell": {
        "align": "center",
        "vertical_align": "middle"
      },
      "children": ["text-1-1"]
    },
    {
      "block_id": "text-1-1",
      "block_type": "p",
      "text": {
        "elements": [
          {
            "text_run": {
              "content": "表头1",
              "text_style": {
                "bold": true
              }
            }
          }
        ]
      }
    },
    {
      "block_id": "cell-1-2",
      "block_type": "table_cell",
      "table_cell": {
        "align": "center",
        "vertical_align": "middle"
      },
      "children": ["text-1-2"]
    },
    {
      "block_id": "text-1-2",
      "block_type": "p",
      "text": {
        "elements": [
          {
            "text_run": {
              "content": "表头2",
              "text_style": {
                "bold": true
              }
            }
          }
        ]
      }
    },
    {
      "block_id": "cell-1-3",
      "block_type": "table_cell",
      "table_cell": {
        "align": "center",
        "vertical_align": "middle"
      },
      "children": ["text-1-3"]
    },
    {
      "block_id": "text-1-3",
      "block_type": "p",
      "text": {
        "elements": [
          {
            "text_run": {
              "content": "表头3",
              "text_style": {
                "bold": true
              }
            }
          }
        ]
      }
    }
  ]
}

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID

请求参数说明

参数	类型	说明

响应示例 1：简单块创建响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "descendant": [
      {
        "block_id": "generated-block-id-001",
        "block_type": "h2",
        "parent_id": "parent-block-id",
        "children": [],
        "heading2": {
          "elements": [
            {
              "text_run": {
                "content": "这是一段"
              }
            },
            {
              "text_run": {
                "content": "带下划线的",
                "text_style": {
                  "underline": true
                }
              }
            },
            {
              "text_run": {
                "content": "H2标题"
              }
            }
          ]
        }
      }
    ],
    "block_id_relation": {}
  }
}

响应示例 2：嵌套结构响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "descendant": [
      {
        "block_id": "real-block-id-001",
        "block_type": "numbered_list",
        "parent_id": "parent-block-id",
        "children": ["real-block-id-002", "real-block-id-003"],
        "numbered": {
          "elements": [
            {
              "text_run": {
                "content": "有序列表第一项"
              }
            }
          ]
        }
      },
      {
        "block_id": "real-block-id-002",
        "block_type": "bulleted_list",
        "parent_id": "real-block-id-001",
        "children": [],
        "bulleted": {
          "elements": [
            {
              "text_run": {
                "content": "无序列表aaa"
              }
            }
          ]
        }
      },
      {
        "block_id": "real-block-id-003",
        "block_type": "bulleted_list",
        "parent_id": "real-block-id-001",
        "children": [],
        "bulleted": {
          "elements": [
            {
              "text_run": {
                "content": "无序列表bbb"
              }
            }
          ]
        }
      }
    ],
    "block_id_relation": {
      "list-item-1": "real-block-id-001",
      "bullet-item-1": "real-block-id-002",
      "bullet-item-2": "real-block-id-003"
    }
  }
}

响应参数说明

参数	类型	说明

# 更新块内容

请求 URL

PUT https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/{block_id}

请求头

参数	是否必须	说明
Content-Type	是	固定值："application/json; charset=utf-8"
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号，作为块修改者

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

请求示例 1：更新文本片段

{
  "update_text_elements": {
    "elements": [
      {
        "text_run": {
          "content": "这是普通文本"
        }
      },
      {
        "text_run": {
          "content": "这是斜体文本",
          "text_style": {
            "italic": true
          }
        }
      }
    ]
  }
}

请求示例 2：更新文本块样式

{
  "update_text_style": {
    "style": {
      "align": "center"
    },
    "fields": ["align"]
  }
}

请求示例 3：更新任务

{
  "update_task": {
    "task": {
      "name": "更新后的任务名",
      "done": false
    },
    "fields": ["name", "done"]
  }
}

请求示例 4：插入表格行

{
  "insert_table_row": {
    "index": 2
  }
}

请求示例 5：插入表格列

{
  "insert_table_column": {
    "index": 1
  }
}

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID
block_id	是	块 ID

参数说明

参数	类型	说明

注意： 每次请求只能选择其中一种更新类型。

响应示例

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "block": {
      "block_id": "block-id-123",
      "block_type": "p",
      "parent_id": "parent-block-id",
      "children": [],
      "text": {
        "elements": [
          {
            "text_run": {
              "content": "这是普通文本"
            }
          },
          {
            "text_run": {
              "content": "这是斜体文本",
              "text_style": {
                "italic": true
              }
            }
          }
        ],
        "style": {
          "align": "center"
        }
      }
    }
  }
}

响应参数说明

参数	类型	说明

# 批量移动块

将指定的块移动到新的父节点下，支持调整顺序。

请求 URL

POST https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/move

请求头

参数	是否必须	说明
Content-Type	是	固定值："application/json; charset=utf-8"
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号，作为块操作者

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID

请求参数说明

参数	类型	说明

请求示例 1：移动块到父节点开头

{
  "block_ids": ["block-id-001", "block-id-002"],
  "parent_block_id": "target-parent-block-id"
}

请求示例 2：移动块到指定块之后

{
  "block_ids": ["block-id-001"],
  "parent_block_id": "target-parent-block-id",
  "after": "existing-block-id-003"
}

响应示例

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "parent": {
      "block_id": "target-parent-block-id",
      "block_type": "p",
      "parent_id": "page-root-id",
      "children": ["block-id-001", "block-id-002", "existing-block-id-003"]
    }
  }
}

响应参数说明

参数	类型	说明

# 删除块

请求 URL

DELETE https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/{block_id}

请求头

参数	是否必须	说明
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号，作为块删除者若不希望指定删除者或忽略权限校验，可设置为固定值："system-bot"

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID
block_id	是	块 ID

响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {}
}

# 批量删除子块

请求 URL

DELETE https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/children

请求头

参数	是否必须	说明
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号，作为块删除者若不希望指定删除者或忽略权限校验，可设置为固定值："system-bot"

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID
parent_block_id	否	父级块 ID，为空时删除 entry 对应 page 的子块
ids	是	删除的子块 ID 列表

请求示例

# 删除指定父块的子块
DELETE https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/entry-123/blocks/children?parent_block_id=parent-block-456&ids[]=child-001&ids[]=child-002

# 删除 entry 对应 page 的子块
DELETE https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/entry-123/blocks/children?ids[]=child-001&ids[]=child-002

响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {}
}

# 块附件上传

申请上传凭证，获取上传会话 ID 和预签名上传地址，用于在创建嵌套块时通过 session_id 字段自动创建文件记录。

完整流程

调用本接口获取 session_id 和 upload_url
使用 HTTP PUT 将文件上传到 upload_url
调用「创建嵌套块」接口，在 attachment/image block 的 session_id 字段传入 session_id

请求 URL

POST https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/files/apply-upload

请求头

参数	是否必须	说明
Content-Type	是	固定值："application/json; charset=utf-8"
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"
x-staff-id	是	成员帐号

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID

请求参数说明

参数	类型	说明

请求示例

{
  "name": "example.png",
  "size": 102400,
  "mime_type": "image/png"
}

响应示例

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "session_id": "upload-session-abc123",
    "upload_url": "https://cos.example.com/presigned-upload-url?sign=xxx"
  }
}

响应参数说明

参数	类型	说明

# 上传文件到 COS

获取到 upload_url 后，使用 HTTP PUT 方法将文件二进制内容上传到该预签名地址（已包含签名，无需额外鉴权）。

curl -X PUT "{upload_url}" --data-binary @/path/to/example.png

响应状态码 200 且包含 ETag 响应头即为上传成功。详细说明请参考腾讯云 COS PUT Object 文档 (opens new window)。

# 完整使用示例

以下示例演示完整的三步流程——申请上传凭证、上传文件、创建图片块：

# 步骤1：申请上传凭证
curl -X POST 'https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/files/apply-upload' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-staff-id: YOUR_STAFF_ID' \
  -d '{
    "name": "example.png",
    "size": 102400
  }'

# 步骤2：使用返回的 upload_url 上传文件（预签名地址已包含鉴权信息）
curl -X PUT "{upload_url}" --data-binary @/path/to/example.png

# 步骤3：创建图片块，使用 session_id 关联上传的文件
curl -X POST 'https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/descendant' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-staff-id: YOUR_STAFF_ID' \
  -d '{
    "parent_block_id": "parent-block-id",
    "index": -1,
    "descendant": [
      {
        "block_type": "image",
        "image": {
          "session_id": "upload-session-abc123"
        }
      }
    ]
  }'

# 获取块详情

请求 URL

GET https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/{block_id}

请求头

参数	是否必须	说明
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID
block_id	是	块 ID

响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "block": {
      "block_id": "block-id-123",
      "block_type": "p",
      "parent_id": "parent-block-id",
      "children": ["child-block-id-001", "child-block-id-002"],
      "text": {
        "elements": [
          {
            "text_run": {
              "content": "这是文本内容",
              "text_style": {
                "bold": true,
                "italic": false,
                "underline": false,
                "strikethrough": false,
                "inline_code": false,
                "text_color": "default"
              }
            }
          }
        ],
        "style": {
          "align": "left",
          "background_color": "default"
        }
      }
    }
  }
}

参数说明

参数	类型	说明

# 获取子块列表

请求 URL

GET https://lxapi.lexiangla.com/cgi-bin/v1/kb/page/entries/{entry_id}/blocks/children

请求头

参数	是否必须	说明
Authorization	是	接口调用凭证 access_token 值格式："Bearer access_token" 示例值："Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJS"

其他说明

事项	说明
权限要求	知识库管理
授权范围	AppKey 绑定团队时，入参`entry_id`条目的知识需在授权的团队下
频率限制	3000 次/分钟

URL 参数说明

参数	是否必须	说明
entry_id	是	条目 ID
parent_block_id	否	父块 ID，为空时查询 entry 对应 page 的子块
with_descendants	否	是否递归获取所有子孙，false 时只返回直接子块，默认 false

响应

200 Ok 状态码

{
  "code": 0,
  "message": "success",
  "request_id": "cf53056e-9170-4218-9907-67bcc623d423",
  "data": {
    "blocks": [
      {
        "block_id": "child-block-id-001",
        "block_type": "p",
        "parent_id": "block-id-123",
        "children": [],
        "text": {
          "elements": [
            {
              "text_run": {
                "content": "第一个子块"
              }
            }
          ]
        }
      },
      {
        "block_id": "child-block-id-002",
        "block_type": "h2",
        "parent_id": "block-id-123",
        "children": ["grandchild-block-id-001"],
        "heading2": {
          "elements": [
            {
              "text_run": {
                "content": "第二个子块（二级标题）"
              }
            }
          ]
        }
      },
      {
        "block_id": "grandchild-block-id-001",
        "block_type": "bulleted_list",
        "parent_id": "child-block-id-002",
        "children": [],
        "bulleted": {
          "elements": [
            {
              "text_run": {
                "content": "孙块（无序列表）"
              }
            }
          ]
        }
      }
    ]
  }
}

参数说明

参数	类型	说明