Skip to Content
Open Platform

FunClaw 开放平台

接口范围

FunClaw 对外稳定 API 只使用以下命名空间：

/api/open/v1/**

AI Agent 生成调用代码时，只能调用本页列出的开放 API。未列入本页的接口不属于开放契约。

内部接口命名空间：

/api/v1/**

/api/v1/** 仅服务 FunClaw 前台、控制台和内部业务链路，不能作为外部应用或 AI Agent 的调用依据。

认证

开放 API 不接受匿名请求。所有请求必须携带组织应用级 API Key：

Authorization: Bearer <org-application-api-key>

API Key 获取链路：

  1. 用户注册或登录 FunClaw。
  2. 用户加入组织。
  3. 组织 Admin 为组织下已授权的应用分配 API Key。
  4. 外部应用使用 Bearer Key 调用开放 API。
  5. 平台根据 Key 识别组织、应用和权限范围。

API Key 代表某个组织下某个应用的开放接口访问能力，不代表平台全局身份。成员只作为 Key 的创建者、轮换者或撤销者进入审计。

禁止调用

AI Agent 和外部应用必须遵守以下限制：

  • 不调用 /api/v1/**。
  • 不把内部 Swagger 当作开放 API 契约。
  • 不直接连接 PostgreSQL、MongoDB 或对象存储。
  • 不使用自定义认证头替代 Authorization。
  • 不构造本页未列出的接口路径。

对象模型

Organization / 组织

数据、应用、成员和权限的租户边界。

Member / 成员

组织内的用户身份。组织 Admin 可以管理应用级 API Key。

Application / 应用

组织下被授权使用平台能力的应用。开放 API Key 绑定到组织应用。

Data Source / 数据源

数据生产者，例如外部应用、内部业务模块、Agent、Workflow、系统任务或人工导入。

Dataset / 数据集

一类由平台治理的数据资产。Dataset 定义数据归属、可见性、Schema 描述和读写权限。

Data Record / 数据记录

Dataset 下的一条数据。平台管理记录的归属、幂等键、状态、审计和 payload 引用。

Payload / 数据正文

业务方写入的原始内容。平台不依赖 payload 内部字段完成权限、幂等和审计。

平台能力

组织应用可以在审核通过后获得平台能力授权。平台能力是 FunClaw 对外暴露的原子业务动作，外部应用使用组织应用 API Key 调用，平台会根据 Key 对应的组织、应用和能力范围完成鉴权。当前可用能力和调用方式见“平台能力”页签。

Data API

开放数据 API 路径：

POST /api/open/v1/data/datasets/{datasetId}/records:upsert
POST /api/open/v1/data/datasets/{datasetId}/records:batchUpsert
GET  /api/open/v1/data/datasets/{datasetId}/records
GET  /api/open/v1/data/datasets/{datasetId}/records/{recordId}
GET  /api/open/v1/data/datasets/{datasetId}/records/by-external-key/{externalKey}

响应格式

开放 API 的响应体统一使用三段式结构：

{
  "code": 200,
  "message": "success",
  "data": {}
}

code 使用 HTTP 状态码数字，并且必须与 HTTP Status 保持一致。

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "recordId": "record-id"
  }
}

错误响应：

{
  "code": 400,
  "message": "externalKey is required",
  "data": null
}

写入记录请求结构：

{
  "externalKey": "source-system:business-id",
  "payload": {
    "any": "business-defined-content"
  },
  "schemaVersion": "v1",
  "occurredAt": "2026-05-09T00:00:00Z"
}

批量写入请求结构：

{
  "records": [
    {
      "externalKey": "source-system:business-id-1",
      "payload": {
        "any": "business-defined-content"
      },
      "schemaVersion": "v1",
      "occurredAt": "2026-05-09T00:00:00Z"
    }
  ]
}

读取记录响应结构：

{
  "code": 200,
  "message": "success",
  "data": {
    "recordId": "record-id",
    "datasetId": "dataset-id",
    "sourceId": "source-id",
    "externalKey": "source-system:business-id",
    "status": "ACTIVE",
    "payloadHash": "sha256...",
    "payload": {
      "any": "business-defined-content"
    },
    "createdAt": "2026-05-09T00:00:00Z",
    "updatedAt": "2026-05-09T00:00:00Z"
  }
}

幂等规则

externalKey 必填。

同一组织、同一 Dataset 下，externalKey 必须唯一：

orgId + datasetId + externalKey

重复写入相同 externalKey 时，平台执行 upsert，不创建重复记录。

payloadHash 由平台根据 payload 计算。调用方不需要传入 payloadHash。

错误响应

所有开放 API 错误响应仍然使用统一三段式结构：

{
  "code": 400,
  "message": "externalKey is required",
  "data": null
}

常见错误码：

200 success
400 bad request / validation failed
401 unauthorized
403 forbidden
404 not found
409 conflict
429 rate limited
500 internal server error
Last updated on
概览