Book a demo

announce_deprecated_versions

Announce deprecated API versions

act entity abstract since 2026-10-01

Trade HQ staff, after a release that supersedes an API version: emails the admins of every org holding an active API key pinned to a superseded version that it is deprecated, the day it stops being served, and how to re-pin the key. Name the release just deployed, the current version; every superseded version not announced yet is announced, each once. The dates are the release's, never the caller's.

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
natural
emits
version.deprecated
MCP tool
announce_deprecated_versions
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/announce_deprecated_versions

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

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
releasedaterequireddate, YYYY-MM-DD
The release just deployed: the current API version, YYYY-MM-DD.

Response

  • superseded · string[] · Every version this build serves that a later one superseded, oldest first, each YYYY-MM-DD.
  • announced · string[] · The versions this call announced, each YYYY-MM-DD; empty when every one already was.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "superseded": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
        "format": "date"
      },
      "description": "Every version this build serves that a later one superseded, oldest first, each YYYY-MM-DD.",
      "x-data-class": "operational"
    },
    "announced": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
        "format": "date"
      },
      "description": "The versions this call announced, each YYYY-MM-DD; empty when every one already was.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "superseded",
    "announced"
  ],
  "additionalProperties": false
}

Refusals

  • release_not_current · 422 · the release named is not this deployment's current version: the release has not reached it yet, or the date is wrong

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

Surfaces

DesktopF
MobileN
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • Mobile: a release step, taken at a desk after a deploy
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a release
  • Outbound: crosses to no counterparty

Events

Related

None.