Book a demo

move_unit

Move a unit

act entity tenant-private since 2026-10-01

Moves a unit, with everything beneath it, to a new parent unit in the same org, or to the root. Roles held on units inside the moved subtree move with it; roles held above its old place stop reaching it, and roles above its new place start to. The caller needs admin on the unit and at the destination (the org role for the root). A unit cannot move beneath itself, its own descendants or a depot. Moving a unit to where it already is changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first
idempotency
natural
emits
unit.moved
MCP tool
move_unit
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/move_unit

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
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose tree it is.
unit_idunit_idrequiredtradehq-unit-id
The unit to move. Everything beneath it moves with it.
new_parent_idunit_idoptionaltradehq-unit-id
The unit it goes beneath, in the same org. Absent, it becomes a root.

Response

  • unit_id · string · The unit moved.
  • org_id · string · Its org.
  • parent_id · stringnull · Its parent now; null for a root.
  • units_moved · integer · The units in the moved subtree, the unit itself included.
  • grants_moved · integer · The roles held on units inside the subtree, which moved with it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "unit_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-unit-id",
      "description": "The unit moved.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "Its org.",
      "x-data-class": "operational"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-unit-id",
      "description": "Its parent now; null for a root.",
      "x-data-class": "operational"
    },
    "units_moved": {
      "type": "integer",
      "description": "The units in the moved subtree, the unit itself included.",
      "x-data-class": "operational"
    },
    "grants_moved": {
      "type": "integer",
      "description": "The roles held on units inside the subtree, which moved with it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "unit_id",
    "org_id",
    "parent_id",
    "units_moved",
    "grants_moved"
  ],
  "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 move
  • Outbound: crosses to no counterparty

Events

Related

None.