Operation details
GET /v1/site-groups
List site groups
- operationId
listSiteGroups- 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
All of：sites.read
Parameters
listSiteGroups Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | Yes | — |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
Responses
listSiteGroups Responses| Status | Description |
|---|
200 | Active groups ordered by creation time and ID. Fields：items: array<SiteGroup> total: integer page: integer limit: integer |
|---|
400 | Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}. |
|---|
401 | Authentication required. |
|---|
403 | Permission denied. |
|---|
503 | Site group service unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/site-groups
Create a site group
- operationId
createSiteGroup- 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
All of：sites.manage
Parameters
createSiteGroup Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createSiteGroup Request body| Name | Type | Required | Description |
|---|
target_scope_id | string(uuid) | Yes | — |
|---|
name | string | Yes | — |
|---|
remark | string | No | Optional; omission creates an empty remark and preserves the legacy request digest. Null is invalid. |
|---|
Responses
createSiteGroup Responses| Status | Description |
|---|
201 | Created group or an exact completed request replay. Fields：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time) |
|---|
400 | Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}. |
|---|
401 | Authentication required. |
|---|
403 | Permission denied. |
|---|
409 | Revision, idempotency, name, or in-use conflict. |
|---|
503 | Site group service unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/site-groups/{id}
Read one exact active site group in an authorized tenant scope
- operationId
getSiteGroup- 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
All of：sites.read
Parameters
getSiteGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | — |
|---|
Responses
getSiteGroup Responses| Status | Description |
|---|
200 | Current group including its real display ID and remark. A newer revision must not be mistaken for exact write readback. Fields：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time) |
|---|
400 | Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}. |
|---|
401 | Authentication required. |
|---|
403 | Permission denied. |
|---|
404 | Site group not found. |
|---|
503 | Site group service unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
PATCH /v1/site-groups/{id}
Rename a site group
- operationId
renameSiteGroup- 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
All of：sites.manage
Parameters
renameSiteGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
renameSiteGroup Request body| Name | Type | Required | Description |
|---|
expected_revision | integer | Yes | — |
|---|
name | string | Yes | — |
|---|
remark | string | No | Omission preserves the current remark and legacy digest. An explicit empty string clears it. Null is invalid. |
|---|
Responses
renameSiteGroup Responses| Status | Description |
|---|
200 | Renamed group or an exact completed request replay. Fields：id: string(uuid) scope_id: string(uuid) name: string remark?: string display_id?: string revision: integer created_at: string(date-time) updated_at: string(date-time) deleted_at?: string(date-time) | null(date-time) |
|---|
400 | Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}. |
|---|
401 | Authentication required. |
|---|
403 | Permission denied. |
|---|
404 | Site group not found. |
|---|
409 | Revision, idempotency, name, or in-use conflict. |
|---|
503 | Site group service unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
DELETE /v1/site-groups/{id}
Delete an unused site group
- operationId
deleteSiteGroup- 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
All of：sites.manage
Parameters
deleteSiteGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Responses
deleteSiteGroup Responses| Status | Description |
|---|
204 | Group deleted or an exact completed request replay. |
|---|
400 | Invalid request or precondition. A refused name or remark is validation_error with error.details {field: name|remark, reason}. |
|---|
401 | Authentication required. |
|---|
403 | Permission denied. |
|---|
404 | Site group not found. |
|---|
409 | Revision, idempotency, name, or in-use conflict. |
|---|
503 | Site group service unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list