Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- false
- permission
- any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.member (account role member or higher in at least one account; the call is scoped to those accounts); org.admin (carried by the caller's role template in the org `org_id` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_orgs
- REST
- POST https://api.containertradehq.com/v1/cap/list_orgs
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| query | text | optional | 1 to 100 characters A case-insensitive substring of the org's name. |
| org_type | one_of | optional | one of internal, demo, customer, synthetic, system Only orgs of this type. |
| account_id | account_id | optional | tradehq-account-id Only orgs of this account; an org with no account never matches. A member may name only an account of theirs. |
| org_id | org_id | optional | tradehq-org-id; 1 to 20 characters Only this org; in test mode, the twin listed in place of it. An org outside the caller's scope is an empty page. An org admin names its own org here, and is refused without it. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | org_id | optional | tradehq-org-id; 1 to 20 characters The previous page's next_after. |
Paginated: next next_after · ceiling not_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": {
"org_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-org-id",
"description": "The org's id.",
"x-data-class": "operational"
},
"name": {
"type": "string",
"description": "The org's name.",
"x-data-class": "operational"
},
"org_type": {
"type": [
"string",
"null"
],
"enum": [
"internal",
"demo",
"customer",
"synthetic",
"system",
null
],
"description": "The org's type (TRA-234); null for a ported org nothing has typed yet.",
"x-data-class": "operational"
},
"account_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-account-id",
"description": "The account the org belongs to; null when it has none yet.",
"x-data-class": "operational"
},
"state": {
"type": [
"string",
"null"
],
"enum": [
"active",
"suspended",
"deletion_scheduled",
"purged",
null
],
"description": "Where the org is in its life (TRA-316); null for an org with no lifecycle row.",
"x-data-class": "operational"
},
"purge_after": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The end of a scheduled deletion's 30 day countdown; null when none is scheduled.",
"x-data-class": "operational"
},
"suspended_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When a suspended org was suspended, as suspend_org recorded it; null in every other state, and for a suspension recorded before the field existed.",
"x-data-class": "operational"
},
"suspended_by": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who suspended a suspended org, as suspend_org recorded it; null in every other state, and for a suspension recorded before the field existed.",
"x-data-class": "operational"
},
"suspended_by_name": {
"type": [
"string",
"null"
],
"description": "That user's name; null when suspended_by is, when they have no name, and once they are anonymized.",
"x-data-class": "operational"
},
"suspend_reason": {
"type": [
"string",
"null"
],
"description": "Why a suspended org was suspended, as suspend_org recorded it. Answered to staff only: null to an account member, in every other state, and when no reason was given.",
"x-data-class": "operational"
},
"sandbox": {
"type": [
"object",
"null"
],
"properties": {
"created_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"key_display": {
"type": "string"
},
"converted_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"converted_by": {
"type": [
"string",
"null"
]
}
},
"required": [
"created_at",
"expires_at",
"key_display",
"converted_at",
"converted_by"
],
"additionalProperties": false,
"description": "For an org that is or was a public sandbox (TRA-474): when it was made, when it expires, its one test key's display (never the secret), and when and by whom staff converted it, both null until then. Null for every other org, and for any caller who is not staff.",
"x-data-class": "operational"
},
"purged_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When a purged org was purged (TRA-467); null for every other org, and for any caller who is not staff.",
"x-data-class": "operational"
},
"purge": {
"type": [
"object",
"null"
],
"properties": {
"dry_run_id": {
"type": "string"
},
"approvers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"principal": {
"type": "boolean"
},
"approved_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"user_id",
"name",
"principal",
"approved_at"
],
"additionalProperties": false
}
},
"counts": {
"type": [
"object",
"null"
]
},
"deleted": {
"type": [
"object",
"null"
]
}
},
"required": [
"dry_run_id",
"approvers",
"counts",
"deleted"
],
"additionalProperties": false,
"description": "A purged org's purge (TRA-467): the dry run it was approved on, who approved it (oldest first), what that dry run counted, which the purge job's recount found unchanged, and what the job deleted ({rows, tables}). Null for every other org, for a purge recorded before dry runs existed, and for any caller who is not staff.",
"x-data-class": "operational"
},
"customer_stage": {
"type": [
"string",
"null"
],
"enum": [
"prospect",
"pilot",
"customer",
null
],
"description": "Where a customer org is in Trade HQ's sales cycle (TRA-1273): prospect, pilot, or customer when it has no stage; a twin answers its live org's. Null for an org that is not a customer org, and for any caller who is not staff.",
"x-data-class": "operational"
},
"sandbox_expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When a running public sandbox and its key are deleted; null once it is converted or purged, for every other org, and for any caller who is not staff.",
"x-data-class": "operational"
}
},
"required": [
"org_id",
"name",
"org_type",
"account_id",
"state",
"purge_after",
"suspended_at",
"suspended_by",
"suspended_by_name",
"suspend_reason",
"sandbox",
"purged_at",
"purge",
"customer_stage",
"sandbox_expires_at"
],
"additionalProperties": false
}
},
"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
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
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates an org listing
- Outbound: crosses to no counterparty
Events
None emitted.
Related
convert_sandbox, list_accounts, list_agent_reads, list_audit_events, list_audit_exports, list_unit_access, list_users