Book a demo

list_announcements

List what is showing to an org

read collection tenant-private since 2026-10-01

Lists what is showing now to the members of one org: the maintenance banner, if it is on, and then the announcements published to the org's account that have not ended, newest first. An org sees only its own account's announcements. Any member of the org may call it, and so may staff.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: org.member (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_announcements
REST
POST https://api.containertradehq.com/v1/cap/list_announcements

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose members are looking: usually the caller's current org.

Paginated: next next_after · ceiling not_declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "maintenance",
              "announcement"
            ],
            "description": "maintenance for the platform banner, announcement for one published to the account.",
            "x-data-class": "operational"
          },
          "id": {
            "type": "string",
            "description": "The banner's or the announcement's id.",
            "x-data-class": "operational"
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "critical"
            ],
            "description": "info, warning or critical.",
            "x-data-class": "operational"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "The headline; null on the banner.",
            "x-data-class": "operational"
          },
          "body": {
            "type": "string",
            "description": "The message.",
            "x-data-class": "operational"
          },
          "starts_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it started showing.",
            "x-data-class": "operational"
          },
          "ends_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it stops; null when it has no end, and it shows until something ends it.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "kind",
          "id",
          "severity",
          "title",
          "body",
          "starts_at",
          "ends_at"
        ],
        "additionalProperties": false
      }
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "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
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a notice
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.