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); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_access_reviews
- REST
- POST https://api.containertradehq.com/v1/cap/list_access_reviews
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 access reviews to list. |
| review_id | text | optional | 1 to 14 characters One review to answer, with its items. |
Paginated: next next_after · page_max 1000 · walk_max 1000 · 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": {
"review_id": {
"type": "string",
"description": "The review'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 whose access it reviews.",
"x-data-class": "operational"
},
"name": {
"type": "string",
"description": "What it is called.",
"x-data-class": "operational"
},
"covers": {
"type": "array",
"items": {
"type": "string"
},
"description": "What it covers, of members, guests, service_accounts, api_keys and staff_grants, in that order.",
"x-data-class": "operational"
},
"due_at": {
"type": "string",
"format": "date-time",
"description": "When it is due: the end (UTC) of its due date.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"open",
"overdue",
"closed"
],
"description": "open; overdue, an open review past due; or closed.",
"x-data-class": "operational"
},
"total": {
"type": "integer",
"minimum": 0,
"description": "How many items it asks about.",
"x-data-class": "operational"
},
"decided": {
"type": "integer",
"minimum": 0,
"description": "How many of them are decided.",
"x-data-class": "operational"
},
"created_by": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who started it.",
"x-data-class": "operational"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When it was started.",
"x-data-class": "operational"
},
"closed_by": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who closed it.",
"x-data-class": "operational"
},
"closed_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it was closed.",
"x-data-class": "operational"
},
"evidence_document_id": {
"type": [
"string",
"null"
],
"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 evidence document closing it wrote: who decided what, and when.",
"x-data-class": "operational"
},
"items": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"item_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 item's id.",
"x-data-class": "operational"
},
"review_id": {
"type": "string",
"description": "The review it belongs to.",
"x-data-class": "operational"
},
"kind": {
"type": "string",
"enum": [
"member",
"guest",
"service_account",
"api_key",
"staff_grant"
],
"description": "member, guest, service_account, api_key or staff_grant.",
"x-data-class": "operational"
},
"subject_id": {
"type": "string",
"description": "Whose access: a user id, a service account id, a key id or a staff grant's id.",
"x-data-class": "operational"
},
"subject_label": {
"anyOf": [
{
"type": "string"
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "What a reviewer reads for it: an email, or a service account's or key's name.",
"x-data-class": "personal"
},
"role": {
"type": [
"string",
"null"
],
"description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.",
"x-data-class": "operational"
},
"last_active_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it was last seen acting before the review began, where known.",
"x-data-class": "operational"
},
"decision": {
"type": [
"string",
"null"
],
"enum": [
"keep",
"change_role",
"revoke",
null
],
"description": "keep, change_role or revoke; null until decided.",
"x-data-class": "operational"
},
"new_role_template_id": {
"type": [
"string",
"null"
],
"description": "The role template a change_role decision gave the member.",
"x-data-class": "operational"
},
"decided_by": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who decided it.",
"x-data-class": "operational"
},
"decided_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it was decided.",
"x-data-class": "operational"
},
"own": {
"type": "boolean",
"description": "Whether it is the caller's own row, which another admin decides.",
"x-data-class": "operational"
}
},
"required": [
"item_id",
"review_id",
"kind",
"subject_id",
"subject_label",
"own"
],
"additionalProperties": false
},
"description": "Its items, when one review is asked for (review_id); null otherwise.",
"x-data-class": "operational"
}
},
"required": [
"review_id",
"org_id",
"name",
"covers",
"due_at",
"status",
"total",
"decided",
"created_by",
"created_at",
"closed_by",
"closed_at",
"evidence_document_id",
"items"
],
"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
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 access review
- Outbound: crosses to no counterparty
Events
None emitted.