开放接口

`/v1/admin/control-site`

11 个接口

方法	路径	摘要	认证
GET	`/v1/admin/control-site`	—	登录会话
PUT	`/v1/admin/control-site`	—	登录会话
POST	`/v1/admin/control-site/assets`	—	登录会话
POST	`/v1/admin/control-site/publish`	—	登录会话
GET	`/v1/admin/control-site/themes`	—	登录会话
POST	`/v1/admin/control-site/themes`	—	登录会话
DELETE	`/v1/admin/control-site/themes/{theme_id}`	—	登录会话
POST	`/v1/admin/control-site/themes/{theme_id}/activate`	—	登录会话
PUT	`/v1/admin/control-site/themes/{theme_id}/customization`	—	登录会话
POST	`/v1/admin/control-site/themes/{theme_id}/install`	—	登录会话
GET	`/v1/admin/control-site/themes/{theme_id}/seed`	—	登录会话

契约文件：api/control-site-website.openapi.yaml

接口详情

GET `/v1/admin/control-site`

operationId

getControlSite

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

响应

getControlSite 响应
状态码	说明
`200`	Draft 字段：`schema?: const cdnca.control-site/v1` `revision?: integer` `theme?: ThemeView \| null` `draft?: Document` `published?: Document \| null` `published_revision?: integer \| null` `dirty?: boolean` `seeded?: boolean` `updated_at?: string(date-time) \| null(date-time)` `published_at?: string(date-time) \| null(date-time)` `assets?: array<Asset>`
`401`	Unauthenticated
`403`	Permission denied

失败时怎么办

401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

PUT `/v1/admin/control-site`

operationId

saveControlSiteDraft

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

saveControlSiteDraft 参数
名称	位置	类型	必填	说明
`If-Match`	header	`string`	是	—
`Idempotency-Key`	header	`string`	是	—
`X-Request-ID`	header	`string`	是	—

请求体

application/json · 必填：是

saveControlSiteDraft 请求体
名称	类型	必填	说明
`draft`	`Document`	是	—

响应

saveControlSiteDraft 响应
状态码	说明
`200`	Saved 字段：`schema?: const cdnca.control-site/v1` `revision?: integer` `theme?: ThemeView \| null` `draft?: Document` `published?: Document \| null` `published_revision?: integer \| null` `dirty?: boolean` `seeded?: boolean` `updated_at?: string(date-time) \| null(date-time)` `published_at?: string(date-time) \| null(date-time)` `assets?: array<Asset>`
`400`	Invalid content or unknown image
`403`	Permission denied
`409`	Revision or idempotency conflict

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST `/v1/admin/control-site/assets`

operationId

uploadControlSiteAsset

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

uploadControlSiteAsset 参数
名称	位置	类型	必填	说明
`Idempotency-Key`	header	`string`	是	—
`X-Request-ID`	header	`string`	是	—

请求体

image/png, image/jpeg, image/webp, image/svg+xml, image/x-icon · 必填：是

响应

uploadControlSiteAsset 响应
状态码	说明
`200`	Stored image 字段：`sha256?: string` `reference?: string` `url?: string` `mime_type?: string` `size_bytes?: integer` `created_at?: string(date-time)`
`400`	Not an accepted image or an unsafe SVG
`413`	Larger than 2 MiB

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。

↑ 回到列表

POST `/v1/admin/control-site/publish`

operationId

publishControlSite

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

publishControlSite 参数
名称	位置	类型	必填	说明
`If-Match`	header	`string`	是	—
`Idempotency-Key`	header	`string`	是	—
`X-Request-ID`	header	`string`	是	—

响应

publishControlSite 响应
状态码	说明
`200`	Published 字段：`schema?: const cdnca.control-site/v1` `revision?: integer` `theme?: ThemeView \| null` `draft?: Document` `published?: Document \| null` `published_revision?: integer \| null` `dirty?: boolean` `seeded?: boolean` `updated_at?: string(date-time) \| null(date-time)` `published_at?: string(date-time) \| null(date-time)` `assets?: array<Asset>`
`403`	Permission denied
`409`	Revision conflict or nothing to publish

失败时怎么办

403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET `/v1/admin/control-site/themes`

operationId

listWebsiteThemes

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Built-in, uploaded and market website theme plugins (installed or available) and the active one.

响应

listWebsiteThemes 响应
状态码	说明
`200`	Catalog 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`403`	Permission denied

失败时怎么办

403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

POST `/v1/admin/control-site/themes`

operationId

uploadWebsiteTheme

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Validates and installs an uploaded package (id custom.*); an upload with the same id is replaced and keeps its parameters.

参数

uploadWebsiteTheme 参数
名称	位置	类型	必填	说明
`X-Request-ID`	header	`string`	是	—

请求体

application/json · 必填：是

uploadWebsiteTheme 请求体
名称	类型	必填	说明
`schema`	`const cdnca.site-theme/v1`	是	—
`id`	`string`	是	official.site-<name> (built-in), custom.<name> (uploaded), market.<plugin id> (plugin market).
`version`	`string`	是	—
`name`	`I18nText`	是	—
`description`	`I18nText`	否	—
`layout`	`string: jidun / xmf`	是	—
`tokens`	`object`	否	—
`images`	`object`	否	—
`seed`	`SeedContent`	是	—

响应

uploadWebsiteTheme 响应
状态码	说明
`200`	Installed 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`400`	control_site_theme_invalid with reason and field
`403`	Permission denied
`413`	Larger than 8 MiB

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。

↑ 回到列表

DELETE `/v1/admin/control-site/themes/{theme_id}`

operationId

uninstallWebsiteTheme

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Uninstalls a plugin that is not active and drops its parameters; website content is kept. A market plugin stays available to install.

参数

uninstallWebsiteTheme 参数
名称	位置	类型	必填	说明
`theme_id`	path	`string`	是	—
`X-Request-ID`	header	`string`	是	—

响应

uninstallWebsiteTheme 响应
状态码	说明
`200`	Uninstalled 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`404`	Unknown theme
`409`	control_site_theme_active or control_site_theme_not_installed

失败时怎么办

404 资源不存在或不属于当前租户。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST `/v1/admin/control-site/themes/{theme_id}/activate`

operationId

activateWebsiteTheme

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Makes an installed plugin the website's theme. The website reads the new layout's content (or the plugin seed); other layouts' content is kept.

参数

activateWebsiteTheme 参数
名称	位置	类型	必填	说明
`theme_id`	path	`string`	是	—
`If-Match`	header	`string`	是	Activation revision seen ("0" before any activation)
`X-Request-ID`	header	`string`	是	—

响应

activateWebsiteTheme 响应
状态码	说明
`200`	Activated 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`403`	Permission denied, or control_site_theme_withdrawn
`409`	Revision conflict, control_site_theme_not_installed or control_site_theme_unchanged

失败时怎么办

403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

PUT `/v1/admin/control-site/themes/{theme_id}/customization`

operationId

customizeWebsiteTheme

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Token overrides (the layout whitelist) and replacement images per plugin slot (uploaded images). Empty maps restore the plugin defaults. Applies at once.

参数

customizeWebsiteTheme 参数
名称	位置	类型	必填	说明
`theme_id`	path	`string`	是	—
`If-Match`	header	`string`	是	Customization revision seen ("0" for none)
`X-Request-ID`	header	`string`	是	—

请求体

application/json · 必填：是

customizeWebsiteTheme 请求体
名称	类型	必填	说明
`tokens`	`object`	否	—
`images`	`object`	否	—

响应

customizeWebsiteTheme 响应
状态码	说明
`200`	Saved 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`400`	Unknown token
`409`	Revision conflict or not installed

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

POST `/v1/admin/control-site/themes/{theme_id}/install`

operationId

installWebsiteTheme

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

说明（契约原文）

Installs a built-in plugin, or a market plugin this installation is authorized for.

参数

installWebsiteTheme 参数
名称	位置	类型	必填	说明
`theme_id`	path	`string`	是	—
`X-Request-ID`	header	`string`	是	—

响应

installWebsiteTheme 响应
状态码	说明
`200`	Installed 字段：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`403`	Permission denied, or control_site_theme_withdrawn
`404`	Unknown theme
`409`	control_site_theme_unchanged (already installed)

失败时怎么办

403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
404 资源不存在或不属于当前租户。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。

↑ 回到列表

GET `/v1/admin/control-site/themes/{theme_id}/seed`

operationId

readWebsiteThemeSeed

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

readWebsiteThemeSeed 参数
名称	位置	类型	必填	说明
`theme_id`	path	`string`	是	—

响应

readWebsiteThemeSeed 响应
状态码	说明
`200`	The plugin's default content 字段：`nav?: array<object> \| null` `actions?: array<Link> \| null` `footer?: object` `pages?: array<object> \| null` `brand?: Brand` `contact?: Contact`
`404`	Unknown theme

失败时怎么办

404 资源不存在或不属于当前租户。

↑ 回到列表

/v1/admin/control-site

接口详情

GET /v1/admin/control-site

响应

失败时怎么办

PUT /v1/admin/control-site

参数

请求体

响应

失败时怎么办

POST /v1/admin/control-site/assets

参数

请求体

响应

失败时怎么办

POST /v1/admin/control-site/publish

参数

响应

失败时怎么办

GET /v1/admin/control-site/themes

说明（契约原文）

响应

失败时怎么办

POST /v1/admin/control-site/themes

说明（契约原文）

参数

请求体

响应

失败时怎么办

DELETE /v1/admin/control-site/themes/{theme_id}

说明（契约原文）

参数

响应

失败时怎么办

POST /v1/admin/control-site/themes/{theme_id}/activate

说明（契约原文）

参数

响应

失败时怎么办

PUT /v1/admin/control-site/themes/{theme_id}/customization

说明（契约原文）

参数

请求体

响应

失败时怎么办

POST /v1/admin/control-site/themes/{theme_id}/install

说明（契约原文）

参数

响应

失败时怎么办

GET /v1/admin/control-site/themes/{theme_id}/seed

参数

响应

失败时怎么办

`/v1/admin/control-site`

GET `/v1/admin/control-site`

PUT `/v1/admin/control-site`

POST `/v1/admin/control-site/assets`

POST `/v1/admin/control-site/publish`

GET `/v1/admin/control-site/themes`

POST `/v1/admin/control-site/themes`

DELETE `/v1/admin/control-site/themes/{theme_id}`

POST `/v1/admin/control-site/themes/{theme_id}/activate`

PUT `/v1/admin/control-site/themes/{theme_id}/customization`

POST `/v1/admin/control-site/themes/{theme_id}/install`

GET `/v1/admin/control-site/themes/{theme_id}/seed`