API 参考: 应用 (Apps)

应用管理端点。创建、更新、删除和发布应用。

创建应用

上传应用定义。如果 app.id 已存在，自动执行更新。

POST /v1/apps

权限要求： write

请求体

字段	类型	必填	说明
app	object	是	应用基本信息
app.id	string	是	应用唯一标识符
app.name	string	是	英文名称
app.nameZh	string	否	中文名称
app.domain	string	否	所属领域
app.subsystem	string	否	子系统类型
serviceConfig	object	否	服务配置（凭据、URL等）
dashboard	object	否	仪表盘组件定义
toolPacks	string[]	否	关联的工具包 ID 列表

请求示例

curl -X POST https://api.invoratec.cn/v1/apps \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "id": "my-erp",
      "name": "My ERP Connector",
      "nameZh": "我的ERP连接器",
      "domain": "operations",
      "subsystem": "ERP"
    },
    "serviceConfig": {
      "credentials": ["username", "password"]
    },
    "dashboard": {},
    "toolPacks": ["erp-inventory-pack"]
  }'

响应 (201 Created)

{
  "_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "appId": "my-erp",
  "developerId": "user_123",
  "definition": {
    "app": { "id": "my-erp", "name": "My ERP Connector", ... },
    "serviceConfig": { ... },
    "dashboard": { ... },
    "toolPacks": ["erp-inventory-pack"]
  },
  "status": "draft",
  "createdAt": "2026-04-12T08:00:00.000Z",
  "updatedAt": "2026-04-12T08:00:00.000Z"
}

如果应用已存在（更新），响应中额外包含 "updated": true。

错误

状态码	说明
400	app.id 或 app.name 缺失
401	API Key 无效
403	缺少 write 权限

---

列出我的应用

GET /v1/apps

请求示例

curl https://api.invoratec.cn/v1/apps \
  -H "X-API-Key: claw_xxxx"

响应

{
  "apps": [
    {
      "_id": "665f...",
      "appId": "my-erp",
      "definition": { ... },
      "status": "draft",
      "updatedAt": "2026-04-12T08:00:00.000Z"
    }
  ],
  "total": 1
}

---

获取应用详情

GET /v1/apps/{id}

路径参数

参数	类型	说明
id	string	应用 appId

请求示例

curl https://api.invoratec.cn/v1/apps/my-erp \
  -H "X-API-Key: claw_xxxx"

响应

返回完整的应用文档，包含 definition 中的所有字段。

错误

状态码	说明
404	应用不存在

---

更新应用

PUT /v1/apps/{id}

权限要求： write

路径参数

参数	类型	说明
id	string	应用 appId

请求体

可以更新 app、serviceConfig、dashboard、toolPacks 中的任意字段，也可以更新 status。

请求示例

curl -X PUT https://api.invoratec.cn/v1/apps/my-erp \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "id": "my-erp",
      "name": "My ERP Connector v2"
    }
  }'

响应

返回更新后的完整应用文档。

错误

状态码	说明
403	缺少 write 权限
404	应用不存在

---

删除应用

DELETE /v1/apps/{id}

权限要求： write

路径参数

参数	类型	说明
id	string	应用 appId

请求示例

curl -X DELETE https://api.invoratec.cn/v1/apps/my-erp \
  -H "X-API-Key: claw_xxxx"

响应

{ "success": true }

---

发布应用到市场

将应用状态从 draft 变为 published，使其在应用市场中可见。

POST /v1/apps/{id}/publish

权限要求： write

路径参数

参数	类型	说明
id	string	应用 appId

请求示例

curl -X POST https://api.invoratec.cn/v1/apps/my-erp/publish \
  -H "X-API-Key: claw_xxxx"

响应

{
  "success": true,
  "status": "published"
}

错误

状态码	说明
403	缺少 write 权限
404	应用不存在