set_flag_lists · Choose the beta lists a flag reaches

set_flag_lists

Choose the beta lists a flag reaches

act entity canonical-registry since 2026-10-01

Sets which beta lists one registered feature flag reaches in PostHog, on the wave you saw: from staff or the beta lists it puts the flag on the lists chosen, and on a percentage of customer orgs it keeps the percentage and takes the lists chosen. Name the wave you saw; if the flag has moved since, nothing changes. Refused for a flag off, not in PostHog, on for everyone or with a rule made in PostHog, and when the lists are the ones it already reaches. Each change is recorded with who made it and the lists before and after. 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: set_flag_lists
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/set_flag_lists

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

name	type	required	validation
flag_key	text	required	1 to 100 characters The flag's key, as the registry has it.
from	one_of	required	one of absent, off, staff, beta, orgs_10, orgs_25, orgs_50, everyone, custom The wave you saw the flag on (list_flags' wave). If PostHog has it anywhere else, nothing changes.
lists	beta_lists	required	1 to 3 items; unique The beta lists the flag reaches, by name, at least one.

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

flag.wave_changed audit_only

None.

curl https://api.containertradehq.com/v1/cap/set_flag_lists \ -H "Authorization: Bearer $TRADEHQ_API_KEY" \ -H "Trade-HQ-Version: 2026-10-01" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"flag_key":"<flag_key>","from":"absent","lists":["Loadstar beta"]}'

import { TradeHQ } from '@containertradehq/sdk'; const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! }); const result = await tradehq.setFlagLists({ "flag_key": "<flag_key>", "from": "absent", "lists": [ "Loadstar beta" ] }); // Idempotency-Key is generated once per call and reused across its retries.

import os from containertradehq import TradeHQ tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"]) result = tradehq.set_flag_lists({ "flag_key": "<flag_key>", "from": "absent", "lists": [ "Loadstar beta", ], }) # Idempotency-Key is generated once per call and reused across its retries.

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "set_flag_lists", "arguments": { "flag_key": "<flag_key>", "from": "absent", "lists": [ "Loadstar beta" ] } } }