Book a demo

turn_off_flag

Turn a flag off

act entity canonical-registry since 2026-10-01

Switches one registered feature flag off in PostHog for everyone, from any wave. A release flag off hides its feature from everyone, staff included; a kill switch off gives everyone the new screen. A flag PostHog does not have is created switched off. Refused for a flag already off. Recorded with who did it. Send an Idempotency-Key header. 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
flag.wave_changed
MCP tool
turn_off_flag
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/turn_off_flag

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
flag_keytextrequired1 to 100 characters
The flag's key, as the registry has it.

Response

  • action_id · string · This move's audit row.
  • flag_key · string · The flag moved.
  • action · string · advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).
  • from_wave · string · The wave PostHog had it on.
  • to_wave · string · The wave it is on now.
  • acted_by · string · Who moved it: the staff member or agent, never PostHog's key.
  • acted_at · string · When.
  • posthog_url · stringnull · The flag in PostHog; null on a replay.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "action_id": {
      "type": "string",
      "description": "This move's audit row.",
      "x-data-class": "operational"
    },
    "flag_key": {
      "type": "string",
      "description": "The flag moved.",
      "x-data-class": "operational"
    },
    "action": {
      "type": "string",
      "enum": [
        "advance",
        "roll_back",
        "set_lists"
      ],
      "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).",
      "x-data-class": "operational"
    },
    "from_wave": {
      "type": "string",
      "description": "The wave PostHog had it on.",
      "x-data-class": "operational"
    },
    "to_wave": {
      "type": "string",
      "description": "The wave it is on now.",
      "x-data-class": "operational"
    },
    "acted_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who moved it: the staff member or agent, never PostHog's key.",
      "x-data-class": "operational"
    },
    "acted_at": {
      "type": "string",
      "format": "date-time",
      "description": "When.",
      "x-data-class": "operational"
    },
    "posthog_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The flag in PostHog; null on a replay.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "action_id",
    "flag_key",
    "action",
    "from_wave",
    "to_wave",
    "acted_by",
    "acted_at",
    "posthog_url"
  ],
  "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 flag
  • Outbound: staff tooling; crosses to no counterparty

Events

Related

None.