Book a demo

list_role_templates

List role templates

read collection tenant-private since 2026-10-01

Lists the role templates an org can assign: the shipped bundles (Owner, Admin, Ops, Sales, Finance, Read-only, Developer and one Counterparty per seat), which cannot be changed, and the org's own clones. Each carries its permissions, its module tags, the Clerk role it maps to, and how many of the org's members hold it. Filters by module and by kind.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: role.read (carried by the caller's role template in the org `org_id`); 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_role_templates
REST
POST https://api.containertradehq.com/v1/cap/list_role_templates

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose templates to list.
moduleone_ofoptionalone of leasing, trading, depot, forwarding
Only templates tagged with this module.
kindone_ofoptionalone of shipped, clone
shipped (read-only bundles) or clone (the org's own).

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": {
          "role_id": {
            "type": "string",
            "description": "The template's id: a shipped id such as admin, or a clone's RT id.",
            "x-data-class": "operational"
          },
          "title": {
            "type": "string",
            "description": "Its name.",
            "x-data-class": "operational"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What it is for.",
            "x-data-class": "operational"
          },
          "kind": {
            "type": "string",
            "enum": [
              "shipped",
              "clone"
            ],
            "description": "shipped or clone.",
            "x-data-class": "operational"
          },
          "read_only": {
            "type": "boolean",
            "description": "True for a shipped template: clone it to change it.",
            "x-data-class": "operational"
          },
          "family": {
            "type": [
              "string",
              "null"
            ],
            "description": "The family it belongs to, such as counterparty.",
            "x-data-class": "operational"
          },
          "seat": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its seat in the family, such as depot.",
            "x-data-class": "operational"
          },
          "modules": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The modules it is tagged with.",
            "x-data-class": "operational"
          },
          "permissions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The permissions it carries.",
            "x-data-class": "operational"
          },
          "clerk_role": {
            "type": "string",
            "description": "The Clerk built-in role its members hold: org:admin when it carries org.admin, else org:member (TRA-963).",
            "x-data-class": "operational"
          },
          "cloned_from": {
            "type": [
              "string",
              "null"
            ],
            "description": "The template a clone was made from; null for a shipped one.",
            "x-data-class": "operational"
          },
          "members": {
            "type": "integer",
            "description": "How many of the org's members hold it.",
            "x-data-class": "operational"
          },
          "units": {
            "type": "integer",
            "description": "How many grants on the org's units name it (TRA-473): it is held on that many units.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "role_id",
          "title",
          "description",
          "kind",
          "read_only",
          "family",
          "seat",
          "modules",
          "permissions",
          "clerk_role",
          "cloned_from",
          "members",
          "units"
        ],
        "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 a role template
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

set_my_notification, set_notification_policy