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); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_granted_capabilities
- REST
- POST https://api.containertradehq.com/v1/cap/list_granted_capabilities
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 grants they are. |
| include_ended | boolean | optional | Also list revoked and expired grants. False by default. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | uuid | optional | UUID The previous page's next_after. |
Paginated: next next_after · page_max 200 · walk_max 200 · 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": {
"org_grant_id": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
"format": "uuid",
"description": "The grant's id.",
"x-data-class": "operational"
},
"org_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-org-id",
"description": "The org it was given to.",
"x-data-class": "operational"
},
"capability_id": {
"type": "string",
"description": "The capability, by its registry name.",
"x-data-class": "operational"
},
"kind": {
"type": "string",
"enum": [
"grant",
"add_on"
],
"description": "grant, given outside the tier, or add_on, bought on top.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
],
"description": "active while it counts; expired past expires_at; revoked once revoked.",
"x-data-class": "operational"
},
"reason": {
"type": "string",
"description": "Why it was given.",
"x-data-class": "operational"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it stops counting; null for never.",
"x-data-class": "operational"
},
"granted_by": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who gave it.",
"x-data-class": "operational"
},
"granted_via": {
"type": "string",
"description": "The principal kind it came through: clerk_user, or mcp_subject for an agent.",
"x-data-class": "operational"
},
"granted_client": {
"type": [
"string",
"null"
],
"description": "The OAuth client an agent acted through; null otherwise.",
"x-data-class": "operational"
},
"granted_at": {
"type": "string",
"format": "date-time",
"description": "When it was given.",
"x-data-class": "operational"
},
"revoked_by": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who revoked it; null while it is not revoked.",
"x-data-class": "operational"
},
"revoked_via": {
"type": [
"string",
"null"
],
"description": "The principal kind the revocation came through.",
"x-data-class": "operational"
},
"revoked_client": {
"type": [
"string",
"null"
],
"description": "The OAuth client an agent revoked it through.",
"x-data-class": "operational"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it was revoked.",
"x-data-class": "operational"
},
"revoke_reason": {
"type": [
"string",
"null"
],
"description": "Why it was revoked.",
"x-data-class": "operational"
}
},
"required": [
"org_grant_id",
"org_id",
"capability_id",
"kind",
"status",
"reason",
"expires_at",
"granted_by",
"granted_via",
"granted_client",
"granted_at",
"revoked_by",
"revoked_via",
"revoked_client",
"revoked_at",
"revoke_reason"
],
"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
capability_not_released· 422 · the release-grant-capability flag is off for the caller; it may be turned on later
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 entitlement
- Outbound: crosses to no counterparty
Events
None emitted.