Contract
- shape
- collection
- authority
- read
- 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); org.member (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
- safe
- emits
- none
- MCP tool
- list_unit_access
- REST
- POST https://api.containertradehq.com/v1/cap/list_unit_access
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. |
| unit_id | unit_id | optional | tradehq-unit-id The unit whose access to list. Name this or user_id. |
| user_id | user_id | optional | tradehq-user-id; 1 to 20 characters The member whose grants to list. Name this or unit_id. |
| include_inherited | boolean | optional | With unit_id, whether to include the grants on the units above it, which reach it. Default true. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | text | optional | 1 to 80 characters The previous page's next_after. |
Paginated: next next_after · page_max 200 · 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": {
"user_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who holds it.",
"x-data-class": "operational"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "Their name, or their address when they have none.",
"x-data-class": "personal"
},
"email": {
"anyOf": [
{
"type": [
"string",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "Their address; null once anonymized.",
"x-data-class": "personal"
},
"role_template_id": {
"type": "string",
"description": "The role template the grant carries.",
"x-data-class": "operational"
},
"role_title": {
"type": "string",
"description": "That template's name.",
"x-data-class": "operational"
},
"role": {
"type": "string",
"enum": [
"admin",
"user"
],
"description": "admin when the template carries org.admin, else user.",
"x-data-class": "operational"
},
"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 it is held on.",
"x-data-class": "operational"
},
"unit_name": {
"type": "string",
"description": "That unit's name.",
"x-data-class": "operational"
},
"beneath": {
"type": "integer",
"minimum": 0,
"description": "How many units are beneath that unit, which the grant also reaches.",
"x-data-class": "operational"
},
"inherited": {
"type": "boolean",
"description": "True when it is held on a unit above the one asked about.",
"x-data-class": "operational"
},
"created_by": {
"type": "string",
"description": "Who gave it: a user id, or a declaration or backfill marker.",
"x-data-class": "operational"
},
"created_by_name": {
"type": [
"string",
"null"
],
"description": "That person's name; null when it was not a person.",
"x-data-class": "operational"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When.",
"x-data-class": "operational"
},
"removable": {
"type": "boolean",
"description": "Whether revoke_unit_role would remove it for you.",
"x-data-class": "operational"
},
"remove_refusal_code": {
"type": [
"string",
"null"
],
"enum": [
"own_access",
"unit_outside_caller",
"holder_above_caller",
null
],
"description": "When it would not, the code it would answer.",
"x-data-class": "operational"
},
"remove_refusal": {
"type": [
"string",
"null"
],
"description": "When it would not, the sentence it would answer.",
"x-data-class": "operational"
}
},
"required": [
"user_id",
"name",
"email",
"role_template_id",
"role_title",
"role",
"unit_id",
"unit_name",
"beneath",
"inherited",
"created_by",
"created_by_name",
"created_at",
"removable",
"remove_refusal_code",
"remove_refusal"
],
"additionalProperties": false
},
"maxItems": 200
},
"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
unit_outside_caller· 422 · You administer {your unit} and the units beneath it. {unit} is outside it.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 role
- Outbound: crosses to no counterparty
Events
None emitted.
Related
grant_unit_role, impersonate_user, list_accounts, list_agent_reads, list_audit_events, list_audit_exports, list_orgs, list_sessions, list_users, revoke_sessions, revoke_unit_role, set_member_role