Book a demo

publish_announcement

Publish an announcement to one account

act entity tenant-private since 2026-10-01

Publishes a titled message to one account. It shows to the members of that account's orgs, and to no other account, from now until it ends after the given number of days (14 unless set). Send an Idempotency-Key header: a retry with the same key and inputs returns the same announcement and publishes nothing new. Staff only.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
keyed
emits
announcement.published
MCP tool
publish_announcement
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/publish_announcement

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
account_idaccount_idrequiredtradehq-account-id
The one account it shows in.
titletextrequired1 to 120 characters
A short headline.
bodytextrequired1 to 2000 characters
The message, as plain text.
severityone_ofrequiredone of info, warning
info, or warning for something the account must act on.
daysintegeroptional1 to 90; default 14
How many days it shows for.

Response

  • announcement_id · string · The announcement's id.
  • account_id · string · The account it shows in.
  • title · string · The headline.
  • body · string · The message.
  • severity · string · info or warning.
  • starts_at · string · When it started showing.
  • ends_at · string · When it stops showing.
  • published_by · string · Who published it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "announcement_id": {
      "type": "string",
      "description": "The announcement's id.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "The account it shows in.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "The headline.",
      "x-data-class": "operational"
    },
    "body": {
      "type": "string",
      "description": "The message.",
      "x-data-class": "operational"
    },
    "severity": {
      "type": "string",
      "enum": [
        "info",
        "warning"
      ],
      "description": "info or warning.",
      "x-data-class": "operational"
    },
    "starts_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it started showing.",
      "x-data-class": "operational"
    },
    "ends_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it stops showing.",
      "x-data-class": "operational"
    },
    "published_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who published it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "announcement_id",
    "account_id",
    "title",
    "body",
    "severity",
    "starts_at",
    "ends_at",
    "published_by"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates an announcement
  • Outbound: staff to a tenant; crosses to no counterparty

Events

Related

None.