Operation details
GET /v1/admin/site-publications
List publications for one tenant scope
- operationId
listAdminSitePublications- 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：edge_publications.read
Description (from the contract)
Requires a platform-scoped principal with edge_publications.read. The opaque keyset cursor is bound to the tenant scope and stable ordering.
Parameters
listAdminSitePublications Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | Yes | Platform route target tenant access-scope UUID. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope returned by the immediately preceding page. It is bound to audience, resolved tenant scope, resource kind, and the rollout ID for deployment pages. It cannot be reused across those boundaries or modified. |
|---|
Responses
listAdminSitePublications Responses| Status | Description |
|---|
200 | Stable publication page. Response body is limited to 1 MiB. Fields：items: array<AdminPublication> current_source_revision: integer(int64) next_cursor?: string pending_modules?: array<PendingModule> automatic_failure?: AutomaticPublicationFailure |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is 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/admin/site-publications
Publish the current Site/L4 revision to an immutable target snapshot
- operationId
publishSiteConfiguration- 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：edge_publications.manage
Description (from the contract)
Requires a platform-scoped principal with edge_publications.manage. Exactly one nodes or line_group_snapshot target is accepted. The domain service performs source revision CAS, target eligibility checks, local non-grace entitlement verification, canonical compilation, signing, config/rollout/deployment/outbox persistence, idempotency, and success audit in one transaction. An unknown write result may be retried only with the same Idempotency-Key and original business payload.
Parameters
publishSiteConfiguration Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
publishSiteConfiguration Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
expected_source_revision | integer(int64) | Yes | — |
|---|
target | ExplicitNodeTarget | LineGroupSnapshotTarget | Yes | — |
|---|
health_check | HealthCheck | Yes | — |
|---|
rollout | RolloutPolicyInput | No | Progressive policy for a target frozen at publication time. Nodes are ordered by UUID bytes, then assigned to the canary and fixed-size cohorts. Commands outside the released cohort remain held. The failure threshold is an absolute failed-node count within the current cohort; reaching it pauses the rollout. |
|---|
max_attempts | integer | Yes | — |
|---|
deadline | string(date-time) | Yes | Future RFC3339 deployment deadline. |
|---|
Responses
publishSiteConfiguration Responses| Status | Description |
|---|
201 | Created publication, or the stored result of an identical retry. Fields：id: string(uuid) configuration_scope_id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) canonical_source_sha256: string artifact_sha256: string target: object | object node_count: integer created_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
412 | The source or rollout expected revision is stale. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is 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.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/site-publications/{publication_id}
Get one publication in an explicit tenant scope
- operationId
getAdminSitePublication- 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：edge_publications.read
Parameters
getAdminSitePublication Parameters| Name | In | Type | Required | Description |
|---|
publication_id | path | string(uuid) | Yes | — |
|---|
scope_id | query | string(uuid) | Yes | Platform route target tenant access-scope UUID. |
|---|
Responses
getAdminSitePublication Responses| Status | Description |
|---|
200 | Platform publication detail. Fields：id: string(uuid) configuration_scope_id: string(uuid) source_revision: integer(int64) config_version_id: string(uuid) rollout_id: string(uuid) canonical_source_sha256: string artifact_sha256: string target: object | object node_count: integer created_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is 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
POST /v1/admin/site-publications/{publication_id}/rollback
Roll selected nodes back to their direct previous published configuration
- operationId
rollbackSitePublication- 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：edge_publications.manage
Description (from the contract)
Creates a rollback rollout for the immutable configuration referenced by the selected publication. Every selected node must currently name that configuration as its direct previous version. No new configuration or artifact bytes are created, and rollback remains available when an entitlement no longer permits expansion.
Parameters
rollbackSitePublication Parameters| Name | In | Type | Required | Description |
|---|
publication_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | Stable for the frozen business payload. Request, correlation, trace, and task identifiers may change on an identical retry. |
|---|
X-Request-ID | header | string(uuid) | Yes | — |
|---|
Traceparent | header | string | Yes | — |
|---|
X-Correlation-ID | header | string(uuid) | No | Defaults to X-Request-ID when omitted. |
|---|
X-Task-ID | header | string | No | — |
|---|
Request body
application/json · Required：Yes
rollbackSitePublication Request body| Name | Type | Required | Description |
|---|
configuration_scope_id | string(uuid) | Yes | — |
|---|
target | ExplicitNodeTarget | LineGroupSnapshotTarget | Yes | — |
|---|
health_check | HealthCheck | Yes | — |
|---|
rollout | RolloutPolicyInput | No | Progressive policy for a target frozen at publication time. Nodes are ordered by UUID bytes, then assigned to the canary and fixed-size cohorts. Commands outside the released cohort remain held. The failure threshold is an absolute failed-node count within the current cohort; reaching it pauses the rollout. |
|---|
max_attempts | integer | Yes | — |
|---|
deadline | string(date-time) | Yes | Future RFC3339 rollback deadline. |
|---|
Responses
rollbackSitePublication Responses| Status | Description |
|---|
201 | Created rollback rollout, or the stored result of an identical retry. Fields：publication_id: string(uuid) configuration_scope_id: string(uuid) config_version_id: string(uuid) rollout_id: string(uuid) action: string target: object | object node_count: integer created_at: string(date-time) replayed?: boolean |
|---|
400 | Invalid UUID, RFC3339 value, enum, cursor, header, query, or JSON body. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | Wrong audience, missing permission, or tenant scope override. |
|---|
404 | Resource is absent in the authorized tenant scope. Cross-tenant IDs use the same response. |
|---|
409 | Idempotency, target snapshot, rollout state, active deployment, or retry conflict. |
|---|
422 | Entitlement or target/resource readiness prevents publication. |
|---|
503 | Storage, signing, cancellation, response validation, or another internal dependency is 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