请求方式	POST
请求地址	`https://api.coze.cn/v1/databases`
权限	说明如需在工作空间资源库中创建扣子数据库，需开通`Workspace.createDatabase`权限。如需在低代码应用中创建扣子数据库，需同时开通`Workspace.createDatabase`和`Project.createDatabase`权限。详细信息参考鉴权方式。
接口说明	在指定工作空间下创建一个新的扣子数据库，支持定义字段、索引、读写模式等。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	请求正文的方式。

Body

参数	类型	是否必选	示例	说明
workspace_id	String	必选	749820488328041****	工作空间 ID。你可以通过调用查看工作空间列表接口获取。
app_id	String	可选	761257394935226****	低代码应用 ID。进入低代码应用编排页面，页面 URL 中 `project-ide` 参数后的数字即为应用 ID。例如`https://www.coze.cn/space/749820488328041**/project-ide/761257394935226`，应用 ID 为 `761257394935226**`。说明如果指定`app_id`，将在对应低代码应用内创建扣子数据库。如果未指定`app_id`，默认在 `workspace_id` 对应的工作空间下的资源库中创建扣子数据库。
table_name	String	必选	user_info	数据表名称。
table_desc	String	可选	存储用户基本信息的数据库	数据表描述。
fields	Array of OpenFieldItem	必选	[{“name”: “user_id”, “desc”: “姓名”, “type”: “string”, “is_required”: true},{“name”:“level”,“desc”:“等级”,“type”:“integer”,“is_required”:true}]	字段信息列表。
rw_mode	String	必选	unlimited_read_write	设置数据表查询模式。 `limited_read_write`（单用户模式）：开发者和用户都可以添加记录，但仅能读/修改/删除自己创建的来自同渠道的数据。 `unlimited_read_write`（多用户模式）：开发者和用户都可读/写/修改/删除表中来自同渠道的任何数据，由业务逻辑控制读写权限。
indexs	Array of OpenIndexItem	可选	[{“index_name”: “idx_level”, “field_names”: [“level”]}]	索引列表（目前只支持单字段的索引）。
connector_rw_config	Array of OpenConnectorInfo	可选	[{“connector_id”:“10000011”,“connector_rw_mode”:“online”}]	为渠道（通过 `connector_id` 标识）配置读写模式，实现对数据访问规则的精细化管控。
connector_read_mode	String	可选	independent_connector	配置渠道模式。 independent_connector（渠道隔离，默认值）：各个不同渠道的数据相互隔离，对应渠道仅可访问对应渠道的数据。 shared_coze_connectors（扣子站内渠道共享，其他渠道隔离）：扣子编程调试台、商店和模板渠道的测试数据共享；扣子商店和模板渠道的线上数据共享。其他不同渠道之间数据相互隔离，对应渠道仅可访问对应渠道的数据。 shared_all_connectors（渠道共享）：不同渠道之间的数据共享，支持跨渠道访问数据。
icon_file_id	String	可选	761258606549234****	数据库图标文件 ID。未指定文件 ID 时，扣子编程默认为数据库指定一个头像。如需使用自定义图标文件，应先通过上传文件接口上传本地文件，从接口响应中获取文件 ID。

OpenFieldItem

参数	类型	是否必选	示例	说明
type	String	可选	string	存储字段的数据类型，大语言模型会按照选择的数据类型对用户输入的内容进行处理和保存。目前支持的数据类型包括 String、Integer、Time、Number、Boolean。
is_required	Boolean	可选	true	存储字段是否为必要字段。枚举值如下： `true`：必要字段。 `false`：非必要字段。
is_system_field	Boolean	可选	false	标识字段是否为系统字段。系统默认字段为 `true`，用户自定义字段均为 `false`。
is_primary_key	Boolean	可选	false	标识字段是否为表主键。仅系统生成的 `id` 字段为 `true`，用户自定义字段均为 `false`。
name	String	可选	name	存储字段名称，只能包含小写字母、数字、下划线（`_`）、必须以英文字母开头，最多 64 字符，不支持使用数据库关键词或保留字作为字段名称。扣子编程关键词和保留字列表，请参考扣子数据库关键词和保留字有哪些？。
desc	String	可选	用户姓名	存储字段的补充说明，可以是对存储字段的自然语言描述、示例数据，也可以是格式说明等。

OpenIndexItem

参数	类型	是否必选	示例	说明
index_name	String	可选	idx_level	索引的名称，需确保唯一性。如果未传入该字段，服务端将按照一定规则自动生成。
field_names	Array of String	可选	[“level”]	当前仅支持单字段索引，即数组中只能包含一个字段名。
comment	String	可选	等级	索引描述。

OpenConnectorInfo

参数	类型	是否必选	示例	说明
connector_id	String	可选	10000011	渠道 ID。扣子编程的渠道 ID 包括： 1024（默认值）：API 渠道。 999：Chat SDK。 10000122：扣子商店。 10000113：微信客服。 10000120：微信服务号。 10000121：微信订阅号。 10000126：抖音小程序。 10000127：微信小程序。 10000011：飞书。 998：WebSDK。自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在账号设置 > 发布渠道 > 企业自定义渠道管理页面查看渠道 ID。
connector_rw_mode	String	可选	online	渠道读写配置。取值如下： `draft`：读写测试数据。 `online`：读写线上数据。说明扣子站内渠道（编程调试台、商店、模板渠道）默认`draft`，其他渠道默认`online`。

参数

类型

是否必选

示例

说明

connector_id

String

可选

10000011

渠道 ID。扣子编程的渠道 ID 包括：

1024（默认值）：API 渠道。
999：Chat SDK。
10000122：扣子商店。
10000113：微信客服。
10000120：微信服务号。
10000121：微信订阅号。
10000126：抖音小程序。
10000127：微信小程序。
10000011：飞书。
998：WebSDK。
自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在账号设置 > 发布渠道 > 企业自定义渠道管理页面查看渠道 ID。

connector_rw_mode

String

可选

online

渠道读写配置。取值如下：

draft：读写测试数据。
online：读写线上数据。

说明

扣子站内渠道（编程调试台、商店、模板渠道）默认draft，其他渠道默认online。

返回参数

参数	类型	示例	说明
data	Object of OpenCreateDatabaseRet	{“database_id”:“761261440756196****”}	已创建的扣子数据库信息。
code	Long	0	调用状态码。 0 表示调用成功。其他值表示调用失败。你可以通过 msg 字段判断详细的错误原因。
msg	String	“”	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	{“logid”:“20260302191950FA84144C90A8818E****”}	包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。

OpenCreateDatabaseRet

参数	类型	示例	说明
database_id	String	761262627636433****	数据表 ID。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此`logid`及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

curl --location --request POST 'https://api.coze.cn/v1/databases' \
--header 'Authorization : Bearer pat_O****' \
--header 'Content-Type: application/json' \
--data-raw '{
    "workspace_id": "749820488328041****",
    "app_id": "761257394935226****",
    "icon_file_id": "761258606549234****",
    "table_name": "user_info",
    "table_desc": "存储用户基本信息的数据库",    
    "fields": [
      {"name": "user_id", "desc": "姓名", "type": "string", "is_required": true},
      {"name":"level","desc":"等级","type":"integer","is_required":true}
    ], 
    "rw_mode": "unlimited_read_write",       
    "indexs": [ 
        {
            "index_name": "idx_level",
            "field_names": [
                "level"  
            ],
            "comment": "等级"
        }
    ],
    "connector_rw_config": [
        {
            "connector_id": "10000011",
            "connector_rw_mode": "online"
        }
    ],
    "connector_read_mode": "independent_connector"
}'

返回示例

{
    "code": 0,
     "msg": "",
    "data": {
        "database_id": "761262627636433****"
    },   
    "detail": {
        "logid": "20260302200207F17DBC7387F656A3****"
    }
}

错误码

如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。

OpenCreateDatabaseRet