Book a demo

set_maintenance_banner

Set the maintenance banner

act entity canonical-registry since 2026-10-01

Turns the platform-wide maintenance banner on with a message, or off. An on banner shows to every signed-in user until it is turned off, or for the given number of hours. Its severity is warning unless set. Each call is kept, so the history says who set what. Send an Idempotency-Key header: a retry with the same key and inputs changes nothing. 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
maintenance_banner.changed
MCP tool
set_maintenance_banner
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/set_maintenance_banner

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
stateone_ofrequiredone of on, off
on shows the banner; off clears it.
messagetextoptional1 to 280 characters
What the banner says. Required when on, refused when off.
severityone_ofoptionalone of info, warning, critical
info, warning or critical; warning when on and not given. Refused when off.
hoursintegeroptional1 to 168
End an on banner by itself after this many hours. Refused when off.

Response

  • banner_id · string · This setting's id.
  • state · string · on or off.
  • message · stringnull · What it says; null when off.
  • severity · stringnull · Its severity; null when off.
  • ends_at · stringnull · When it ends by itself; null when it does not.
  • set_by · string · Who set it.
  • set_at · string · When.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "banner_id": {
      "type": "string",
      "description": "This setting's id.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ],
      "description": "on or off.",
      "x-data-class": "operational"
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "What it says; null when off.",
      "x-data-class": "operational"
    },
    "severity": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "info",
        "warning",
        "critical",
        null
      ],
      "description": "Its severity; null when off.",
      "x-data-class": "operational"
    },
    "ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it ends by itself; null when it does not.",
      "x-data-class": "operational"
    },
    "set_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who set it.",
      "x-data-class": "operational"
    },
    "set_at": {
      "type": "string",
      "format": "date-time",
      "description": "When.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "banner_id",
    "state",
    "message",
    "severity",
    "ends_at",
    "set_by",
    "set_at"
  ],
  "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*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a banner
  • Outbound: platform-wide; crosses to no counterparty

Events

Related

None.