/v1/admin/announcements

GET /v1/admin/announcements

List tenant announcements

operationId

listAnnouncements

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

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/announcements

Create an announcement draft

operationId

createAnnouncementDraft

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/announcements/audience-directory

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

operationId

searchAnnouncementAudience

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)

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

Parameters

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/announcements/global

List platform global announcements

operationId

listGlobalAnnouncements

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

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/announcements/global

Create a platform global announcement draft

operationId

createGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

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)

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.

Parameters

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Get a platform global announcement

operationId

getGlobalAnnouncement

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

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Update a platform global announcement draft

operationId

updateGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Archive a global announcement in management; published messages remain available

operationId

archiveGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

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

operationId

countGlobalAnnouncementAudience

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)

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

Parameters

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Publish a platform global announcement and freeze recipients

operationId

publishGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Restore a global announcement to management

operationId

restoreGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Withdraw a platform global announcement

operationId

withdrawGlobalAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/announcements/{id}

Get the current announcement version

operationId

getAnnouncement

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

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

PATCH /v1/admin/announcements/{id}

Update an announcement draft

operationId

updateAnnouncementDraft

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Archive a tenant announcement for reversible deletion

operationId

archiveAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

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

operationId

countAnnouncementAudience

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)

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

Parameters

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Publish an announcement

operationId

publishAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Restore an archived tenant announcement

operationId

restoreAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Create a revised announcement draft

operationId

reviseAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Schedule an announcement

operationId

scheduleAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list

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

Withdraw an announcement

operationId

withdrawAnnouncement

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

Request body

application/json · Required：Yes

Responses

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.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.

↑ Back to list