Book a demo

set_session_mode

Switch between live and test

act entity tenant-private since 2026-10-01

Switches the caller's own session between live and test. In test, everything the session reads and writes is the org's test twin: the same members, roles, units and settings, and its own business data. Switching to test brings the twin in line with the live org first. Only admins and people with API key access may switch to test; anyone in test may switch back to live. Refused in test for an org with no twin. Setting the mode the session is already in changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: self.read (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first
idempotency
natural
emits
session.mode_changed
MCP tool
set_session_mode
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/set_session_mode

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
modeone_ofrequiredone of live, test
live or test.

Response

  • mode · string · The session's mode now.
  • org_id · stringnull · The org the session now acts in: the live org, or its twin in test. Null for a session that has selected no org.
  • live_org_id · stringnull · The live org, whose people these are.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "live",
        "test"
      ],
      "description": "The session's mode now.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org the session now acts in: the live org, or its twin in test. Null for a session that has selected no org.",
      "x-data-class": "operational"
    },
    "live_org_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The live org, whose people these are.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "mode",
    "org_id",
    "live_org_id"
  ],
  "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 mode switch
  • Outbound: crosses to no counterparty

Events

Related

None.