API reference

`/v1/admin/control-site`

11 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

Method	Path	Summary	Auth
GET	`/v1/admin/control-site`	—	Session
PUT	`/v1/admin/control-site`	—	Session
POST	`/v1/admin/control-site/assets`	—	Session
POST	`/v1/admin/control-site/publish`	—	Session
GET	`/v1/admin/control-site/themes`	—	Session
POST	`/v1/admin/control-site/themes`	—	Session
DELETE	`/v1/admin/control-site/themes/{theme_id}`	—	Session
POST	`/v1/admin/control-site/themes/{theme_id}/activate`	—	Session
PUT	`/v1/admin/control-site/themes/{theme_id}/customization`	—	Session
POST	`/v1/admin/control-site/themes/{theme_id}/install`	—	Session
GET	`/v1/admin/control-site/themes/{theme_id}/seed`	—	Session

Contract file：api/control-site-website.openapi.yaml

Operation details

GET `/v1/admin/control-site`

operationId

getControlSite

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Responses

getControlSite Responses
Status	Description
`200`	Draft Fields：`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

What to do on failure

401 Check the credential format and whether it expired or was rotated.
403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

PUT `/v1/admin/control-site`

operationId

saveControlSiteDraft

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

saveControlSiteDraft Parameters
Name	In	Type	Required	Description
`If-Match`	header	`string`	Yes	—
`Idempotency-Key`	header	`string`	Yes	—
`X-Request-ID`	header	`string`	Yes	—

Request body

application/json · Required：Yes

saveControlSiteDraft Request body
Name	Type	Required	Description
`draft`	`Document`	Yes	—

Responses

saveControlSiteDraft Responses
Status	Description
`200`	Saved Fields：`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

What to do on failure

400 Fix the parameters or body per the field list; do not retry unchanged.
403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

uploadControlSiteAsset

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

uploadControlSiteAsset Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	Yes	—
`X-Request-ID`	header	`string`	Yes	—

Request body

image/png, image/jpeg, image/webp, image/svg+xml, image/x-icon · Required：Yes

Responses

uploadControlSiteAsset Responses
Status	Description
`200`	Stored image Fields：`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

What to do on failure

400 Fix the parameters or body per the field list; do not retry unchanged.

↑ Back to list

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

operationId

publishControlSite

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

publishControlSite Parameters
Name	In	Type	Required	Description
`If-Match`	header	`string`	Yes	—
`Idempotency-Key`	header	`string`	Yes	—
`X-Request-ID`	header	`string`	Yes	—

Responses

publishControlSite Responses
Status	Description
`200`	Published Fields：`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

What to do on failure

403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

listWebsiteThemes

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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

Responses

listWebsiteThemes Responses
Status	Description
`200`	Catalog Fields：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`403`	Permission denied

What to do on failure

403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

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

operationId

uploadWebsiteTheme

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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

Parameters

uploadWebsiteTheme Parameters
Name	In	Type	Required	Description
`X-Request-ID`	header	`string`	Yes	—

Request body

application/json · Required：Yes

uploadWebsiteTheme Request body
Name	Type	Required	Description
`schema`	`const cdnca.site-theme/v1`	Yes	—
`id`	`string`	Yes	official.site-<name> (built-in), custom.<name> (uploaded), market.<plugin id> (plugin market).
`version`	`string`	Yes	—
`name`	`I18nText`	Yes	—
`description`	`I18nText`	No	—
`layout`	`string: jidun / xmf`	Yes	—
`tokens`	`object`	No	—
`images`	`object`	No	—
`seed`	`SeedContent`	Yes	—

Responses

uploadWebsiteTheme Responses
Status	Description
`200`	Installed Fields：`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

What to do on failure

400 Fix the parameters or body per the field list; do not retry unchanged.
403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

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

operationId

uninstallWebsiteTheme

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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

Parameters

uninstallWebsiteTheme Parameters
Name	In	Type	Required	Description
`theme_id`	path	`string`	Yes	—
`X-Request-ID`	header	`string`	Yes	—

Responses

uninstallWebsiteTheme Responses
Status	Description
`200`	Uninstalled Fields：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`404`	Unknown theme
`409`	control_site_theme_active or control_site_theme_not_installed

What to do on failure

404 The resource does not exist or belongs to another tenant.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

activateWebsiteTheme

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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.

Parameters

activateWebsiteTheme Parameters
Name	In	Type	Required	Description
`theme_id`	path	`string`	Yes	—
`If-Match`	header	`string`	Yes	Activation revision seen ("0" before any activation)
`X-Request-ID`	header	`string`	Yes	—

Responses

activateWebsiteTheme Responses
Status	Description
`200`	Activated Fields：`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

What to do on failure

403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

customizeWebsiteTheme

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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

Parameters

customizeWebsiteTheme Parameters
Name	In	Type	Required	Description
`theme_id`	path	`string`	Yes	—
`If-Match`	header	`string`	Yes	Customization revision seen ("0" for none)
`X-Request-ID`	header	`string`	Yes	—

Request body

application/json · Required：Yes

customizeWebsiteTheme Request body
Name	Type	Required	Description
`tokens`	`object`	No	—
`images`	`object`	No	—

Responses

customizeWebsiteTheme Responses
Status	Description
`200`	Saved Fields：`themes?: array<ThemeEntry>` `active_theme_id?: string` `activation_revision?: integer`
`400`	Unknown token
`409`	Revision conflict or not installed

What to do on failure

400 Fix the parameters or body per the field list; do not retry unchanged.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

installWebsiteTheme

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

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

Parameters

installWebsiteTheme Parameters
Name	In	Type	Required	Description
`theme_id`	path	`string`	Yes	—
`X-Request-ID`	header	`string`	Yes	—

Responses

installWebsiteTheme Responses
Status	Description
`200`	Installed Fields：`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)

What to do on failure

403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
404 The resource does not exist or belongs to another tenant.
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

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

operationId

readWebsiteThemeSeed

Auth

Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

readWebsiteThemeSeed Parameters
Name	In	Type	Required	Description
`theme_id`	path	`string`	Yes	—

Responses

readWebsiteThemeSeed Responses
Status	Description
`200`	The plugin's default content Fields：`nav?: array<object> \| null` `actions?: array<Link> \| null` `footer?: object` `pages?: array<object> \| null` `brand?: Brand` `contact?: Contact`
`404`	Unknown theme

What to do on failure

404 The resource does not exist or belongs to another tenant.

↑ Back to list

/v1/admin/control-site

Operation details

GET /v1/admin/control-site

Responses

What to do on failure

PUT /v1/admin/control-site

Parameters

Request body

Responses

What to do on failure

POST /v1/admin/control-site/assets

Parameters

Request body

Responses

What to do on failure

POST /v1/admin/control-site/publish

Parameters

Responses

What to do on failure

GET /v1/admin/control-site/themes

Description (from the contract)

Responses

What to do on failure

POST /v1/admin/control-site/themes

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

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

Description (from the contract)

Parameters

Responses

What to do on failure

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

Description (from the contract)

Parameters

Responses

What to do on failure

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

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

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

Description (from the contract)

Parameters

Responses

What to do on failure

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

Parameters

Responses

What to do on failure

`/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`