乐享知识库接口文档

# 在线文档块接口

# 创建嵌套块

请求 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 次/分钟

使用说明

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

  1. 创建简单块(无嵌套关系):只需在 descendant 数组中指定块内容,无需指定 block_id 和 children 字段。服务端会自动生成块 ID。适用于创建平级的、互不包含的块。

  2. 创建嵌套块(有父子关系):需要使用临时 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

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": {}
}

# 获取块详情

请求 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": "孙块（无序列表）"
              }
            }
          ]
        }
      }
    ]
  }
}

参数说明

参数 类型 说明

← 查询成员任务列表 →