set_beta_list_member · Add or remove an org or user on a beta list

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: beta_list.changed
MCP tool: set_beta_list_member
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/set_beta_list_member

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
list	text	required	1 to 60 characters The beta list's name, as src/beta_lists.json has it (not staff).
member_kind	one_of	required	one of org, user org or user.
member_id	text	required	1 to 20 characters The org's org_id or the user's user_id.
state	one_of	required	one of add, remove add or remove.
agreed_by	text	optional	1 to 200 characters Who at the customer agreed to test early. Required to add; refused to remove.
agreed_at	date	optional	date, YYYY-MM-DD The day they agreed, never in the future. Required to add; refused to remove.

Response

action_id · string · This change's audit row.
list · string · The beta list.
member_kind · string · org or user.
member_id · string · The org or user.
state · string · add or remove.
agreed_by · stringnull · Who agreed; null on a remove.
agreed_at · stringnull · When they agreed; null on a remove.
acted_by · string · Who on staff made the change.
acted_at · string · When.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "action_id": {
      "type": "string",
      "description": "This change's audit row.",
      "x-data-class": "operational"
    },
    "list": {
      "type": "string",
      "description": "The beta list.",
      "x-data-class": "operational"
    },
    "member_kind": {
      "type": "string",
      "enum": [
        "org",
        "user"
      ],
      "description": "org or user.",
      "x-data-class": "operational"
    },
    "member_id": {
      "type": "string",
      "description": "The org or user.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "add",
        "remove"
      ],
      "description": "add or remove.",
      "x-data-class": "operational"
    },
    "agreed_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Who agreed; null on a remove.",
      "x-data-class": "operational"
    },
    "agreed_at": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
      "format": "date",
      "description": "When they agreed; null on a remove.",
      "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 on staff made the change.",
      "x-data-class": "operational"
    },
    "acted_at": {
      "type": "string",
      "format": "date-time",
      "description": "When.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "action_id",
    "list",
    "member_kind",
    "member_id",
    "state",
    "agreed_by",
    "agreed_at",
    "acted_by",
    "acted_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 beta list
Outbound: staff tooling; crosses to no counterparty

Events

beta_list.changed audit_only

None.