Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- false
- permission
- any one of: org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `root_id` or any unit above it by a member of that org; without `root_id`, by the template); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_units
- REST
- POST https://api.containertradehq.com/v1/cap/list_units
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose tree it is. |
| root_id | unit_id | optional | tradehq-unit-id Only this unit and what is beneath it. |
| limit | integer | optional | 1 to 1000; default 500 The page size. |
| after | unit_id | optional | tradehq-unit-id The previous page's next_after. |
Paginated: next next_after · page_max 1000 · walk_max 10000 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"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's id.",
"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; null for a root.",
"x-data-class": "operational"
},
"kind": {
"type": "string",
"enum": [
"division",
"region",
"depot",
"office"
],
"description": "Its kind.",
"x-data-class": "operational"
},
"name": {
"type": "string",
"description": "Its name.",
"x-data-class": "operational"
},
"bfc": {
"type": [
"string",
"null"
],
"description": "The BIC Facility Code of a claimed depot; null otherwise.",
"x-data-class": "operational"
},
"depth": {
"type": "integer",
"description": "Its distance from its root: 0 for a root.",
"x-data-class": "operational"
},
"my_role": {
"type": [
"string",
"null"
],
"enum": [
"admin",
"user",
null
],
"description": "The caller's role at this unit, inherited downward; null for none.",
"x-data-class": "operational"
}
},
"required": [
"unit_id",
"parent_id",
"kind",
"name",
"bfc",
"depth",
"my_role"
],
"additionalProperties": false
},
"maxItems": 1000
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
tree_too_large· 422 · the org's unit tree holds more units than one listing reads
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates a unit listing
- Outbound: crosses to no counterparty
Events
None emitted.