cdnca

开放接口

/v1/admin/announcements

22 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/admin/announcementsList tenant announcements登录会话
POST/v1/admin/announcementsCreate an announcement draft登录会话
GET/v1/admin/announcements/audience-directorySearch the current tenant's users or roles by name for an announcement audience登录会话
GET/v1/admin/announcements/globalList platform global announcements登录会话
POST/v1/admin/announcements/globalCreate a platform global announcement draft登录会话
GET/v1/admin/announcements/global/audience-directorySearch tenants, or one tenant's roles and users, by name for a platform global announcement audience登录会话
GET/v1/admin/announcements/global/{id}Get a platform global announcement登录会话
PATCH/v1/admin/announcements/global/{id}Update a platform global announcement draft登录会话
POST/v1/admin/announcements/global/{id}/archiveArchive a global announcement in management; published messages remain available登录会话
GET/v1/admin/announcements/global/{id}/audience/countCount the recipients a platform global announcement would be delivered to now登录会话
POST/v1/admin/announcements/global/{id}/publishPublish a platform global announcement and freeze recipients登录会话
POST/v1/admin/announcements/global/{id}/restoreRestore a global announcement to management登录会话
POST/v1/admin/announcements/global/{id}/withdrawWithdraw a platform global announcement登录会话
GET/v1/admin/announcements/{id}Get the current announcement version登录会话
PATCH/v1/admin/announcements/{id}Update an announcement draft登录会话
POST/v1/admin/announcements/{id}/archiveArchive a tenant announcement for reversible deletion登录会话
GET/v1/admin/announcements/{id}/audience/countCount the recipients the head version of an announcement would be delivered to now登录会话
POST/v1/admin/announcements/{id}/publishPublish an announcement登录会话
POST/v1/admin/announcements/{id}/restoreRestore an archived tenant announcement登录会话
POST/v1/admin/announcements/{id}/reviseCreate a revised announcement draft登录会话
POST/v1/admin/announcements/{id}/scheduleSchedule an announcement登录会话
POST/v1/admin/announcements/{id}/withdrawWithdraw an announcement登录会话

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

接口详情

GET /v1/admin/announcements

List tenant announcements

operationId
listAnnouncements
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

listAnnouncements 参数
名称位置类型必填说明
limitqueryinteger否—
cursorquerystring否—
statusquerystring: draft / scheduled / published / withdrawn / archived否—

响应

listAnnouncements 响应
状态码说明
200Announcement page

字段：items: array<Announcement> next_cursor?: string

400Stable API error
401Stable API error
403Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements

Create an announcement draft

operationId
createAnnouncementDraft
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

createAnnouncementDraft 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createAnnouncementDraft 请求体
名称类型必填说明
titlestring是—
bodystring是Required for format=content; empty for format=link. UTF-8 encoded body must not exceed 65536 bytes; only the documented safe Markdown subset is accepted.
formatstring: content / link否—
link_urlstring(uri)否Required for format=link and limited to http(s).
sort_orderinteger否—
visibleboolean否—
popupboolean否—
redboolean否—
boldboolean否—
allboolean是—
user_idsarray<string(uuid)>是—
group_idsarray<string(uuid)>是—
withdrawal_visibilitystring: retain / hide是—

响应

createAnnouncementDraft 响应
状态码说明
201Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/audience-directory

Search the current tenant's users or roles by name for an announcement audience

operationId
searchAnnouncementAudience
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Read-only; authorized by announcements.manage in the current tenant. ids resolves stored targets back to names and returns only those that still exist.

参数

searchAnnouncementAudience 参数
名称位置类型必填说明
kindquerystring: user / role是—
searchquerystring否Case-insensitive name substring; mutually exclusive with ids.
idsquerystring否Comma-separated IDs to resolve to names (at most 100).
limitqueryinteger否—

响应

searchAnnouncementAudience 响应
状态码说明
200Audience directory entries

字段：items: array<AudienceDirectoryEntry>

400Stable API error
401Stable API error
403Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/global

List platform global announcements

operationId
listGlobalAnnouncements
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

listGlobalAnnouncements 参数
名称位置类型必填说明
limitqueryinteger否—
cursorquerystring否—
statusquerystring: draft / published / withdrawn / archived否—

响应

listGlobalAnnouncements 响应
状态码说明
200Platform global announcement page

字段：items: array<GlobalAnnouncement> next_cursor?: string

400Stable API error
401Stable API error
403Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/global

Create a platform global announcement draft

operationId
createGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

createGlobalAnnouncement 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是—

请求体

application/json · 必填：是

createGlobalAnnouncement 请求体
名称类型必填说明
all_tenantsboolean是—
tenant_scope_idsarray<string(uuid)>是—
role_targetsarray<GlobalRoleTarget>是—
user_targetsarray<GlobalUserTarget>是—
titlestring是—
bodystring是Required for format=content; empty for format=link. HTML content is rendered in a script-disabled sandbox with remote resource loading blocked.
formatstring: content / link否—
link_urlstring(uri)否Required for format=link and limited to http(s).
sort_orderinteger否—
visibleboolean否—
popupboolean否—
redboolean否—
boldboolean否—
withdrawal_visibilitystring: retain / hide是—

响应

createGlobalAnnouncement 响应
状态码说明
201Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/global/audience-directory

Search tenants, or one tenant's roles and users, by name for a platform global announcement audience

operationId
searchGlobalAnnouncementAudience
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Read-only; authorized by announcements.manage (or platform.admin) in the platform scope. Role and user searches require scope_id. ids resolves stored targets back to names and returns only those that still exist.

参数

searchGlobalAnnouncementAudience 参数
名称位置类型必填说明
kindquerystring: tenant / role / user是—
searchquerystring否Case-insensitive name substring; mutually exclusive with ids.
idsquerystring否Comma-separated IDs to resolve to names (at most 100).
limitqueryinteger否—
scope_idquerystring(uuid)否Tenant scope for role and user searches.

响应

searchGlobalAnnouncementAudience 响应
状态码说明
200Audience directory entries

字段：items: array<AudienceDirectoryEntry>

400Stable API error
401Stable API error
403Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/global/{id}

Get a platform global announcement

operationId
getGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

getGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

getGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/admin/announcements/global/{id}

Update a platform global announcement draft

operationId
updateGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

updateGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

updateGlobalAnnouncement 请求体
名称类型必填说明
all_tenantsboolean是—
tenant_scope_idsarray<string(uuid)>是—
role_targetsarray<GlobalRoleTarget>是—
user_targetsarray<GlobalUserTarget>是—
titlestring是—
bodystring是Required for format=content; empty for format=link. HTML content is rendered in a script-disabled sandbox with remote resource loading blocked.
formatstring: content / link否—
link_urlstring(uri)否Required for format=link and limited to http(s).
sort_orderinteger否—
visibleboolean否—
popupboolean否—
redboolean否—
boldboolean否—
withdrawal_visibilitystring: retain / hide是—
expected_revisioninteger是—

响应

updateGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/global/{id}/archive

Archive a global announcement in management; published messages remain available

operationId
archiveGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

archiveGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

archiveGlobalAnnouncement 请求体
名称类型必填说明
expected_lifecycle_revisioninteger是—

响应

archiveGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/global/{id}/audience/count

Count the recipients a platform global announcement would be delivered to now

operationId
countGlobalAnnouncementAudience
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Read-only; resolves recipients with the same query publication uses and writes nothing.

参数

countGlobalAnnouncementAudience 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

countGlobalAnnouncementAudience 响应
状态码说明
200Audience recipient count

字段：announcement_id: string(uuid) version?: integer recipient_count: integer

400Stable API error
401Stable API error
403Stable API error
404Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/global/{id}/publish

Publish a platform global announcement and freeze recipients

operationId
publishGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

publishGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

publishGlobalAnnouncement 请求体
名称类型必填说明
expected_revisioninteger是—

响应

publishGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/global/{id}/restore

Restore a global announcement to management

operationId
restoreGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

restoreGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

restoreGlobalAnnouncement 请求体
名称类型必填说明
expected_lifecycle_revisioninteger是—

响应

restoreGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/global/{id}/withdraw

Withdraw a platform global announcement

operationId
withdrawGlobalAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

withdrawGlobalAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

withdrawGlobalAnnouncement 请求体
名称类型必填说明
expected_revisioninteger是—

响应

withdrawGlobalAnnouncement 响应
状态码说明
200Platform global announcement

字段：id: string(uuid) platform_scope_id: string(uuid) version: integer revision: integer status: string: draft / published / withdrawn title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: GlobalAudience withdrawal_visibility: string: retain / hide recipient_count: integer published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/{id}

Get the current announcement version

operationId
getAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

getAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

getAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/admin/announcements/{id}

Update an announcement draft

operationId
updateAnnouncementDraft
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

updateAnnouncementDraft 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

updateAnnouncementDraft 请求体
名称类型必填说明
titlestring是—
bodystring是Required for format=content; empty for format=link. UTF-8 encoded body must not exceed 65536 bytes; only the documented safe Markdown subset is accepted.
formatstring: content / link否—
link_urlstring(uri)否Required for format=link and limited to http(s).
sort_orderinteger否—
visibleboolean否—
popupboolean否—
redboolean否—
boldboolean否—
allboolean是—
user_idsarray<string(uuid)>是—
group_idsarray<string(uuid)>是—
withdrawal_visibilitystring: retain / hide是—
versioninteger是—
expected_revisioninteger是—

响应

updateAnnouncementDraft 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/archive

Archive a tenant announcement for reversible deletion

operationId
archiveAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

archiveAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

archiveAnnouncement 请求体
名称类型必填说明
expected_lifecycle_revisioninteger是—

响应

archiveAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

GET /v1/admin/announcements/{id}/audience/count

Count the recipients the head version of an announcement would be delivered to now

operationId
countAnnouncementAudience
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

说明（契约原文）

Read-only; resolves recipients with the same query publication uses and writes nothing.

参数

countAnnouncementAudience 参数
名称位置类型必填说明
idpathstring(uuid)是—

响应

countAnnouncementAudience 响应
状态码说明
200Audience recipient count

字段：announcement_id: string(uuid) version?: integer recipient_count: integer

400Stable API error
401Stable API error
403Stable API error
404Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/publish

Publish an announcement

operationId
publishAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

publishAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

publishAnnouncement 请求体
名称类型必填说明
versioninteger是—
expected_revisioninteger是—

响应

publishAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/restore

Restore an archived tenant announcement

operationId
restoreAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

restoreAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

restoreAnnouncement 请求体
名称类型必填说明
expected_lifecycle_revisioninteger是—

响应

restoreAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/revise

Create a revised announcement draft

operationId
reviseAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

reviseAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

reviseAnnouncement 请求体
名称类型必填说明
titlestring是—
bodystring是Required for format=content; empty for format=link. UTF-8 encoded body must not exceed 65536 bytes; only the documented safe Markdown subset is accepted.
formatstring: content / link否—
link_urlstring(uri)否Required for format=link and limited to http(s).
sort_orderinteger否—
visibleboolean否—
popupboolean否—
redboolean否—
boldboolean否—
allboolean是—
user_idsarray<string(uuid)>是—
group_idsarray<string(uuid)>是—
withdrawal_visibilitystring: retain / hide是—
expected_head_versioninteger是—

响应

reviseAnnouncement 响应
状态码说明
201Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
422Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/schedule

Schedule an announcement

operationId
scheduleAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

scheduleAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

scheduleAnnouncement 请求体
名称类型必填说明
versioninteger是—
expected_revisioninteger是—
publish_atstring(date-time)是—

响应

scheduleAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/admin/announcements/{id}/withdraw

Withdraw an announcement

operationId
withdrawAnnouncement
认证
  • 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
所需权限

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

参数

withdrawAnnouncement 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是—
If-Matchheaderstring是—

请求体

application/json · 必填：是

withdrawAnnouncement 请求体
名称类型必填说明
versioninteger是—
expected_revisioninteger是—

响应

withdrawAnnouncement 响应
状态码说明
200Announcement

字段：id: string(uuid) scope_id: string(uuid) version: integer head_version: integer revision: integer status: string: draft / scheduled / published / withdrawn / archived title: string body: string format: string: content / link link_url?: string(uri) sort_order: integer visible: boolean popup: boolean red: boolean bold: boolean audience: Audience withdrawal_visibility: string: retain / hide scheduled_at?: string(date-time) published_at?: string(date-time) withdrawn_at?: string(date-time) created_at: string(date-time) state_changed_at: string(date-time) archived: boolean lifecycle_revision: integer archived_at?: string(date-time) replayed?: boolean

400Stable API error
401Stable API error
403Stable API error
404Stable API error
409Stable API error
415Stable API error
500Stable API error

失败时怎么办

  • 400 按字段说明修正参数或请求体再发；不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。

↑ 回到列表