Skip to main content

企业专属市场 API

管理企业集合、Plugin、Skill、Connector、分类及内容下发策略。

通过企业专属市场 API,将团队的 Plugin、Skill 和 Connector 发布到组织集合,并管理可见范围、分类和下发策略。
组织需已开通企业专属市场能力,并使用该组织的 API Key。
调用前请阅读获取 API Key和约定与规范。

前置条件

  • Base URL:https://api.qoder.com。
  • 统一路径前缀:/v1/organizations/{organization_id}/apphub。
  • 请求头携带 Authorization: Bearer <api_key>;organization_id 必须为 API Key 所属组织。
  • JSON 请求使用 Content-Type: application/json;上传使用 multipart/form-data,由 HTTP 客户端生成 boundary。
  • 示例 ID 均为占位 UUID,请替换为当前组织的实际资源 ID。不同地域的组织、密钥和内容不能混用。
路径参数类型说明
organization_idstring所有接口必填,组织ID。
collection_idstring集合接口路径出现时必填,来自集合查询或创建响应的id。
extension_idstring内容接口路径出现时必填,来自内容查询或发布响应的id。
category_idstring分类接口路径出现时必填,来自分类查询或创建响应的id。

可见性与下发策略

集合的 visibility 决定成员是否能在市场看到集合;内容的 distribution 决定向哪些成员下发以及如何启用。强制启用和静默启用属于内容条目,不是集合属性。 指定群组时,先通过群组 API查询本组织的群组,使用响应中的群组 id 填写 targetGroupIds,不是成员 ID 或计费组 ID。 新上传或注册时省略 distribution,默认 scope=none、clientPolicy=configurable,不会自动全员下发。换包保留原下发策略。更新下发范围为 none 且省略 clientPolicy 时,保留原客户端策略。配置提交成功后,客户端通过既有同步机制获取更新。

分页与调用约定

  • 列表接口使用 maxResults(默认20,1–100)和 nextToken。最后一页明确返回 nextToken: "";空列表返回 []。
  • 下一页须沿用相同组织、路径、筛选参数和页大小,仅替换 nextToken。不要解析或自行构造游标;分页不保证快照一致性。
  • 查询、更新返回200,创建、发布及导入返回201,删除返回204且无响应体。
  • 拒绝未知字段、重复JSON字段及多个JSON值;JSON元数据最多64 KiB。文本长度限制按UTF-8字节计算。
  • Connector更新元信息或下发策略时,先获取详情,将 revision 作为 expectedRevision 传入;冲突返回409。Plugin和Skill不得传入该参数。
  • 响应丢失或超时后,先查询资源确认结果,再决定是否重试;尤其注意自动版本生成和覆盖导入。

数据模型

Collection

字段类型说明
idstring集合ID。
organizationIdstring所属组织ID。
namestring集合名称。
displayNamestring显示名称。
descriptionstring集合描述。
typestringplugin、skill、connector;创建后不可修改。
productsstring[]适用产品,例如["qoder"]。
visibilityVisibility市场可见范围。
createdAt / updatedAtstring创建/更新时间,RFC3339格式。

Visibility

字段类型说明
scopestringnone:全员不可见;all:全员可见;group:指定群组可见。
targetGroupIdsstring[]仅group时必填且非空,最多1000个本组织群组ID,不得重复;其他scope省略或传[]。

Distribution

字段类型说明
scopestringnone:不下发;all:全员;group:指定群组。
targetGroupIdsstring[]仅group时必填且非空,最多1000个本组织群组ID,不得重复;其他scope省略或传[]。
clientPolicystring / nullconfigurable:允许用户配置启停;force_enabled:可见且强制启用;silent_enabled:静默启用。scope非none时请求必填。历史内容无法映射到上述策略时,响应可为null。

Extension

字段类型说明
id / organizationId / collectionIdstring内容ID、组织ID及集合ID。
typestringplugin、skill或connector。
name / displayName / descriptionstring名称、显示名称和描述。
versionstring内容版本。
categoryIdstring / null分类ID;未指定分类时为null。
clientsstring[]适用产品,从集合获取。
statusstring内容状态,例如active、archived。
distributionDistribution下发范围和客户端启用策略。
fileHashstring包文件哈希;无包时可为空。
fileSizeinteger包大小,单位字节。
configConnectorConfig可公开的连接配置;无配置时省略。
revisioninteger仅Connector返回,更新时作为expectedRevision传入。
createdAt / updatedAtstringRFC3339时间。

Category

字段类型说明
id / organizationIdstring分类ID和组织ID。
namestring分类名称。
sortOrderinteger排序值。
usageCountinteger引用该分类的内容数量。
isSystemboolean是否系统分类;uncategorized不可修改或删除。
createdAt / updatedAtstringRFC3339时间。

Changelog

字段类型说明
idstring日志ID。
actionstring变更动作,例如created、updated、scope_changed、status_changed、archived。
version / scope / statusstring变更记录中的版本、下发范围及状态。
changeNotestring变更说明。
operator.typestringuser或apiKey。
operator.idstring用户ID或组织API Key ID,不是API Key密钥本身。
operator.emailstring用户邮箱;不可用时省略。
createdAtstringRFC3339时间。

MarketplaceCandidate

字段类型说明
sourceTypestringqoder_plugin或qoder_skill。
sourceIdstring公共市场内容ID,用于导入请求。
name / displayName / description / versionstring公共内容的名称、显示名称、描述和版本。
statusstringimportable、confirm_required或not_importable。
reasonstring状态原因,例如same_collection_name_conflict或other_collection_name_conflict;无原因时为空字符串。
existingExtensionIdstring / null冲突的企业内容ID;无冲突时为null。

ConnectorConfig

字段类型说明
serversobject[]必填,必须且只能包含一个server。
servers[].namestring必填,去除首尾空白后不能为空,不允许控制字符。
servers[].protocolstring必填,支持streamable_http、sse、stdio。
servers[].urlstringstreamable_http或sse必填,必须为HTTPS URL,不能含用户信息、查询参数(包括空的?)或片段。stdio不得填写。
servers[].commandstringstdio必填,不能仅包含空白或含换行、空字符;远程协议不得填写。
servers[].argsstring[]仅stdio可选,命令参数;远程协议不得配置。
servers[].envobject仅stdio可选,环境变量的值为字符串,不得包含凭据;远程协议不得配置。
servers[].enabledboolean可选,默认true。
servers[].runtimeKindstring可选,仅支持client_direct,默认client_direct。
servers[].descriptionstring描述,可选。

Download

字段类型说明
extensionId / versionstring企业内容ID和版本。
downloadUrlstring短期下载URL。
expiresAtstringURL过期时间,RFC3339。
fileHashstring包文件哈希。
fileSizeinteger包大小,单位字节。

ImportResult

字段类型说明
extensionIdstring导入后企业内容ID;需要完整内容时再获取详情。
sourceIdstring公共市场源内容ID。
name / versionstring导入内容名称和版本。
未提供的时间可能返回空字符串。ConnectorConfig仅接受表中列出的连接字段;所选协议、URL及运行方式需符合当前产品的连接配置规则,不接受OAuth凭据或认证配置。

API 参考

接口方法相对路径
查询集合列表GET/extension-collections
获取集合详情GET/extension-collections/{collection_id}
创建集合POST/extension-collections
更新集合PUT/extension-collections/{collection_id}
删除集合DELETE/extension-collections/{collection_id}
查询内容列表GET/extensions
获取内容详情GET/extensions/{extension_id}
上传并发布到集合POST/extension-collections/{collection_id}/extensions
更新内容包PUT/extensions/{extension_id}/package
更新内容元信息PUT/extensions/{extension_id}/metadata
修改内容下发策略PUT/extensions/{extension_id}/distribution
删除内容DELETE/extensions/{extension_id}
查询内容变更日志GET/extensions/{extension_id}/changelogs
获取内容下载地址GET/extensions/{extension_id}/download
查询分类列表GET/extension-categories
获取分类详情GET/extension-categories/{category_id}
创建分类POST/extension-categories
更新分类PUT/extension-categories/{category_id}
删除分类DELETE/extension-categories/{category_id}
批量更新分类PUT/extension-categories
查询可导入的公共市场内容GET/extension-collections/{collection_id}/marketplace-items
导入公共市场内容POST/extension-collections/{collection_id}/imports
注册ConnectorPOST/extension-collections/{collection_id}/connectors

1. 查询集合列表

GET /v1/organizations/{organization_id}/apphub/extension-collections

查询参数

参数类型必填说明
keywordstring否搜索关键词。
typestring否内容类型:plugin、skill、connector。
productstring否适用产品:qoder。
visibilityScopestring否可见范围:none、all、group。
maxResultsinteger否每页数量,1–100,默认20。
nextTokenstring否上一页返回的游标;第一页省略。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections?maxResults=20" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "collections": [
    {
      "id": "32345678-1234-4234-8234-123456789abc",
      "organizationId": "12345678-1234-4234-8234-123456789abc",
      "name": "team-skills",
      "displayName": "Team Skills",
      "description": "Shared team skills",
      "type": "skill",
      "products": [
        "qoder"
      ],
      "visibility": {
        "scope": "all",
        "targetGroupIds": []
      },
      "createdAt": "2026-11-11T08:00:00Z",
      "updatedAt": "2026-11-11T08:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

2. 获取集合详情

GET /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id}

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "id": "32345678-1234-4234-8234-123456789abc",
  "organizationId": "12345678-1234-4234-8234-123456789abc",
  "name": "team-skills",
  "displayName": "Team Skills",
  "description": "Shared team skills",
  "type": "skill",
  "products": [
    "qoder"
  ],
  "visibility": {
    "scope": "all",
    "targetGroupIds": []
  },
  "createdAt": "2026-11-11T08:00:00Z",
  "updatedAt": "2026-11-11T08:00:00Z"
}

3. 创建集合

POST /v1/organizations/{organization_id}/apphub/extension-collections

请求参数

参数类型必填说明
namestring是名称,不可为空,最多128个UTF-8字节。
displayNamestring否显示名称,最多256个UTF-8字节。
descriptionstring否描述,最多2048个UTF-8字节。
typestring是plugin、skill或connector;创建后不可修改。
productsstring[]是适用产品,传["qoder"];创建后不能通过本接口修改。
visibilityobject是集合市场可见范围,见 Visibility。

请求体示例

{
  "name": "team-skills",
  "displayName": "Team Skills",
  "description": "Shared team skills",
  "type": "skill",
  "products": [
    "qoder"
  ],
  "visibility": {
    "scope": "all",
    "targetGroupIds": []
  }
}

请求示例

curl --request POST \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"team-skills","displayName":"Team Skills","description":"Shared team skills","type":"skill","products":["qoder"],"visibility":{"scope":"all","targetGroupIds":[]}}'

成功响应 (201 Created)

{
  "collection": {
    "id": "32345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "name": "team-skills",
    "displayName": "Team Skills",
    "description": "Shared team skills",
    "type": "skill",
    "products": [
      "qoder"
    ],
    "visibility": {
      "scope": "all",
      "targetGroupIds": []
    },
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

4. 更新集合

PUT /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id} 至少提供一个字段;省略的字段保持原值。不能修改type或products。

请求参数

参数类型必填说明
namestring否非空,最多128个UTF-8字节。
displayNamestring否最多256个UTF-8字节。
descriptionstring否最多2048个UTF-8字节。
visibilityobject否新的市场可见范围,见 Visibility。

请求体示例

{
  "displayName": "Engineering Skills"
}

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"displayName":"Engineering Skills"}'

成功响应 (200 OK)

{
  "collection": {
    "id": "32345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "name": "team-skills",
    "displayName": "Engineering Skills",
    "description": "Shared team skills",
    "type": "skill",
    "products": [
      "qoder"
    ],
    "visibility": {
      "scope": "all",
      "targetGroupIds": []
    },
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

5. 删除集合

DELETE /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id} 仅支持删除空集合,非空集合返回409。

请求示例

curl --request DELETE \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (204 No Content)

无响应体。

6. 查询内容列表

GET /v1/organizations/{organization_id}/apphub/extensions

查询参数

参数类型必填说明
collectionIdstring否按集合ID筛选。
keywordstring否搜索关键词。
typestring否plugin、skill、connector。
statusstring否内容状态:active或archived。
scopestring否下发范围:none、all、group。
containsstring否包内扩展类型:hooks、skills、rules、mcp、agents、commands;多个值重复传入,例如contains=skills&contains=commands。
maxResultsinteger否每页数量,1–100,默认20。
nextTokenstring否上一页返回的游标;第一页省略。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions?maxResults=20" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "extensions": [
    {
      "id": "42345678-1234-4234-8234-123456789abc",
      "organizationId": "12345678-1234-4234-8234-123456789abc",
      "collectionId": "32345678-1234-4234-8234-123456789abc",
      "type": "skill",
      "name": "code-review",
      "displayName": "Code Review",
      "description": "Review code changes",
      "version": "1.0.0",
      "categoryId": null,
      "clients": [
        "qoder"
      ],
      "status": "active",
      "distribution": {
        "scope": "none",
        "targetGroupIds": [],
        "clientPolicy": "configurable"
      },
      "fileHash": "example-file-hash",
      "fileSize": 1024,
      "createdAt": "2026-11-11T08:00:00Z",
      "updatedAt": "2026-11-11T08:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

7. 获取内容详情

GET /v1/organizations/{organization_id}/apphub/extensions/{extension_id}

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "id": "42345678-1234-4234-8234-123456789abc",
  "organizationId": "12345678-1234-4234-8234-123456789abc",
  "collectionId": "32345678-1234-4234-8234-123456789abc",
  "type": "skill",
  "name": "code-review",
  "displayName": "Code Review",
  "description": "Review code changes",
  "version": "1.0.0",
  "categoryId": null,
  "clients": [
    "qoder"
  ],
  "status": "active",
  "distribution": {
    "scope": "none",
    "targetGroupIds": [],
    "clientPolicy": "configurable"
  },
  "fileHash": "example-file-hash",
  "fileSize": 1024,
  "createdAt": "2026-11-11T08:00:00Z",
  "updatedAt": "2026-11-11T08:00:00Z"
}

8. 上传并发布到集合

POST /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id}/extensions 每次仅允许一个file part和一个metadata part。目标集合类型必须与包匹配;Connector使用JSON注册接口。无需单独申请上传地址或上传到对象存储。

请求参数

file 和 metadata 为 multipart 字段;其余字段放在 metadata JSON 内,不是额外的 part。
参数类型必填说明
filefile是一个Plugin或Skill ZIP,最大50 MiB。
metadataobject是JSON part,Content-Type必须为application/json;无参数时传{}。支持下列metadata字段。
versionstring否仅Skill可指定版本;省略由服务生成。Plugin版本来自包manifest,不可覆盖。
categoryIdstring否企业分类ID,省略时不指定分类。
distributionobject否下发范围及客户端策略;省略时为none/configurable,见 Distribution。
changeNotestring否变更说明,最多1024个UTF-8字节。

请求示例

curl --request POST \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc/extensions" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --form "file=@skill.zip;type=application/zip" \
  --form 'metadata={};type=application/json'

成功响应 (201 Created)

{
  "extension": {
    "id": "42345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "collectionId": "32345678-1234-4234-8234-123456789abc",
    "type": "skill",
    "name": "code-review",
    "displayName": "Code Review",
    "description": "Review code changes",
    "version": "1.0.0",
    "categoryId": null,
    "clients": [
      "qoder"
    ],
    "status": "active",
    "distribution": {
      "scope": "none",
      "targetGroupIds": [],
      "clientPolicy": "configurable"
    },
    "fileHash": "example-file-hash",
    "fileSize": 1024,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

9. 更新内容包

PUT /v1/organizations/{organization_id}/apphub/extensions/{extension_id}/package 适用于Plugin和Skill。保留内容ID、集合、分类及下发策略;metadata不能传categoryId或distribution。以下示例假设Skill当前版本为1.0.0,省略version后升级为2.0.0。

请求参数

file 和 metadata 为 multipart 字段;其余字段放在 metadata JSON 内,不是额外的 part。
参数类型必填说明
filefile是一个替换ZIP,最大50 MiB。
metadataobject是application/json part,支持version、changeNote;无参数时传{}。
versionstring否仅Skill可指定,必须为严格大于当前版本的语义化版本。省略时主版本加1,次版本和修订版本归零,例如1.0.0变为2.0.0。Plugin版本来自包manifest,也必须严格大于当前版本,不可用metadata覆盖。
changeNotestring否变更说明,最多1024个UTF-8字节。

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc/package" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --form "file=@skill.zip;type=application/zip" \
  --form 'metadata={};type=application/json'

成功响应 (200 OK)

{
  "extension": {
    "id": "42345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "collectionId": "32345678-1234-4234-8234-123456789abc",
    "type": "skill",
    "name": "code-review",
    "displayName": "Code Review",
    "description": "Review code changes",
    "version": "2.0.0",
    "categoryId": null,
    "clients": [
      "qoder"
    ],
    "status": "active",
    "distribution": {
      "scope": "none",
      "targetGroupIds": [],
      "clientPolicy": "configurable"
    },
    "fileHash": "example-file-hash",
    "fileSize": 1024,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

10. 更新内容元信息

PUT /v1/organizations/{organization_id}/apphub/extensions/{extension_id}/metadata 至少提供displayName、description、categoryId或config之一。更新Connector时还必须传expectedRevision。

请求参数

参数类型必填说明
displayNamestring否显示名称。
descriptionstring否描述。
categoryIdstring / null否分类ID;null清除分类;省略保留原分类。
configobject否仅Connector支持,见 ConnectorConfig。
expectedRevisioninteger否Connector更新必填,取详情中的revision且至少为1;Plugin和Skill不得传入。
changeNotestring否变更说明,最多1024个UTF-8字节。

请求体示例

{
  "description": "Updated review instructions"
}

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc/metadata" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"description":"Updated review instructions"}'

成功响应 (200 OK)

{
  "extension": {
    "id": "42345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "collectionId": "32345678-1234-4234-8234-123456789abc",
    "type": "skill",
    "name": "code-review",
    "displayName": "Code Review",
    "description": "Updated review instructions",
    "version": "1.0.0",
    "categoryId": null,
    "clients": [
      "qoder"
    ],
    "status": "active",
    "distribution": {
      "scope": "none",
      "targetGroupIds": [],
      "clientPolicy": "configurable"
    },
    "fileHash": "example-file-hash",
    "fileSize": 1024,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

11. 修改内容下发策略

PUT /v1/organizations/{organization_id}/apphub/extensions/{extension_id}/distribution

请求参数

参数类型必填说明
scopestring是none、all、group。
targetGroupIdsstring[]否仅scope=group时必填,最多1000个不重复的本组织群组ID。
clientPolicystring否scope非none时必填;configurable、force_enabled或silent_enabled。scope=none且省略时保留原策略。
expectedRevisioninteger否Connector更新必填,取详情中的revision且至少为1;Plugin和Skill不得传入。
changeNotestring否变更说明,最多1024个UTF-8字节。

请求体示例

{
  "scope": "group",
  "targetGroupIds": [
    "62345678-1234-4234-8234-123456789abc"
  ],
  "clientPolicy": "force_enabled"
}

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc/distribution" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"scope":"group","targetGroupIds":["62345678-1234-4234-8234-123456789abc"],"clientPolicy":"force_enabled"}'

成功响应 (200 OK)

{
  "extension": {
    "id": "42345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "collectionId": "32345678-1234-4234-8234-123456789abc",
    "type": "skill",
    "name": "code-review",
    "displayName": "Code Review",
    "description": "Review code changes",
    "version": "1.0.0",
    "categoryId": null,
    "clients": [
      "qoder"
    ],
    "status": "active",
    "distribution": {
      "scope": "group",
      "targetGroupIds": [
        "62345678-1234-4234-8234-123456789abc"
      ],
      "clientPolicy": "force_enabled"
    },
    "fileHash": "example-file-hash",
    "fileSize": 1024,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

12. 删除内容

DELETE /v1/organizations/{organization_id}/apphub/extensions/{extension_id} 移除企业内容并执行相关企业包清理,不承诺可恢复。不会删除公共市场的源作品。

请求示例

curl --request DELETE \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (204 No Content)

无响应体。

13. 查询内容变更日志

GET /v1/organizations/{organization_id}/apphub/extensions/{extension_id}/changelogs

查询参数

参数类型必填说明
maxResultsinteger否每页数量,1–100,默认20。
nextTokenstring否上一页返回的游标;第一页省略。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc/changelogs?maxResults=20" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "changelogs": [
    {
      "id": "72345678-1234-4234-8234-123456789abc",
      "action": "created",
      "version": "1.0.0",
      "scope": "none",
      "status": "active",
      "changeNote": "Initial release",
      "operator": {
        "type": "apiKey",
        "id": "22345678-1234-4234-8234-123456789abc"
      },
      "createdAt": "2026-11-11T08:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

14. 获取内容下载地址

GET /v1/organizations/{organization_id}/apphub/extensions/{extension_id}/download 仅Plugin和Skill支持;Skill返回原始Skill ZIP。下载地址短期有效,响应包含Cache-Control: no-store,请勿缓存或公开转发。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extensions/42345678-1234-4234-8234-123456789abc/download" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "extensionId": "42345678-1234-4234-8234-123456789abc",
  "version": "1.0.0",
  "downloadUrl": "https://example.com/package.zip?signature=example",
  "expiresAt": "2026-11-11T08:10:00Z",
  "fileHash": "example-file-hash",
  "fileSize": 1024
}

15. 查询分类列表

GET /v1/organizations/{organization_id}/apphub/extension-categories

查询参数

参数类型必填说明
keywordstring否搜索关键词。
maxResultsinteger否每页数量,1–100,默认20。
nextTokenstring否上一页返回的游标;第一页省略。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories?maxResults=20" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "categories": [
    {
      "id": "52345678-1234-4234-8234-123456789abc",
      "organizationId": "12345678-1234-4234-8234-123456789abc",
      "name": "Engineering",
      "sortOrder": 10,
      "usageCount": 0,
      "isSystem": false,
      "createdAt": "2026-11-11T08:00:00Z",
      "updatedAt": "2026-11-11T08:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

16. 获取分类详情

GET /v1/organizations/{organization_id}/apphub/extension-categories/{category_id}

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories/52345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "id": "52345678-1234-4234-8234-123456789abc",
  "organizationId": "12345678-1234-4234-8234-123456789abc",
  "name": "Engineering",
  "sortOrder": 10,
  "usageCount": 0,
  "isSystem": false,
  "createdAt": "2026-11-11T08:00:00Z",
  "updatedAt": "2026-11-11T08:00:00Z"
}

17. 创建分类

POST /v1/organizations/{organization_id}/apphub/extension-categories

请求参数

参数类型必填说明
namestring是名称,不可为空,最多128个UTF-8字节。
sortOrderinteger否排序值(int32)。

请求体示例

{
  "name": "Engineering",
  "sortOrder": 10
}

请求示例

curl --request POST \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"Engineering","sortOrder":10}'

成功响应 (201 Created)

{
  "category": {
    "id": "52345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "name": "Engineering",
    "sortOrder": 10,
    "usageCount": 0,
    "isSystem": false,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

18. 更新分类

PUT /v1/organizations/{organization_id}/apphub/extension-categories/{category_id} 至少提供一个字段。系统分类uncategorized不可修改。

请求参数

参数类型必填说明
namestring否非空分类名称,最多128个UTF-8字节。
sortOrderinteger否排序值(int32)。

请求体示例

{
  "sortOrder": 20
}

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories/52345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"sortOrder":20}'

成功响应 (200 OK)

{
  "category": {
    "id": "52345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "name": "Engineering",
    "sortOrder": 20,
    "usageCount": 0,
    "isSystem": false,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z"
  }
}

19. 删除分类

DELETE /v1/organizations/{organization_id}/apphub/extension-categories/{category_id} 仍被内容引用时返回409;先调整内容分类再删除。系统分类uncategorized不可删除。

请求示例

curl --request DELETE \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories/52345678-1234-4234-8234-123456789abc" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (204 No Content)

无响应体。

20. 批量更新分类

PUT /v1/organizations/{organization_id}/apphub/extension-categories 批量操作仅用于分类管理,不支持批量上传ZIP。未传入的分类不会被删除。

请求参数

参数类型必填说明
itemsobject[]是1–1000项,ID不得重复;只修改传入项。
items[].idstring是分类ID,不得为uncategorized。
items[].namestring否非空,最多128个UTF-8字节;与sortOrder至少提供一个。
items[].sortOrderinteger否排序值(int32)。

请求体示例

{
  "items": [
    {
      "id": "52345678-1234-4234-8234-123456789abc",
      "sortOrder": 20
    }
  ]
}

请求示例

curl --request PUT \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-categories" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"items":[{"id":"52345678-1234-4234-8234-123456789abc","sortOrder":20}]}'

成功响应 (200 OK)

{
  "categories": [
    {
      "id": "52345678-1234-4234-8234-123456789abc",
      "organizationId": "12345678-1234-4234-8234-123456789abc",
      "name": "Engineering",
      "sortOrder": 20,
      "usageCount": 0,
      "isSystem": false,
      "createdAt": "2026-11-11T08:00:00Z",
      "updatedAt": "2026-11-11T08:00:00Z"
    }
  ]
}

21. 查询可导入的公共市场内容

GET /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id}/marketplace-items 按目标集合类型查询候选内容,检查status、reason及existingExtensionId后再决定是否导入。

查询参数

参数类型必填说明
keywordstring否搜索关键词。
maxResultsinteger否每页数量,1–100,默认20。
nextTokenstring否上一页返回的游标;第一页省略。

请求示例

curl --request GET \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc/marketplace-items?maxResults=20" \
  --header "Authorization: Bearer $QODER_API_KEY"

成功响应 (200 OK)

{
  "items": [
    {
      "sourceType": "qoder_skill",
      "sourceId": "82345678-1234-4234-8234-123456789abc",
      "name": "code-review",
      "displayName": "Code Review",
      "description": "Review code changes",
      "version": "1.0.0",
      "status": "importable",
      "reason": "",
      "existingExtensionId": null
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

22. 导入公共市场内容

POST /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id}/imports 每次导入一个内容。overwrite可能创建新的企业内容ID,不继承旧副本下发策略,默认scope=none。公共源作品不变;失败或超时后先查询集合确认结果,再决定是否重试。

请求参数

参数类型必填说明
sourceTypestring是qoder_plugin或qoder_skill。
sourceIdstring是候选列表返回的公共内容ID。
categoryIdstring否企业分类ID,省略时不指定分类。
onConflictstring否reject(默认)或overwrite。

请求体示例

{
  "sourceType": "qoder_skill",
  "sourceId": "82345678-1234-4234-8234-123456789abc",
  "onConflict": "reject"
}

请求示例

curl --request POST \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc/imports" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"sourceType":"qoder_skill","sourceId":"82345678-1234-4234-8234-123456789abc","onConflict":"reject"}'

成功响应 (201 Created)

{
  "extensionId": "42345678-1234-4234-8234-123456789abc",
  "sourceId": "82345678-1234-4234-8234-123456789abc",
  "name": "code-review",
  "version": "1.0.0"
}

23. 注册Connector

POST /v1/organizations/{organization_id}/apphub/extension-collections/{collection_id}/connectors 集合type必须为connector。通过JSON注册,不上传ZIP;不接收OAuth凭据或认证配置。

请求参数

参数类型必填说明
namestring是连接器程序标识,最多128个UTF-8字节;仅支持小写字母、数字,以及分隔这些字符段的单个连字符,例如docs-search。不允许开头、结尾或连续的连字符;展示名称使用displayName。
displayNamestring是显示名称。
descriptionstring否描述。
categoryIdstring否企业分类ID,省略时不指定分类。
configobject是见ConnectorConfig,必须包含且仅包含一个server。
distributionobject否下发范围及客户端策略;省略时为none/configurable,见 Distribution。
changeNotestring否变更说明,最多1024个UTF-8字节。

请求体示例

{
  "name": "docs",
  "displayName": "Docs",
  "config": {
    "servers": [
      {
        "name": "docs",
        "protocol": "streamable_http",
        "url": "https://example.com/mcp"
      }
    ]
  }
}

请求示例

curl --request POST \
  "https://api.qoder.com/v1/organizations/12345678-1234-4234-8234-123456789abc/apphub/extension-collections/32345678-1234-4234-8234-123456789abc/connectors" \
  --header "Authorization: Bearer $QODER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"docs","displayName":"Docs","config":{"servers":[{"name":"docs","protocol":"streamable_http","url":"https://example.com/mcp"}]}}'

成功响应 (201 Created)

{
  "extension": {
    "id": "42345678-1234-4234-8234-123456789abc",
    "organizationId": "12345678-1234-4234-8234-123456789abc",
    "collectionId": "32345678-1234-4234-8234-123456789abc",
    "type": "connector",
    "name": "docs",
    "displayName": "Docs",
    "description": "Review code changes",
    "version": "",
    "categoryId": null,
    "clients": [
      "qoder"
    ],
    "status": "active",
    "distribution": {
      "scope": "none",
      "targetGroupIds": [],
      "clientPolicy": "configurable"
    },
    "fileHash": "",
    "fileSize": 0,
    "createdAt": "2026-11-11T08:00:00Z",
    "updatedAt": "2026-11-11T08:00:00Z",
    "revision": 1,
    "config": {
      "servers": [
        {
          "name": "docs",
          "protocol": "streamable_http",
          "url": "https://example.com/mcp",
          "enabled": true,
          "runtimeKind": "client_direct"
        }
      ]
    }
  }
}

上传限制

每次仅支持一个ZIP,包含一个独立Plugin或Skill;Plugin内部可以包含多个子Skill。单文件最大50 MiB,完整multipart请求最大51 MiB,ZIP展开最大256 MiB、最多10,000个条目。不接受路径穿越、符号链接、损坏包或包含多个独立内容的批量包。更新包时不能同时修改分类或下发策略;使用对应管理接口修改。

ZIP目录结构

独立Skill必须恰好包含一个顶层目录,目录名作为Skill名称,目录内必须存在大小写一致的 SKILL.md。不要直接将 SKILL.md 放在ZIP根目录;包中只能有一个 SKILL.md,也不能包含 .qoder-plugin/plugin.json。例如:
code-review/
└── SKILL.md
在 code-review 的父目录执行以下命令,生成上述目录结构:
zip -r skill.zip code-review/
Plugin必须包含唯一的 .qoder-plugin/plugin.json,可位于ZIP根目录,或统一放在一层顶层目录下。使用顶层目录时,所有包文件都必须位于该目录内;不能再套多层目录。以下是根目录形式:
.qoder-plugin/
└── plugin.json
plugin.json 中的 name 提供Plugin名称,version 提供包版本;更新时版本必须严格大于当前版本。最小示例:
{
  "name": "team-tools",
  "version": "1.0.0"
}
在包含 .qoder-plugin 的目录执行以下命令。实际Plugin如还包含skills、commands等内容,需将对应文件一并打包;Plugin内的子Skill不计为多个独立上传内容。
zip -r plugin.zip .qoder-plugin/

错误响应

错误格式沿用OpenAPI约定,排查时保留requestId。常见HTTP状态如下;实际code以响应为准。
{
  "requestId": "example-request-id",
  "code": "BadRequest",
  "message": "invalid request body"
}
HTTP说明
400参数、包格式或类型无效;Connector缺少expectedRevision。
401认证失败。
403组织不匹配、能力未开通或无访问权限。
404集合、内容、分类或导入来源不存在。
409名称或版本冲突;非空集合/被引用分类无法删除;导入冲突。
413上传请求或文件超过限制。
429请求过多或上传并发达到限制。
500服务内部错误。
503依赖服务暂不可用。
公共市场导入的同名冲突返回409/AlreadyExists;来源不存在返回404/NotFound;类型不匹配、已下架或解析失败返回400/BadRequest;下载或上传依赖失败返回503/DEPENDENCY_UNAVAILABLE。覆盖导入不是整体原子回滚,失败后应先查询集合中的实际内容。