Buildin

Search pages, databases, folders and mind maps **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 429: Rate limited **请求示例:** ```json { "query": "项目计划", "filter": { "property": "object", "value": "page" }, "sort": { "timestamp": "last_edited_time", "direction": "descending" }, "page_size": 10 } ``` **响应示例:** ```json { "object": "list", "results": [ { "object": "page", "id": "11111111-1111-4111-8111-111111111111", "page_type": "page", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "workspace", "workspace": true }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, "cover": null, "properties": { "title": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "项目计划", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "项目计划", "href": null } ] } }, "url": "https://buildin.ai/11111111-1111-4111-8111-111111111111" }, { "object": "page", "id": "33333333-3333-4333-8333-333333333333", "page_type": "folder", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "workspace", "workspace": true }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, ... ```

Semantic search **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 429: Rate limited **请求示例:** ```json { "query": "如何配置 CI/CD", "page_size": 3, "score_threshold": 0.7 } ``` **响应示例:** ```json { "object": "list", "results": [ { "object": "search_result", "page_id": "44444444-4444-4444-8444-444444444444", "page_title": "CI/CD 配置指南", "score": 0.92, "snippet": "项目使用 GitHub Actions 进行持续集成与部署。", "url": "https://buildin.ai/44444444-4444-4444-8444-444444444444" } ], "next_cursor": null, "has_more": false } ```

Get current bot identity **可能的错误响应:** - 401: Authentication failed - 429: Rate limited **响应示例:** ```json { "object": "bot_user", "id": "20202020-2020-4020-8020-202020202020", "name": "Buildin MCP Integration", "workspace_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "workspace_name": "演示空间", "owner": { "object": "user", "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" }, "capabilities": { "pages.read": true, "pages.write": true, "blocks.read": true, "blocks.write": true, "databases.read": true, "databases.write": true, "search.read": true }, "type": "integration", "integration_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee" } ```

Get user **必需参数**: user_id **可能的错误响应:** - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "user_id": "ffffffff-ffff-4fff-8fff-ffffffffffff" } ``` **响应示例:** ```json { "object": "user", "id": "ffffffff-ffff-4fff-8fff-ffffffffffff", "type": "person", "name": "张三", "avatar_url": "https://example.com/avatar.png", "person": { "email": null } } ```

Create page **参数说明:** - `parent` (可选): 如果不提供，将默认创建在当前认证空间根目录 - `parent` 传参时只能是 `{ "page_id": "..." }` 或 `{ "database_id": "..." }`，不要附带 `type`、`workspace`、`space` 之类字段 - `properties` (可选): 页面属性；如果要创建带标题的普通页面，优先提供 `properties.title`，并保持 `title` 属性值里包含 `type: "title"` - `children` (可选): 页面初始内容块；`children` 必须是 JSON array，不要传 JSON string - `icon` (可选): 页面图标 **注意**: 只有在你明确需要把页面创建到指定页面或数据库下时，才传 `parent`；创建根目录页面时省略它最稳妥 **children 示例:** ```json { "children": [ { "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "正文" } }] } } ] } ``` **可选参数**: Idempotency-Key, parent, icon, cover, properties, children **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 409: Conflict - 429: Rate limited **请求示例:** ```json { "icon": { "type": "emoji", "emoji": "📝" }, "properties": { "title": { "type": "title", "title": [ { "type": "text", "text": { "content": "发布计划", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "发布计划", "href": null } ] } }, "children": [ { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "第一版发布范围与时间安排。", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "第一版发布范围与时间安排。", "href": null } ] } } ] } ``` **响应示例:** ```json { "object": "page", "id": "11111111-1111-4111-8111-111111111111", "page_type": "page", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "workspace", "workspace": true }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, "cover": null, "properties": { "title": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "发布计划", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "发布计划", "href": null } ] } }, "url": "https://buildin.ai/11111111-1111-4111-8111-111111111111" } ```

Get page **必需参数**: page_id **可能的错误响应:** - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "page_id": "22222222-2222-4222-8222-222222222222" } ``` **响应示例:** ```json { "object": "page", "id": "22222222-2222-4222-8222-222222222222", "page_type": "page", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "page_id", "page_id": "55555555-5555-4555-8555-555555555555" }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, "cover": null, "properties": { "title": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "季度规划", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "季度规划", "href": null } ] } }, "url": "https://buildin.ai/22222222-2222-4222-8222-222222222222" } ```

Update page **可选参数**: If-Match **必需参数**: page_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 409: Conflict - 429: Rate limited **请求示例:** ```json { "icon": { "type": "emoji", "emoji": "🚀" }, "properties": { "title": { "type": "title", "title": [ { "type": "text", "text": { "content": "季度规划（更新）", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "季度规划（更新）", "href": null } ] } } } ``` **响应示例:** ```json { "object": "page", "id": "22222222-2222-4222-8222-222222222222", "page_type": "page", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "page_id", "page_id": "55555555-5555-4555-8555-555555555555" }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, "cover": null, "properties": { "title": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "季度规划（更新）", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "季度规划（更新）", "href": null } ] } }, "url": "https://buildin.ai/22222222-2222-4222-8222-222222222222" } ```

Move page **必需参数**: page_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "parent": { "page_id": "55555555-5555-4555-8555-555555555555" }, "after": "11111111-1111-4111-8111-111111111111" } ``` **响应示例:** ```json { "object": "move_result", "id": "22222222-2222-4222-8222-222222222222", "object_type": "page", "parent": { "type": "page_id", "page_id": "55555555-5555-4555-8555-555555555555" }, "after": "11111111-1111-4111-8111-111111111111", "before": null } ```

Get page property **可选参数**: page_size, start_cursor **必需参数**: page_id, property_id **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "page_id": "22222222-2222-4222-8222-222222222222", "property_id": "title", "page_size": 25, "start_cursor": "0" } ``` **响应示例:** ```json { "object": "list", "type": "property_item", "property_item": { "object": "property_item", "id": "title", "type": "title" }, "results": [ { "type": "text", "text": { "content": "季度规划", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "季度规划", "href": null } ], "next_cursor": null, "has_more": false } ```

Get block **必需参数**: block_id **可能的错误响应:** - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "block_id": "88888888-8888-4888-8888-888888888888" } ``` **响应示例:** ```json { "object": "block", "id": "88888888-8888-4888-8888-888888888888", "parent": { "type": "page_id", "page_id": "11111111-1111-4111-8111-111111111111" }, "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "has_children": false, "in_trash": false, "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "这里是一段正文内容。", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "这里是一段正文内容。", "href": null } ], "color": "default" } } ```

Update block **必需参数**: block_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "这里是一段更新后的正文内容。", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "这里是一段更新后的正文内容。", "href": null } ] } } ``` **响应示例:** ```json { "object": "block", "id": "88888888-8888-4888-8888-888888888888", "parent": { "type": "page_id", "page_id": "11111111-1111-4111-8111-111111111111" }, "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "has_children": false, "in_trash": false, "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "这里是一段更新后的正文内容。", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "这里是一段更新后的正文内容。", "href": null } ], "color": "default" } } ```

Get block children **可选参数**: start_cursor, page_size **必需参数**: block_id **可能的错误响应:** - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "block_id": "99999999-9999-4999-8999-999999999999", "start_cursor": "0", "page_size": 20 } ``` **响应示例:** ```json { "object": "list", "results": [ { "object": "block", "id": "12121212-1212-4212-8212-121212121212", "parent": { "type": "page_id", "page_id": "11111111-1111-4111-8111-111111111111" }, "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "has_children": false, "in_trash": false, "type": "heading_2", "heading_2": { "rich_text": [ { "type": "text", "text": { "content": "本周重点", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "本周重点", "href": null } ], "color": "default", "is_toggleable": false } }, { "object": "block", "id": "13131313-1313-4313-8313-131313131313", "parent": { "type": "page_id", "page_id": "11111111-1111-4111-8111-111111111111" }, "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "has_children": false, "in_trash": false, "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "text": { "content": "跟进接口联调与回归测试。", "link": null ... ```

Append block children **必需参数**: block_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "children": [ { "object": "block", "type": "to_do", "to_do": { "rich_text": [ { "type": "text", "text": { "content": "补充监控告警", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "补充监控告警", "href": null } ], "checked": false } } ], "after": "12121212-1212-4212-8212-121212121212" } ``` **响应示例:** ```json { "object": "list", "results": [ { "object": "block", "id": "14141414-1414-4414-8414-141414141414", "parent": { "type": "page_id", "page_id": "11111111-1111-4111-8111-111111111111" }, "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "has_children": false, "in_trash": false, "type": "to_do", "to_do": { "rich_text": [ { "type": "text", "text": { "content": "补充监控告警", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "补充监控告警", "href": null } ], "checked": false, "color": "default" } } ], "next_cursor": null, "has_more": false } ```

Create database **参数说明:** - `parent` (可选): 如果不提供，将默认创建在当前认证空间根目录 - `parent` 传参时只能是 `{ "page_id": "..." }`，不要附带 `type` 字段 - `properties` (必需): 数据库属性定义，必须包含至少一个 title 属性 - `is_inline` (可选): 是否创建为行内数据库 **注意**: 只有在你明确需要把数据库创建到指定页面下时，才传 `parent` **可选参数**: parent, title, description, icon, cover, is_inline **必需参数**: properties **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "title": [ { "type": "text", "text": { "content": "任务看板", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "任务看板", "href": null } ], "properties": { "Name": { "name": "Name", "type": "title" }, "Status": { "name": "Status", "type": "select", "select": { "options": [ { "name": "To Do", "color": "grey" }, { "name": "Doing", "color": "yellow" }, { "name": "Done", "color": "green" } ] } } } } ``` **响应示例:** ```json { "object": "database", "id": "66666666-6666-4666-8666-666666666666", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "title": [ { "type": "text", "text": { "content": "任务看板", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "任务看板", "href": null } ], "description": [ { "type": "text", "text": { "content": "用于演示 MCP 的数据库对象", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "用于演示 MCP 的数据库对象", "href": null } ], "icon": { "type": "emoji", "emoji": "🗂️" }, "cover": null, "parent": { "type": "workspace", "workspace": true }, "properties": { "Name": { "id": "title", "type": "title", "name": "Name", "title": {} }, "Status": { "id": "16161616-1616-4616-8616-161616161616", "type": "select", "name": "Status", "select": { "options": [ { "id": "17171717-1717-4717-8717-171717171717", "name": "To Do", "color": "grey" }, { "id": "18181818-1818-4818-8818-181818181818", "name": "Doing", "color": "yellow" }, { "id": "19191919-1919-4919-8919-191919191919", "name": "Done", "color": "green" } ] } } }, "in_trash": fals ... ```

Get database **必需参数**: database_id **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "database_id": "66666666-6666-4666-8666-666666666666" } ``` **响应示例:** ```json { "object": "database", "id": "66666666-6666-4666-8666-666666666666", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "title": [ { "type": "text", "text": { "content": "任务看板", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "任务看板", "href": null } ], "description": [ { "type": "text", "text": { "content": "用于演示 MCP 的数据库对象", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "用于演示 MCP 的数据库对象", "href": null } ], "icon": { "type": "emoji", "emoji": "🗂️" }, "cover": null, "parent": { "type": "workspace", "workspace": true }, "properties": { "Name": { "id": "title", "type": "title", "name": "Name", "title": {} }, "Status": { "id": "16161616-1616-4616-8616-161616161616", "type": "select", "name": "Status", "select": { "options": [ { "id": "17171717-1717-4717-8717-171717171717", "name": "To Do", "color": "grey" }, { "id": "18181818-1818-4818-8818-181818181818", "name": "Doing", "color": "yellow" }, { "id": "19191919-1919-4919-8919-191919191919", "name": "Done", "color": "green" } ] } } }, "in_trash": fals ... ```

Update database **必需参数**: database_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "title": [ { "type": "text", "text": { "content": "任务看板（新版）", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "任务看板（新版）", "href": null } ], "properties": { "Priority": { "name": "Priority", "type": "select", "select": { "options": [ { "name": "P0", "color": "red" }, { "name": "P1", "color": "orange" } ] } } } } ``` **响应示例:** ```json { "object": "database", "id": "66666666-6666-4666-8666-666666666666", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "title": [ { "type": "text", "text": { "content": "任务看板（新版）", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "任务看板（新版）", "href": null } ], "description": [ { "type": "text", "text": { "content": "用于演示 MCP 的数据库对象", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "用于演示 MCP 的数据库对象", "href": null } ], "icon": { "type": "emoji", "emoji": "🗂️" }, "cover": null, "parent": { "type": "workspace", "workspace": true }, "properties": { "Name": { "id": "title", "type": "title", "name": "Name", "title": {} }, "Status": { "id": "16161616-1616-4616-8616-161616161616", "type": "select", "name": "Status", "select": { "options": [ { "id": "17171717-1717-4717-8717-171717171717", "name": "To Do", "color": "grey" }, { "id": "18181818-1818-4818-8818-181818181818", "name": "Doing", "color": "yellow" }, { "id": "19191919-1919-4919-8919-191919191919", "name": "Done", "color": "green" } ] } } }, "in_tras ... ```

Query database **必需参数**: database_id, body **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "filter": { "property": "Status", "select": { "equals": "Doing" } }, "sorts": [ { "property": "Status", "direction": "ascending" } ], "page_size": 10 } ``` **响应示例:** ```json { "object": "list", "results": [ { "object": "page", "id": "77777777-7777-4777-8777-777777777777", "page_type": "page", "created_time": "2026-04-09T08:00:00.000Z", "last_edited_time": "2026-04-09T09:30:00.000Z", "created_by": { "object": "user", "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }, "last_edited_by": { "object": "user", "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc" }, "parent": { "type": "database_id", "database_id": "66666666-6666-4666-8666-666666666666" }, "in_trash": false, "icon": { "type": "emoji", "emoji": "📄" }, "cover": null, "properties": { "title": { "id": "title", "type": "title", "title": [ { "type": "text", "text": { "content": "完成 MCP 接入", "link": null }, "annotations": { "bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default" }, "plain_text": "完成 MCP 接入", "href": null } ] } }, "url": "https://buildin.ai/77777777-7777-4777-8777-777777777777" } ], "next_cursor": null, "has_more": false } ```

Mutate database schema and records atomically **数据库原子变更说明:** - 重命名已有字段时，先读取数据库并在 `properties` 中传真实属性 `id`；不要新增同名文本字段模拟重命名 - 新增记录使用 `create_records`；更新已有记录必须在 `update_records` 中明确传 `record_id` - 需要同时改 schema 和记录时放在同一次调用中；任一权限或校验失败都会使整笔事务不写入 **可选参数**: Idempotency-Key, properties, create_records, update_records **必需参数**: database_id **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 409: Conflict - 429: Rate limited **请求示例:** ```json { "properties": { "Name": { "id": "title", "name": "Name", "type": "title", "title": {} } }, "create_records": [ { "title": "New record" } ] } ```

Get page content as markdown **必需参数**: page_id **可能的错误响应:** - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "page_id": "22222222-2222-4222-8222-222222222222" } ``` **响应示例:** ```json { "object": "markdown", "page_id": "22222222-2222-4222-8222-222222222222", "markdown": "# 季度规划\n\n- 完成 API 联调\n- 编写发布说明", "last_edited_time": "2026-04-09T09:30:00.000Z" } ```

Get file upload URL **上传说明:** - `content_length` 必须是精确字节数；本地文件请用 `stat -f%z <path>` 获取，不要用 `ls -lh` 的近似大小 - 拿到 `upload_url` 后，用 PUT 上传文件，并使用响应里的 `headers`；不要手动设置 `Content-Length`，让 HTTP 客户端按实际文件计算 - 只有 PUT 返回 2xx 才表示上传成功；连接 reset、timeout 或只看到 “upload completely sent off” 都不能当作成功 - 创建文件块时传 `file.oss_name`，不要把兼容字段 `file_url` 当作 `external.url` **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "filename": "roadmap.pdf", "content_type": "application/pdf", "content_length": 1048576, "parent": { "type": "page_id", "page_id": "22222222-2222-4222-8222-222222222222" } } ``` **响应示例:** ```json { "object": "file_upload", "id": "upload_15151515-1515-4515-8515-151515151515", "upload_url": "https://buildin-bucket.s3.us-west-1.amazonaws.com/s3/15151515-1515-4515-8515-151515151515/roadmap.pdf", "oss_name": "s3/15151515-1515-4515-8515-151515151515/roadmap.pdf", "file_url": "https://cdn2.buildin.ai/s3/15151515-1515-4515-8515-151515151515/roadmap.pdf", "size": 1048576, "expiry_time": "2026-04-09T09:30:00.000Z", "method": "PUT", "headers": { "Content-Type": "application/pdf" } } ```

Get file or image download URL **可选参数**: filename, img_process, x_oss_process **必需参数**: block_id, oss_name **可能的错误响应:** - 400: Validation or request format error - 401: Authentication failed - 403: Permission denied - 404: Resource not found - 429: Rate limited **请求示例:** ```json { "block_id": "88888888-8888-4888-8888-888888888888", "oss_name": "oss/15151515-1515-4515-8515-151515151515/roadmap.pdf", "filename": "roadmap.pdf", "img_process": "imageMogr2/thumbnail/1200x", "x_oss_process": "imageMogr2/format/webp" } ``` **响应示例:** ```json { "object": "file", "name": "roadmap.pdf", "type": "file", "file": { "url": "https://cdn.flowus.cn/oss/15151515-1515-4515-8515-151515151515/roadmap.pdf?time=1775725200&token=example&role=free", "expiry_time": "2026-04-09T09:30:00.000Z", "oss_name": "oss/15151515-1515-4515-8515-151515151515/roadmap.pdf" }, "ttl": 1800 } ```